aip_sdk.DatasetClusters

aip_sdk.DatasetClusters(dataset_id: str, version_id: str, *, client: APIClient)

Clustering operations for one dataset version, obtained with dataset.clusters(version_id).

aip_sdk.DatasetClusters.availability

aip_sdk.DatasetClusters.availability() -> DatasetClustersAvailability

Check whether this version can start clustering.

Returns

• DatasetClustersAvailability: DatasetClustersAvailability with a reason when unavailable.

Raises

• APIError: Access is denied or the platform rejects the request.
• RunConnectionError: The platform cannot be reached.
• ResponseParseError: The response cannot be read.

aip_sdk.DatasetClusters.get_result

aip_sdk.DatasetClusters.get_result(run_id: str) -> DatasetClustersResult

Read a completed run's saved result without starting computation.

Parameters

• run_id str: Completed run whose embeddings and membership should be read.

Returns

• DatasetClustersResult: DatasetClustersResult, including points even when every row is noise.

Raises

• InvalidArgumentError: The run identifier is empty.
• APIError: The result is unavailable or the run is not complete; use wait().
• RunConnectionError: The platform cannot be reached.
• ResponseParseError: The response cannot be read.

aip_sdk.DatasetClusters.get_run

aip_sdk.DatasetClusters.get_run(run_id: str) -> DatasetClustersRun

Read a particular clustering run's status and saved parameters.

Parameters

• run_id str: Run returned by run() or latest_run().

Returns

• DatasetClustersRun: DatasetClustersRun for the requested run.

Raises

• InvalidArgumentError: The run identifier is empty.
• APIError: The run cannot be read, including a run belonging to another version.
• RunConnectionError: The platform cannot be reached.
• ResponseParseError: The response cannot be read.

aip_sdk.DatasetClusters.latest_run

aip_sdk.DatasetClusters.latest_run() -> DatasetClustersRun | None

Read the run currently followed by the dataset dashboard.

Returns

• DatasetClustersRun | None: DatasetClustersRun, or None when this version has no clustering runs.

Raises

• APIError: The platform rejects the request.
• RunConnectionError: The platform cannot be reached.
• ResponseParseError: The response cannot be read.

aip_sdk.DatasetClusters.run

aip_sdk.DatasetClusters.run(*, min_cluster_size: int | None = None) -> DatasetClustersRun

Start clustering and return promptly, or return an active run with matching settings.

A completed run is retained when another run starts. The dataset dashboard follows the latest run. Different settings while a run is active raise ConflictError; wait for that run before submitting new settings.

Parameters

• min_cluster_size int | None: Minimum rows per group, from 2 to 10,000 and no greater than the dataset row count. Omit it or pass None to preserve the project's configured minimum, or use the platform default when no project recipe applies. Pass an integer to override it. The algorithm determines the number of clusters.

Returns

• DatasetClustersRun: DatasetClustersRun identifying the queued or already active run.

Raises

• InvalidArgumentError: The minimum is not an integer within the supported range.
• APIError: The platform rejects the request, including unavailable computation, insufficient access or conflicting active settings.
• RunConnectionError: The platform cannot be reached; inspect latest_run before retrying.
• ResponseParseError: The response cannot be read; the run may have started.

aip_sdk.DatasetClusters.wait

aip_sdk.DatasetClusters.wait(run_id: str, *, timeout: float = 600, poll_interval: float = 3) -> DatasetClustersResult

Poll a specific run until it completes, then return its saved result.

Parameters

• run_id str: Run to follow, even if a newer run starts for the same version.
• timeout float: Positive finite polling budget in seconds. In-flight HTTP requests use the API client's timeouts. Expiry does not cancel the run.
• poll_interval float: Positive finite seconds between status reads.

Returns

• DatasetClustersResult: DatasetClustersResult after the run completes.

Raises

• InvalidArgumentError: An identifier or timing argument is invalid.
• DatasetClustersTimeoutError: The polling budget expires; call wait() again to resume.
• RunFailedError: Computation failed; inspect the run's error before starting again.
• APIError: The platform rejects a status or result request.
• RunConnectionError: The platform cannot be reached.
• ResponseParseError: A response cannot be read.