Skip to main content

Block Model API

Version: 1.17.0

Start a block model data update

PATCH
/blockmodel/orgs/{org_id}/workspaces/{workspace_id}/block-models/{bm_id}/blocks

Starts the workflow to update the latest version of the block model. On workflow success, a new version of the block model will be created that will contain the changes specified in the request.

When a user wishes to update the blocks of a block model, they need to hit multiple endpoints to complete the workflow. This includes:

  1. An initial request;
  2. An upload of data (for new and update operations);
  3. And finally, a confirmation that the update job can proceed from the state PENDING_UPLOAD to QUEUED.

This endpoint is the initial request, where the server does a sanity check/validation on what the client is attempting to do.

With regards to the request body,

  • We require the columns field to be supplied, which is used to convey which operations the client wishes the service to perform on the block model during the update. The sub-fields of columns (or operations) new, update, rename, update_metadata, and delete specify the downstream behaviour on the specified columns during the update workflow. Note that new, update, and delete can be provided in concert, whilst rename can only be provided by itself. update_metadata can be provided along with new, update, and delete, but only when there are no columns being renamed (i.e. when only the unit ID is being updated). Some general rules/mechanics for all of these fields:
    • The reserved system columns [i, j, k, sidx, x, y, z, dx, dy, dz, version_id] and any other model type specific sub-block index columns, cannot be targeted using any of the update operations.
    • Any list of titles provided cannot contain duplicates.
    • In all cases, unless specifically stated otherwise, columns that are targeted in one operation cannot be targeted in another.
  • There is an optional field update_type, which is used to determine which blocks are updated in the block model. The supported update types are replace and merge.
    • If update_type is set to replace, the values of the columns provided in the update file are updated for all blocks within the block model. If a block is not provided in the update file, the column values for that block are set to null. The columns not provided in the update file are not affected.
    • If update_type is set to merge (the default), only the blocks and columns that are provided in the update file are updated. The blocks and columns not provided in the update file are not affected.
  • Note that the optional field geometry_change can only be provided for sub-blocked models.
    • If geometry_change is set to false, no new sub-blocks can be created nor destroyed, only sub-blocks that exist in the latest version can be updated.
    • If geometry_change is set to true, new sub-blocks can be created and/or existing sub-blocks can be destroyed, but all columns must be provided. If update_type is set to merge, then all sub-blocks within a parent block must be provided.
  • For new and update operations, the details of the data file for upload can be specified using the optional input_options field.

If the request is successful, the server then sends back a pollable job_url and an upload_url (if required). The upload_url is where the data associated with a new or update operation should be uploaded to, which can be done with a PUT request. Note that the generated URL contains a SAS token, which is used to authenticate the upload. An upload can be started no later than 30 minutes after the generation of the SAS token.

With regards to the data file to be uploaded,

  • The file can either be in Parquet or CSV format.
  • The file needs to contain either IJK (block index) or XYZ (centroid coordinate) information for each block/row, along with the data for the columns specified in the request body, using the correct data type.
  • If both IJK and XYZ columns are supplied in the data file, the service will only make use of the IJK information.

A minimum workspace role of Editor is required to use this endpoint.

Request

Path parameters

Example: "860be2f5-fe06-4c1b-ac8b-7d34d2b6d2ef"

ID of the workspace this call is scoped to. Represented as a v4 UUID.

Example: "bf1a040c-8c58-4bc2-bec2-c5ae7de8bd84"

ID of the organization this call is scoped to. Represented as a v4 UUID.

Example: "e3c277c2-edc6-4a7a-8380-251dd19231f2"

ID of the block model this call is scoped to. Represented as a v4 UUID.

Body parameters
Required

The list of column titles for deletion

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

The new human-readable label for the column identified by title

The original human-readable label used to identify the column

The list of column titles for update

update_metadataarray | null
commentstring | null

Whether the update will create or destroy sub-blocks.

  • If set to false, no sub-blocks can be created nor destroyed, only sub-blocks that exist in the latest version can be updated.
  • If set to true:
    • New sub-blocks can be created and/or existing sub-blocks can be destroyed, but all columns must be provided.
    • Only new, update, and delete column operations are allowed as standalone operations.
    • update_metadata is allowed, but only when the target columns are being updated as part of the update operation, and only when there are no columns being renamed.
    • If update_type is set to merge, then all sub-blocks within a parent block must be provided.
file_format"parquet"
Default: "parquet"
column_name_mappingarray | null
Default: []
decimal_charstring | null
Default: "."
delimiterstring | null
Default: ","
file_format"csv"
Default: "csv"
quote_charstring | null
Default: """
skip_rowsinteger | null
skip_rows_after_headersinteger | null
null
Default: "merge"

Behaviour of the update, for blocks that are omitted from the update file.

  • If set to replace, the values for blocks that are omitted will be set to null, for the selected columns. If geometry_change is true, the geometry of any parent block that has no blocks in the update file will be reset to an un-subdivided state.
  • If set to merge, blocks that are omitted will be left unchanged, the values within those blocks will be the same as within the previous version.

Responses

202

Successful Response

base_version_uuiduuid

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

null

The list of column IDs for deletion

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: "618d6339-2fa7-4dfd-9c7f-c0b12016639e"

The ID of the column, a UUID for non-system columns

The new human-readable label for the column identified by col_id

The list of column IDs for update

update_metadataarray | null
commentstring | null

Whether the update will create or destroy sub-blocks.

  • If set to false, no sub-blocks can be created nor destroyed, only sub-blocks that exist in the latest version can be updated.
  • If set to true:
    • New sub-blocks can be created and/or existing sub-blocks can be destroyed, but all columns must be provided.
    • Only new, update, and delete column operations are allowed as standalone operations.
    • update_metadata is allowed, but only when the target columns are being updated as part of the update operation, and only when there are no columns being renamed.
    • If update_type is set to merge, then all sub-blocks within a parent block must be provided.
Default: "merge"

Behaviour of the update, for blocks that are omitted from the update file.

  • If set to replace, the values for blocks that are omitted will be set to null, for the selected columns. If geometry_change is true, the geometry of any parent block that has no blocks in the update file will be reset to an un-subdivided state.
  • If set to merge, blocks that are omitted will be left unchanged, the values within those blocks will be the same as within the previous version.

The list of column titles for deletion

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

The new human-readable label for the column identified by title

The original human-readable label used to identify the column

The list of column titles for update

update_metadataarray | null
commentstring | null

Whether the update will create or destroy sub-blocks.

  • If set to false, no sub-blocks can be created nor destroyed, only sub-blocks that exist in the latest version can be updated.
  • If set to true:
    • New sub-blocks can be created and/or existing sub-blocks can be destroyed, but all columns must be provided.
    • Only new, update, and delete column operations are allowed as standalone operations.
    • update_metadata is allowed, but only when the target columns are being updated as part of the update operation, and only when there are no columns being renamed.
    • If update_type is set to merge, then all sub-blocks within a parent block must be provided.
file_format"parquet"
Default: "parquet"
column_name_mappingarray | null
Default: []
decimal_charstring | null
Default: "."
delimiterstring | null
Default: ","
file_format"csv"
Default: "csv"
quote_charstring | null
Default: """
skip_rowsinteger | null
skip_rows_after_headersinteger | null
null
Default: "merge"

Behaviour of the update, for blocks that are omitted from the update file.

  • If set to replace, the values for blocks that are omitted will be set to null, for the selected columns. If geometry_change is true, the geometry of any parent block that has no blocks in the update file will be reset to an un-subdivided state.
  • If set to merge, blocks that are omitted will be left unchanged, the values within those blocks will be the same as within the previous version.
job_urluri
job_uuiduuid
upload_urlstring | null
version_uuiduuid

400

Bad Request

Example: "Update would cause number of user columns to exceed max of 300."

A human-readable explanation specific to this occurrence of the problem.

Example: 400

The HTTP status code generated by the origin server for this occurrence of the problem.

Example: "Too Many Columns"

A short, human-readable summary of the problem type.

Example: "https://seequent.com/error-codes/block-model-service/too-many-columns"

A URI reference that is the primary identifier of the problem type.

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: "Error validating input data for lite update of block model 11111111-2222-3333-4444-555555555555, against latest version 99999999-2222-3333-4444-555555555555: Reserved column(s): i cannot be renamed."

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.

Developer Portal

Guides

API Reference

Cookie policy•Terms of use•Privacy policy
© Seequent, The Bentley Subsurface Company