Create Datamart

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. Each datamart requires tenancy settings for multi-tenant data isolation. 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.

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

name

string

required

Name of the datamart to create. Must be unique within your organization.

Show Naming guidelines

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

datasourceName

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

tableList

array

required

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

tableList.name

string

required

Table name from your datasource.

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.

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.

tenancySettings

object

required

Multi-tenant configuration for the datamart. Defines how data is isolated between different tenants/clients.

Show Tenancy configuration details

TABLE level: Uses a dedicated table to map client identifiers
DATABASE level: Each client has a separate database
Required for all datamarts to ensure proper data isolation

tenancySettings.tenancyLevel

string

required

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

tenancySettings.clientColumnType

string

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

tenancySettings.schemaName

string

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

tenancySettings.tableName

string

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

tenancySettings.tableClientNameColumn

string

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

tenancySettings.tablePrimaryKeyColumn

string

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

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.

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

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

string

The name of the created datamart (same as the input name).

error

null | object

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

Examples

Error Codes

INVALID_REQUEST_BODY

string

Invalid request body - Check required fields, table list cannot be empty

DATASOURCE_NAME_ERROR

string

Invalid datasource name - The specified datasource doesn’t exist or you don’t have access

INTERNAL_SERVER_ERROR

string

Server error - Contact support if error persists

HTTP Status Code Summary

Status Code	Description
`200`	OK - Datamart created successfully
`400`	Bad Request - Invalid request parameters
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied to datasource
`404`	Not Found - Datasource not found
`409`	Conflict - Datamart name already exists
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error - Server error occurred

Possible Errors

Error Code	HTTP Status	Description
`INVALID_REQUEST_BODY`	400	Missing or invalid parameters
`DATASOURCE_NAME_ERROR`	404	Datasource not found
`DUPLICATE_DATAMART_NAME`	409	Datamart name already exists
`EMPTY_TABLE_LIST`	400	Table list cannot be empty
`INVALID_COLUMN_CONFIG`	400	Invalid column configuration
`MISSING_TENANCY_SETTINGS`	400	Tenancy settings are required
`INVALID_TENANCY_LEVEL`	400	Invalid tenancy level
`MISSING_TENANCY_FIELDS`	400	Required tenancy fields missing
`AUTHENTICATION_ERROR`	401	Invalid API key
`RATE_LIMIT_EXCEEDED`	429	Too many requests
`INTERNAL_SERVER_ERROR`	500	Server error

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",
      "columns": [
        {"name": "order_id", "alias": "id", "label": "Order ID"},
        {"name": "customer_id", "label": "Customer"},
        {"name": "order_date", "alias": "date", "label": "Order Date"}
      ]
    }
  ],
  "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",
        "columns": [
          {"name": "order_id", "alias": "id", "label": "Order ID"},
          {"name": "customer_id", "label": "Customer"}
        ]
      }
    ],
    "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

Create Embed Configuration

Use your datamart in embed configurations

Getting Started

Learn how to get started with DataBrain embedding

Authentication

Datasource APIs

Datamart APIs

Workspace APIs

Embed Configuration

Embedding APIs (Legacy)

Data App APIs

Metric APIs

Endpoint Formats

Authentication

Headers

Request Body

Response

Examples

Error Codes

HTTP Status Code Summary

Possible Errors

Quick Start Guide

Next Steps

List Datamarts

Delete Datamart

Create Embed Configuration

Getting Started

Authentication

Datasource APIs

Datamart APIs

Workspace APIs

Embed Configuration

Embedding APIs (Legacy)

Data App APIs

Metric APIs

​Endpoint Formats

​Authentication

​Headers

​Request Body

​Response

​Examples

​Error Codes

​HTTP Status Code Summary

​Possible Errors

​Quick Start Guide

​Next Steps

List Datamarts

Delete Datamart

Create Embed Configuration

Getting Started

Endpoint Formats

Authentication

Headers

Request Body

Response

Examples

Error Codes

HTTP Status Code Summary

Possible Errors

Quick Start Guide

Next Steps