Update Datamart

Update an existing datamart’s table configurations and tenancy settings without recreating from scratch.

PUT https://api.usedatabrain.com/api/v2/data-app/datamarts

cURL - Update Tables Only

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",
        "clientColumn": "tenant_id",
        "isHide": false,
        "columns": [
          {
            "name": "order_id",
            "alias": "id",
            "label": "Order ID",
            "isHide": false
          },
          {
            "name": "customer_id",
            "label": "Customer",
            "isHide": false
          },
          {
            "name": "order_date",
            "alias": "date",
            "label": "Order Date",
            "isHide": false
          },
          {
            "name": "total_amount",
            "label": "Total Amount",
            "isHide": true
          }
        ]
      },
      {
        "schemaName": "public",
        "name": "customers",
        "label": "Customer Records",
        "clientColumn": "tenant_id",
        "isHide": false,
        "columns": [
          {
            "name": "customer_id",
            "alias": "id",
            "isHide": false
          },
          {
            "name": "customer_name",
            "alias": "name",
            "isHide": false
          }
        ]
      }
    ]
  }'

200 - Success

{
  "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

This endpoint requires a service token in the Authorization header. Service tokens differ from data app API keys and provide organization-level permissions.

To access your service token:

1. Go to your Databrain dashboard and open Settings.
2. Navigate to Settings.
3. Find the Service Tokens section.
4. Click the “Generate Token” button to generate a new service token if you don’t have one already.

Use this token as the Bearer value in your Authorization header.

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.clientColumn · string

Optional column name in this table that identifies the client/tenant. This column is used for multi-tenant data isolation at the table level. Must exist in the table schema.

Show Client column usage

• Used for table-level tenancy when tenancyLevel is TABLE
• The column should contain client/tenant identifiers

tableList.isHide · boolean

Optional flag to hide the table from the datamart interface.

tableList.label · string

Optional label for the table to provide a human-readable display name. When provided, this label can be used in the UI instead of the technical table name for better readability.

Show Label usage

• Provides a user-friendly display name for the table
• Useful when table names are cryptic or technical
• Does not affect the actual table reference in queries

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.

tableList.columns.isCustomColumn · boolean

Optional flag to mark this as a custom/calculated column. When true, the sql field is required to define the column’s SQL expression.

Show Custom column usage

• Custom columns allow you to define calculated fields using SQL expressions
• The name field should reference an existing column from the datasource schema
• Use the alias field to give the calculated column a custom display name
• The SQL expression can reference other columns from the same table
• Useful for derived metrics, concatenations, or transformations

tableList.columns.sql · string

SQL expression that defines the calculated value for a custom column. Required when isCustomColumn is true. The expression can reference other columns from the same table.

Show SQL expression examples

• Simple calculation: quantity * unit_price
• Date extraction: EXTRACT(YEAR FROM order_date)
• String concatenation: CONCAT(first_name, ' ', last_name)
• Case statement: CASE WHEN status = 'active' THEN 1 ELSE 0 END

tableList.columns.isAggregate · boolean

Optional flag to indicate if this column should be treated as an aggregate column. When true, the column is marked as AGGREGATE drop type for metric calculations.

Show Aggregate column usage

• Aggregate columns are used for pre-aggregated metrics
• Affects how the column behaves in metric calculations and drag-drop operations
• Common for SUM, COUNT, AVG type pre-calculated values

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 one of: TABLE, DATABASE, or MULTI_DATABASE.

• TABLE: Client mapping is stored in a specific table (most common)
• DATABASE: Each client has a separate database instance
• MULTI_DATABASE: Multiple databases are used for tenant isolation

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 tenancySettings.tenancyLevel is set to TABLE in the request.

tenancySettings.schemaName · string

Schema name where the client mapping table is located.

Required when tenancySettings.tenancyLevel is set to TABLE in the request.

tenancySettings.tableName · string

Name of the table that contains client mapping information.

Required when tenancySettings.tenancyLevel is set to TABLE in the request.

tenancySettings.tableClientNameColumn · string

Column name in the mapping table that stores the client identifier.

Required when tenancySettings.tenancyLevel is set to TABLE in the request.

tenancySettings.tablePrimaryKeyColumn · string

Primary key column of the client mapping table.

Required when tenancySettings.tenancyLevel is set to TABLE in the request.

relationships · array

Optional array of table relationships to define how tables in the datamart are connected. Relationships enable joins between tables for more complex queries.

Replaces all existing relationships: When provided, the relationships array completely replaces all existing relationships. Include all relationships you want to keep. If omitted entirely, existing relationships remain unchanged.

Show Relationship configuration

• Define how tables relate to each other (e.g., orders.customer_id → customers.id)
• Supports different join types and cardinalities
• Useful for creating metrics that span multiple tables
• Optional - omit this field to keep existing relationships unchanged

relationships.parentTableName · string · required

Name of the parent table in the relationship.

relationships.parentColumnName · string · required

Column name in the parent table that participates in the relationship.

relationships.childTableName · string · required

Name of the child table in the relationship.

relationships.childColumnName · string · required

Column name in the child table that participates in the relationship.

relationships.relationshipName · string · required

A descriptive name for the relationship (e.g., “orders_to_customers”).

relationships.cardinality · string

The cardinality of the relationship. Must be one of: ManyToMany, ManyToOne, OneToMany, OneToOne.

Optional: Can be omitted or set to null if not specified.

relationships.join · string

The type of SQL join to use. Must be one of: INNER JOIN, LEFT JOIN, RIGHT JOIN, FULL JOIN.

Optional: Can be omitted or set to null if not specified.

Response

id · 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

1. 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.

2. 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.

3. 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",
           "label": "Customer Orders",
           "clientColumn": "tenant_id",
           "columns": [
             {"name": "order_id", "alias": "id"},
             {"name": "customer_id"}
           ]
         }
       ]
     }'
   

   Successful response returns the datamart name.

4. 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