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

# Update Datamart

> Update an existing datamart's table configurations and tenancy settings without recreating from scratch.

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.

<Warning>
  **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.
</Warning>

<Note>
  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.
</Note>

## 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

<ParamField header="Authorization" type="string" required>
  Bearer token for API authentication. Use your service token.

  ```
  Authorization: Bearer dbn_live_abc123...
  ```
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be set to `application/json` for all requests.

  ```
  Content-Type: application/json
  ```
</ParamField>

## Request Body

<ParamField body="datamartName" type="string" required>
  Name of the existing datamart to update. Must match exactly (case-sensitive).

  <Expandable title="Finding datamart names">
    * Use the [List Datamarts API](/developer-docs/helpers/api-reference/list-datamarts) to get all datamart names
    * Names are case-sensitive and must match exactly
    * This field identifies which datamart to update (cannot be used to rename)
  </Expandable>
</ParamField>

<ParamField body="tableList" type="array">
  Array of tables with columns to include in the datamart. Optional - if not provided, only tenancy settings will be updated.

  <Warning>
    **Replaces all existing tables:** The new table list completely replaces the existing configuration. Include all tables you want to keep.
  </Warning>
</ParamField>

<ParamField body="tableList.name" type="string" required>
  Table name from your datasource. Must exist in the datasource schema.
</ParamField>

<ParamField body="tableList.schemaName" type="string">
  Optional schema name (required only for schema-based datasources like PostgreSQL, SQL Server).
</ParamField>

<ParamField body="tableList.clientColumn" type="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.

  <Expandable title="Client column usage">
    * Used for table-level tenancy when `tenancyLevel` is `TABLE`
    * The column should contain client/tenant identifiers
  </Expandable>
</ParamField>

<ParamField body="tableList.isHide" type="boolean">
  Optional flag to hide the table from the datamart interface.
</ParamField>

<ParamField body="tableList.label" type="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.

  <Expandable title="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
  </Expandable>
</ParamField>

<ParamField body="tableList.wildcard" type="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.

  <Expandable title="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
  </Expandable>
</ParamField>

<ParamField body="tableList.columns" type="array" required>
  List of column objects for this table. Must be non-empty.
</ParamField>

<ParamField body="tableList.columns.name" type="string" required>
  Column name from the table. Must exist in the datasource schema.
</ParamField>

<ParamField body="tableList.columns.alias" type="string">
  Optional alias for the column to display a different name.
</ParamField>

<ParamField body="tableList.columns.label" type="string">
  Optional label for the column for better readability.
</ParamField>

<ParamField body="tableList.columns.isHide" type="boolean">
  Optional flag to hide the column from the datamart interface. Defaults to `false`.
</ParamField>

<ParamField body="tableList.columns.isCustomColumn" type="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.

  <Expandable title="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
  </Expandable>
</ParamField>

<ParamField body="tableList.columns.sql" type="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.

  <Expandable title="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`
  </Expandable>
</ParamField>

<ParamField body="tableList.columns.isAggregate" type="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.

  <Expandable title="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
  </Expandable>
</ParamField>

<ParamField body="tableList.columns.isApplyTimezone" type="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.

  <Info>
    This field has no effect unless `params.timezone` is set in the guest token. See [Timezone Handling in Guest Token](/developer-docs/solutions-alchemy/guest-token-timezone) for the full setup guide.
  </Info>

  <Expandable title="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
  </Expandable>
</ParamField>

<ParamField body="tenancySettings" type="object">
  Multi-tenant configuration for the datamart. Optional - if not provided, existing tenancy settings remain unchanged.

  <Expandable title="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 optional primary database routing
    * All fields are optional; omitted fields retain their existing values
  </Expandable>
</ParamField>

<ParamField body="tenancySettings.tenancyLevel" type="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.
</ParamField>

<ParamField body="tenancySettings.clientColumnType" type="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.
</ParamField>

<ParamField body="tenancySettings.primaryDatabase" type="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`.

  <Warning>
    To avoid accidental clearing, include `tenancySettings.tenancyLevel` whenever you send `tenancySettings`.
  </Warning>
</ParamField>

<ParamField body="tenancySettings.schemaName" type="string">
  Schema name where the client mapping table is located.

  **Required when** `tenancySettings.tenancyLevel` is set to `TABLE` in the request.
</ParamField>

<ParamField body="tenancySettings.tableName" type="string">
  Name of the table that contains client mapping information.

  **Required when** `tenancySettings.tenancyLevel` is set to `TABLE` in the request.
</ParamField>

<ParamField body="tenancySettings.tableClientNameColumn" type="string">
  Column name in the mapping table that stores the client identifier.

  **Required when** `tenancySettings.tenancyLevel` is set to `TABLE` in the request.
</ParamField>

<ParamField body="tenancySettings.tablePrimaryKeyColumn" type="string">
  Primary key column of the client mapping table.

  **Required when** `tenancySettings.tenancyLevel` is set to `TABLE` in the request.
</ParamField>

<ParamField body="relationships" type="array">
  Optional array of table relationships to define how tables in the datamart are connected. Relationships enable joins between tables for more complex queries.

  <Warning>
    **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.
  </Warning>

  <Expandable title="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 - omit this field to keep existing relationships unchanged
  </Expandable>
</ParamField>

<ParamField body="relationships.parentTableName" type="string" required>
  Name of the parent table in the relationship.
</ParamField>

<ParamField body="relationships.parentColumnName" type="string" required>
  Column name in the parent table that participates in the relationship.
</ParamField>

<ParamField body="relationships.childTableName" type="string" required>
  Name of the child table in the relationship.
</ParamField>

<ParamField body="relationships.childColumnName" type="string" required>
  Column name in the child table that participates in the relationship.
</ParamField>

<ParamField body="relationships.relationshipName" type="string" required>
  A descriptive name for the relationship (e.g., "orders\_to\_customers").
</ParamField>

<ParamField body="relationships.cardinality" type="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.
</ParamField>

<ParamField body="relationships.join" type="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.
</ParamField>

## Response

<ResponseField name="id" type="string">
  The name of the updated datamart (same as the input datamartName) on success.
</ResponseField>

<ResponseField name="error" type="object">
  Error object returned only when the request fails. Not included in successful responses.

  <Expandable title="error properties">
    <ResponseField name="code" type="string">
      Error code identifying the type of error.
    </ResponseField>

    <ResponseField name="message" type="string">
      Human-readable error message describing what went wrong.
    </ResponseField>
  </Expandable>
</ResponseField>

## Examples

<Panel>
  <RequestExample>
    ```bash cURL - Update Tables Only theme={"dark"}
    curl --request PUT \
      --url https://api.usedatabrain.com/api/v2/data-app/datamarts \
      --header 'Authorization: Bearer dbn_live_abc123...' \
      --header 'Content-Type: application/json' \
      --data '{
        "datamartName": "sales-analytics",
        "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
              },
              {
                "name": "order_date",
                "alias": "date",
                "label": "Order Date",
                "isHide": false
              },
              {
                "name": "total_amount",
                "label": "Total Amount",
                "isHide": true
              }
            ]
          },
          {
            "schemaName": "public",
            "name": "customers",
            "label": "Customer Records",
            "clientColumn": "tenant_id",
            "isHide": false,
            "columns": [
              {
                "name": "customer_id",
                "alias": "id",
                "isHide": false
              },
              {
                "name": "customer_name",
                "alias": "name",
                "isHide": false
              }
            ]
          }
        ]
      }'
    ```

    ```bash cURL - Update Tenancy Settings Only theme={"dark"}
    curl --request PUT \
      --url https://api.usedatabrain.com/api/v2/data-app/datamarts \
      --header 'Authorization: Bearer dbn_live_abc123...' \
      --header 'Content-Type: application/json' \
      --data '{
        "datamartName": "sales-analytics",
        "tenancySettings": {
          "tenancyLevel": "TABLE",
          "clientColumnType": "STRING",
          "schemaName": "public",
          "tableName": "clients",
          "tableClientNameColumn": "client_name",
          "tablePrimaryKeyColumn": "id"
        }
      }'
    ```

    ```bash cURL - Update to Multi-Database Tenancy theme={"dark"}
    curl --request PUT \
      --url https://api.usedatabrain.com/api/v2/data-app/datamarts \
      --header 'Authorization: Bearer dbn_live_abc123...' \
      --header 'Content-Type: application/json' \
      --data '{
        "datamartName": "sales-analytics",
        "tenancySettings": {
          "tenancyLevel": "MULTI_DATABASE",
          "primaryDatabase": "core_analytics"
        }
      }'
    ```

    ```bash cURL - Update Both Tables and Tenancy theme={"dark"}
    curl --request PUT \
      --url https://api.usedatabrain.com/api/v2/data-app/datamarts \
      --header 'Authorization: Bearer dbn_live_abc123...' \
      --header 'Content-Type: application/json' \
      --data '{
        "datamartName": "sales-analytics",
        "tableList": [
          {
            "schemaName": "public",
            "name": "orders",
            "clientColumn": "tenant_id",
            "isHide": false,
            "columns": [
              {"name": "order_id", "alias": "id", "isHide": false},
              {"name": "customer_id", "isHide": false}
            ]
          }
        ],
        "tenancySettings": {
          "tenancyLevel": "TABLE",
          "clientColumnType": "NUMBER",
          "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"
          }
        ]
      }'
    ```

    ```bash cURL - Update Relationships Only theme={"dark"}
    curl --request PUT \
      --url https://api.usedatabrain.com/api/v2/data-app/datamarts \
      --header 'Authorization: Bearer dbn_live_abc123...' \
      --header 'Content-Type: application/json' \
      --data '{
        "datamartName": "sales-analytics",
        "relationships": [
          {
            "parentTableName": "orders",
            "parentColumnName": "customer_id",
            "childTableName": "customers",
            "childColumnName": "id",
            "relationshipName": "orders_to_customers",
            "cardinality": "ManyToOne",
            "join": "LEFT JOIN"
          }
        ]
      }'
    ```

    ```bash cURL - Add Custom Columns theme={"dark"}
    curl --request PUT \
      --url https://api.usedatabrain.com/api/v2/data-app/datamarts \
      --header 'Authorization: Bearer dbn_live_abc123...' \
      --header 'Content-Type: application/json' \
      --data '{
        "datamartName": "sales-analytics",
        "tableList": [
          {
            "schemaName": "public",
            "name": "orders",
            "label": "Customer Orders",
            "columns": [
              {
                "name": "order_id",
                "alias": "id",
                "label": "Order ID"
              },
              {
                "name": "quantity",
                "label": "Quantity"
              },
              {
                "name": "unit_price",
                "alias": "total_revenue",
                "label": "Total Revenue",
                "isCustomColumn": true,
                "sql": "quantity * unit_price"
              },
              {
                "name": "order_date",
                "alias": "order_year",
                "label": "Order Year",
                "isCustomColumn": true,
                "sql": "EXTRACT(YEAR FROM order_date)"
              },
              {
                "name": "created_at",
                "label": "Created At",
                "isApplyTimezone": true
              }
            ]
          }
        ]
      }'
    ```

    ```javascript Node.js icon="fa-brands fa-node-js" theme={"dark"}
    const response = await fetch('https://api.usedatabrain.com/api/v2/data-app/datamarts', {
      method: 'PUT',
      headers: {
        'Authorization': 'Bearer dbn_live_abc123...',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        datamartName: 'sales-analytics',
        tableList: [
          {
            schemaName: 'public',
            name: 'orders',
            label: 'Customer Orders',
            clientColumn: 'tenant_id',
            columns: [
              { name: 'order_id', alias: 'id', label: 'Order ID' },
              { name: 'customer_id', label: 'Customer' },
              { name: 'order_date', alias: 'date', label: 'Order Date' }
            ]
          }
        ]
      })
    });

    const result = await response.json();

    if (result.error) {
      console.error('Update failed:', result.error.message);
    } else {
      console.log('Datamart updated:', result.id);
    }
    ```

    ```python Python icon="fa-brands fa-python" theme={"dark"}
    import requests

    response = requests.put(
        'https://api.usedatabrain.com/api/v2/data-app/datamarts',
        headers={
            'Authorization': 'Bearer dbn_live_abc123...',
            'Content-Type': 'application/json'
        },
        json={
            'datamartName': 'sales-analytics',
            'tableList': [
                {
                    'schemaName': 'public',
                    'name': 'orders',
                    'label': 'Customer Orders',
                    'clientColumn': 'tenant_id',
                    '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'
                }
            ]
        }
    )

    result = response.json()

    if result.get('error'):
        print(f"Update failed: {result['error']['message']}")
    else:
        print(f"Datamart updated: {result['id']}")
    ```

    ```ruby Ruby icon="fa-solid fa-gem" theme={"dark"}
    require 'net/http'
    require 'json'

    uri = URI('https://api.usedatabrain.com/api/v2/data-app/datamarts')
    http = Net::HTTP.new(uri.host, uri.port)
    http.use_ssl = true

    request = Net::HTTP::Put.new(uri)
    request['Authorization'] = 'Bearer dbn_live_abc123...'
    request['Content-Type'] = 'application/json'
    request.body = {
      datamartName: 'sales-analytics',
      tableList: [
        {
          schemaName: 'public',
          name: 'orders',
          label: 'Customer Orders',
          columns: [
            { name: 'order_id', alias: 'id', label: 'Order ID' },
            { name: 'customer_id', label: 'Customer' }
          ]
        }
      ]
    }.to_json

    response = http.request(request)
    result = JSON.parse(response.body)

    if result['error']
      puts "Update failed: #{result['error']['message']}"
    else
      puts "Datamart updated: #{result['id']}"
    end
    ```

    ```go Go icon="fa-brands fa-golang" theme={"dark"}
    package main

    import (
        "bytes"
        "encoding/json"
        "fmt"
        "net/http"
    )

    type UpdateDatamartRequest struct {
        DatamartName    string          `json:"datamartName"`
        TableList       []TableInfo     `json:"tableList,omitempty"`
        TenancySettings *TenancySettings `json:"tenancySettings,omitempty"`
    }

    type TableInfo struct {
        SchemaName string       `json:"schemaName,omitempty"`
        Name       string       `json:"name"`
        Label      string       `json:"label,omitempty"`
        Columns    []ColumnInfo `json:"columns"`
    }

    type ColumnInfo struct {
        Name   string `json:"name"`
        Alias  string `json:"alias,omitempty"`
        Label  string `json:"label,omitempty"`
        IsHide bool   `json:"isHide,omitempty"`
    }

    type TenancySettings struct {
        TenancyLevel           string `json:"tenancyLevel,omitempty"`
        ClientColumnType       string `json:"clientColumnType,omitempty"`
        SchemaName             string `json:"schemaName,omitempty"`
        TableName              string `json:"tableName,omitempty"`
        TableClientNameColumn  string `json:"tableClientNameColumn,omitempty"`
        TablePrimaryKeyColumn  string `json:"tablePrimaryKeyColumn,omitempty"`
    }

    func main() {
        reqData := UpdateDatamartRequest{
            DatamartName: "sales-analytics",
            TableList: []TableInfo{
                {
                    SchemaName: "public",
                    Name:       "orders",
                    Label:      "Customer Orders",
                    Columns: []ColumnInfo{
                        {Name: "order_id", Alias: "id", Label: "Order ID"},
                        {Name: "customer_id", Label: "Customer"},
                    },
                },
            },
        }
        
        jsonData, _ := json.Marshal(reqData)
        
        req, _ := http.NewRequest("PUT", 
            "https://api.usedatabrain.com/api/v2/data-app/datamarts", 
            bytes.NewBuffer(jsonData))
        req.Header.Set("Authorization", "Bearer dbn_live_abc123...")
        req.Header.Set("Content-Type", "application/json")
        
        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()
        
        fmt.Println("Datamart updated successfully")
    }
    ```

    ```php PHP icon="fa-brands fa-php" theme={"dark"}
    <?php
    $url = 'https://api.usedatabrain.com/api/v2/data-app/datamarts';
    $data = [
        'datamartName' => 'sales-analytics',
        'tableList' => [
            [
                'schemaName' => 'public',
                'name' => 'orders',
                'label' => 'Customer Orders',
                'columns' => [
                    [
                        'name' => 'order_id',
                        'alias' => 'id',
                        'label' => 'Order ID'
                    ],
                    [
                        'name' => 'customer_id',
                        'label' => 'Customer'
                    ]
                ]
            ]
        ]
    ];

    $options = [
        'http' => [
            'header' => [
                'Authorization: Bearer dbn_live_abc123...',
                'Content-Type: application/json'
            ],
            'method' => 'PUT',
            'content' => json_encode($data)
        ]
    ];

    $context = stream_context_create($options);
    $response = file_get_contents($url, false, $context);
    $result = json_decode($response, true);

    if (isset($result['error'])) {
        echo "Update failed: " . $result['error']['message'];
    } else {
        echo "Datamart ID: " . $result['id'];
    }
    ?>
    ```
  </RequestExample>

  <ResponseExample>
    ```json 200 - Success theme={"dark"}
    {
      "id": "sales-analytics"
    }
    ```

    ```json 400 - Datamart Not Found theme={"dark"}
    {
      "error": {
        "code": "INVALID_DATAMART",
        "message": "invalid datamart name."
      }
    }
    ```

    ```json 400 - Invalid Table Structure theme={"dark"}
    {
      "error": {
        "code": "INVALID_REQUEST_BODY",
        "message": "Invalid table or column structure"
      }
    }
    ```

    ```json 400 - Invalid Schema or Table theme={"dark"}
    {
      "error": {
        "code": "INVALID_REQUEST_BODY",
        "message": "Invalid schema or table name"
      }
    }
    ```

    ```json 400 - Invalid Column Names theme={"dark"}
    {
      "error": {
        "code": "INVALID_REQUEST_BODY",
        "message": "Invalid column names in table"
      }
    }
    ```

    ```json 400 - Validation Error theme={"dark"}
    {
      "error": {
        "code": "INVALID_REQUEST_BODY",
        "message": "\"datamartName\" is required"
      }
    }
    ```

    ```json 401 - Unauthorized theme={"dark"}
    {
      "error": {
        "code": "INVALID_DATA_APP_API_KEY",
        "message": "invalid or expired API KEY, data app not found"
      }
    }
    ```

    ```json 500 - Server Error theme={"dark"}
    {
      "error": {
        "code": "INTERNAL_SERVER_ERROR",
        "message": "Internal Server Error"
      }
    }
    ```
  </ResponseExample>
</Panel>

## HTTP Status Code Summary

| Status Code | Description                                       |
| ----------- | ------------------------------------------------- |
| `200`       | **OK** - Datamart updated successfully            |
| `400`       | **Bad Request** - Invalid request parameters      |
| `401`       | **Unauthorized** - Invalid or missing API key     |
| `500`       | **Internal Server Error** - Server error occurred |

## Possible Errors

| Error Code                 | HTTP Status | Description                   |
| -------------------------- | ----------- | ----------------------------- |
| `INVALID_REQUEST_BODY`     | 400         | Missing or invalid parameters |
| `INVALID_DATAMART`         | 400         | Datamart not found            |
| `INVALID_DATA_APP_API_KEY` | 401         | Invalid API key               |
| `INTERNAL_SERVER_ERROR`    | 500         | Server error                  |

## Quick Start Guide

<Steps>
  <Step title="Get current configuration">
    Retrieve the existing datamart configuration before making changes:

    ```bash theme={"dark"}
    curl --request GET \
      --url 'https://api.usedatabrain.com/api/v2/data-app/datamarts?isPagination=false' \
      --header 'Authorization: Bearer dbn_live_abc123...'
    ```

    <Check>
      Save this response in case you need to rollback your changes.
    </Check>
  </Step>

  <Step title="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

    <Tip>
      If only updating tenancy, omit the tableList field to keep existing tables intact.
    </Tip>
  </Step>

  <Step title="Update the datamart">
    Make the update request:

    ```bash theme={"dark"}
    curl --request PUT \
      --url https://api.usedatabrain.com/api/v2/data-app/datamarts \
      --header 'Authorization: Bearer dbn_live_abc123...' \
      --header 'Content-Type: application/json' \
      --data '{
        "datamartName": "sales-analytics",
        "tableList": [
          {
            "schemaName": "public",
            "name": "orders",
            "label": "Customer Orders",
            "clientColumn": "tenant_id",
            "columns": [
              {"name": "order_id", "alias": "id"},
              {"name": "customer_id"}
            ]
          }
        ]
      }'
    ```

    <Check>
      Successful response returns the datamart name.
    </Check>
  </Step>

  <Step title="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

    <Warning>
      If metrics break, you can update again with your saved previous configuration to rollback.
    </Warning>
  </Step>
</Steps>

## Next Steps

<CardGroup cols={2}>
  <Card title="Create Datamart" icon="plus" href="/developer-docs/helpers/api-reference/create-datamart">
    Create a new datamart from scratch
  </Card>

  <Card title="List Datamarts" icon="list" href="/developer-docs/helpers/api-reference/list-datamarts">
    View all datamarts in your organization
  </Card>

  <Card title="Delete Datamart" icon="trash" href="/developer-docs/helpers/api-reference/delete-datamart">
    Remove datamarts you no longer need
  </Card>

  <Card title="Datamart Concepts" icon="book" href="/getting-started/core-concepts/datamarts">
    Learn more about datamarts
  </Card>
</CardGroup>