Skip to main content

aip_sdk.save_clusters

aip_sdk.save_clusters(dataset: str, name: str, pipeline_id: str, *, df: pd.DataFrame | None = None, coordinates: pd.DataFrame | None = None, compute_result: EmbeddingComputeResult | None = None, source_run_id: str | None = None, version_id: str | None = None, client: APIClient | None = None) -> SavedAssignedDimension

Save one pipeline's cluster labels as a dataset-scoped assigned dimension.

Extracts row_id → cluster_id from embedding coordinates and calls POST /datasets/{id}/dimensions:assign with authored_by="clustering". The saved dimension resolves as assigned:<name> on every later run of the same dataset, so slice delta grouping can use group_by=assigned:<name>.

Unclustered rows are omitted from the assignment: HDBSCAN reports them as the label "noise", and a pipeline with clustering disabled as null. Both are dropped rather than saved, so they appear under missing: in join coverage rather than as a noise category.

Parameters

  • dataset str: Dataset id, or "name@vN" to pin the validation version.
  • name str: Assigned dimension name — lowercase, underscores, no dots.
  • pipeline_id str: Which pipeline's cluster labels to save.
  • df pd.DataFrame | None: Run output carrying a nested embed column. Mutually exclusive with coordinates= and compute_result=.
  • coordinates pd.DataFrame | None: Tidy coordinate frame with COORDINATE_COLUMNS.
  • compute_result EmbeddingComputeResult | None: Result of compute(); its coordinates are used.
  • source_run_id str | None: Run the labels were extracted from — stored as metadata.
  • version_id str | None: Dataset version whose row ids are validated. Defaults to the latest version. Mutually exclusive with a name@vN pin on dataset — passing both raises rather than silently choosing one.
  • client APIClient | None: Optional pre-configured API client.

Returns

Raises

  • EmbeddingsError: If no coordinate source is given, more than one is given, df carries no embed column, the coordinates frame is missing a required column, dataset is malformed, dataset and version_id= pin different versions, the pinned version does not exist, the pipeline has no cluster labels, a row carries conflicting labels, or every row is unclustered noise.
  • AipError: If no client is given and none is configured.
  • UnprocessableEntityError: If the name or assignments fail platform validation.
  • NotFoundError: If the dataset does not exist.
  • ConflictError: If concurrent saves of the same dimension cannot be serialised.

Examples:

df = run.output()
saved = aip.embeddings.save_clusters(
    dataset.id,
    "clusters_semantic",
    "umap.text_qa.unsupervised",
    df=df,
    source_run_id=run.id,
)
# Slice delta: group_by=saved.id