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.

Note 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

Concept	Description
Tag Key	A classification dimension. For example, environment.
Tag Value	An allowed value under a key. For example, prod or staging.
Tag Association	A link between one or more tag values and a catalog entity such as a policy or asset.

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

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

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

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

Important 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:

Entity Type	Description
TagEntityType.ASSET	A data asset such as a table, view, or file.
TagEntityType.POLICY	A data reliability policy.
TagEntityType.RULE	An individual rule within a policy.
TagEntityType.RULE_SET	A rule set grouping multiple rules.
TagEntityType.UDF	A user-defined function.

Common Mistakes

Mistake	How to avoid it
Creating a key without providing any values.	Always provide at least one value in the values list when calling `create_tag()`.
Attempting to add a value that already exists on the key.	Check existing values before calling `add_values()`. Adding a duplicate returns an error.
Creating a key that already exists.	Use s`earch_tag_key_values()` to check whether a key already exists before creating it.
Calling `associate_tags()` with an empty `key_value_ids` list.	Verify that the `search_tag_key_values()` result is not empty before extracting IDs.
Using an entity ID that does not exist.	Confirm the entity exists in ADOC before attempting to associate tags with it.
Skipping verification after association.	Always call `get_tags_for_entity()` after associating to confirm the tags were applied.

Last updated on

Was this page helpful?