Create Datamart

curl --request POST \
  --url https://api.usedatabrain.com/api/v2/data-app/datamarts \
  --header 'Authorization: Bearer dbn_live_...' \
  --header 'Content-Type: application/json'

{
  "id": "<string>",
  "error": {}
}

POST

api

data-app

datamarts

curl --request POST \
  --url https://api.usedatabrain.com/api/v2/data-app/datamarts \
  --header 'Authorization: Bearer dbn_live_...' \
  --header 'Content-Type: application/json'

{
  "id": "<string>",
  "error": {}
}

Create datamarts to organize your data sources into logical business units. Datamarts provide structured access to your datasource tables and columns with optional schema support.

Endpoint Migration Notice: We’re transitioning to kebab-case endpoints. The new endpoint is /api/v2/data-app/datamarts. The old endpoint /api/v2/dataApp/datamarts will be deprecated soon. Please update your integrations to use the new endpoint format.

Datamarts help organize data sources by defining which tables and columns are accessible. Tenancy settings are optional and can be omitted if multi-tenant data isolation is handled at the application level. Ensure your datasource exists before creating a datamart.

Endpoint Formats

New Endpoint (Recommended)
Legacy Endpoint (Deprecated Soon)

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

Use this endpoint for all new integrations. This is the recommended endpoint format.

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

This endpoint still works but will be deprecated. Please migrate to the new endpoint format.

Authentication

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

In Settings page, navigate to the Service Tokens section.
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.

Authorization: Bearer dbn_live_abc123...

string

required

Must be set to application/json for all requests.

Content-Type: application/json

Request Body

string

required

Name of the datamart to create. Must be unique within your organization — the API will reject the request with an error if a datamart with the same name already exists.

Show Naming guidelines

Use descriptive names (e.g., “sales-analytics”, “customer-data”)
Alphanumeric characters and hyphens recommended
Must be unique within your organization (enforced server-side)
Cannot be changed after creation

string

required

The datasource to which this datamart belongs. Must match an existing datasource in your organization.

Show Finding datasource names

Check your datasources list in the DataBrain dashboard
Use the exact name as it appears in your datasource configuration
Names are case-sensitive

array

required

Array of tables with columns to include in the datamart. Must be non-empty.

string

required

Table name from your datasource.

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.

Show Client column usage

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

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.

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

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.

Show OpenSearch wildcard usage

Only applicable to OpenSearch datasources
Accepts a valid OpenSearch index wildcard pattern (e.g., logs-*, events-2024-*)
When set, the wildcard value is used instead of the exact name when constructing the FROM clause
Allows a single datamart table to cover multiple time-partitioned or sharded OpenSearch indices

array

required

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

string

required

Column name from the table.

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.

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

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

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

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.

Show Timezone conversion details

Apply to datetime or timestamp columns that store values in UTC or a fixed timezone
The timezone is sourced from params.timezone in the guest token — not a user or workspace setting
Supported datasources: Postgres, CockroachDB, Trino, Athena, BigQuery, MSSQL, OpenSearch, Databricks, Clickhouse, Redshift, Snowflake
Has no effect on non-datetime column types

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, to leave the column without a default sort. Values are case-sensitive; lowercase values such as "asc" fail validation.

object

Multi-tenant configuration for the datamart. Defines how data is isolated between different tenants/clients. Optional - if not provided, the datamart will be created without explicit tenancy settings.

Show Tenancy configuration details

TABLE level: Uses a dedicated table to map client identifiers
DATABASE level: Each client has a separate database
MULTI_DATABASE level: Supports multi-database tenancy with an optional primary database
Optional - can be omitted if tenancy is handled at the application level

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

Required when tenancySettings is provided. If tenancySettings is omitted, this field is not needed.

string

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

string | null

Optional primary database name used for DATABASE and MULTI_DATABASE tenancy levels. Set to null when you do not want a default database.Note: The API accepts this field for all tenancy levels. It is primarily used by DATABASE and MULTI_DATABASE.

string

Schema name where the client mapping table is located.Required when tenancyLevel is TABLE.

string

Name of the table that contains client mapping information.Required when tenancyLevel is TABLE.

string

Column name in the mapping table that stores the client identifier.Required when tenancyLevel is TABLE.

string

Primary key column of the client mapping table.Required when tenancyLevel is TABLE.

array

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

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 - datamarts can work without relationships for single-table queries

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 created datamart (same as the input name).

null | object

Error object if the request failed, otherwise null for successful requests.

Examples

Errors

HTTP Status	Error Code	Description
`200`	-	Success - Datamart created successfully
`200`	-	Success - Datamart created successfully
`400`	`INVALID_REQUEST_BODY`	Invalid request parameters. Common causes: missing required fields, empty table list, invalid table/column structure, invalid schema/table names, invalid column names, validation errors from Joi schema, or duplicate datamart name (`"Datamart name already exists"`).
`400`	`AUTH_ERROR`	Invalid or expired service token
`400`	`DATASOURCE_NAME_ERROR`	The specified datasource doesn’t exist or you don’t have access to it
`500`	`INTERNAL_SERVER_ERROR`	Server error occurred. Contact support if error persists

Quick Start Guide

Verify your datasource

Ensure your datasource exists and is properly configured. You’ll need the exact datasource name as it appears in your DataBrain workspace.

Prepare your table structure

Identify the tables and columns you want to include in your datamart:

{
  "name": "sales-analytics",
  "datasourceName": "postgres-main",
    "tableList": [
      {
        "schemaName": "public",
        "name": "orders",
        "label": "Customer 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}
        ]
      }
    ],
  "tenancySettings": {
    "tenancyLevel": "TABLE",
    "clientColumnType": "STRING",
    "schemaName": "public",
    "tableName": "client_mapping",
    "tableClientNameColumn": "client_id",
    "tablePrimaryKeyColumn": "id"
  },
  "relationships": [
    {
      "parentTableName": "orders",
      "parentColumnName": "customer_id",
      "childTableName": "customers",
      "childColumnName": "id",
      "relationshipName": "orders_to_customers",
      "cardinality": "ManyToOne",
      "join": "LEFT JOIN"
    }
  ]
}

Create your datamart

Make the API call to create your datamart:

curl --request POST \
  --url https://api.usedatabrain.com/api/v2/data-app/datamarts \
  --header 'Authorization: Bearer dbn_live_abc123...' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "sales-analytics",
    "datasourceName": "postgres-main",
    "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}
        ]
      }
    ],
    "tenancySettings": {
      "tenancyLevel": "TABLE",
      "clientColumnType": "STRING",
      "schemaName": "public",
      "tableName": "client_mapping",
      "tableClientNameColumn": "client_id",
      "tablePrimaryKeyColumn": "id"
    },
    "relationships": [
      {
        "parentTableName": "orders",
        "parentColumnName": "customer_id",
        "childTableName": "customers",
        "childColumnName": "id",
        "relationshipName": "orders_to_customers",
        "cardinality": "ManyToOne",
        "join": "LEFT JOIN"
      }
    ]
  }'

Use your datamart

Reference your new datamart in embed configurations:

const embedConfig = await createEmbedConfiguration({
  dashboardId: 'your-dashboard-id',
  embedType: 'dashboard',
  workspaceName: 'your-workspace',
  accessSettings: {
    datamartName: 'sales-analytics', // Your new datamart
    // ... other settings
  }
});

Next Steps

List Datamarts

View all datamarts in your organization

Delete Datamart

Remove datamarts you no longer need

Embed a Pre-built Dashboard/Metric

Use your datamart in embed configurations

Getting Started

Learn how to get started with DataBrain embedding

Authentication

Datasource APIs

Datamart APIs

Semantic Layer APIs

Workspace APIs

Embeds

Data App APIs

Metric APIs

Self-Hosted APIs

Endpoint Formats

Authentication

Headers

Request Body

Response

Examples

Errors

Quick Start Guide

Next Steps

List Datamarts

Delete Datamart

Embed a Pre-built Dashboard/Metric

Getting Started

​Endpoint Formats

​Authentication

​Headers

​Request Body

​Response

​Examples

​Errors

​Quick Start Guide

​Next Steps

List Datamarts

Delete Datamart

Embed a Pre-built Dashboard/Metric

Getting Started

Endpoint Formats

Authentication

Headers

Request Body

Response

Examples

Errors

Quick Start Guide

Next Steps