This is an automated email from the ASF dual-hosted git repository.
mchades pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/gravitino.git
The following commit(s) were added to refs/heads/main by this push:
new d228c46bab [#14810] docs: Correct sort-order examples and function API
documentation (#14815)
d228c46bab is described below
commit d228c46bab84bb3087c2022e2bf00f4624bdfc70
Author: Srihari Srithar <[email protected]>
AuthorDate: Tue Nov 10 23:38:27 2026 -0600
[#14810] docs: Correct sort-order examples and function API documentation
(#14815)
### What changes were proposed in this pull request?
- Use `"nullOrdering": "nulls_last"` in both sort-order examples.
- List the six supported function alter operations and show how to add
an implementation using REST and Java.
- Require non-blank `newComment` and Python `handler` values in the
OpenAPI schemas, clarify that `codeBlock` is optional, and use lowercase
`functionType` values in response schemas and examples.
### Why are the changes needed?
Gravitino ignores the `nullOrder` field in the old examples and falls
back to the default null ordering. The previous function docs also
listed unsupported operations and described inputs the server rejects.
Fixes #14810
### Does this PR introduce _any_ user-facing change?
The guides and OpenAPI schemas now describe the existing REST and Java
API behavior.
### How was this patch tested?
Ran `./gradlew :docs:build` and validated the updated schemas with
missing, null, blank, and valid values for `newComment` and `handler`.
---
...manage-user-defined-function-using-gravitino.md | 43 +++++++++++++++++-----
docs/open-api/functions.yaml | 26 +++++++------
...partitioning-distribution-sort-order-indexes.md | 4 +-
3 files changed, 49 insertions(+), 24 deletions(-)
diff --git a/docs/manage-user-defined-function-using-gravitino.md
b/docs/manage-user-defined-function-using-gravitino.md
index 3d0b977734..f6ed69be90 100755
--- a/docs/manage-user-defined-function-using-gravitino.md
+++ b/docs/manage-user-defined-function-using-gravitino.md
@@ -106,7 +106,8 @@ function = functions.register_function(
### Register a Python Function
-A Python implementation names a handler entrypoint, and can carry inline code
and the packages the
+A Python implementation must name a non-blank `handler` entrypoint. Inline
code in `codeBlock` is
+optional and does not replace the handler. The implementation can also carry
the resources the
runtime needs.
<Tabs groupId='language' queryString>
@@ -275,14 +276,22 @@ identifiers =
functions.list_functions(Namespace.of("public"))
### Alter a Function
-Changes are applied as a list in one request.
+Changes are applied as a list in one request. A definition is identified by
its parameter list,
+and an implementation within a definition by its runtime.
-| Change | JSON
| Java |
-|--------------------|--------------------------------------------------------------|--------------------------------------------------|
-| Rename | `{"@type":"rename","newName":"add_one_v2"}`
| `FunctionChange.rename("add_one_v2")` |
-| Update the comment | `{"@type":"updateComment","newComment":"new_comment"}`
| `FunctionChange.updateComment("new_comment")` |
-| Set a property |
`{"@type":"setProperty","property":"key1","value":"value1"}` |
`FunctionChange.setProperty("key1", "value1")` |
-| Remove a property | `{"@type":"removeProperty","property":"key1"}`
| `FunctionChange.removeProperty("key1")` |
+| Change | JSON `@type` | Other JSON fields
| Java |
+|---------------------------|--------------------|-------------------------------------------|-------------------------------------------------------------|
+| Update the comment | `updateComment` | `newComment`
| `FunctionChange.updateComment("new comment")` |
+| Add a definition | `addDefinition` | `definition`
| `FunctionChange.addDefinition(definition)` |
+| Remove a definition | `removeDefinition` | `parameters`
| `FunctionChange.removeDefinition(parameters)` |
+| Add an implementation | `addImpl` | `parameters`,
`implementation` | `FunctionChange.addImpl(parameters,
implementation)` |
+| Replace an implementation | `updateImpl` | `parameters`, `runtime`,
`implementation` | `FunctionChange.updateImpl(parameters, runtime,
implementation)` |
+| Remove an implementation | `removeImpl` | `parameters`, `runtime`
| `FunctionChange.removeImpl(parameters, runtime)` |
+
+In the Java column, `definition` is a `FunctionDefinition`, `parameters` is a
`FunctionParam[]`,
+`runtime` is a `FunctionImpl.RuntimeType` and `implementation` is a
`FunctionImpl`.
+
+`newComment` must not be null or blank; a function's comment cannot be cleared
with `updateComment`.
<Tabs groupId='language' queryString>
<TabItem value="shell" label="REST">
@@ -291,7 +300,16 @@ Changes are applied as a list in one request.
curl -X PUT -H "Accept: application/vnd.gravitino.v1+json" \
-H "Content-Type: application/json" -d '{
"updates": [
- {"@type": "updateComment", "newComment": "Adds one, reviewed"}
+ {"@type": "updateComment", "newComment": "Adds one, reviewed"},
+ {
+ "@type": "addImpl",
+ "parameters": [{"name": "x", "dataType": "integer"}],
+ "implementation": {
+ "language": "JAVA",
+ "runtime": "SPARK",
+ "className": "com.example.AddOneFunction"
+ }
+ }
]
}'
http://localhost:8090/api/metalakes/example/catalogs/sales/schemas/public/functions/add_one
```
@@ -300,9 +318,14 @@ curl -X PUT -H "Accept: application/vnd.gravitino.v1+json"
\
<TabItem value="java" label="Java">
```java
+FunctionParam[] parameters = new FunctionParam[] {FunctionParams.of("x",
Types.IntegerType.get())};
+
Function function = functions.alterFunction(
NameIdentifier.of("public", "add_one"),
- FunctionChange.updateComment("Adds one, reviewed"));
+ FunctionChange.updateComment("Adds one, reviewed"),
+ FunctionChange.addImpl(
+ parameters,
+ FunctionImpls.ofJava(FunctionImpl.RuntimeType.SPARK,
"com.example.AddOneFunction")));
```
</TabItem>
diff --git a/docs/open-api/functions.yaml b/docs/open-api/functions.yaml
index 6dc8533477..c1045d2631 100644
--- a/docs/open-api/functions.yaml
+++ b/docs/open-api/functions.yaml
@@ -187,11 +187,11 @@ components:
description: The name of the function
functionType:
type: string
- description: The type of the function
+ description: The type of the function. Responses always use
lowercase values.
enum:
- - SCALAR
- - AGGREGATE
- - TABLE
+ - scalar
+ - aggregate
+ - table
deterministic:
type: boolean
description: Whether the function is deterministic
@@ -414,6 +414,7 @@ components:
required:
- language
- runtime
+ - handler
properties:
language:
type: string
@@ -427,11 +428,11 @@ components:
- TRINO
handler:
type: string
- description: The Python handler function
- nullable: true
+ description: The Python handler entrypoint. Cannot be null or blank.
+ pattern: '\S'
codeBlock:
type: string
- description: The Python code block
+ description: The inline Python code block. Optional; it does not
replace the handler.
nullable: true
resources:
$ref: "#/components/schemas/FunctionResources"
@@ -530,6 +531,7 @@ components:
type: object
required:
- "@type"
+ - newComment
properties:
"@type":
type: string
@@ -537,8 +539,8 @@ components:
- "updateComment"
newComment:
type: string
- description: The new comment of the function. Can be null to clear
the comment.
- nullable: true
+ description: The new comment of the function. Cannot be null or
blank.
+ pattern: '\S'
example: {
"@type": "updateComment",
"newComment": "This is a new comment"
@@ -800,7 +802,7 @@ components:
"code": 0,
"function": {
"name": "add_one",
- "functionType": "SCALAR",
+ "functionType": "scalar",
"deterministic": true,
"comment": "A simple scalar function that adds one",
"definitions": [
@@ -832,7 +834,7 @@ components:
"code": 0,
"function": {
"name": "generate_series",
- "functionType": "TABLE",
+ "functionType": "table",
"deterministic": true,
"comment": "A table function that generates a series of integers",
"definitions": [
@@ -871,7 +873,7 @@ components:
"functions": [
{
"name": "add_one",
- "functionType": "SCALAR",
+ "functionType": "scalar",
"deterministic": true,
"comment": "A simple scalar function",
"definitions": [
diff --git a/docs/table-partitioning-distribution-sort-order-indexes.md
b/docs/table-partitioning-distribution-sort-order-indexes.md
index 6ce5b419ec..02e86940be 100644
--- a/docs/table-partitioning-distribution-sort-order-indexes.md
+++ b/docs/table-partitioning-distribution-sort-order-indexes.md
@@ -122,7 +122,7 @@ Note: If the direction value is `ascending`, the default
ordering value is `null
```json
{
"direction": "asc",
- "nullOrder": "NULLS_LAST",
+ "nullOrdering": "nulls_last",
"sortTerm": {
"type": "field",
"fieldName": ["score"]
@@ -203,7 +203,7 @@ curl -X POST -H "Accept: application/vnd.gravitino.v1+json"
\
"sortOrders": [
{
"direction": "asc",
- "nullOrder": "NULLS_LAST",
+ "nullOrdering": "nulls_last",
"sortTerm": {
"type": "field",
"fieldName": ["name"]