Package org.apache.flink.table.api

Interface TableResult

@PublicEvolving public interface TableResult
A TableResult is the representation of the statement execution result.

  • Method Details

    • getJobClient

      Optional<JobClient> getJobClient()
      For DML and DQL statement, return the JobClient which associates the submitted Flink job. For other statements (e.g. DDL, DCL) return empty.

    • await

      void await() throws InterruptedException, ExecutionException
      Wait if necessary until the data is ready.

      For a select operation, this method will wait until the first row can be accessed locally. For an insert operation, this method will wait for the job to finish, because the result contains only one row. For other operations, this method will return immediately, because the result is already available locally.

      Throws:
      ExecutionException - if a problem occurred
      InterruptedException - if the operation was interrupted while waiting

    • await

      void await(long timeout, TimeUnit unit) throws InterruptedException, ExecutionException, TimeoutException
      Wait if necessary for at most the given time for the data to be ready.

      For a select operation, this method will wait until the first row can be accessed locally. For an insert operation, this method will wait for the job to finish, because the result contains only one row. For other operations, this method will return immediately, because the result is already available locally.

      Parameters:
      timeout - the maximum time to wait
      unit - the time unit of the timeout argument
      Throws:
      ExecutionException - if a problem occurred
      InterruptedException - if the operation was interrupted while waiting
      TimeoutException - if the wait timed out

    • getResolvedSchema

      ResolvedSchema getResolvedSchema()
      Returns the schema of the result.

    • getResultKind

      ResultKind getResultKind()
      Return the ResultKind which represents the result type.

      For DDL operation and USE operation, the result kind is always ResultKind.SUCCESS. For other operations, the result kind is always ResultKind.SUCCESS_WITH_CONTENT.

    • collect

      CloseableIterator<Row> collect()
      Get the result contents as a closeable row iterator.

      NOTE:

      • For SELECT operation, the job will not be finished unless all result data has been collected. So we should actively close the job to avoid resource leak through CloseableIterator#close method. Calling CloseableIterator#close method will cancel the job and release related resources.
      • For DML operation, Flink does not support getting the real affected row count now. So the affected row count is always -1 (unknown) for every sink, and them will be returned until the job is finished. Calling CloseableIterator#close method will cancel the job.
      • For other operations, no flink job will be submitted (getJobClient() is always empty), and the result is bounded. Do nothing when calling CloseableIterator#close method.

      Recommended code to call CloseableIterator#close method looks like: 

      
 TableResult result = tEnv.execute("select ...");
 // using try-with-resources statement
 try (CloseableIterator<Row> it = result.collect()) {
     it... // collect same data
 }

      This method has slightly different behaviors under different checkpointing settings (to enable checkpointing for a streaming job, set checkpointing properties through TableConfig).

      • For batch jobs or streaming jobs without checkpointing, this method has neither exactly-once nor at-least-once guarantee. Query results are immediately accessible by the clients once they're produced, but exceptions will be thrown when the job fails and restarts.
      • For streaming jobs with exactly-once checkpointing, this method guarantees an end-to-end exactly-once record delivery. A result will be accessible by clients only after its corresponding checkpoint completes.
      • For streaming jobs with at-least-once checkpointing, this method guarantees an end-to-end at-least-once record delivery. Query results are immediately accessible by the clients once they're produced, but it is possible for the same result to be delivered multiple times.

      In order to fetch result to local, you can call either collect() and print(). But, they can't be called both on the same TableResult instance, because the result can only be accessed once.

    • print

      void print()
      Print the result contents as tableau form to client console.

      This method has slightly different behaviors under different checkpointing settings (to enable checkpointing for a streaming job, set checkpointing properties through TableConfig).

      • For batch jobs or streaming jobs without checkpointing, this method has neither exactly-once nor at-least-once guarantee. Query results are immediately accessible by the clients once they're produced, but exceptions will be thrown when the job fails and restarts.
      • For streaming jobs with exactly-once checkpointing, this method guarantees an end-to-end exactly-once record delivery. A result will be accessible by clients only after its corresponding checkpoint completes.
      • For streaming jobs with at-least-once checkpointing, this method guarantees an end-to-end at-least-once record delivery. Query results are immediately accessible by the clients once they're produced, but it is possible for the same result to be delivered multiple times.

      In order to fetch result to local, you can call either collect() and print(). But, they can't be called both on the same TableResult instance, because the result can only be accessed once.