Skip to main content
PUT
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. In Settings page, navigate to the Service Tokens section.
  2. Click the “Generate Token” button to create a new service token if you don’t have one already.
Use this token as the Bearer value in your Authorization header.

Headers

string
required
Bearer token for API authentication. Use your service token.
string
required
Must be set to application/json for all requests.

Request Body

string
required
Name of the existing datamart to update. Must match exactly (case-sensitive).
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.
string
required
Table name from your datasource. Must exist in the datasource schema.
string
Optional schema name (required only for schema-based datasources like PostgreSQL, SQL Server).
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.
boolean
Optional flag to hide the table from the datamart interface.
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.
string
Optional wildcard index pattern for OpenSearch tables. When set, this value is used as the table name in queries, enabling you to query multiple OpenSearch indices that match a pattern.
array
required
List of column objects for this table. Must be non-empty.
string
required
Column name from the table. Must exist in the datasource schema.
string
Optional alias for the column to display a different name.
string
Optional label for the column for better readability.
boolean
Optional flag to hide the column from the datamart interface. Defaults to false.
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.
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.
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.
boolean
Optional flag to enable default aggregation for the column. When true, Databrain uses the value set in defaultAggregation when the column is added as a measure.
string
Optional field to define the default aggregation applied to the column when used as a measure.
boolean
Optional flag to enable timezone conversion for this column. When true, the column’s datetime values are converted using the timezone passed as params.timezone in the guest token at query execution time.
This field has no effect unless params.timezone is set in the guest token. See Timezone Handling in Guest Token for the full setup guide.
string | null
Optional default sort direction for the column. Supported values are ASC and DESC. The value is propagated to data-app embed access settings and used as the initial sort direction when this column is selected during metric creation.Pass an empty string ("") or null, or omit this field on a submitted column, to clear its default sort. Values are case-sensitive; lowercase values such as "asc" fail validation.
object
Multi-tenant configuration for the datamart. Optional - if not provided, existing tenancy settings remain unchanged.
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: Tenancy spans multiple databases with optional default routing via primaryDatabase
Optional: If not provided, existing tenancy level is retained.
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.
string | null
Optional primary database name used for DATABASE and MULTI_DATABASE tenancy levels.
  • If tenancyLevel is DATABASE or MULTI_DATABASE, this value is stored (or null when omitted).
  • In update requests, if tenancySettings is sent without tenancyLevel, backend logic clears primaryDatabase to null.
  • If tenancyLevel is TABLE, backend logic also clears primaryDatabase to null.
To avoid accidental clearing, include tenancySettings.tenancyLevel whenever you send tenancySettings.
string
Schema name where the client mapping table is located.Required when tenancySettings.tenancyLevel is set to TABLE in the request.
string
Name of the table that contains client mapping information.Required when tenancySettings.tenancyLevel is set to TABLE in the request.
string
Column name in the mapping table that stores the client identifier.Required when tenancySettings.tenancyLevel is set to TABLE in the request.
string
Primary key column of the client mapping table.Required when tenancySettings.tenancyLevel is set to TABLE in the request.
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.
string
required
Name of the parent table in the relationship.
string
required
Column name in the parent table that participates in the relationship.
string
required
Name of the child table in the relationship.
string
required
Column name in the child table that participates in the relationship.
string
required
A descriptive name for the relationship (e.g., “orders_to_customers”).
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.
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

string
The name of the updated datamart (same as the input datamartName) on success.
object
Error object returned only when the request fails. Not included in successful responses.

Examples

HTTP Status Code Summary

Possible Errors

Quick Start Guide

1

Get current configuration

Retrieve the existing datamart configuration before making changes:
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:
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