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

# Create Dimension Tables

> Learn how to create dimension tables using the API.

export const HowToSchema = ({name, description, steps = []}) => {
  const schema = {
    "@context": "https://schema.org",
    "@type": "HowTo",
    name,
    description
  };
  if (steps.length > 0) {
    schema.step = steps.map((s, i) => ({
      "@type": "HowToStep",
      position: i + 1,
      name: typeof s === "string" ? s : s.name,
      text: typeof s === "string" ? s : s.text || s.name
    }));
  }
  return <script type="application/ld+json" dangerouslySetInnerHTML={{
    __html: JSON.stringify(schema)
  }} />;
};

<HowToSchema
  name="Create Dimension Tables"
  description="Learn how to create dimension tables using the API."
  steps={[
{
  name: "Before You Begin",
  text: "Before creating a dimension table, ensure you have: - An API access token with appropriate permissions - Created the entities you want to segment",
},
{
  name: "Create a Dimension Table",
  text: "Create a dimension table with a country dimension:",
},
{
  name: "Create a Dimension Table with Multiple Dimensions",
  text: "Track multiple attributes for segmentation:",
},
{
  name: "Dimension Types",
  text: "Supported dimension types: - COLUMN_TYPE_STRING: Categorical values (country, platform, etc.) - COLUMN_TYPE_BOOLEAN: Binary attributes (is_premium, is_active, etc.)",
},
{
  name: "Data Delivery",
  text: "After creation, the dimension table enters the CREATING state. Confidence runs a sample query to verify the SQL produces the expected columns, then transitions to either ACTIVE or FAILED.",
},
]}
/>

Create dimension tables that let you segment your entities for analysis.

## Before You Begin

Before creating a dimension table, ensure you have:

* An API access token with appropriate permissions
* Created the entities you want to segment
* Prepared a SQL query that selects dimension data from your data warehouse
* Identified entity and dimension columns

## Create a Dimension Table

Create a dimension table with a country dimension:

```bash theme={null}
curl -X POST "https://metrics.confidence.dev/v1/dimensionTables" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "User Location",
    "sql": "SELECT * FROM confidence.user_data.location",
    "timestampColumn": {
      "name": "date",
      "type": "COLUMN_TYPE_STRING",
      "repeated": false
    },
    "entityColumnMapping": [
      {
        "column": {
          "name": "user_id",
          "type": "COLUMN_TYPE_STRING",
          "repeated": false
        },
        "entity": "entities/user"
      }
    ],
    "dimensions": [
      {
        "name": "country",
        "type": "COLUMN_TYPE_STRING",
        "repeated": false
      }
    ],
    "dataDeliveredUntilUpdateStrategyConfig": {
      "dailyUpdateConfig": {}
    }
  }'
```

## Create a Dimension Table with Multiple Dimensions

Track multiple attributes for segmentation:

```bash theme={null}
curl -X POST "https://metrics.confidence.dev/v1/dimensionTables" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "User Demographics",
    "sql": "SELECT * FROM user_demographics",
    "timestampColumn": {
      "name": "updated_at",
      "type": "COLUMN_TYPE_STRING",
      "repeated": false
    },
    "entityColumnMapping": [
      {
        "column": {
          "name": "user_id",
          "type": "COLUMN_TYPE_STRING",
          "repeated": false
        },
        "entity": "entities/user"
      }
    ],
    "dimensions": [
      {
        "name": "country",
        "type": "COLUMN_TYPE_STRING",
        "repeated": false
      },
      {
        "name": "age_group",
        "type": "COLUMN_TYPE_STRING",
        "repeated": false
      },
      {
        "name": "is_premium",
        "type": "COLUMN_TYPE_BOOLEAN",
        "repeated": false
      }
    ],
    "dataDeliveredUntilUpdateStrategyConfig": {
      "dailyUpdateConfig": {}
    }
  }'
```

## Dimension Types

Supported dimension types:

* `COLUMN_TYPE_STRING`: Categorical values (country, platform, etc.)
* `COLUMN_TYPE_BOOLEAN`: Binary attributes (`is_premium`, `is_active`, etc.)
* `COLUMN_TYPE_INTEGER`: Numeric categories (age group codes, tier levels, etc.)

## Data Delivery

After creation, the dimension table enters the `CREATING` state. Confidence runs a sample query to verify the SQL produces the expected columns, then transitions to either `ACTIVE` or `FAILED`.

## Next Steps

After creating dimension tables:

* Use dimensions to segment metrics in experiment analysis
* [Create metrics](./create-metric) that you can break down by these dimensions
* Configure experiments to analyze results by dimension