dawidwys commented on a change in pull request #12473:
URL: https://github.com/apache/flink/pull/12473#discussion_r436743704
##########
File path:
flink-table/flink-table-api-java/src/main/java/org/apache/flink/table/api/TableResult.java
##########
@@ -40,6 +40,40 @@
/**
* Get the schema of result.
+ *
+ * <p>The schema of DDL, SHOW, EXPLAIN:
+ * <pre>
+ * +-------------+-------------+----------+
+ * | column name | column type | comments |
+ * +-------------+-------------+----------+
+ * | result | STRING | |
+ * +-------------+-------------+----------+
+ * </pre>
+ *
+ * <p>The schema of DESCRIBE:
+ * <pre>
+ *
+------------------+-------------+-----------------------------------------------------------------------------+
+ * | column name | column type |
comments |
+ *
+------------------+-------------+-----------------------------------------------------------------------------+
+ * | name | STRING | field name
|
+ * | type | STRING | field type expressed as a String
|
+ * | null | BOOLEAN | field nullability: true if a
field is nullable, else false |
+ * | key | BOOLEAN | key constraint: 'PRI' for primary
keys, 'UNQ' for unique keys, else null |
+ * | computed column | STRING | computed column: string
expression if a field is computed column, else null |
+ * | watermark | STRING | watermark: string expression if a
field is watermark, else null |
+ *
+------------------+-------------+-----------------------------------------------------------------------------+
+ * </pre>
+ *
+ * <p>The schema of INSERT: (one column per one sink)
+ * <pre>
+ * +----------------------------+-------------+-----------------------+
+ * | column name | column type | comments |
+ * +----------------------------+-------------+-----------------------+
+ * | (name of the insert table) | BIGINT | the insert table name |
+ * +----------------------------+-------------+-----------------------+
+ * </pre>
+ *
+ * <p>The schema of SELECT is the selected field names and types.
Review comment:
Good job with the javadoc here. It's definitely helpful.
##########
File path:
flink-table/flink-table-api-java/src/main/java/org/apache/flink/table/api/TableResult.java
##########
@@ -49,9 +83,39 @@
ResultKind getResultKind();
/**
- * Get the result contents as a row iterator.
+ * Get the result contents as a closeable row iterator.
+ *
+ * <p><strong>NOTE:</strong>
+ * <ul>
+ * <li>
+ * 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.
+ * </li>
+ * <li>
+ * 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 after the job is submitted.
+ * Do nothing when calling CloseableIterator#close method
(which will not cancel the job
Review comment:
```suggestion
* Calling CloseableIterator#close method does not bind to the
job. Therefore the `CloseableIterator#close` will not cancel the job as in the
case of SELECT. If you need to cancel the job, you can use the {@link
#getJobClient()}
```
----------------------------------------------------------------
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:
[email protected]
