Unified Tags

This page describes how to create, manage, and assign tags to catalog entities 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. One or more values are then associated with an entity such as a policy, asset, or rule.

Concept Model

Prerequisites

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

Workflow Overview

The standard workflow for tagging a catalog entity follows four 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 sections below walk through each step with working 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())

Step 2: Add Values to a Tag Key

Call add_values() on the tag object returned in Step 1 to add additional 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 do not have a reference to the original tag object:

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

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)
)

The search returns a paginated list of key-value pairs matching the name. Iterate the results to extract the IDs you need.

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. See Supported Entity Types below for the full list.

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,
)
)

Verify Tag Associations

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

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