tengqm commented on code in PR #6921:
URL: https://github.com/apache/gravitino/pull/6921#discussion_r2042076383
##########
docs/manage-model-metadata-using-gravitino.md:
##########
@@ -302,6 +302,110 @@ model: Model =
catalog.as_model_catalog().get_model(ident=NameIdentifier.of("mod
</TabItem>
</Tabs>
+### alter a model
+
+You can modify a model's metadata (e.g., rename, update comment, or modify
properties) by sending a `PUT` request to the
`/api/metalakes/{metalake_name}/catalogs/{catalog_name}/schemas/{schema_name}/models/{model_name}`
endpoint or using the Gravitino Java/Python client. The following is an
example of modifying a model:
+
+<Tabs groupId="language" queryString>
+ <TabItem value="shell" label="Shell">
+
+```shell
+ curl -X PUT -H "Accept: application/vnd.gravitino.v1+json" \
+ -H "Content-Type: application/json" -d '{
+ "updates": [
+ {
+ "@type": "updateComment",
+ "newComment": "Updated model comment"
+ },
+ {
+ "@type": "rename",
+ "newName": "example_model_renamed"
+ },
+ {
+ "@type": "setProperty",
+ "property": "k2",
+ "value": "v2"
+ },
+ {
+ "@type": "removeProperty",
+ "property": "k1"
+ }
+ ]
+ }'
http://localhost:8090/api/metalakes/example/catalogs/model_catalog/schemas/model_schema/models/example_model
+ ```
Review Comment:
This is a common pitfall in most of the previous docs -- the `curl` command
simply doesn't work because of the JSON data spreads to several lines.
Concatenating the whole JSON body to a huge string really hurts readability,
while adding `\` to each and every line is also not elegant.
In the docs rework effort, I had made the following revisions to all `curl`
commands:
- split the huge command into two: one for creating the JSON, the other for
using the JSON (if any).
- split the `curl` line to several lines for readability without breaking
its syntax
- use `-H "Content-Type: application/json"` only when necessary, i.e. for
POST, PUT or PATCH commands. For GET, DELETE verbs, we don't need to provide
"Content-Type"
- always use "mymetalake", "mycatalog", "myschema" as names for entities,
`metalake` sounds like a standard component of the endpoint, while
`model_catalog` is unnecessarily complex and it has to be changed for other
catalog types.
In summary, the following style is suggested for your consideration:
````suggestion
```shell
cat <<EOF >model.json
{
"updates": [
{
"@type": "updateComment",
"newComment": "Updated model comment"
},
{
"@type": "rename",
"newName": "new_name"
},
{
"@type": "setProperty",
"property": "k2",
"value": "v2"
},
{
"@type": "removeProperty",
"property": "k1"
}
]
}
EOF
curl -X PUT \
-H "Accept: application/vnd.gravitino.v1+json" \
-H "Content-Type: application/json" \
-d '@model.json' \
http://localhost:8090/api/metalakes/mymetalake/catalogs/mycatalog/schemas/myschema/models/mymodel
```
````
--
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]
