> ## Documentation Index
> Fetch the complete documentation index at: https://confidence-auth-testing.mintlify.site/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.md).

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

## Set Up the Data

**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.md#metrics-without-sql).

### Choose an Entity

An [entity](/docs/capabilities/metrics/entities.md) 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.md)
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.md) 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`).

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

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.

**1. Go to Confidence**

**2. Navigate to Entities**

On the left sidebar, select **Admin > Entities**.

**3. Click + Create**

**4. Enter User as the name of the entity**

**5. Select a data type**

Select a data type for how your data warehouse represents the entity. For the sake of this tutorial, select `String`.

**6. Click Create**

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

> [!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.
> ```

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.md),
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:

**1. Go to Confidence**

**2. Navigate to Assignment tables**

On the left sidebar, select **Admin > Data Tables > Assignment tables**.

**3. Click + Create**

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

**5. Enter the SQL query**

Enter the SQL query that projects the assignment data from your data warehouse.

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

**6. 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.

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

**8. 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.md) page.

**9. Click Create**

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.

Follow these steps to set up a fact table:

**1. Go to Confidence**

**2. Navigate to Fact tables**

On the left sidebar, select **Admin > Data Tables > Fact tables**.

**3. Click + Create**

**4. Give the table a name**

Give the table a name, such as `sales`.

**5. Enter the SQL query**

Enter the SQL query that projects the fact data from your data warehouse.

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

**6. Click Run Query**

This executes the query and shows you a preview.

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

**8. 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.md) page.

**9. Click Create**

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

[Handling time in metrics in Confidence](https://www.youtube.com/embed/3faa2_gFjWQ?si=jEeT9zPUFlX8FM9D)

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:

**1. Go to Confidence**

**2. Navigate to Metrics**

On the left sidebar, select **Metrics**.

**3. Click + Create**

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

**5. Select Consumption as the metric type**

**6. Select the consumption value**

Select the `User` entity, the fact table that holds your sales data, and the `amount` measurement as the **Consumption value**.

**7. Add attribute criteria**

Click **Add Attribute criteria** and select `product` as the attribute. Set the filter to `product is podcast`.

**8. 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`.

**9. Click Next to skip the Suggested usage**

**10. Review and create**

Review your metric setup, and then click **Create**.

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

## Related Resources

> **[Launch an A/B Test](/docs/guides/run-an-ab-test.md)**
>
> Use your metric to measure experiment results

> **[Launch a Rollout](/docs/guides/roll-out-a-change.md)**
>
> Use your metric to monitor a gradual release

> **[Metrics Reference](/docs/capabilities/metrics/overview)**
>
> Deep dive into metric types and configuration

> **[Validate Metrics](/docs/capabilities/metrics/validate-metric.md)**
>
> Learn how to verify your metrics are working correctly