Versions
Endpoints that retrieve information about versions of a block model
Start a block model data query
Block Model API
Starts a query job against the block model identified by bm_id. This will produce a file that
contains block model data for selected columns, and within the bounding box if provided.
This request will respond with a reflection of the query criteria, as well as a pollable job_url. The job_url should
be polled with a GET request to wait for the job_status field of the job to become either FAILED or COMPLETE. When
the job_status becomes COMPLETE, the response will look like this:
{
"job_status": "COMPLETE",
"payload": {
"download_url": "<download url>"
}
}
The download_url points to the output file of the query job, and can be downloaded using either a GET request
or using the Azure SDK. The download URL that is generated every time the completed job_url is
polled has a 30 minute time-to-live (TTL), so the download process must be started within 30 minutes. The download
itself can take longer than 30 minutes, as long as the connection remains open.
The downloaded file will either be an Apache Parquet file or a CSV file, depending on the value specified in the
file_format field under output_options. The columns included within the file depend on the type of sub-blocking and
the values specified in the geometry_columns and columns fields. The geometry_columns field determines whether
the blocks within the output file are primarily identified by their coordinates or by their block indices.
If geometry_columns is set to "indices" (the default), then the first columns in the output file will be i, j, k followed by the sub-block index columns (if applicable).
If geometry_columns is set to "coordinates", then the output file will contain the columns x, y, z for regular block models and x, y, z, dx, dy, dz for sub-blocked block models. These columns are referred to as the "geometry" columns.
The remaining columns within the output file are determined by the columns field. The columns field supports
selecting columns by either their title or ID, and can also include a wildcard ("*") placeholder, which will expand to
all user columns, ordered alphabetically by title, in a case-insensitive manner. Please note that the wildcard does not
cover the system column version_id and sub_block_derivation. To include version_id and sub_block_derivation in the output file, they
must also be explicitly specified in the columns field alongside the wildcard. The order of columns in the output file
will match the order in the columns field. Columns that are part of the initial "geometry" columns will be ignored if specified.
The sub_block_derivation column indicates the source of the block values with one of the following statuses:
"user specified": Column values come directly from uploaded file, or the block has no data available."derived from parent": Column values were calculated entirely by the system based on parent block values, with no corresponding data in the original uploaded file."some columns derived": Column values are a mix of original data and system-calculated values.
Examples:
Given a model has the following user columns: A(with a column ID of d718abe4-56a5-4e27-ad51-813e69eb8aac), B, and
C. The table below shows the output file columns for different model types and parameters:
| Model Type | geometry_columns field | columns field | Output File Columns |
|---|---|---|---|
| Regular | "indices" | ["d718abe4-56a5-4e27-ad51-813e69eb8aac", "B"] | i, j, k, A, B |
| Regular | "coordinates" | [] | x, y, z |
| Fully sub-blocked | "indices" | ["*"] | i, j, k, sidx, A, B, C |
| Flexible | "coordinates" | ["*", "start_si"] | x, y, z, dx, dy, dz, A, B, C, start_si |
The column headers (header row values in CSV files and schema field names in Parquet files) will either be the name of
the columns or the column ID, depending on the value specified in the column_headers field.
Example: for a fully sub-blocked model with a columns field:
["col_1", "dx", "x", "z", "d635868c-24ae-4ebe-9358-acb433b3c8cb"] (where d635868c-24ae-4ebe-9358-acb433b3c8cb is the
column ID of col_2) and column_headers: name, the output file will contain the following columns in order:
[i, j, k, sidx, col_1, dx, x, z, col_2].
For CSV files, the delimiter that separate values in the output file can also be configured using the delimiter
field.
For Parquet files, the output file will have the following characteristics:
- Row group size of 100,000
- Compressed using Zstd
- Parquet data page version set to 1.0 and Parquet version set to 2.6
This request may be cached, so the job_url may point to an already completed job.
All workspace roles can use this endpoint.
Parameters
{
"bbox": {
"i_minmax": {
"max": 0,
"min": 0
},
"j_minmax": {
"max": 0,
"min": 0
},
"k_minmax": {
"max": 0,
"min": 0
}
},
"columns": [
"string"
],
"geometry_columns": "indices",
"output_options": {
"column_headers": "id",
"exclude_null_rows": true,
"file_format": "parquet"
},
"version_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
Returns
200
Successful Response
Endpoint
Request
curl -X POST 'https://{service_host}/blockmodel/orgs/{org_id}/workspaces/{workspace_id}/block-models/{bm_id}/blocks' \
-H 'Authorization: Bearer <ACCESS_TOKEN>'
Response
{
"bbox": {
"i_minmax": {
"max": 0,
"min": 0
},
"j_minmax": {
"max": 0,
"min": 0
},
"k_minmax": {
"max": 0,
"min": 0
}
},
"bm_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"columns": [
"string"
],
"job_url": "https://example.com",
"mapping": {
"columns": [
{
"col_id": "string",
"data_type": "Boolean",
"title": "string",
"unit_id": "string"
}
]
},
"version_id": 0,
"version_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
List version metadata for all versions of a block model
Block Model API
Gets all versions of the block model bm_id.
The list is ordered from the newest version to the oldest version.
This endpoint is paginated, therefore by default this lists, at most, the first 50 versions. To get other versions, use
the offset and limit query parameters to select the desired part of the list. An offset beyond the total number of
versions for the block model will result in an empty results list. The limit must be an integer from 1 to 100.
The response includes total, which is the total number of versions within the list.
All workspace roles can use this endpoint.
Parameters
Returns
200
Successful Response
Endpoint
Request
curl -X GET 'https://{service_host}/blockmodel/orgs/{org_id}/workspaces/{workspace_id}/block-models/{bm_id}/versions' \
-H 'Authorization: Bearer <ACCESS_TOKEN>'
Response
{
"count": 0,
"limit": 0,
"offset": 0,
"referenced_units": [
{
"conversion_factor": 0,
"description": "string",
"symbol": "string",
"unit_id": "string",
"unit_type": "LENGTH"
}
],
"results": [
{
"base_version_id": 0,
"bbox": {
"i_minmax": {
"max": 0,
"min": 0
},
"j_minmax": {
"max": 0,
"min": 0
},
"k_minmax": {
"max": 0,
"min": 0
}
},
"bm_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"comment": "string",
"created_at": "2024-07-29T15:51:28.071Z",
"created_by": {
"email": "string",
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "string"
},
"geoscience_version_id": "string",
"mapping": {
"columns": [
{
"col_id": "string",
"data_type": "Boolean",
"title": "string",
"unit_id": "string"
}
]
},
"parent_version_id": 0,
"version_id": 0,
"version_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
],
"total": 0
}
Request version metadata for a specific block model version
Block Model API
Gets the version of the block model bm_id identified by the version_id UUID.
If the include_changes query parameter is set to true, then the response will include the changes made in the update.
Returned object will be of type VersionWithChanges, this object extends the Version object to include the field changes.
The changes field contains the VersionChanges object.
The fields of the VersionChanges object are as follows:
- blocks_uploaded: The number of blocks (rows) present in the update file if one was used for the update, null otherwise.
- total_blocks: The total number of blocks in the block model. Will remain static for regular models, will change for sub-blocked models when the sub-block count changes due to geometry change updates.
- update_type: Whether the update that created the Version was of type
mergeorreplace; field contains null if the update did not update any blocks. - columns:
- columns->new: List of columns (specified by title) created in the update that created the Version. Empty if the update did not create any columns.
- columns->deleted: List of columns (specified by title) deleted in the update that created the Version. Empty if the update did not delete any columns.
- columns->updated: List of columns (specified by title) updated in the update that created the Version. Empty if the update did not update any columns.
- columns->renamed: List of the
ColumnRenameobject, denoting which columns were renamed in the update the created the version. Empty if the update did not rename any columns.ColumnRenamecontains the fields: (old_title,new_title). - columns->metadata_updated: List of the
UpdateMetadataLiteobject, containing column metadata changes if they were made in the update. This includes thetitleof the column, the new title, and updated unit ID, respective of what was modified in the update. Empty if the update did not update any column metadata.
All workspace roles can use this endpoint.
Parameters
Returns
200
Successful Response
Endpoint
Request
curl -X GET 'https://{service_host}/blockmodel/orgs/{org_id}/workspaces/{workspace_id}/block-models/{bm_id}/versions/{version_id}' \
-H 'Authorization: Bearer <ACCESS_TOKEN>'
Response
{
"base_version_id": 0,
"bbox": {
"i_minmax": {
"max": 0,
"min": 0
},
"j_minmax": {
"max": 0,
"min": 0
},
"k_minmax": {
"max": 0,
"min": 0
}
},
"bm_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"comment": "string",
"created_at": "2024-07-29T15:51:28.071Z",
"created_by": {
"email": "string",
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "string"
},
"geoscience_version_id": "string",
"mapping": {
"columns": [
{
"col_id": "string",
"data_type": "Boolean",
"title": "string",
"unit_id": "string"
}
]
},
"parent_version_id": 0,
"version_id": 0,
"version_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
Check for deltas
Block Model API
Checks if there have been any changes to the block model within a given bounding box, between two specified versions.
Changes are searched for within a range of versions. The first version searched for changes is the version
after version_id. The last version that is searched is the version that is specified by end_version_id (inclusive),
or if end_version_id isn't specified, the latest version of the block model.
This request only checks for updates or deletions for specified columns. The columns are specified as list of column_id
UUIDs or a wildcard ("*"), for all columns that exist within the version_id version (the starting version). Using
column titles is not supported on this endpoint.
For this endpoint, changes that are considered are:
- Addition of any new columns, regardless of the columns specified in this request
- Deletions of any of the columns specified
- Updates to any of the columns specified, within the given bounding box. When block models are updated, a bounding box that encloses all updated blocks is computed. Only updates that have a bounding box that intersects with the specified bounding box are included.
Column renames aren't considered as part of this and they do not count as a change.
If no changes are found, then the response will have a status code of 304, with no content in the response.
If there are changes found, then the verbose flag inside the request body changes the response.
If verbose is false, then the response body will be empty.
If verbose is true, then the response body will contain information about the difference in versions.
For clarity, if no changes are found, then the verbose flag does nothing, as in that case the system will always return
a 304 with no content.
All workspace roles can use this endpoint.
Parameters
{
"bbox": {
"i_minmax": {
"max": 0,
"min": 0
},
"j_minmax": {
"max": 0,
"min": 0
},
"k_minmax": {
"max": 0,
"min": 0
}
},
"columns": [
"string"
],
"end_version_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"verbose": false
}
Returns
200
Successful Response
Endpoint
Request
curl -X POST 'https://{service_host}/blockmodel/orgs/{org_id}/workspaces/{workspace_id}/block-models/{bm_id}/versions/{version_id}/delta' \
-H 'Authorization: Bearer <ACCESS_TOKEN>'
Response
{
"delete_deltas": [
"3fa85f64-5717-4562-b3fc-2c963f66afa6"
],
"new_deltas": [
"3fa85f64-5717-4562-b3fc-2c963f66afa6"
],
"update_deltas": [
"3fa85f64-5717-4562-b3fc-2c963f66afa6"
],
"version_data": [
{
"bbox": {
"i_minmax": {
"max": 0,
"min": 0
},
"j_minmax": {
"max": 0,
"min": 0
},
"k_minmax": {
"max": 0,
"min": 0
}
},
"mapping": {
"columns": [
{
"col_id": "string",
"data_type": "Boolean",
"title": "string",
"unit_id": "string"
}
]
},
"update_columns": {
"delete": [
"string"
],
"new": [
{
"col_id": "string",
"data_type": "Boolean",
"title": "string",
"unit_id": "string"
}
],
"rename": [
{
"col_id": "string",
"new_title": "string"
}
],
"update": [
"string"
],
"update_metadata": [
{
"col_id": "string",
"values": {
"title": "string",
"unit_id": "string"
}
}
]
},
"version_id": 0,
"version_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
]
}
