twalthr commented on code in PR #24224:
URL: https://github.com/apache/flink/pull/24224#discussion_r1470779501
##########
docs/content/docs/dev/table/functions/udfs.md:
##########
@@ -846,6 +847,119 @@ If you intend to implement or call functions in Python,
please refer to the [Pyt
{{< top >}}
+Asynchronous Scalar Functions
+----------------
+
+A user-defined asynchronous scalar function maps zero, one, or multiple scalar
values to a new scalar value, but does it asynchronously. Any data type listed
in the [data types section]({{< ref "docs/dev/table/types" >}}) can be used as
a parameter or return type of an evaluation method.
+
+In order to define an asynchronous scalar function, one has to extend the base
class `AsyncScalarFunction` in `org.apache.flink.table.functions` and implement
one or more evaluation methods named `eval(...)`. The first argument must be a
`CompletableFuture<...>` which is used to return the result, with subsequent
arguments being the parameters passed to the function.
+
+The following example shows how to do work on a thread pool in the background,
though any libraries exposing an async interface may be directly used to
complete the `CompletableFuture` from a callback. See the [Implementation
Guide](#implementation-guide) for more details.
Review Comment:
Could we go into some runtime details as well? For example, about:
- the need for Asynchronous I/O Operations
- Order of Results
- Event Time
- Error handling
I would suggest to summarize
https://nightlies.apache.org/flink/flink-docs-master/docs/dev/datastream/operators/asyncio/
to what is necessary for `AsyncScalarFunction`. Otherwise we will face many
questions on the user@ ML. Maybe we can also adopt the diagram from the page
for clarity. We need to assume that a reader is a beginner that we should guide
to the decision whether `ScalarFunction` or `AsyncScalarFunction` are more
appropriate.
--
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: issues-unsubscr...@flink.apache.org
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
