Create Datamart

Create a new datamart to organize and manage your data sources with custom table and column configurations.

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)

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.

Response

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

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

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

3. 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"
       }
     }'
   

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