Unified Tags

This page describes how to create, manage, and assign tags to catalog entities in Acceldata Data Observability Cloud (ADOC) by using acceldata-sdk-python. Unified Tags replace the previous separate tags and labels model with a single, consistent key-value tagging system.

Tags are organized as key-value pairs. A tag key defines the classification dimension — for example, environment — and each key can have one or more values, such as prod or staging. You then associate one or more values with an entity such as a policy, asset, or rule.

This page covers SDK-level tag operations using acceldata-sdk-python. For UI-based tag management — including the tag library, Data Labelers, and Data Protection — see Tags.

Concepts

Prerequisites

• acceldata-sdk-python installed and configured. See acceldata-sdk-python Overview.
• A valid ADOC URL, access key, and secret key.

Workflow overview

To tag a catalog entity, complete the following steps:

1. Create a tag key.
2. Add values to the key.
3. Search for the key to retrieve value IDs.
4. Associate the value IDs with an entity.

The following sections describe each step with code examples.

Step 1: Create a tag key

Use client.create_tag() to create a new tag key and define its first value. The tag type can be CreateTagType.USER for a user-defined tag or CreateTagType.GOVERNED for a governed tag.

from acceldata.client.adoc_client import AdocClient
from acceldata.models.api.tags.create_tag_request import CreateTagRequest
from acceldata.models.sdk.tags.create_tag_type import CreateTagType
client = AdocClient(
    url="https://<your-adoc-url>",
    access_key="<your-access-key>",
    secret_key="<your-secret-key>",
)
tag = client.create_tag(
    CreateTagRequest(
        key="environment",
        values=["prod"],
        type=CreateTagType.USER,
    )
)
print(tag.to_dict())

You must provide at least one value when you create a tag key.

Step 2: Add values to a tag key

Call add_values() on the tag object returned in Step 1 to add more values to the key:

tag.add_values(["staging", "dev"])

You can also add values by key ID using add_values_to_tag_key(...) if you don't have a reference to the original tag object:

client.add_values_to_tag_key(key_id=tag.id, values=["staging", "dev"])

Values must be unique within a key. Adding a value that already exists on the key returns an error.

Step 3: Search for tag keys and values

Before associating tags with an entity, use search_tag_key_values() to retrieve the key-value IDs you need. The key_value_id field on each result is required for the association step.

from acceldata.models.sdk.tags.search_key_values_request import SearchKeyValuesRequest
search = client.search_tag_key_values(
    SearchKeyValuesRequest(name="environment", page=0, size=20)
)

Step 4: Associate tags with an entity

Use client.associate_tags() to link one or more tag values to a catalog entity. The entity_type parameter specifies the type of entity being tagged. For the full list, see Supported entity types.

from acceldata.models.api.catalog.associate_tags_request import AssociateTagsRequest
from acceldata.models.sdk.tags import TagEntityType
key_value_ids = [item.key_value_id for item in (search.results or []) if item.key_value_id]
client.associate_tags(
    AssociateTagsRequest(
        entity_id=89,
        entity_type=TagEntityType.POLICY,
        key_value_ids=key_value_ids,
    )
)

The key_value_ids list must not be empty. Calling with an empty list will not associate any tags and may return an error.

Verify tag associations

Use get_tags_for_entity() to retrieve all tags currently associated with an entity and confirm that the association was applied:

entity_tags = client.get_tags_for_entity(89, TagEntityType.POLICY)
print([t.to_dict() for t in entity_tags])

Supported entity types

The TagEntityType enum defines the catalog entity types that support tag associations:

Common mistakes