Assigned dimensions

An assigned dimension maps each row's stable identifier to a category label. Use it to retain saved clusters or manually curated categories for later run analysis without changing the golden data.

Scope and authorship

Prefix	Scope	Created from
declared:	Dataset configuration, snapshotted on version promotion	Declared dimensions
derived:	Dataset version	Analysis computed for that version
assigned:	Dataset	Saved clustering or user-authored categories

For assigned dimensions, authored_by records how the categories were created, not who created them. Saved cluster labels use "clustering"; user-authored categories, including lasso selections, use "user".

Both types use identifiers in the form assigned:<name>. When provided, source_op identifies the operation and source_run_id identifies the run that produced the categories. The same name in another namespace refers to a different dimension.

Save a category mapping

Use each row's stable identifier as the mapping key: input_id for text datasets or image_id for image datasets. Do not use row positions, because positions can change when rows are added, removed or reordered.

Before you begin, configure authentication and identify the dataset version whose row IDs you want to validate. Saving a dimension requires workspace_admin or workspace_editor access. This example calls a live AIP deployment and assumes prompt-001 exists in the selected version:

import aip_sdk as aip

aip.init()
saved = aip.save_dimension(
    "DATASET_ID",
    "review_groups",
    {"prompt-001": "needs_review"},
    version_id="VERSION_ID",
)
print(saved.id, saved.authored_by)
print(saved.assigned_rows, saved.total_rows, saved.unassigned_rows)

The returned coverage counts show how many rows in the validation version received a category. Specify version_id to validate against a particular version; otherwise, AIP uses the latest version.

Dimension names must start with a lowercase letter and can contain up to 64 lowercase letters, digits or underscores. Every row ID and category label must be a non-empty string. A mapping can contain up to 100 categories and 100,000 rows. AIP rejects invalid names, assignments and row IDs that do not exist in the validation version.

To save cluster labels instead, use run.embeddings.save_clusters(...) as described in Embeddings and clustering.

Saving an existing dimension name replaces all of its assignments; it does not append or merge rows. If concurrent saves raise ConflictError, wait for the competing save to finish, confirm which complete mapping should remain, and retry.

AIP stores assigned dimensions separately from the golden dataset. Saving one does not create a dataset version or change golden rows, declared-dimension snapshots or quality verdicts.

Check coverage across versions

Assigned dimensions apply across versions of the same dataset. If a later version contains the same stable row ID, that row keeps its assigned category. New row IDs remain unassigned, and rows removed from the dataset do not count towards the later version's coverage. Keep row identity semantics stable to avoid reusing a category for an unrelated row.

When you save a dimension, assigned_rows, total_rows and unassigned_rows describe coverage for the version used to validate the save. When you group a later evaluation by that dimension, AIP joins assignments to rows by their stable IDs. Rows without an assignment appear in the missing: group, which the interface displays as Unknown.

Cluster saves omit noise and null cluster labels, so an assigned dimension can have partial coverage even for the version that produced it. AIP does not automatically assign categories to new rows or rerun clustering for later versions.

Use the qualified dimension ID to group a completed evaluation of the same dataset:

# Live-only: run is a completed evaluation of this dataset.
analysis = run.analysis(group_by="assigned:review_groups")