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.

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

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:

• Create a tag key.
• Add values to the key.
• Search for the key to retrieve value IDs.
• 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 [INLINE_CODE]CreateTagType.USER[/INLINE_CODE] for a user-defined tag or [INLINE_CODE]CreateTagType.GOVERNED[/INLINE_CODE] for a governed tag.

from acceldata.client.adoc_client import AdocClientfrom acceldata.models.api.tags.create_tag_request import CreateTagRequestfrom acceldata.models.sdk.tags.create_tag_type import CreateTagTypeclient = 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())

At least one value must be provided when creating a tag key. You cannot create a key without an initial value.

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

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 [INLINE_CODE]key_value_id[/INLINE_CODE] field on each result is required for the association step.

from acceldata.models.sdk.tags.search_key_values_request import SearchKeyValuesRequestsearch = 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 [INLINE_CODE]entity_type[/INLINE_CODE] 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 AssociateTagsRequestfrom acceldata.models.sdk.tags import TagEntityTypekey_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 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 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