lincoln-lil commented on code in PR #20577:
URL: https://github.com/apache/flink/pull/20577#discussion_r952185567
##########
docs/content/docs/dev/table/sql/queries/hints.md:
##########
@@ -84,4 +84,311 @@ insert into kafka_table1 /*+
OPTIONS('sink.partitioner'='round-robin') */ select
```
+## Query Hints
+
+### Join Hints
+
+#### LOOKUP Hint
+
+{{< label Streaming >}}
+
+The LOOKUP hint allows users to suggest the Flink optimizer to:
+1. use synchronous(sync) or asynchronous(async) lookup function
+2. configure the async parameters
+3. enable delayed retry strategy for lookup
+
+```sql
+SELECT /*+ LOOKUP(key=value[, key=value]*) */
+
+key:
+ stringLiteral
+
+value:
+ stringLiteral
+```
+
+The available hint options:
+
+<table class="table table-bordered">
+<thead>
+<tr>
+ <th>option type</th>
+ <th>option name</th>
+ <th>optional</th>
+ <th>value type</th>
+ <th>default value</th>
+ <th>description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+ <th rowspan="1">table</th>
+ <th>table</th>
+ <th>N</th>
+ <th>string</th>
+ <th>N/A</th>
+ <th>the table name of the lookup source</th>
+</tr>
+<tr>
+ <th rowspan="4">async</th>
+ <th>async</th>
+ <th>Y</th>
+ <th>boolean</th>
+ <th>N/A</th>
+ <th>value can be 'true' or 'false' to suggest the planner choose the
corresponding lookup function.
+ If the backend lookup source does not support the suggested lookup
mode, it will take no effect.</th>
+</tr>
+<tr>
+ <th>output-mode</th>
+ <th>Y</th>
+ <th>string</th>
+ <th>ordered</th>
+ <th>value can be 'ordered' or 'allow_unordered'.<br />'allow_unordered'
means if users allow unordered result, it will attempt to use
AsyncDataStream.OutputMode.UNORDERED when it does not affect the correctness of
the result, otherwise ORDERED will be still used. It is consistent with <br
/>`ExecutionConfigOptions#TABLE_EXEC_ASYNC_LOOKUP_OUTPUT_MODE`.</th>
+</tr>
+<tr>
+ <th>capacity</th>
+ <th>Y</th>
+ <th>integer</th>
+ <th>100</th>
+ <th>the buffer capacity for the backend asyncWaitOperator of the lookup
join operator.</th>
+</tr>
+<tr>
+ <th>timeout</th>
+ <th>Y</th>
+ <th>duration</th>
+ <th>300s</th>
+ <th>timeout from first invoke to final completion of asynchronous
operation, may include multiple retries, and will be reset in case of
failover</th>
+</tr>
+<tr>
+ <th rowspan="4">retry</th>
+ <th>retry-predicate</th>
+ <th>Y</th>
+ <th>string</th>
+ <th>N/A</th>
+ <th>can be 'lookup_miss' which will enable retry if lookup result is
empty.</th>
+</tr>
+<tr>
+ <th>retry-strategy</th>
+ <th>Y</th>
+ <th>string</th>
+ <th>N/A</th>
+ <th>can be 'fixed_delay'</th>
+</tr>
+<tr>
+ <th>fixed-delay</th>
+ <th>Y</th>
+ <th>duration</th>
+ <th>N/A</th>
+ <th>delay time for the 'fixed_delay' strategy</th>
+</tr>
+<tr>
+ <th>max-attempts</th>
+ <th>Y</th>
+ <th>integer</th>
+ <th>N/A</th>
+ <th>max attempt number of the 'fixed_delay' strategy</th>
+</tr>
+</tbody>
+</table>
+
+Note:
+- 'table' option is required, only table name is supported, alias name is not
supported currently(will be supported in later versions).
+- async options are all optional, will use default value if not configured.
+- there is no default value for retry options, all retry options should be set
to valid values when need to enable retry.
+
+##### 1. Use Sync And Async Lookup Function
+If the connector has both capabilities of async and sync lookup, users can
give the option value 'async'='false'
+to suggest the planner to use the sync lookup or 'async'='true' to use the
async lookup:
+
+Example:
+```sql
+-- suggest the optimizer to use sync lookup
+LOOKUP('table'='Customers', 'async'='false')
+
+-- suggest the optimizer to use async lookup
+LOOKUP('table'='Customers', 'async'='true')
+```
+Note: the optimizer prefers async lookup if no 'async' option is specified, it
will always use sync lookup when:
+1. the connector only implements the sync lookup
+2. user enables 'TRY_RESOLVE' mode of
'table.optimizer.non-deterministic-update.strategy' and the
Review Comment:
yes, there should be a configuration link
--
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.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
