BlockModelAPIClient

GitHub source

BlockModelAPIClient

evo.blockmodels.client.BlockModelAPIClient

__init__

__init__(environment: Environment, connector: APIConnector, cache: ICache | None = None) -> 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

from_context classmethod

from_context(context: IContext) -> 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

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[Version]

List versions of a block model.

Returns a list of Versions 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.

Parameters:

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

Returns:

Type	Description
list[Version]	A list of Version 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[Version]

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.

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[Version]	A list of Version dataclasses for the block model, ordered newest to oldest.

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,
    comment: str | None = None,
) -> 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
comment	str | None	An optional comment describing the initial data.	None

Returns:

Type	Description
tuple[BlockModel, Version]	A tuple containing the created block model and the version of the block model.

add_new_subblocked_columns async

add_new_subblocked_columns(bm_id: UUID, data: Table, units: dict[str, str] | None = None) -> 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.	required
units	dict[str, str] | None	A dictionary mapping column names within data to units.	None

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) -> 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.	required
units	dict[str, str] | None	A dictionary mapping column names within data to units.	None

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,
) -> 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 new columns to add.	required
new_columns	list[str]	A list of new column names to add to the block model.	required
update_columns	set[str] | None	A set of column names to update in the block model.	None
delete_columns	set[str] | None	A set of column names to delete from the block model.	None
units	dict[str, str] | None	A dictionary mapping column names within data to units.	None

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,
) -> 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 new columns to add.	required
new_columns	list[str]	A list of new column names to add to the block model.	required
update_columns	set[str] | None	A set of column names to update in the block model.	None
delete_columns	set[str] | None	A set of column names to delete from the block model.	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

update_column_metadata async

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

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

This method updates column properties 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_updates	dict[str, str | None]	A dictionary mapping column titles to their new unit IDs. Set the unit ID to None to remove the unit. Example: {"Cu": "%[mass]", "Au": None}	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.

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

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

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
) -> DeltaResponseData | 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
DeltaResponseData | EmptyResponse	A DeltaResponseData describing any detected changes, or an EmptyResponse (HTTP 304) when no changes are found.

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.