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

> Learn how to create materialized segments that load units from BigQuery.

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 Materialized Segments"
  description="Learn how to create materialized segments that load units from BigQuery."
  steps={[
{
  name: "Create a Materialized Segment",
  text: "To create a materialized segment:",
},
{
  name: "Create a Load Job",
  text: "After creating the segment, create a load job to populate it with data from your SQL query: The entityIdColumn specifies which column in your query results contains the entity IDs to include in the segment.",
},
{
  name: "Get a Materialized Segment",
  text: "To retrieve a materialized segment's configuration:",
},
{
  name: "List Load Jobs",
  text: "To see the load jobs for a materialized segment:",
},
{
  name: "Delete a Materialized Segment",
  text: "To delete a materialized segment:",
},
]}
/>

A materialized segment is a segment that loads its list of units from your BigQuery instance using a SQL query.

<Note>
  Materialized segments are only available for BigQuery.
</Note>

## Create a Materialized Segment

To create a materialized segment:

```bash theme={null}
curl -X POST "https://flags.confidence.dev/v1/materializedSegments?materializationId=my-mat-segment" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "materializedSegment": {
      "displayName": "My Materialized Segment"
    }
  }'
```

## Create a Load Job

After creating the segment, create a load job to populate it with data from your SQL query:

```bash theme={null}
curl -X POST "https://flags.confidence.dev/v1/materializedSegments/my-mat-segment/loadJobs" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "materializedSegmentJob": {
      "entityIdColumn": "user_id",
      "sql": "SELECT user_id FROM your_dataset.your_table WHERE your_criteria"
    }
  }'
```

The `entityIdColumn` specifies which column in your query results contains the entity IDs to include in the segment.

## Get a Materialized Segment

To retrieve a materialized segment's configuration:

```bash theme={null}
curl -X GET "https://flags.confidence.dev/v1/materializedSegments/my-mat-segment" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

## List Load Jobs

To see the load jobs for a materialized segment:

```bash theme={null}
curl -X GET "https://flags.confidence.dev/v1/materializedSegments/my-mat-segment/loadJobs" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

## Delete a Materialized Segment

To delete a materialized segment:

```bash theme={null}
curl -X DELETE "https://flags.confidence.dev/v1/materializedSegments/my-mat-segment" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

## Next Steps

After creating materialized segments:

1. Use the segment in [flag rules](./create-flag-rule) to target specific users
2. Set up [coordination](./coordinate-segments) to make segments mutually exclusive