> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usedatabrain.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Datamarts

> Create optimized data models for analytics and AI-powered insights

## What is a Datamart?

A Datamart is a curated, optimized subset of your data specifically designed for analytics and AI-powered queries. It sits between your raw data and your dashboards / AI layer, providing a clean, query-ready model that is easy for both humans and AI to work with.

## Why Use Datamarts?

<CardGroup cols={2}>
  <Card title="Faster Queries" icon="gauge-high">
    Optimized tables and columns for lightning-fast analytics
  </Card>

  <Card title="AI-Ready Data" icon="robot">
    Structured for natural language queries and AI insights
  </Card>

  <Card title="Simplified Schema" icon="diagram-project">
    Business-friendly data model hiding technical complexity
  </Card>

  <Card title="Consistent Metrics" icon="check-double">
    Single source of truth for key business metrics
  </Card>
</CardGroup>

## Creating a Datamart

<Steps>
  <Step title="Create Datamart">
    Provide a name and select a datasource. Each datamart connects to a single datasource.
  </Step>

  <Step title="Select Tables">
    Choose which tables from the schema to include in your datamart. You can select tables from different schemas within the same datasource.
  </Step>

  <Step title="Configure Columns">
    Select which columns to include from the selected tables. Preview table data and configure column visibility.
  </Step>

  <Step title="Configure Tenancy (Optional)">
    Set up multi-tenancy settings:

    * **Table-level tenancy**: Select a table with primary key and client name columns
    * **Database-level tenancy**: Use separate databases per tenant
    * **Multi-database tenancy**: Use multiple databases (MSSQL only)
  </Step>

  <Step title="Add Descriptions & Metadata">
    After creation, add business-friendly names, descriptions, and relationships in the Datamart Description page.
  </Step>
</Steps>

<Card title="Create a Datamart" icon="plus" href="/guides/datasources/create-a-datamart">
  Step-by-step datamart creation guide
</Card>

## Key Features

### Tables

Select tables from your datasource:

* Choose tables from available schemas
* Preview table data before including
* Select multiple tables from different schemas
* Hide tables that aren't needed

### Columns

Configure which columns to include:

* Select specific columns from each table
* Hide unnecessary columns
* Preview column data
* Configure column visibility

### Tenancy Configuration

Set up multi-tenancy (optional):

* Table-level tenancy with primary key and client columns
* Database-level tenancy for complete isolation
* Multi-database tenancy (MSSQL only)

### Relationships

Define relationships between tables (configured after creation):

* One-to-many relationships
* Many-to-many relationships
* Self-referential joins
* Configure join types and cardinality

### Metadata & Descriptions

Add context to make your datamart analytics- and AI-ready (configured after creation):

* Table descriptions
* Column descriptions and labels
* Business-friendly aliases
* Example questions for downstream AI experiences

## Datamart Structure

Each datamart connects to a single datasource. Within that datasource, you can:

* Select tables from multiple schemas
* Configure columns from selected tables
* Define relationships between tables
* Set up multi-tenancy at table, database, or multi-database level

<Card title="Semantic Layer" icon="layer-group" href="/guides/datasources/semantic-layer">
  Learn about semantic layer capabilities
</Card>

## Tenancy & Multi-Tenancy

Datamarts support multi-tenant architectures for data isolation:

### Tenancy Levels

**Table-Level Tenancy**

* Select a table with primary key and client name columns
* Data is filtered automatically based on client ID
* Suitable for single-database multi-tenant setups

**Database-Level Tenancy**

* Use separate databases per tenant
* Each tenant's data is completely isolated
* Automatically routes queries to the correct database

**Multi-Database Tenancy** (MSSQL only)

* Use multiple databases for tenant isolation
* Supports complex multi-tenant architectures
* Configure schema lists per tenant

### Access Control

Datamart access is controlled through workspace permissions:

* View, Create, Edit, Delete permissions
* Edit Tenancy permission for configuring multi-tenancy

## Use Cases

### AI-Powered Analytics

Enable business users to ask questions in natural language (powered by the semantic layer you configure later):

* "Top customers by revenue"
* "Sales trends last quarter"
* "Compare regions"

### Consistent Metrics

Ensure everyone uses the same definitions:

* Standard KPI calculations
* Consistent aggregations
* Unified dimensions

### Fast Dashboards

Power dashboards with optimized data models:

* Selected tables and columns for faster queries
* Clear relationships between tables
* Multi-tenant data isolation

### Multi-Tenant Applications

Enable data isolation for SaaS applications:

* Table-level tenancy for single-database setups
* Database-level tenancy for complete isolation
* Multi-database tenancy for complex architectures

## Best Practices

<AccordionGroup>
  <Accordion title="Start Simple" icon="seedling">
    Begin with core tables and metrics. Expand the datamart gradually as needs grow.
  </Accordion>

  <Accordion title="Use Business Language" icon="users">
    Name fields and tables using terms your business users understand, not technical jargon.
  </Accordion>

  <Accordion title="Document Everything" icon="file-text">
    Add descriptions to all fields. This helps both dashboard users and AI understand your data.
  </Accordion>

  <Accordion title="Optimize for Common Queries" icon="gauge-high">
    Model your datamart around your most frequent query patterns.
  </Accordion>

  <Accordion title="Keep It Fresh" icon="rotate">
    Set up regular updates to ensure datamart data is current.
  </Accordion>
</AccordionGroup>

## Datamart vs. Data Warehouse

| Aspect          | Datamart                     | Data Warehouse            |
| --------------- | ---------------------------- | ------------------------- |
| **Scope**       | Focused on specific use case | Enterprise-wide data      |
| **Purpose**     | Analytics & AI queries       | Source of truth storage   |
| **Schema**      | Denormalized, optimized      | Normalized, comprehensive |
| **Users**       | Business analysts, AI        | Data engineers, analysts  |
| **Performance** | Optimized for reads          | Balanced read/write       |

## Datamart Features

### Table & Column Management

* Select tables from schemas within your datasource
* Configure which columns are visible
* Preview table data before including
* Hide tables or columns as needed

### Relationships

* Define relationships between tables in your datamart
* Configure cardinality and join types

### Metadata & Descriptions

* Table descriptions
* Column descriptions and labels
* Business-friendly aliases

## Datamart API

Manage datamarts programmatically through the Data App API:

### List Datamarts

```bash theme={"dark"}
curl --request GET \
  --url https://api.usedatabrain.com/api/v2/datamarts \
  --header 'Authorization: Bearer YOUR_API_TOKEN'
```

### Create Datamart

```bash theme={"dark"}
curl --request POST \
  --url https://api.usedatabrain.com/api/v2/datamarts \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Sales Datamart",
    "datasourceId": "your-datasource-id"
  }'
```

### Update Datamart

```bash theme={"dark"}
curl --request PUT \
  --url https://api.usedatabrain.com/api/v2/datamarts \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": "your-datamart-id",
    "name": "Updated Name"
  }'
```

<Card title="Data App API" icon="code" href="/developer-docs/helpers/api-reference/data-app-api">
  Complete Data App API reference
</Card>

***

## Semantic Layer & AI Chat

The semantic layer and AI chat features are built **on top of** your datamart. Once your datamart is created, you configure the semantic layer to make it AI-friendly.

### Semantic Layer Basics

The semantic layer translates technical data structures into business concepts.

#### Business Names

```text theme={"dark"}
customer_acq_date → Customer Acquisition Date
mrr               → Monthly Recurring Revenue
cac               → Customer Acquisition Cost
```

#### Descriptions

Add helpful descriptions that appear in AI responses and tooltips:

* What the metric or column measures
* How it's calculated
* When to use it
* Known limitations

#### Data Types

Define appropriate data types:

* Dimensions (categories)
* Measures (numeric values)
* Dates and times
* Text and strings

### AI Chat Mode Integration

Datamarts power AI chat mode, enabling natural language analytics.

#### How It Works

1. **User asks a question** – e.g. "What were total sales last month?"
2. **AI understands intent** – uses datamart metadata and semantic layer to interpret the question
3. **Generate SQL** – creates an optimized query based on the datamart structure
4. **Return results** – displays data with a natural language explanation

#### LLM Configuration

Connect your preferred LLM:

* OpenAI GPT
* Claude AI
* Azure OpenAI
* Llama
* Mixtral

<Card title="LLM Connectors" icon="plug" href="/developer-docs/helpers/llm-connectors">
  Configure AI models for chat mode
</Card>

### Datamart Management for Semantic Layer

Once the datamart exists, you configure the semantic layer and examples from the Semantic Layer and Datamart Description pages.

#### Datamart Description

Add metadata and context to your datamart:

* **Table Descriptions**: Add business-friendly descriptions for tables
* **Column Descriptions**: Document what each column represents
* **Relationships**: Define relationships between tables
* **Examples**: Add example questions for AI chat mode
* **Synonyms**: Configure column synonyms for better AI understanding

#### Semantic Layer Tools

* **Lab**: Generate and test synthetic queries
* **Playground**: Test natural language questions against the datamart
* **Sample Set**: Configure sample data for AI training and evaluation

### Best Practices for Semantic Layer

<AccordionGroup>
  <Accordion title="Align With Business Language" icon="users">
    Use the same terms your business stakeholders use in meetings and reports.
  </Accordion>

  <Accordion title="Iterate With Real Questions" icon="robot">
    Test the semantic layer using real questions from users and refine names, descriptions, and examples.
  </Accordion>

  <Accordion title="Keep Examples Up To Date" icon="file-text">
    Regularly review and update example questions and feedback to improve AI answers over time.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Create a Datamart" icon="plus" href="/guides/datasources/create-a-datamart">
    Build your first datamart
  </Card>

  <Card title="Enable AI Chat" icon="message-bot" href="/developer-docs/chat-mode/step-1-create-datamart-and-workspace">
    Set up AI-powered queries
  </Card>

  <Card title="Semantic Layer" icon="layer-group" href="/guides/datasources/semantic-layer">
    Configure your semantic layer
  </Card>

  <Card title="LLM Architecture" icon="brain" href="/developer-docs/helpers/llm-architecture">
    Understand AI integration
  </Card>
</CardGroup>