Update Datamart

curl --request PUT \
  --url https://api.usedatabrain.com/api/v2/data-app/datamarts \
  --header 'Authorization: Bearer dbn_live_abc123...' \
  --header 'Content-Type: application/json' \
  --data '{
    "datamartName": "sales-analytics",
    "tableList": [
      {
        "schemaName": "public",
        "name": "orders",
        "columns": [
          {
            "name": "order_id",
            "alias": "id",
            "label": "Order ID"
          },
          {
            "name": "customer_id",
            "label": "Customer"
          },
          {
            "name": "order_date",
            "alias": "date",
            "label": "Order Date"
          },
          {
            "name": "total_amount",
            "label": "Total Amount"
          }
        ]
      },
      {
        "schemaName": "public",
        "name": "customers",
        "columns": [
          {
            "name": "customer_id",
            "alias": "id"
          },
          {
            "name": "customer_name",
            "alias": "name"
          }
        ]
      }
    ]
  }'

{
  "id": "sales-analytics"
}

curl --request PUT \
  --url https://api.usedatabrain.com/api/v2/data-app/datamarts \
  --header 'Authorization: Bearer dbn_live_abc123...' \
  --header 'Content-Type: application/json' \
  --data '{
    "datamartName": "sales-analytics",
    "tableList": [
      {
        "schemaName": "public",
        "name": "orders",
        "columns": [
          {
            "name": "order_id",
            "alias": "id",
            "label": "Order ID"
          },
          {
            "name": "customer_id",
            "label": "Customer"
          },
          {
            "name": "order_date",
            "alias": "date",
            "label": "Order Date"
          },
          {
            "name": "total_amount",
            "label": "Total Amount"
          }
        ]
      },
      {
        "schemaName": "public",
        "name": "customers",
        "columns": [
          {
            "name": "customer_id",
            "alias": "id"
          },
          {
            "name": "customer_name",
            "alias": "name"
          }
        ]
      }
    ]
  }'

{
  "id": "sales-analytics"
}

curl --request PUT \
  --url https://api.usedatabrain.com/api/v2/data-app/datamarts \
  --header 'Authorization: Bearer dbn_live_abc123...' \
  --header 'Content-Type: application/json' \
  --data '{
    "datamartName": "sales-analytics",
    "tableList": [
      {
        "schemaName": "public",
        "name": "orders",
        "columns": [
          {
            "name": "order_id",
            "alias": "id",
            "label": "Order ID"
          },
          {
            "name": "customer_id",
            "label": "Customer"
          },
          {
            "name": "order_date",
            "alias": "date",
            "label": "Order Date"
          },
          {
            "name": "total_amount",
            "label": "Total Amount"
          }
        ]
      },
      {
        "schemaName": "public",
        "name": "customers",
        "columns": [
          {
            "name": "customer_id",
            "alias": "id"
          },
          {
            "name": "customer_name",
            "alias": "name"
          }
        ]
      }
    ]
  }'

{
  "id": "sales-analytics"
}

PUT

api

data-app

datamarts

curl --request PUT \
  --url https://api.usedatabrain.com/api/v2/data-app/datamarts \
  --header 'Authorization: Bearer dbn_live_abc123...' \
  --header 'Content-Type: application/json' \
  --data '{
    "datamartName": "sales-analytics",
    "tableList": [
      {
        "schemaName": "public",
        "name": "orders",
        "columns": [
          {
            "name": "order_id",
            "alias": "id",
            "label": "Order ID"
          },
          {
            "name": "customer_id",
            "label": "Customer"
          },
          {
            "name": "order_date",
            "alias": "date",
            "label": "Order Date"
          },
          {
            "name": "total_amount",
            "label": "Total Amount"
          }
        ]
      },
      {
        "schemaName": "public",
        "name": "customers",
        "columns": [
          {
            "name": "customer_id",
            "alias": "id"
          },
          {
            "name": "customer_name",
            "alias": "name"
          }
        ]
      }
    ]
  }'

{
  "id": "sales-analytics"
}

Update the table list and tenancy settings of an existing datamart. This endpoint allows you to modify which tables and columns are accessible through the datamart, as well as update multi-tenant configurations.

Destructive Operation: Updating a datamart will delete all existing table and column configurations before applying the new ones. Ensure your new configuration includes all tables and columns you need.

The datamart name identifies which datamart to update and cannot be changed through this endpoint. To rename a datamart, you’ll need to delete the old one and create a new one with the desired name.

Authentication

All API requests must include your API key in the Authorization header. Get your API token when creating a data app - see our data app creation guide for details. Finding your API token: For detailed instructions, see the API Token guide.

Headers

Authorization

string

required

Bearer token for API authentication. Use your API key from the data app.

Authorization: Bearer dbn_live_abc123...

Content-Type

string

required

Must be set to application/json for all requests.

Content-Type: application/json

Request Body

datamartName

string

required

Name of the existing datamart to update. Must match exactly (case-sensitive).

Show Finding datamart names

Use the List Datamarts API to get all datamart names
Names are case-sensitive and must match exactly
This field identifies which datamart to update (cannot be used to rename)

tableList

array

Array of tables with columns to include in the datamart. Optional - if not provided, only tenancy settings will be updated.

Replaces all existing tables: The new table list completely replaces the existing configuration. Include all tables you want to keep.

tableList.name

string

required

Table name from your datasource. Must exist in the datasource schema.

tableList.schemaName

string

Optional schema name (required only for schema-based datasources like PostgreSQL, SQL Server).

tableList.columns

array

required

List of column objects for this table. Must be non-empty.

tableList.columns.name

string

required

Column name from the table. Must exist in the datasource schema.

tableList.columns.alias

string

Optional alias for the column to display a different name.

tableList.columns.label

string

Optional label for the column for better readability.

tableList.columns.isHide

boolean

Optional flag to hide the column from the datamart interface. Defaults to false.

tenancySettings

object

Multi-tenant configuration for the datamart. Optional - if not provided, existing tenancy settings remain unchanged.

Show Tenancy configuration details

TABLE level: Uses a dedicated table to map client identifiers
DATABASE level: Each client has a separate database
All fields are optional; omitted fields retain their existing values

tenancySettings.tenancyLevel

string

The level at which tenant isolation occurs. Must be either TABLE or DATABASE.

TABLE: Client mapping is stored in a specific table (most common)
DATABASE: Each client has a separate database instance

Optional: If not provided, existing tenancy level is retained.

tenancySettings.clientColumnType

string

Data type of the client identifier column. Must be either NUMBER or STRING.Required when tenancyLevel is TABLE (either new or existing).

tenancySettings.schemaName

string

Schema name where the client mapping table is located.Required when tenancyLevel is TABLE (either new or existing).

tenancySettings.tableName

string

Name of the table that contains client mapping information.Required when tenancyLevel is TABLE (either new or existing).

tenancySettings.tableClientNameColumn

string

Column name in the mapping table that stores the client identifier.Required when tenancyLevel is TABLE (either new or existing).

tenancySettings.tablePrimaryKeyColumn

string

Primary key column of the client mapping table.Required when tenancyLevel is TABLE (either new or existing).

Response

string

The name of the updated datamart (same as the input datamartName) on success.

error

object

Error object returned only when the request fails. Not included in successful responses.

Show error properties

code

string

Error code identifying the type of error.

message

string

Human-readable error message describing what went wrong.

Examples

HTTP Status Code Summary

Status Code	Description
`200`	OK - Datamart updated successfully
`400`	Bad Request - Invalid request parameters
`401`	Unauthorized - Invalid or missing API key
`500`	Internal Server Error - Server error occurred

Possible Errors

Error Code	HTTP Status	Description
`INVALID_REQUEST_BODY`	400	Missing or invalid parameters
`INVALID_DATAMART`	400	Datamart not found
`INVALID_DATA_APP_API_KEY`	401	Invalid API key
`INTERNAL_SERVER_ERROR`	500	Server error

Quick Start Guide

Get current configuration

Retrieve the existing datamart configuration before making changes:

curl --request GET \
  --url 'https://api.usedatabrain.com/api/v2/data-app/datamarts?isPagination=false' \
  --header 'Authorization: Bearer dbn_live_abc123...'

Save this response in case you need to rollback your changes.

Prepare your update

Determine what you want to update:

Tables/Columns: Prepare the complete new tableList (replaces existing)
Tenancy: Prepare updated tenancySettings (optional)
Both: You can update both in a single request

If only updating tenancy, omit the tableList field to keep existing tables intact.

Update the datamart

Make the update request:

curl --request PUT \
  --url https://api.usedatabrain.com/api/v2/data-app/datamarts \
  --header 'Authorization: Bearer dbn_live_abc123...' \
  --header 'Content-Type: application/json' \
  --data '{
    "datamartName": "sales-analytics",
    "tableList": [
      {
        "schemaName": "public",
        "name": "orders",
        "columns": [
          {"name": "order_id", "alias": "id"},
          {"name": "customer_id"}
        ]
      }
    ]
  }'

Successful response returns the datamart name.

Verify the update

Test that the datamart works correctly:

Load metrics that use this datamart
Check that all expected tables and columns are accessible
Verify tenancy is working if you updated those settings
Monitor for any errors in your dashboards

If metrics break, you can update again with your saved previous configuration to rollback.

Next Steps

Create Datamart

Create a new datamart from scratch

List Datamarts

View all datamarts in your organization

Delete Datamart

Remove datamarts you no longer need

Datamart Concepts

Learn more about datamarts

List Datamarts

Delete Datamart

⌘I

Authentication

Datamart APIs

Workspace APIs

Embed Configuration

Embedding APIs (Legacy)

Data App APIs

Authentication

Headers

Request Body

Response

Examples

HTTP Status Code Summary

Possible Errors

Quick Start Guide

Next Steps

Create Datamart

List Datamarts

Delete Datamart

Datamart Concepts

Authentication

Datamart APIs

Workspace APIs

Embed Configuration

Embedding APIs (Legacy)

Data App APIs

​Authentication

​Headers

​Request Body

​Response

​Examples

​HTTP Status Code Summary

​Possible Errors

​Quick Start Guide

​Next Steps

Create Datamart

List Datamarts

Delete Datamart

Datamart Concepts

Authentication

Headers

Request Body

Response

Examples

HTTP Status Code Summary

Possible Errors

Quick Start Guide

Next Steps