tengqm commented on code in PR #6921:
URL: https://github.com/apache/gravitino/pull/6921#discussion_r2042114288
##########
docs/manage-model-metadata-using-gravitino.md:
##########
@@ -302,6 +302,117 @@ 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
+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
+ ```
+
+
+ </TabItem>
+ <TabItem value="java" label="Java">
+
+ ```java
+ // Load the catalog and model
+ GravitinoClient gravitinoClient = GravitinoClient
+ .builder("http://localhost:8090";)
+ .withMetalake("example")
+ .build();
+
+ Catalog catalog = gravitinoClient.loadCatalog("model_catalog");
+ ModelCatalog modelCatalog = catalog.asModelCatalog();
+
+ // Define modifications
+ ModelChange[] changes = {
+ ModelChange.updateComment("Updated model comment"),
+ ModelChange.rename("example_model_renamed"),
+ ModelChange.setProperty("k2", "v2"),
+ ModelChange.removeProperty("k1")
+ };
+
+ // Apply changes
+ Model updatedModel = modelCatalog.alterModel(
+ NameIdentifier.of("model_schema", "example_model"),
+ changes
+ );
+ ```
+
+ </TabItem>
+<TabItem value="python" label="Python">
+
+ ```python
+ gravitino_client: GravitinoClient =
GravitinoClient(uri="http://localhost:8090";, metalake_name="example")
+
+ catalog: Catalog = gravitino_client.load_catalog(name="model_catalog")
+ model_catalog = catalog.as_model_catalog()
+
+ # Define modifications
+ changes = (
+ ModelChange.update_comment("Updated model comment"),
+ ModelChange.rename("example_model_renamed"),
+ ModelChange.set_property("k2", "v2"),
+ ModelChange.remove_property("k1")
+ )
+
+ # Apply changes
+ updated_model = model_catalog.alter_model(
+ ident=NameIdentifier.of("model_schema", "example_model"),
+ *changes
+ )
+ ```
+ </TabItem>
+ </Tabs>
+
+#### Supported modifications
+
+The following operations are supported for altering a model:
+
+
+| Operation | JSON Example
| Java Method | Python
Method |
+
|-------------------------|------------------------------------------------------------------------------|-------------------------------------------|---------------------------------------|
+| **Rename model** | `{"@type":"rename","newName":"new_name"}`
| `ModelChange.rename("new_name")` |
`ModelChange.rename("new_name")` |
+| **Update comment** |
`{"@type":"updateComment","newComment":"new_comment"}` |
`ModelChange.updateComment("new_comment")` |
`ModelChange.update_comment("new_comment")` |
+| **Set property** |
`{"@type":"setProperty","property":"key","value":"value"}` |
`ModelChange.setProperty("key", "value")` | `ModelChange.set_property("key",
"value")` |
+| **Remove property** | `{"@type":"removeProperty","property":"key"}`
| `ModelChange.removeProperty("key")` |
`ModelChange.remove_property("key")` |
Review Comment:
Markdown tables are convenient for narrow tables, such as comparison between
datatypes. They are cumbersome for wide tables.
In the docs revision effort, I have reworked all "wide" tables into HTML
tables.
In your case, please consider using a HTML table like this:
```html
<table>
<thead>
<tr>
<th>Supported modification</th>
<th>JSON</th>
<th>Java</th>
<th>Python</th>
</tr>
</thead>
<tbody>
<tr>
<td>Rename a model</td>
<td>`{"@type":"rename","newName":"new_name"}`</td>
<td>`ModelChange.rename("new_name")`</td>
<td>`ModelChange.rename("new_name")`</td>
</tr>
<tr>
<td>Update model comment</td>
<td>...</td>
<td>...</td>
<td>...</td>
</tr>
</tbody>
</table>
```
A side effect is that in the table cells, according to MDX and Docusaurus,
we can use markdown syntax. For example:
```html
<td>
```java
ModelChange.updateComment("new_comment");
```
</td>
```
For another example:
```html
<td>
The valid options are:
- `foo` (default): an option for ...
- `bar`: another option
</td>
```
I'm not encouraging us to write long paragraphs in table cells.
I'm instead showing some pretty common scenarios in our docs.
--
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]
