Skip to main content

Column operations

Operations that modify the columns/blocks within a block model

Start a block model data update​

Block Model API

Version: 1.42.9

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.
      • Note for Datamine file imports, this restriction extends to the fields [IJK, XC, YC, ZC, XINC, YINC, ZINC]. These will be mapped automatically from the file to their BMS equivalents.
    • 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, CSV, or Datamine (.dm) 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.
    • Datamine is an exception to this rule - for these files, BlockSync only uses the XYZ information and ignores the IJK field.
  • The file must include the required system columns, which vary depending on the block model type:
    • Regular models: Require i, j, k (block indices) or x, y, z (centroid coordinates).
    • Fully sub-blocked models: Require i, j, k, sidx (sub-block index) or x, y, z, dx, dy, dz (sub-block sizes along each axis).
    • Octree models: Requirements are the same as fully sub-blocked models.
    • Flexible models: Require i, j, k, start_si, start_sj, start_sk, end_si, end_sj, end_sk (sub-block grid indices) or x, y, z, dx, dy, dz.
  • Reserved system columns must use the correct data types:
    • Indices i, j, k, and sidx must be UInt32.
    • Coordinates x, y, z, dx, dy, and dz must be Float64.
    • Sub-block grid indices start_si, start_sj, start_sk, end_si, end_sj, end_sk must be UInt8.

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

Parameters

authorizationstring
Required

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.

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_metadataUpdateMetadataLite[] | null
commentstring | null
<= 250 chars

If set to true, any missing sub-blocks will be filled with data from the parent block. This is only available for fully sub-blocked models, when update_type is merge, and geometry_change is true.

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.

column_name_mappingColumnNameMappingGeneric[] | null
Default: []
file_format"parquet"
Default: "parquet"

column_name_mappingColumnNameMapping[] | ColumnNameMappingGeneric[] | null
Default: []
decimal_charstring | null
1 char
Default: "."
delimiterstring | null
1 char
Default: ","
file_format"csv"
Default: "csv"
quote_charstring | null
1 char
Default: '"'
skip_rowsinteger | null
skip_rows_after_headersinteger | null

column_name_mappingColumnNameMappingGeneric[] | null
Default: []
file_format"datamine"
Default: "datamine"
null

Lineage of the block model update

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.

{
  "columns": {
    "delete": [
      "string"
    ],
    "new": [
      {
        "data_type": "Boolean",
        "title": "string",
        "unit_id": "string"
      }
    ],
    "rename": [
      {
        "new_title": "string",
        "title": "string"
      }
    ],
    "update": [
      "string"
    ],
    "update_metadata": [
      {
        "title": "string",
        "values": {
          "title": "string",
          "unit_id": "string"
        }
      }
    ]
  },
  "comment": "string",
  "fill_subblocks": true,
  "geometry_change": true,
  "input_options": {
    "column_name_mapping": [
      {
        "column_title": "string",
        "file_column_name": "string"
      }
    ],
    "file_format": "parquet"
  },
  "lineage": {
    "events": [
      {
        "eventTime": "string",
        "eventType": "string",
        "inputs": [
          {
            "facets": {
              "additionalProp1": {
                "additionalProp1": "string",
                "additionalProp2": "number",
                "additionalProp3": "boolean"
              },
              "additionalProp2": {
                "additionalProp1": "string",
                "additionalProp2": "number",
                "additionalProp3": "boolean"
              },
              "additionalProp3": {
                "additionalProp1": "string",
                "additionalProp2": "number",
                "additionalProp3": "boolean"
              }
            },
            "inputFacets": {
              "additionalProp1": {
                "additionalProp1": "string",
                "additionalProp2": "number",
                "additionalProp3": "boolean"
              },
              "additionalProp2": {
                "additionalProp1": "string",
                "additionalProp2": "number",
                "additionalProp3": "boolean"
              },
              "additionalProp3": {
                "additionalProp1": "string",
                "additionalProp2": "number",
                "additionalProp3": "boolean"
              }
            },
            "name": "string",
            "namespace": "string"
          }
        ],
        "job": {
          "facets": {
            "additionalProp1": {
              "additionalProp1": "string",
              "additionalProp2": "number",
              "additionalProp3": "boolean"
            },
            "additionalProp2": {
              "additionalProp1": "string",
              "additionalProp2": "number",
              "additionalProp3": "boolean"
            },
            "additionalProp3": {
              "additionalProp1": "string",
              "additionalProp2": "number",
              "additionalProp3": "boolean"
            }
          },
          "name": "string",
          "namespace": "string"
        },
        "outputs": [
          {
            "facets": {
              "additionalProp1": {
                "additionalProp1": "string",
                "additionalProp2": "number",
                "additionalProp3": "boolean"
              },
              "additionalProp2": {
                "additionalProp1": "string",
                "additionalProp2": "number",
                "additionalProp3": "boolean"
              },
              "additionalProp3": {
                "additionalProp1": "string",
                "additionalProp2": "number",
                "additionalProp3": "boolean"
              }
            },
            "name": "string",
            "namespace": "string",
            "outputFacets": {
              "additionalProp1": {
                "additionalProp1": "string",
                "additionalProp2": "number",
                "additionalProp3": "boolean"
              },
              "additionalProp2": {
                "additionalProp1": "string",
                "additionalProp2": "number",
                "additionalProp3": "boolean"
              },
              "additionalProp3": {
                "additionalProp1": "string",
                "additionalProp2": "number",
                "additionalProp3": "boolean"
              }
            }
          }
        ],
        "producer": "string",
        "run": {
          "facets": {
            "additionalProp1": {
              "additionalProp1": "string",
              "additionalProp2": "number",
              "additionalProp3": "boolean"
            },
            "additionalProp2": {
              "additionalProp1": "string",
              "additionalProp2": "number",
              "additionalProp3": "boolean"
            },
            "additionalProp3": {
              "additionalProp1": "string",
              "additionalProp2": "number",
              "additionalProp3": "boolean"
            }
          },
          "runId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        },
        "schemaURL": "string"
      }
    ],
    "self_link": "string"
  },
  "update_type": "merge"
}

Returns

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_metadataUpdateMetadata[] | null
commentstring | null
<= 250 chars

If set to true, any missing sub-blocks will be filled with data from the parent block. This is only available for fully sub-blocked models, when update_type is merge, and geometry_change is true.

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.

Lineage of the block model update

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_metadataUpdateMetadataLite[] | null
commentstring | null
<= 250 chars

If set to true, any missing sub-blocks will be filled with data from the parent block. This is only available for fully sub-blocked models, when update_type is merge, and geometry_change is true.

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.

column_name_mappingColumnNameMappingGeneric[] | null
Default: []
file_format"parquet"
Default: "parquet"

column_name_mappingColumnNameMapping[] | ColumnNameMappingGeneric[] | null
Default: []
decimal_charstring | null
1 char
Default: "."
delimiterstring | null
1 char
Default: ","
file_format"csv"
Default: "csv"
quote_charstring | null
1 char
Default: '"'
skip_rowsinteger | null
skip_rows_after_headersinteger | null

column_name_mappingColumnNameMappingGeneric[] | null
Default: []
file_format"datamine"
Default: "datamine"
null

Lineage of the block model update

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
>= 1 char
job_uuiduuid
upload_urluri | null
>= 1 char
version_uuiduuid

Endpoint

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

Request

curl -X PATCH 'https://{service_host}/blockmodel/orgs/{org_id}/workspaces/{workspace_id}/block-models/{bm_id}/blocks' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'

Response

{
  "changes": {
    "base_version_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "bbox": {
      "i_minmax": {
        "max": 0,
        "min": 0
      },
      "j_minmax": {
        "max": 0,
        "min": 0
      },
      "k_minmax": {
        "max": 0,
        "min": 0
      }
    },
    "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"
          }
        }
      ]
    },
    "comment": "string",
    "fill_subblocks": true,
    "geometry_change": true,
    "lineage": {
      "events": [
        {
          "eventTime": "string",
          "eventType": "string",
          "inputs": [
            {
              "facets": {
                "additionalProp1": {
                  "additionalProp1": "string",
                  "additionalProp2": "number",
                  "additionalProp3": "boolean"
                },
                "additionalProp2": {
                  "additionalProp1": "string",
                  "additionalProp2": "number",
                  "additionalProp3": "boolean"
                },
                "additionalProp3": {
                  "additionalProp1": "string",
                  "additionalProp2": "number",
                  "additionalProp3": "boolean"
                }
              },
              "inputFacets": {
                "additionalProp1": {
                  "additionalProp1": "string",
                  "additionalProp2": "number",
                  "additionalProp3": "boolean"
                },
                "additionalProp2": {
                  "additionalProp1": "string",
                  "additionalProp2": "number",
                  "additionalProp3": "boolean"
                },
                "additionalProp3": {
                  "additionalProp1": "string",
                  "additionalProp2": "number",
                  "additionalProp3": "boolean"
                }
              },
              "name": "string",
              "namespace": "string"
            }
          ],
          "job": {
            "facets": {
              "additionalProp1": {
                "additionalProp1": "string",
                "additionalProp2": "number",
                "additionalProp3": "boolean"
              },
              "additionalProp2": {
                "additionalProp1": "string",
                "additionalProp2": "number",
                "additionalProp3": "boolean"
              },
              "additionalProp3": {
                "additionalProp1": "string",
                "additionalProp2": "number",
                "additionalProp3": "boolean"
              }
            },
            "name": "string",
            "namespace": "string"
          },
          "outputs": [
            {
              "facets": {
                "additionalProp1": {
                  "additionalProp1": "string",
                  "additionalProp2": "number",
                  "additionalProp3": "boolean"
                },
                "additionalProp2": {
                  "additionalProp1": "string",
                  "additionalProp2": "number",
                  "additionalProp3": "boolean"
                },
                "additionalProp3": {
                  "additionalProp1": "string",
                  "additionalProp2": "number",
                  "additionalProp3": "boolean"
                }
              },
              "name": "string",
              "namespace": "string",
              "outputFacets": {
                "additionalProp1": {
                  "additionalProp1": "string",
                  "additionalProp2": "number",
                  "additionalProp3": "boolean"
                },
                "additionalProp2": {
                  "additionalProp1": "string",
                  "additionalProp2": "number",
                  "additionalProp3": "boolean"
                },
                "additionalProp3": {
                  "additionalProp1": "string",
                  "additionalProp2": "number",
                  "additionalProp3": "boolean"
                }
              }
            }
          ],
          "producer": "string",
          "run": {
            "facets": {
              "additionalProp1": {
                "additionalProp1": "string",
                "additionalProp2": "number",
                "additionalProp3": "boolean"
              },
              "additionalProp2": {
                "additionalProp1": "string",
                "additionalProp2": "number",
                "additionalProp3": "boolean"
              },
              "additionalProp3": {
                "additionalProp1": "string",
                "additionalProp2": "number",
                "additionalProp3": "boolean"
              }
            },
            "runId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
          },
          "schemaURL": "string"
        }
      ],
      "self_link": "string"
    },
    "update_type": "merge"
  },
  "job_url": "https://example.com",
  "job_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "upload_url": "https://example.com",
  "version_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Advise that the update file has finished uploading​

Block Model API

Version: 1.42.9

Signals that you have finished uploading the update file to the server blob storage indicated by the upload_url, and that the update can continue. This moves the job_status from PENDING_UPLOAD to QUEUED.

After this endpoint is called, the job_url should then be polled with a GET request to wait for the job_status field of the job to become either FAILED or COMPLETE. On workflow success, a new version of the block model will be created that will contain the changes specified in the update request.

Note that this endpoint still needs to be hit even when an update does not require a file upload.

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

Parameters

authorizationstring
Required

Example: "ff0b8078-c7ec-41ab-87fb-f3eb32812b32"

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

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.

Returns

201

Successful Response

job_urluri
>= 1 char

Endpoint

POST
/blockmodel/orgs/{org_id}/workspaces/{workspace_id}/block-models/{bm_id}/jobs/{job_id}/uploaded

Request

curl -X POST 'https://{service_host}/blockmodel/orgs/{org_id}/workspaces/{workspace_id}/block-models/{bm_id}/jobs/{job_id}/uploaded' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'

Response

{
  "job_url": "https://example.com"
}

What is the reason for your feedback?

Developer Portal

Guides

API reference

Get in touch

Explore more about Seequent and Evo or reach out to our team for enquiries.

Cookie policy•Developer terms of service•Terms of use•Privacy policy
© Seequent, The Bentley Subsurface Company • Version 2026.4.211-vf168bd9e