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"]

Reply via email to