roryqi commented on code in PR #12510:
URL: https://github.com/apache/gravitino/pull/12510#discussion_r3812338588
##########
docs/tags.md:
##########
@@ -82,6 +82,24 @@ every object carrying the tag sees the same values.
Properties suit facts about
which team owns it or which external system it came from. Properties do not
suit facts about one
tagged object.
+Assignment values describe one tag on one object. For example, the same
`data_domain` tag can have
+the value `finance` on one table and `risk` on another. An assignment can have
no value, one value,
+or several values. Adding a value is incremental, so adding `risk` to an
assignment that already has
+`finance` leaves both values in place.
+
+When you create a tag, you can choose one of three value constraints:
+
+| Constraint | Meaning |
+|------------|---------|
+| Any value | The tag accepts any non-blank string, and can also be assigned
without a value |
+| No value | The tag can only be assigned without a value |
+| Allowed values | The tag accepts only values from the configured list |
Review Comment:
Updated the separator row to the explicit `| --- | --- |` form in 5765b7593.
##########
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:
Replaced `Optional.get()` with safe `map(...).orElse(new String[0])`
unwrapping in 5765b7593.
##########
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:
Updated the Java example to safely unwrap the optional with
`map(...).orElse(new String[0])` in 5765b7593.
##########
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:
Added a REST response JSON example showing `allowedValues`,
`assignmentValues`, and `inherited` in 5765b7593.
--
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]
