mchades commented on code in PR #12510:
URL: https://github.com/apache/gravitino/pull/12510#discussion_r3812117032
##########
docs/manage-tags-in-gravitino.md:
##########
@@ -243,10 +289,71 @@ raw_events.supports_tags().associate_tags(["pii"], None)
</TabItem>
</Tabs>
+### Assign and Remove Tag Values
+
+Tag values are updated as pairs of tag name and value. Adding a pair preserves
the tag's other
+values; removing a pair removes only that value. Omit `value` to represent an
assignment without a
+value. The REST operation uses the v2 media type for the request body.
+
+<Tabs groupId='language' queryString>
+<TabItem value="shell" label="REST">
+
+```shell
+curl -X POST -H "Accept: application/vnd.gravitino.v2+json" \
+ -H "Content-Type: application/vnd.gravitino.v2+json" -d '{
+ "tagsToAdd": [
+ {"name": "data_domain", "value": "finance"},
+ {"name": "data_domain", "value": "risk"},
+ {"name": "pii"}
+ ],
+ "tagsToRemove": [
+ {"name": "data_domain", "value": "old"}
+ ]
+}'
http://localhost:8090/api/metalakes/test/objects/table/catalog1.schema1.customers/tags
+```
+
+</TabItem>
+<TabItem value="java" label="Java">
+
+```java
+Table customers = ...
+customers.supportsTags().associateTags(
+ new TagValue[] {
+ TagValue.of("data_domain", "finance"),
+ TagValue.of("data_domain", "risk"),
+ TagValue.noValue("pii")
+ },
+ new TagValue[] {TagValue.of("data_domain", "old")});
+```
+
+</TabItem>
+<TabItem value="python" label="Python">
+
+```python
+customers = ...
+customers.supports_tags().assign_tags(
+ tags_to_add=[
+ {"name": "data_domain", "value": "finance"},
+ {"name": "data_domain", "value": "risk"},
+ {"name": "pii"},
+ ],
+ tags_to_remove=[{"name": "data_domain", "value": "old"}])
+```
+
+</TabItem>
+</Tabs>
+
+The same pair can be added or removed repeatedly without changing the result.
A request cannot add
+the same tag both with and without values, or include the same pair in both
lists. To convert a
+valued assignment to a valueless one, remove every active value and add the
valueless pair in the
+same request. Removing the last value without adding a valueless pair detaches
the tag.
+
### List Tags on an Object
The response includes tags inherited from ancestors. With `details=true` each
tag carries an
-`inherited` field, which a plain name listing does not.
+`inherited` field and its `assignmentValues`, which a plain name listing does
not. An empty
+`assignmentValues` array means the tag is assigned without a value.
`allowedValues` is null for an
+unrestricted tag, empty for a valueless-only tag, and otherwise contains the
tag's allowed values.
Review Comment:
[Suggestion] The text explanation for `assignmentValues` and `allowedValues`
is very clear. To make the REST response shape even more intuitive for users,
it might be helpful to add a brief REST response JSON snippet showing what the
returned `TagDTO` with `assignmentValues` looks like, e.g.:
```json
{
"tags": [
{
"name": "data_domain",
"comment": "Business data domain",
"properties": {},
"allowedValues": ["finance", "risk", "ml"],
"assignmentValues": ["finance", "risk"],
"inherited": false
}
]
}
```
##########
docs/manage-tags-in-gravitino.md:
##########
@@ -263,6 +370,7 @@ curl -X GET -H "Accept: application/vnd.gravitino.v1+json" \
Table customers = ...
String[] tagNames = customers.supportsTags().listTags();
Tag[] tags = customers.supportsTags().listTagsInfo();
+String[] values = tags[0].assignment().get().values();
Review Comment:
[Nit] `tags[0].assignment()` returns `Optional<TagAssignment>`. Although
`assignment()` will be present when tags are queried in an object context,
calling `.get()` directly could throw `NoSuchElementException` in non-object
contexts.
Consider adding a quick note or demonstrating safe unwrapping for cleaner
code example, e.g.:
```java
String[] values = tags[0].assignment()
.map(TagAssignment::values)
.orElse(new String[0]);
```
--
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]
