BlockModelAPIClient

evo.blockmodels.client.BlockModelAPIClient

init

__init__(environment: Environment, connector: APIConnector, cache: ICache | None = None, preview: bool = False) -> None

Constructor for the Block Model Service client.

Some methods need a cache to store temporary files. If you want to use these methods, you must provide a cache.

Parameters:

Name	Type	Description	Default
`environment`	`Environment`	The environment object.	required
`connector`	`APIConnector`	The connector object.	required
`cache`	`ICache \| None`	The cache to use for storing temporary files.	`None`
`preview`	`bool`	Whether to use preview mode and include the `API-Preview: opt-in` header.	`False`

from_context `classmethod`

from_context(context: IContext, preview: bool = False) -> BlockModelAPIClient

Create a BlockModelAPIClient from the given context.

The context must have a hub_url, org_id, and workspace_id set.

Parameters:

Name	Type	Description	Default
`context`	`IContext`	The context to create the client from.	required
`preview`	`bool`	Whether to use preview mode and include the `API-Preview: opt-in` header.	`False`

Returns:

Type	Description
`BlockModelAPIClient`	A BlockModelAPIClient instance.

get_service_health `async`

get_service_health(check_type: HealthCheckType = HealthCheckType.FULL) -> ServiceHealth

Get the health of the service.

Parameters:

Name	Type	Description	Default
`check_type`	`HealthCheckType`	The type of health check to perform.	`FULL`

Returns:

Type	Description
`ServiceHealth`	A ServiceHealth object.

Raises:

Type	Description
`EvoAPIException`	If the API returns an unexpected status code.
`ClientValueError`	If the response is not a valid service health check response.

upload_block_model `async`

upload_block_model(bm_id: UUID, job_uuid: UUID, upload_url: str, filename: PathLike) -> Version

Upload a local file to a block model, notify completion, and poll until the job finishes.

Uploads the file at the given path to the provided upload URL, notifies the block model service that the upload is complete, and then polls the job until it finishes processing.

Parameters:

Name	Type	Description	Default
`bm_id`	`UUID`	The ID of the block model to upload data to.	required
`job_uuid`	`UUID`	The UUID of the upload job.	required
`upload_url`	`str`	The pre-signed URL to upload the file to.	required
`filename`	`PathLike`	The path to the local file to upload.	required

Returns:

Type	Description
`Version`	The new version of the block model created from the uploaded data.

Raises:

Type	Description
`JobFailedException`	If the upload processing job fails.

list_block_models `async`

list_block_models() -> list[BlockModel]

List block models in the current workspace.

Returns a list of BlockModels for the workspace referenced by the client's Environment. Limited to the first 100 results.

get_block_model `async`

get_block_model(bm_id: UUID) -> BlockModel

Get a block model by ID.

Parameters:

Name	Type	Description	Default
`bm_id`	`UUID`	The ID of the block model to retrieve.	required

Returns:

Type	Description
`BlockModel`	The BlockModel metadata.

list_all_block_models `async`

list_all_block_models(page_limit: int | None = 100, deleted: bool | None = None) -> list[BlockModel]

Return all block models for the current workspace, following paginated responses.

This method will page through the list_block_models endpoint using offset and limit until all entries are retrieved. The page_limit is clamped to the service maximum (100).

Parameters:

Name	Type	Description	Default
`page_limit`	`int \| None`	Maximum items to request per page (1..100). Defaults to 100.	`100`
`deleted`	`bool \| None`	(optional) An optional boolean parameter specifying whether to list only deleted block models.	`None`

Returns:

Type	Description
`list[BlockModel]`	A list of `BlockModel` dataclasses for the workspace.

list_versions `async`

list_versions(bm_id: UUID) -> list[ListingVersion]

List versions of a block model.

Returns a list of ListingVersions for the block model referenced by bm_id, limited to the first 100 results (or the service maximum).

Versions are ordered from newest to oldest.

Listing columns never carry tags; fetch a version individually to read tags.

Parameters:

Name	Type	Description	Default
`bm_id`	`UUID`	The ID of the block model.	required

Returns:

Type	Description
`list[ListingVersion]`	A list of `ListingVersion` dataclasses for the block model, ordered newest to oldest.

list_all_versions `async`

list_all_versions(bm_id: UUID, page_limit: int | None = 100) -> list[ListingVersion]

Return all versions of a block model, following paginated responses.

This method will page through the list_block_model_versions endpoint using offset and limit until all entries are retrieved. The page_limit is clamped to the service maximum (100).

Versions are ordered from newest to oldest.

Listing columns never carry tags; fetch a version individually to read tags.

Parameters:

Name	Type	Description	Default
`bm_id`	`UUID`	The ID of the block model.	required
`page_limit`	`int \| None`	Maximum items to request per page (1..100). Defaults to 100.	`100`

Returns:

Type	Description
`list[ListingVersion]`	A list of `ListingVersion` dataclasses for the block model, ordered newest to oldest.

get_version `async`

get_version(bm_id: UUID, version_uuid: UUID) -> Version

Get a single version of a block model, including each column's tags.

Unlike :meth:list_versions, which returns ListingVersions whose columns never carry tags, this retrieves a single version whose columns carry their tags.

Parameters:

Name	Type	Description	Default
`bm_id`	`UUID`	The ID of the block model.	required
`version_uuid`	`UUID`	The UUID of the version to retrieve.	required

Returns:

Type	Description
`Version`	The `Version`, with columns carrying their `tags`.

create_block_model `async`

create_block_model(
    name: str,
    grid_definition: BaseGridDefinition,
    description: str | None = None,
    object_path: str | None = None,
    coordinate_reference_system: str | None = None,
    size_unit_id: str | None = None,
    initial_data: Table | None = None,
    units: dict[str, str] | None = None,
    tags: dict[str, dict[str, Any]] | None = None,
    comment: str | None = None,
    fill_subblocks: bool = False,
) -> tuple[BlockModel, Version]

Create a block model.

Optionally, takes initial data to populate the block model with. Units for the columns within the initial data can be provided in the units dictionary. This requires the pyarrow package to be installed, and the 'cache' parameter to be set in the constructor.

If initial_data is provided, this method will wait for the initial data to be successfully uploaded and processed before returning. This then returns both the block model and the version created from the initial data update.

Otherwise, if initial_data is not provided, this waits for the block model creation job to complete before returning. This then returns both the block model and the initial block model version.

Parameters:

Name	Type	Description	Default
`name`	`str`	Name of the block model. This may not contain `/` nor `\`.	required
`grid_definition`	`BaseGridDefinition`	Definition of the block model grid.	required
`description`	`str \| None`	Description of the block model.	`None`
`object_path`	`str \| None`	Path of the folder in Geoscience Object Service to create the reference object in.	`None`
`coordinate_reference_system`	`str \| None`	Coordinate reference system used in the block model.	`None`
`size_unit_id`	`str \| None`	Unit ID denoting the length unit used for the block model's blocks.	`None`
`initial_data`	`Table \| None`	The initial data to populate the block model with.	`None`
`units`	`dict[str, str] \| None`	A dictionary mapping column names within `initial_data` to units.	`None`
`tags`	`dict[str, dict[str, Any]] \| None`	A dictionary mapping column names within `initial_data` to their tags object. Column tags are a preview feature; the client must be constructed with `preview=True` to use them.	`None`
`comment`	`str \| None`	An optional comment describing the initial data.	`None`
`fill_subblocks`	`bool`	Sets the default fill_subblocks behaviour for this block model. If `True`, updates to a fully sub-blocked model with `update_type`=`merge` and `geometry_change`=`True` will fill any missing sub-blocks with data from the parent block. Defaults to `False`.	`False`

Returns:

Type	Description
`tuple[BlockModel, Version]`	A tuple containing the created block model and the version of the block model. .. note:: To place columns in a group, first create the model, define the groups with :meth:`update_groups`, then add the columns with `column_groups` on :meth:`add_new_columns` / :meth:`update_block_model_columns`. Groups cannot be referenced during creation because none exist yet.

add_new_subblocked_columns `async`

add_new_subblocked_columns(
    bm_id: UUID,
    data: Table,
    units: dict[str, str] | None = None,
    tags: dict[str, dict[str, Any]] | None = None,
    column_groups: dict[str, str] | None = None,
    separator: str = _QUALIFIED_TITLE_SEPARATOR,
) -> Version

Add new columns to an existing sub-blocked block model. This will not change the sub-blocking structure, thus the provided data must match existing sub-blocks in the model.

Units for the columns can be provided in the units dictionary.

This method requires the pyarrow package to be installed, and the 'cache' parameter to be set in the constructor.

Parameters:

Name	Type	Description	Default
`bm_id`	`UUID`	The ID of the block model to add columns to.	required
`data`	`Table`	The data containing the new columns to add, keyed by each column's title (a plain title for an ungrouped column, or the qualified `group▸title` for a grouped one).	required
`units`	`dict[str, str] \| None`	A dictionary mapping column names within `data` to units.	`None`
`tags`	`dict[str, dict[str, Any]] \| None`	A dictionary mapping column names within `data` to their tags object. Column tags are a preview feature; the client must be constructed with `preview=True` to use them.	`None`
`column_groups`	`dict[str, str] \| None`	A dictionary mapping a grouped column's qualified title (its key in `data`, e.g. `"Assays▸Cu"`) to the qualified title of the group it belongs to (e.g. `"Assays"`). Ungrouped columns are keyed by their plain title in `data` and omitted here. `data` must be keyed by each column's exact title; :func:`~evo.blockmodels.data.qualify_column_titles` can build that from plain-titled data.	`None`
`separator`	`str`	The single character separating a group's qualified title from a column title in qualified column titles (e.g. `Assays▸Cu`). Defaults to `▸`. Provide this only when the block model uses a non-default separator; it is then forwarded to the service for this request.	`QUALIFIED_TITLE_SEPARATOR`

Returns:

Type	Description
`Version`	The new version of the block model with the added columns.

Raises:

Type	Description
`CacheNotConfiguredException`	If the cache is not configured.

add_new_columns `async`

add_new_columns(
    bm_id: UUID,
    data: Table,
    units: dict[str, str] | None = None,
    tags: dict[str, dict[str, Any]] | None = None,
    column_groups: dict[str, str] | None = None,
    separator: str = _QUALIFIED_TITLE_SEPARATOR,
) -> Version

Add new columns to an existing regular block model.

Units for the columns can be provided in the units dictionary.

This method requires the pyarrow package to be installed, and the 'cache' parameter to be set in the constructor.

Parameters:

Name	Type	Description	Default
`bm_id`	`UUID`	The ID of the block model to add columns to.	required
`data`	`Table`	The data containing the new columns to add, keyed by each column's title (a plain title for an ungrouped column, or the qualified `group▸title` for a grouped one).	required
`units`	`dict[str, str] \| None`	A dictionary mapping column names within `data` to units.	`None`
`tags`	`dict[str, dict[str, Any]] \| None`	A dictionary mapping column names within `data` to their tags object. Column tags are a preview feature; the client must be constructed with `preview=True` to use them.	`None`
`column_groups`	`dict[str, str] \| None`	A dictionary mapping a grouped column's qualified title (its key in `data`, e.g. `"Assays▸Cu"`) to the qualified title of the group it belongs to (e.g. `"Assays"`). Ungrouped columns are keyed by their plain title in `data` and omitted here. `data` must be keyed by each column's exact title; :func:`~evo.blockmodels.data.qualify_column_titles` can build that from plain-titled data.	`None`
`separator`	`str`	The single character separating a group's qualified title from a column title in qualified column titles (e.g. `Assays▸Cu`). Defaults to `▸`. Provide this only when the block model uses a non-default separator; it is then forwarded to the service for this request.	`QUALIFIED_TITLE_SEPARATOR`

Returns:

Type	Description
`Version`	The new version of the block model with the added columns.

Raises:

Type	Description
`CacheNotConfiguredException`	If the cache is not configured.

update_block_model_columns `async`

update_block_model_columns(
    bm_id: UUID,
    data: Table,
    new_columns: list[str],
    update_columns: set[str] | None = None,
    delete_columns: set[str] | None = None,
    units: dict[str, str] | None = None,
    tags: dict[str, dict[str, Any]] | None = None,
    update_type: UpdateType = models.UpdateType.replace,
    column_groups: dict[str, str] | None = None,
    group_missing_column_override: dict[str, MissingColumnPolicy] | None = None,
    separator: str = _QUALIFIED_TITLE_SEPARATOR,
) -> Version

Add, update, or delete regular block model columns.

Units for the columns can be provided in the units dictionary.

This method requires the pyarrow package to be installed, and the 'cache' parameter to be set in the constructor.

Parameters:

Name	Type	Description	Default
`bm_id`	`UUID`	The ID of the block model to add columns to.	required
`data`	`Table`	The data containing the affected columns, keyed by each column's title (a plain title for an ungrouped column, or the qualified `group▸title` for a grouped one). :func:`~evo.blockmodels.data.qualify_column_titles` can build these titles from plain-titled data.	required
`new_columns`	`list[str]`	A list of new columns to add, named by their title in `data` (qualified `group▸title` for a grouped column, plain otherwise).	required
`update_columns`	`set[str] \| None`	A set of existing columns to re-upload, each identified by the title the service currently stores it under: its qualified title (`group▸title`) if grouped, or its plain title if not.	`None`
`delete_columns`	`set[str] \| None`	A set of existing columns to delete, identified the same way as `update_columns` (qualified title if grouped, plain otherwise).	`None`
`units`	`dict[str, str] \| None`	A dictionary mapping column names within `data` to units.	`None`
`tags`	`dict[str, dict[str, Any]] \| None`	A dictionary mapping new column names to their tags object. Column tags are a preview feature; the client must be constructed with `preview=True` to use them.	`None`
`column_groups`	`dict[str, str] \| None`	A dictionary assigning new columns to groups: map a new column's qualified title (its key in `data`, e.g. `"Assays▸Cu"`) to the qualified title of the group it belongs to. To move or ungroup an existing column, use :meth:`update_column_metadata` instead — a group change is metadata-only and does not require re-uploading data.	`None`
`group_missing_column_override`	`dict[str, MissingColumnPolicy] \| None`	Per-request override of the resolved missing-column policy for specific groups, keyed by the group's qualified title (e.g. `"Assays▸Geochem"`). The override is local to this request only and does not affect other groups in the same zone. The service currently only supports :attr:`~evo.blockmodels.data.MissingColumnPolicy.USE_PREVIOUS`, which keeps a group's omitted columns at their previous values instead of applying the group's resolved policy (e.g. `SET_NULL`).	`None`
`separator`	`str`	The single character separating a group's qualified title from a column title in qualified column titles (e.g. `Assays▸Cu`). Defaults to `▸`. Provide this only when the block model uses a non-default separator; it is then forwarded to the service for this request.	`QUALIFIED_TITLE_SEPARATOR`

Returns:

Type	Description
`Version`	The new version of the block model with the added columns.

Raises:

Type	Description
`CacheNotConfiguredException`	If the cache is not configured.

update_subblocked_columns `async`

update_subblocked_columns(
    bm_id: UUID,
    data: Table,
    new_columns: list[str],
    update_columns: set[str] | None = None,
    delete_columns: set[str] | None = None,
    units: dict[str, str] | None = None,
    geometry_change: bool = False,
    fill_subblocks: bool | None = None,
    tags: dict[str, dict[str, Any]] | None = None,
    update_type: UpdateType = models.UpdateType.replace,
    column_groups: dict[str, str] | None = None,
    group_missing_column_override: dict[str, MissingColumnPolicy] | None = None,
    separator: str = _QUALIFIED_TITLE_SEPARATOR,
) -> Version

Add, update, or delete sub-blocked block model columns.

Whether the sub-blocking structure changes can be specified with the geometry_change parameter.

If True, the geometry of the sub-blocked model changes, but all existing sub-blocks columns must either be updated or deleted. If False, the geometry of the sub-blocked model does not change, but the provided data must match existing sub-blocks in the model.

Units for the columns can be provided in the units dictionary.

This method requires the pyarrow package to be installed, and the 'cache' parameter to be set in the constructor.

Parameters:

Name	Type	Description	Default
`bm_id`	`UUID`	The ID of the block model to add columns to.	required
`data`	`Table`	The data containing the affected columns, keyed by each column's title (a plain title for an ungrouped column, or the qualified `group▸title` for a grouped one). :func:`~evo.blockmodels.data.qualify_column_titles` can build these titles from plain-titled data.	required
`new_columns`	`list[str]`	A list of new columns to add, named by their title in `data` (qualified `group▸title` for a grouped column, plain otherwise).	required
`update_columns`	`set[str] \| None`	A set of existing columns to re-upload, each identified by the title the service currently stores it under: its qualified title (`group▸title`) if grouped, or its plain title if not.	`None`
`delete_columns`	`set[str] \| None`	A set of existing columns to delete, identified the same way as `update_columns` (qualified title if grouped, plain otherwise).	`None`
`units`	`dict[str, str] \| None`	A dictionary mapping column names within `data` to units.	`None`
`geometry_change`	`bool`	Whether the geometry of the sub-blocked model changes.	`False`
`fill_subblocks`	`bool \| None`	If `True`, any missing sub-blocks will be filled with data from the parent block. Only applicable for fully sub-blocked models when `geometry_change` is `True`. If `None` (the default), the block model's own `fill_subblocks` setting is used.	`None`
`tags`	`dict[str, dict[str, Any]] \| None`	A dictionary mapping new column names to their tags object. Column tags are a preview feature; the client must be constructed with `preview=True` to use them.	`None`
`column_groups`	`dict[str, str] \| None`	A dictionary assigning new columns to groups: map a new column's qualified title (its key in `data`, e.g. `"Assays▸Cu"`) to the qualified title of the group it belongs to. To move or ungroup an existing column, use :meth:`update_column_metadata` instead — a group change is metadata-only and does not require re-uploading data.	`None`
`group_missing_column_override`	`dict[str, MissingColumnPolicy] \| None`	Per-request override of the resolved missing-column policy for specific groups, keyed by the group's qualified title (e.g. `"Assays▸Geochem"`). The override is local to this request only and does not affect other groups in the same zone. The service currently only supports :attr:`~evo.blockmodels.data.MissingColumnPolicy.USE_PREVIOUS`, which keeps a group's omitted columns at their previous values instead of applying the group's resolved policy (e.g. `SET_NULL`).	`None`
`separator`	`str`	The single character separating a group's qualified title from a column title in qualified column titles (e.g. `Assays▸Cu`). Defaults to `▸`. Provide this only when the block model uses a non-default separator; it is then forwarded to the service for this request.	`QUALIFIED_TITLE_SEPARATOR`

update_column_metadata `async`

update_column_metadata(
    bm_id: UUID, column_updates: dict[str, str | None | ColumnMetadataUpdate], comment: str | None = None
) -> Version

Update metadata (e.g., units and tags) for existing block model columns.

This method updates column properties without requiring data upload or cache configuration.

Each entry in column_updates maps a column title to its update:

A str sets the column's unit ID.
None clears the column's unit ID.
A :class:ColumnMetadataUpdate sets any combination of unit ID, tags and/or group. Only the fields explicitly set on the object are sent; unset fields are left untouched. Set tags=\{\} to clear a column's tags, unit_id=None to clear its unit, or group="" to move the column out of any group.

A column's group is metadata, so it can be moved (or ungrouped) here without re-uploading its data. Address the column by the title the service currently stores it under: its qualified title (group▸title) if it is currently grouped, or its plain title if it is not. Set ColumnMetadataUpdate(group=...) to the target group's qualified title (or "" to ungroup).

Column tags are a preview feature; the client must be constructed with preview=True to use them.

Parameters:

Name	Type	Description	Default
`bm_id`	`UUID`	The ID of the block model to update.	required
`column_updates`	`dict[str, str \| None \| ColumnMetadataUpdate]`	A dictionary mapping column titles to their metadata update. Example: {"Cu": "%[mass]", "Au": None, "Assays▸Ag": ColumnMetadataUpdate(group="Geology")}	required
`comment`	`str \| None`	An optional comment describing the metadata changes. This is max 250 characters.	`None`

Returns:

Type	Description
`Version`	The new version of the block model with updated metadata.

update_groups `async`

update_groups(
    bm_id: UUID,
    *,
    new: list[GroupDefinition] | None = None,
    update: dict[str, GroupMetadataUpdate] | None = None,
    delete: list[str] | None = None,
    comment: str | None = None,
) -> Version

Create, update, and/or delete column groups on a block model.

This method manages group definitions without requiring data upload or cache configuration. Any combination of new, update and delete can be supplied in a single call.

Groups are addressed by their qualified title (a bare title for a top-level group, or segments joined by ▸ for a nested group). To assign a new column to a group, use the column_groups parameter on the column methods; to move or ungroup an existing column, use :meth:update_column_metadata. To resolve a written group back to its server-assigned UUID and resolved policy, use the helpers on the returned :class:~evo.blockmodels.data.Version, e.g. :meth:~evo.blockmodels.data.Version.group_by_qualified_title.

Parameters:

Name	Type	Description	Default
`bm_id`	`UUID`	The ID of the block model to update.	required
`new`	`list[GroupDefinition] \| None`	Definitions of new groups to create.	`None`
`update`	`dict[str, GroupMetadataUpdate] \| None`	A dictionary mapping the qualified title of an existing group to the metadata update to apply to it. Use :class:`GroupMetadataUpdate` to rename, re-parent, change the missing-column policy, replace tags, or toggle the hidden flag.	`None`
`delete`	`list[str] \| None`	Qualified titles of groups to delete.	`None`
`comment`	`str \| None`	An optional comment describing the changes. This is max 250 characters.	`None`

Returns:

Type	Description
`Version`	The new version of the block model with the updated groups.

rename_block_model_columns `async`

rename_block_model_columns(bm_id: UUID, column_renames: dict[str, str], comment: str | None = None) -> Version

Rename existing block model columns.

This method renames columns without requiring data upload or cache configuration.

Parameters:

Name	Type	Description	Default
`bm_id`	`UUID`	The ID of the block model to update.	required
`column_renames`	`dict[str, str]`	A dictionary mapping current column titles to their new titles. Example: {"Cu": "Copper", "Au": "Gold"}	required
`comment`	`str \| None`	An optional comment describing the rename operation. This is max 250 characters.	`None`

Returns:

Type	Description
`Version`	The new version of the block model with renamed columns.

delete_block_model_columns `async`

delete_block_model_columns(bm_id: UUID, column_titles: list[str], comment: str | None = None) -> Version

Delete existing columns from a block model.

This method deletes columns without requiring data upload or cache configuration.

Parameters:

Name	Type	Description	Default
`bm_id`	`UUID`	The ID of the block model to update.	required
`column_titles`	`list[str]`	The titles of the columns to delete.	required
`comment`	`str \| None`	An optional comment describing the rename operation. This is max 250 characters.	`None`

Returns:

Type	Description
`Version`	The new version of the block model with renamed columns.

query_block_model_to_cache `async`

query_block_model_to_cache(
    bm_id: UUID,
    columns: list[str | UUID],
    bbox: BBox | BBoxXYZ | None = None,
    version_uuid: UUID | None = None,
    geometry_columns: GeometryColumns = GeometryColumns.coordinates,
    column_headers: ColumnHeaderType = ColumnHeaderType.id,
    exclude_null_rows: bool = True,
    separator: str = _QUALIFIED_TITLE_SEPARATOR,
) -> Path

Query a block model and download the result as a Parquet file to the cache.

This requires the 'cache' parameter to be set in the constructor.

Parameters:

Name	Type	Description	Default
`bm_id`	`UUID`	The ID of the block model to query.	required
`columns`	`list[str \| UUID]`	The columns to query, can either be the title or the ID of the column.	required
`bbox`	`BBox \| BBoxXYZ \| None`	The bounding box to query, if None (the default) the entire block model is queried.	`None`
`version_uuid`	`UUID \| None`	The version UUID to query, if None (the default) the latest version is queried.	`None`
`geometry_columns`	`GeometryColumns`	Whether rows in the returned table should include coordinates, or block indices of the block, that the row belongs to.	`coordinates`
`column_headers`	`ColumnHeaderType`	Whether the names of the columns in the returned column should be the title or the ID of the block model column.	`id`
`exclude_null_rows`	`bool`	Whether to exclude rows where all values are null within the queried columns.	`True`
`separator`	`str`	The single character separating a group's qualified title from a column title in qualified column titles (e.g. `Assays▸Cu`). Defaults to `▸`. Provide this only when the block model uses a non-default separator; it is then used to parse any qualified titles in `columns` and to render returned qualified headers, and is forwarded to the service for this request. It must match the separator the model was written with, otherwise the query is rejected.	`QUALIFIED_TITLE_SEPARATOR`

Returns:

Type	Description
`Path`	The file path of the downloaded Parquet file in the cache.

Raises:

Type	Description
`CacheNotConfiguredException`	If the cache is not configured.
`JobFailedException`	If the job failed.

query_block_model_as_table `async`

query_block_model_as_table(
    bm_id: UUID,
    columns: list[str | UUID],
    bbox: BBox | BBoxXYZ | None = None,
    version_uuid: UUID | None = None,
    geometry_columns: GeometryColumns = GeometryColumns.coordinates,
    column_headers: ColumnHeaderType = ColumnHeaderType.id,
    exclude_null_rows: bool = True,
    separator: str = _QUALIFIED_TITLE_SEPARATOR,
) -> Table

Query a block model and return the result as a PyArrow Table.

This requires the pyarrow package to be installed, and the 'cache' parameter to be set in the constructor.

Parameters:

Name	Type	Description	Default
`bm_id`	`UUID`	The ID of the block model to query.	required
`columns`	`list[str \| UUID]`	The columns to query, can either be the title or the ID of the column.	required
`bbox`	`BBox \| BBoxXYZ \| None`	The bounding box to query, if None (the default) the entire block model is queried.	`None`
`version_uuid`	`UUID \| None`	The version UUID to query, if None (the default) the latest version is queried.	`None`
`geometry_columns`	`GeometryColumns`	Whether rows in the returned table should include coordinates, or block indices of the block, that the row belongs to.	`coordinates`
`column_headers`	`ColumnHeaderType`	Whether the names of the columns in the returned column should be the title or the ID of the block model column.	`id`
`exclude_null_rows`	`bool`	Whether to exclude rows where all values are null within the queried columns.	`True`
`separator`	`str`	The single character separating a group's qualified title from a column title in qualified column titles (e.g. `Assays▸Cu`). Defaults to `▸`. Provide this only when the block model uses a non-default separator; it is then used to parse any qualified titles in `columns` and to render returned qualified headers, and is forwarded to the service for this request. It must match the separator the model was written with, otherwise the query is rejected.	`QUALIFIED_TITLE_SEPARATOR`

Returns:

Type	Description
`Table`	The result as a PyArrow Table.

Raises:

Type	Description
`CacheNotConfiguredException`	If the cache is not configured.
`JobFailedException`	If the job failed.

get_deltas_for_block_model `async`

get_deltas_for_block_model(
    version_id: UUID, bm_id: UUID, delta_request_data: DeltaRequestData
) -> ListingDeltaResponseData | EmptyResponse

Check for changes to a block model between two versions within a bounding box.

Delegates to the versions API get_deltas_for_block_model endpoint. Changes include additions, deletions, and updates to the specified columns within the provided bounding box.

Parameters:

Name	Type	Description	Default
`version_id`	`UUID`	The starting version UUID (changes are searched after this version).	required
`bm_id`	`UUID`	The ID of the block model.	required
`delta_request_data`	`DeltaRequestData`	The delta request payload specifying columns, bounding box, and options.	required

Returns:

Type	Description
`ListingDeltaResponseData \| EmptyResponse`	A `ListingDeltaResponseData` describing any detected changes, or an `EmptyResponse` (HTTP 304) when no changes are found.

update_block_model_metadata `async`

update_block_model_metadata(bm_id: UUID, update_block_model: UpdateBlockModel) -> BlockModel

Update a block model's metadata.

Updates the block model name, description, coordinate reference system, size unit ID, and/or fill sub-blocks setting for the given block model.

Parameters:

Name	Type	Description	Default
`bm_id`	`UUID`	The ID of the block model to update.	required
`update_block_model`	`UpdateBlockModel`	The update payload containing the fields to change.	required

Returns:

Type	Description
`BlockModel`	The updated BlockModel.

delete_block_model `async`

delete_block_model(bm_id: UUID) -> EmptyResponse

Delete a block model from the current workspace.

Parameters:

Name	Type	Description	Default
`bm_id`	`UUID`	The ID of the block model to delete.	required

Returns:

Type	Description
`EmptyResponse`	An empty response on success.