Block Model API
Start a block model data query
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. To include version_id in the output file, it 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.
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.
Request
Responses
200
Successful Response
Bounding box of the search area as integer indexes or model aligned coordinates. If not provided, this is set to the entire block model.
If using integer indexes, they must be >= zero and <= the number of blocks - 1.
For example, if a block model has:
n_blocks: { nx: 10, ny: 10, nz: 10 }
then i_max, j_max, and k_max must all be >= 0 and <= 9.
If using model aligned coordinates, that is, rotated by the same scheme as the block model, centroids that are
encapsulated by the bounding box will be selected. A side effect of this behaviour is a bounding box with x, y, z
min-max can exceed the model along any axis.
Minimum and maximum values for the i column in the file
Maximum value for the column
Minimum value for the column
Minimum and maximum values for the j column in the file
Maximum value for the column
Minimum value for the column
Minimum and maximum values for the k column in the file
Maximum value for the column
Minimum value for the column
Minimum and maximum values for the x column in the file
Maximum value for the column
Minimum value for the column
Minimum and maximum values for the y column in the file
Maximum value for the column
Minimum value for the column
Minimum and maximum values for the z column in the file
Maximum value for the column
Minimum value for the column
Example: "e3c277c2-edc6-4a7a-8380-251dd19231f2"
ID of the block model
List of columns, in addition to the "geometry" columns, that will be included in the output file.
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. To include version_id in the output file, it 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.
Pollable job URL for this query
List of columns, in addition to the "geometry" columns, that will be included in the output file.
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. To include version_id in the output file, it 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.
Example: "618d6339-2fa7-4dfd-9c7f-c0b12016639e"
The ID of the column, a UUID for non-system columns
Capitalized list of supported PyArrow datatypes outlined in https://arrow.apache.org/docs/python/api/datatypes.html.
Timestamp datatype is expected to be used with unit measured in "us" and timezone set to "UTC" inside of parquet column header schema or it won't be accepted; an example for PyArrow binding would look like this: pa.timestamp("us", tz="UTC")
The human-readable label used to identify the column
The ID of the column's unit
Example: 5
Identifier for the version within a block model as a monotonically increasing integer, where 1 is
the version_id for the version created upon creation of the block model.
Example: "3e9ce8de-f6ba-4920-8c6e-0882e90f0ed7"
A universally unique identifier for the version
401
Unauthorized
Example: "Invalid authentication credentials"
A human-readable explanation specific to this occurrence of the problem.
Example: 401
The HTTP status code generated by the origin server for this occurrence of the problem.
Example: "Invalid authentication credentials"
A short, human-readable summary of the problem type.
Example: "https://seequent.com/error-codes/block-model-service/auth/unauthorized"
A URI reference that is the primary identifier of the problem type.
403
Forbidden
Example: "Permission denied"
A human-readable explanation specific to this occurrence of the problem.
Example: 403
The HTTP status code generated by the origin server for this occurrence of the problem.
Example: "Permission Denied"
A short, human-readable summary of the problem type.
Example: "https://seequent.com/error-codes/block-model-service/auth/forbidden"
A URI reference that is the primary identifier of the problem type.
404
Not Found
Example: "The requested resource is deleted."
A human-readable explanation specific to this occurrence of the problem.
Example: 404
The HTTP status code generated by the origin server for this occurrence of the problem.
Example: "Workspace not found."
A short, human-readable summary of the problem type.
Example: "https://seequent.com/error-codes/workspace/not-found"
A URI reference that is the primary identifier of the problem type.
410
Gone
Example: "The requested resource was not found."
A human-readable explanation specific to this occurrence of the problem.
Example: 410
The HTTP status code generated by the origin server for this occurrence of the problem.
Example: "Workspace soft deleted."
A short, human-readable summary of the problem type.
Example: "https://seequent.com/error-codes/workspace/gone"
A URI reference that is the primary identifier of the problem type.
422
Unprocessable Entity
Example: "Query criteria validation failed for block model 11111111-2222-3333-4444-555555555555"
A human-readable explanation specific to this occurrence of the problem.
Example: 422
The HTTP status code generated by the origin server for this occurrence of the problem.
Example: "Unprocessable Entity"
A short, human-readable summary of the problem type.
Example: "https://seequent.com/error-codes/block-model-service/unprocessable-entity"
A URI reference that is the primary identifier of the problem type.
500
Internal Server Error
Example: "An error occurred"
A human-readable explanation specific to this occurrence of the problem.
Example: 500
The HTTP status code generated by the origin server for this occurrence of the problem.
Example: "Service Error"
A short, human-readable summary of the problem type.
Example: "https://seequent.com/error-codes/block-model-service/service"
A URI reference that is the primary identifier of the problem type.
