godfreyhe commented on a change in pull request #12867:
URL: https://github.com/apache/flink/pull/12867#discussion_r456225483
##########
File path:
flink-table/flink-table-api-java/src/main/java/org/apache/flink/table/api/TableResult.java
##########
@@ -132,10 +132,22 @@
* }
* }</pre>
*
- * <p>For streaming mode, this method guarantees end-to-end
exactly-once record delivery
- * which requires the checkpointing mechanism to be enabled.
- * By default, checkpointing is disabled. To enable checkpointing, set
checkpointing properties
- * (see ExecutionCheckpointingOptions) through {@link
TableConfig#getConfiguration()}.
+ * <p>This method has slightly different behaviors under different
checkpointing settings
+ * (to enable checkpointing for a streaming job,
+ * set checkpointing properties through {@link
TableConfig#getConfiguration()}).
+ * <ul>
+ * <li>If the user is running a batch job, or does not enable
checkpointing for a streaming job,
+ * this method has neither exactly-once nor at-least-once guarantee.
+ * Query results are immediately accessible by the clients once
they're produced,
+ * but the function calls will throw an exception when the job
fails and restarts.
Review comment:
ditto
##########
File path: docs/dev/table/sql/queries.md
##########
@@ -145,21 +145,16 @@ A SELECT statement or a VALUES statement can be executed
to collect the content
`TableResult.collect()` method returns a closeable row iterator. The select
job will not be finished unless all result data has been collected. We should
actively close the job to avoid resource leak through the
`CloseableIterator#close()` method.
We can also print the select result to client console through the
`TableResult.print()` method. The result data in `TableResult` can be accessed
only once. Thus, `collect()` and `print()` must not be called after each other.
-For streaming job, `TableResult.collect()` method or `TableResult.print`
method guarantee end-to-end exactly-once record delivery. This requires the
checkpointing mechanism to be enabled. By default, checkpointing is disabled.
To enable checkpointing, we can set checkpointing properties (see the <a
href="{{ site.baseurl }}/ops/config.html#checkpointing">checkpointing
config</a> for details) through `TableConfig`.
-So a result record can be accessed by client only after its corresponding
checkpoint completes.
-
-**Notes:** For streaming mode, only append-only query is supported now.
+`TableResult.collect()` and `TableResult.print()` have slightly different
behaviors under different checkpointing settings (to enable checkpointing for a
streaming job, see <a href="{{ site.baseurl
}}/ops/config.html#checkpointing">checkpointing config</a>).
+* If the user is running a batch job, or does not enable checkpointing for a
streaming job, `TableResult.collect()` and `TableResult.print()` have neither
exactly-once nor at-least-once guarantee. Query results are immediately
accessible by the clients once they're produced, but the function calls will
throw an exception when the job fails and restarts;
Review comment:
users do not know what the `the function calls` means
##########
File path:
flink-table/flink-table-api-java/src/main/java/org/apache/flink/table/api/TableResult.java
##########
@@ -146,10 +158,22 @@
/**
* Print the result contents as tableau form to client console.
*
- * <p>For streaming mode, this method guarantees end-to-end
exactly-once record delivery
- * which requires the checkpointing mechanism to be enabled.
- * By default, checkpointing is disabled. To enable checkpointing, set
checkpointing properties
- * (see ExecutionCheckpointingOptions) through {@link
TableConfig#getConfiguration()}.
+ * <p>This method has slightly different behaviors under different
checkpointing settings
+ * (to enable checkpointing for a streaming job,
+ * set checkpointing properties through {@link
TableConfig#getConfiguration()}).
+ * <ul>
+ * <li>If the user is running a batch job, or does not enable
checkpointing for a streaming job,
+ * this method has neither exactly-once nor at-least-once guarantee.
+ * Query results are immediately accessible by the clients once
they're produced,
+ * but the function calls will throw an exception when the job
fails and restarts.
Review comment:
ditto
##########
File path:
flink-table/flink-table-api-java/src/main/java/org/apache/flink/table/api/TableResult.java
##########
@@ -132,10 +132,22 @@
* }
* }</pre>
*
- * <p>For streaming mode, this method guarantees end-to-end
exactly-once record delivery
- * which requires the checkpointing mechanism to be enabled.
- * By default, checkpointing is disabled. To enable checkpointing, set
checkpointing properties
- * (see ExecutionCheckpointingOptions) through {@link
TableConfig#getConfiguration()}.
+ * <p>This method has slightly different behaviors under different
checkpointing settings
+ * (to enable checkpointing for a streaming job,
+ * set checkpointing properties through {@link
TableConfig#getConfiguration()}).
+ * <ul>
+ * <li>If the user is running a batch job, or does not enable
checkpointing for a streaming job,
+ * this method has neither exactly-once nor at-least-once guarantee.
+ * Query results are immediately accessible by the clients once
they're produced,
+ * but the function calls will throw an exception when the job
fails and restarts.
+ * <li>If the user enables exactly-once checkpointing for a
streaming job,
Review comment:
`If exactly-once checkpointing is enabled for a streaming job,` ?
##########
File path:
flink-table/flink-table-api-java/src/main/java/org/apache/flink/table/api/TableResult.java
##########
@@ -146,10 +158,22 @@
/**
* Print the result contents as tableau form to client console.
*
- * <p>For streaming mode, this method guarantees end-to-end
exactly-once record delivery
- * which requires the checkpointing mechanism to be enabled.
- * By default, checkpointing is disabled. To enable checkpointing, set
checkpointing properties
- * (see ExecutionCheckpointingOptions) through {@link
TableConfig#getConfiguration()}.
+ * <p>This method has slightly different behaviors under different
checkpointing settings
Review comment:
please update the doc of `TableResult` in flink-python
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
