Create a segment

Segments are lists of user IDs that can you can create and share across your feature flags in an environment. You can segment your customer base and target these segments in your release process.

A segment is a pre-defined list of user IDs (user keys) that a feature flag can target. Segments can:

• be created and edited in the Split UI by manually adding IDs or by importing a file containing one ID per line
• be created and edited via the Split API
• sync with any Amplitude Cohort

Segments are best for targeting relatively fixed or specific groups of users that you can easily identify, like individual accounts. If you would like to learn about more dynamic targeting, refer to the Custom attributes guide.

For feature releases, you can use segments to:

• Ensure quality testing. For example, you can release to your internal or outsourced QA team by creating a qa_team segment.
• Target employees for internal testing. For example, you can release to your entire company to test a feature or gather feedback by creating an employees segment.
• Plan your release strategy. For example, you can release to a group of customers who have expressed interest in a particular feature by creating a beta_tester segment.

These are a few examples of using segments to deploy safe and successful feature releases.

Segment types

Split supports the following segment types:

• Standard segments - can contain up to 100,000 user IDs
• Large segments - can contain up to 1,000,000 user IDs (may be increased upon request)

Large segments are created and managed differently than standard segments. A brief summary:

• Creating and updating Large segments is done in two steps, including using Split API to upload a CSV file containing the segment's full list of user IDs.
• In Split UI, you can search a Large segment for a given User ID, but the full list of user IDs in a Large segment cannot be displayed.

This article shows how to work with Standard segments and Large segments and explains the differences in detail.

The segment type is displayed at the top of each Segment page in the Split UI, as shown below.

In Split UI, you can filter the segments listed on the Segments pane by segment type.

Creating a segment

When creating a segment, the segment name, description, owners, and tags can help you and your team later manage your segment. This information can be customized to your team's workflow.

To create a segment:

1. From the navigation bar, click Create segment. The Create a segment page appears.

   

2. Fill in the fields as follows:

• Name. Give your segment an easily recognizable name.

• Segment type. Select the segment type according to the maximum size the segment will reach.
• Traffic type. Select a traffic type for this segment. The feature flags that target this segment must be assigned the same traffic type.
• Owners. Add one or more owners to your segment. Use owners to isolate segments in the browse panes to those owned by me and simplify permissions by providing owner edit rights for a single segment across all environments by toggling permissions on. When toggled on, permissions inherit owners as editors.
• Tags. Optionally add one or more tags to help you categorize the segment. Use tags to isolate to a particular team or feature release (e.g. reporting team, front end, or geo search release).
• Description. Optionally, provide a description of the segment. This helps your team members understand the segment's purpose.

3. Click Create to create your new segment.

Next, you can create a segment definition and add user IDs.

Adding user IDs to a segment

You need to add a segment definition for a given environment (this creates an empty segment in that environment) and then add user IDs to the segment. This is done as follows:

1. Select a segment in the Segments pane to open the segment page.

   

2. In the Environment dropdown, select a Split environment where the segment will be defined.

3. Click Add definition. A new blank definition for the segment (for the selected environment) appears.

4. In the User section, click Add user.

   

   For Standard segments you can choose to individually add user IDs or to add them via file import.

   For Large segments user IDs are added via file import using Split API.

   For details about the import file contents, see the CSV import file format section below.

File import for Standard segments

When using file import for a Standard segment, the user IDs listed in the file are added to the IDs already in the segment. Duplicate IDs are not added. This means that you can repeatedly import up to 10,000 user IDs at a time until the 100,000 limit is reached. (This is different from the way file import works for Large segments.)

File import for Large segments

When using file import for a Large segment, the list of user IDs in the file will replace all the IDs that were already in the segment. The import file contents represent the new segment version and overwrite the previous segment version.

To import user IDs into a Large segment you need to prepare a CSV import file. Then do the following:

1. On the segment page, click Add user and select Import via API.

   

2. On the Change summary page, click Save to generate an upload URL.

   
   The upload URL will time out after 5 minutes, and the Large segment change request will be automatically withdrawn if the upload URL was not used.

3. Copy the Upload URL by clicking the copy icon. You are actually copying a curl command to upload a CSV file using a Split API endpoint. The command has the following format:

curl -XPUT -H 'Host: split-large-segments-....' \
   'https://split-large-segments-...' \
   -T filename.csv

Replace `filename.csv` with the name of your CSV file.

4. Run the curl command from the location of your CSV file. You may need to wait a moment for the command to complete. During this time, the segment will show pending changes in the Split UI.

   

5. Refresh the Segment page to see the segment size updated. You can search for a user ID to confirm that it is in the Large segment.

   

CSV import file format

When adding user keys to a segment by importing them from a file, use a CSV file (a file with .csv extension) that lists the user IDs in a single column with no header. User IDs containing commas, line breaks, or any other special character need to be wrapped in double quotes. Duplicate user IDs are ignored.

Example CSV file content:

id1
id2
id3