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

> Define a metric in Confidence by setting up an entity, assignment table, fact table, and metric definition.

Create a metric that measures the average weekly sales per user. The setup
depends on where your data lives:

* **Confidence Cloud**, the default for every new account: choose an entity,
  send an event, and Confidence generates the fact table for you.
* **Warehouse Native**: create an entity, an assignment table, and a fact table
  in your own data warehouse with SQL.

Both paths end with the same step: [create the metric](#create-a-metric).

## Before You Begin

* You need a [Confidence](https://app.confidence.spotify.com) account.
* To do steps with AI, connect the Confidence MCP servers or use the Confidence
  Agent. See [Set up Confidence for your AI assistant](/docs/guides/build-with-an-ai-assistant).

<Tip>
  Use the metric in [Roll out a change](/docs/guides/roll-out-a-change) or
  [Run an A/B test](/docs/guides/run-an-ab-test) to measure the effect of a
  change.
</Tip>

## Set Up the Data

<Tabs>
  <Tab title="Confidence Cloud">
    On Confidence Cloud you don't write SQL tables. You send events, and Confidence
    generates a fact table for each event that references an entity. See
    [Metrics without SQL](/docs/start/confidence-cloud#metrics-without-sql).

    ### Choose an Entity

    An [entity](/docs/capabilities/metrics/entities) represents what you measure,
    such as a user, an account, or a device. Every account comes with two
    built-in entities: `User` and `Visitor`. This guide uses `User`.

    To measure another kind of unit, [create an entity](/docs/capabilities/metrics/create-entity)
    in the app or with the API. The MCP servers can't create entities, but
    `listEntities` shows the ones you have.

    ### Define the Event

    An event is a record of something that happens in your product, such as a
    purchase. For this guide, define a `purchase` event with these fields:

    * `user_id`: a string that references the `User` entity
    * `amount`: a number, which becomes a measurement
    * `product`: a string, which becomes a dimension

    You can define the event schema in advance, or send events first and then
    review and create the event from the schema that Confidence detects.

    **In the app**:

    * To define the event in advance, select **Events** in the sidebar and click
      **Create**. In the **Create event** dialog, enter `purchase` and add the
      fields. Set `user_id` to type String with semantic type Entity.
    * To create the event from events you already send, find `purchase` in the
      **Events** table. It shows as **Sent but not stored**. In its row, click the
      outlined **Create**, review the schema, set `user_id` to semantic
      type Entity, and click **Create**.

    At least one String field must have semantic type Entity. Without an entity
    field, Confidence generates no fact table.

    **With AI**: the Flags MCP server creates event definitions with the
    `createEventDefinition` tool. For example:

    ```text theme={null}
    Create a Confidence event definition called "purchase" with a string field
    user_id that references the User entity, a double field amount, and a string
    field product.
    ```

    ### Send Events

    Send the event from your application with a
    [Confidence SDK](/docs/reference/sdks/overview) or the events API. To check
    that events arrive, ask your AI assistant to query event usage. It uses the
    `queryEventsUsage` tool.

    ### Use the Generated Fact Table

    Confidence creates a fact table for the event as soon as the event exists:

    * Numeric fields, such as `amount`, become measurements.
    * Other fields, such as `product`, become dimensions.
    * The event timestamp becomes the timestamp column.

    An event that references no entity gets no fact table, because a fact table
    needs an entity to join assignments on. Assignments come from flag resolves
    through the built-in connection, so you don't create an assignment table.

    The generated fact table has the same ID as the event, for example
    `purchase`. It appears in the regular list of fact tables. To find it, select
    **Admin > Data Tables > Fact tables** in the app, or ask your AI assistant to
    list fact tables (`listFactTables`).
  </Tab>

  <Tab title="Warehouse Native">
    On Warehouse Native you define the entity, the assignment table, and the fact
    table yourself, with SQL against your own data warehouse.

    Before you begin:

    * [Connect your data warehouse](/docs/start/warehouse-native) to Confidence.
    * Have assignment data and fact data in your data warehouse.

    ### Create an Entity

    <Note>
      The MCP servers can't create entities. `listEntities` shows the entities you
      already have. Create new entities in the app or with the API.
    </Note>

    An entity is a representation of the users that are part of your experiments.
    Entities can be anything really, but typically they are users, customers, or
    visitors.

    In Confidence, the entity connects other concepts such as experiments,
    variants, facts, dimensions and metrics to each other. It's via the entity that
    Confidence can understand how it should traverse the data in your data
    warehouse. For example, when you configure an experiment to use the
    `User` entity, Confidence only considers metrics that use facts that
    have a relationship to the `User` entity.

    Confidence comes with two default entities: `User` and `Visitor`. If you want to
    experiment on and create metrics for another entity, follow these steps.

    <Steps>
      <Step title="Go to Confidence" />

      <Step title="Navigate to Entities">
        On the left sidebar, select **Admin > Entities**.
      </Step>

      <Step title="Click + Create" />

      <Step title="Enter User as the name of the entity" />

      <Step title="Select a data type">
        Select a data type for how your data warehouse represents the entity. For the sake of this tutorial, select `String`.
      </Step>

      <Step title="Click Create" />
    </Steps>

    You now have an entity that you can tie other concepts to. Next, use the entity
    in an assignment table so that Confidence knows how the entity is assigned to
    experiments and variants.

    ### Create an Assignment Table

    <Note>
      If you already have an assignment table, skip to [Create a fact table](#create-a-fact-table).
    </Note>

    <Tip>
      **With AI**: the Flags MCP server can create the assignment table for you with
      the `createAssignmentTable` tool. For example:

      ```text theme={null}
      Create an assignment table called "assignment" in Confidence that reads from
      assignment_log. Use timestamp as the timestamp column, user_id as the User
      entity column, experiment_id as the experiment key and variant_id as the
      variant key.
      ```
    </Tip>

    The most fundamental part of Confidence Metrics is the experiment assignment
    data. Without it you can't compute metrics for an A/B test or any type of
    experiment.

    Assignment data is a log of records that contain information about how
    users were assigned to experiments and variants. Confidence needs the following
    data:

    * A **timestamp** that indicates when the assignment happened.
    * An **entity identifier**, normally a user identifier, that uniquely
      identifies the user that was assigned a variant.
    * An **experiment identifier** that identifies the experiment that the user was
      assigned to.
    * A **variant identifier** that identifies the variant that the user was
      assigned to.

    Any table in your data warehouse can store the assignment data. For
    Confidence to understand the data, you need to tell Confidence where to find it
    and how to interpret it. You define this in your [Assignment Table](/docs/capabilities/metrics/assignment-tables),
    which is a query that projects the data
    outlined above. You can write the query in any SQL dialect that your data
    warehouse supports.

    For this tutorial, your assignment data should exist in a table
    called `assignment_log` in your data warehouse.
    Data should be continuously appended to the table as users are assigned to experiments.

    The table has the following schema:

    ```sql theme={null}
    CREATE TABLE assignment_log (
      timestamp TIMESTAMP,
      user_id STRING,
      experiment_id STRING,
      variant_id STRING
    )
    ```

    Follow these steps to set up an assignment table:

    <Steps>
      <Step title="Go to Confidence" />

      <Step title="Navigate to Assignment tables">
        On the left sidebar, select **Admin > Data Tables > Assignment tables**.
      </Step>

      <Step title="Click + Create" />

      <Step title="Give the table a name">
        Give the table a name, such as `assignment`. If your data comes from a particular feature flagging system, you can name it after that, for example `launchdarkly`.
      </Step>

      <Step title="Enter the SQL query">
        Enter the SQL query that projects the assignment data from your data warehouse.

        <CodeGroup>
          ```sql BigQuery theme={null}
          SELECT
            timestamp,
            user_id,
            experiment_id,
            variant_id
          FROM assignment_log
          ```

          ```sql Redshift theme={null}
          SELECT
            timestamp,
            user_id,
            experiment_id,
            variant_id
          FROM assignment_log
          ```

          ```sql Snowflake theme={null}
          SELECT
            timestamp,
            user_id,
            experiment_id,
            variant_id
          FROM assignment_log
          ```
        </CodeGroup>
      </Step>

      <Step title="Click Run Query">
        This executes the query and shows you a preview.

        <Note>
          To make the query cheap, the query runs with a `LIMIT` clause to limit the number of rows.
        </Note>
      </Step>

      <Step title="Map the columns">
        To the right of the result table, you see a form where you can specify the columns in the result that correspond to the assignment data. It's this mapping that tells Confidence how to interpret the data. Fill in the form as follows:

        * `timestamp` as the timestamp column.
        * For entity, select `User` and enter `user_id` as the entity column.
        * `experiment_id` as the experiment key column.
        * `variant_id` as the variant key column.
      </Step>

      <Step title="Configure data delivery cadence">
        For **Data delivery cadence** select `Data is delivered continuously`. Leave **Commit delay** at its default value. You can read more about these settings on the [data delivery cadence](/docs/capabilities/metrics/delivery-cadence) page.
      </Step>

      <Step title="Click Create" />
    </Steps>

    You have now set up an assignment table and can move on to create
    fact tables and metrics for your experiments.

    ### Create a Fact Table

    Facts are measurable data that you want to use in your metrics. Facts can be
    anything that you can measure, such as revenue, number of clicks, or number of
    impressions.

    Facts are stored in tables in your data warehouse. For Confidence to understand
    the data, you need to tell Confidence where to find it and how to interpret it.

    This tutorial assumes you have your fact data in a table called
    `sales` in your data warehouse. Each time a sale occurs, the system adds a new
    row to the data. `amount` is the sales amount and `product` is the product sold.

    Assume that data is continuously appended to the table as sales happen.

    The table has the following schema:

    ```sql theme={null}
    CREATE TABLE sales (
      timestamp TIMESTAMP,
      user_id STRING,
      amount FLOAT,
      product STRING
    )
    ```

    <Note>
      The MCP servers can't create fact tables. Create the fact table in the app, as
      described here, or with the API.
    </Note>

    Follow these steps to set up a fact table:

    <Steps>
      <Step title="Go to Confidence" />

      <Step title="Navigate to Fact tables">
        On the left sidebar, select **Admin > Data Tables > Fact tables**.
      </Step>

      <Step title="Click + Create" />

      <Step title="Give the table a name">
        Give the table a name, such as `sales`.
      </Step>

      <Step title="Enter the SQL query">
        Enter the SQL query that projects the fact data from your data warehouse.

        <CodeGroup>
          ```sql BigQuery theme={null}
          SELECT
            timestamp,
            user_id,
            amount,
            product
          FROM sales
          ```

          ```sql Redshift theme={null}
          SELECT
            timestamp,
            user_id,
            amount,
            product
          FROM sales
          ```

          ```sql Snowflake theme={null}
          SELECT
            timestamp,
            user_id,
            amount,
            product
          FROM sales
          ```
        </CodeGroup>
      </Step>

      <Step title="Click Run Query">
        This executes the query and shows you a preview.
      </Step>

      <Step title="Map the columns">
        To the right of the result table, you see a form where you can specify the columns in the result that correspond to the fact data. It's this mapping that tells Confidence how to interpret the data. Fill in the form as follows:

        * Select `timestamp` as the timestamp column.
        * For entity, select `User` and select `user_id` as the entity column.
        * Add `amount` to the list of measurements.
        * Add `product` to the list of dimensions.
      </Step>

      <Step title="Configure data delivery cadence">
        For **Data delivery cadence** select `Data is delivered continuously`. Leave **Commit delay** at its default value. You can read more about these settings on the [data delivery cadence](/docs/capabilities/metrics/delivery-cadence) page.
      </Step>

      <Step title="Click Create" />
    </Steps>
  </Tab>
</Tabs>

## Create a Metric

The final step is the same on Confidence Cloud and Warehouse Native: create a
metric that aggregates the fact data. A metric can be any aggregation of the
fact data, such as a sum, an average, or a count.

All metrics aggregate measurements over some time window. Watch the following video for a 4-minute overview of the different ways to handle time in metrics.

<iframe className="w-full aspect-video rounded-xl" src="https://www.youtube.com/embed/3faa2_gFjWQ?si=jEeT9zPUFlX8FM9D" title="Handling time in metrics in Confidence" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />

For this tutorial, create a metric that computes the average weekly sales
amount per user.

### With AI

The Flags MCP server can create the metric with the `createMetric` tool. The
in-app Confidence Agent can't create metrics. Create them in the app or with
the Flags MCP server. For example:

```text theme={null}
Create a Confidence metric called "Average weekly sales per user" on the User
entity. Average the amount measurement from the sales fact table, cumulatively
over a 1-week window starting at exposure, filtered to product = "podcast".
```

To check the metric against real data, ask the assistant to run a metric
calculation. It uses `createMetricCalculation` and `queryMetricCalculation`.

### In the App

To create a metric, follow these steps:

<Steps>
  <Step title="Go to Confidence" />

  <Step title="Navigate to Metrics">
    On the left sidebar, select **Metrics**.
  </Step>

  <Step title="Click + Create" />

  <Step title="Enter metric details">
    Enter `Average weekly sales per user` as the name of the metric and assign yourself as the owner. Skip the description for now.
  </Step>

  <Step title="Select Consumption as the metric type" />

  <Step title="Select the consumption value">
    Select the `User` entity, the fact table that holds your sales data, and the `amount` measurement as the **Consumption value**.
  </Step>

  <Step title="Add attribute criteria">
    Click **Add Attribute criteria** and select `product` as the attribute. Set the filter to `product is podcast`.
  </Step>

  <Step title="Configure when to include users">
    In the **When to Include Users In Metrics Results** step, select `Cumulatively during a window` and `1 week` starting `at exposure`.
  </Step>

  <Step title="Click Next to skip the Suggested usage" />

  <Step title="Review and create">
    Review your metric setup, and then click **Create**.
  </Step>
</Steps>

You now have a metric that you can use in an A/B test or a rollout.

## Related Resources

<CardGroup cols={2}>
  <Card title="Launch an A/B Test" href="/docs/guides/run-an-ab-test">
    Use your metric to measure experiment results
  </Card>

  <Card title="Launch a Rollout" href="/docs/guides/roll-out-a-change">
    Use your metric to monitor a gradual release
  </Card>

  <Card title="Metrics Reference" href="/docs/capabilities/metrics/overview">
    Deep dive into metric types and configuration
  </Card>

  <Card title="Validate Metrics" href="/docs/capabilities/metrics/validate-metric">
    Learn how to verify your metrics are working correctly
  </Card>
</CardGroup>