User Segments
Segments enable you to create user groups based on the unique ID of end users defined when initializing the Bucketeer SDK, on attribute-based rules, or both. A user is included in a segment if their ID is in the uploaded user list or if they match any of the segment rules. It allows you to create specific user targets to manage all users for a single feature flag variation or beta tests on a small number of users.
Use case
You can use segments to target specific user groups and make a new feature only available to them. For example, before releasing a new feature, the QA team may need to test it. In such a situation, you can create a segment with all QA team members' IDs and make the new feature only available to them.
With segment rules, you can also define membership by user attributes instead of maintaining an ID list. For example, you can create a segment for all users on a premium plan in Japan, and every feature flag using that segment will automatically target them — no user list uploads required.
Access the Targeting with feature flags page to learn how to use segments to target users.
Creating segments
To create a segment on Bucketeer, navigate to the User Segments page and click + New User Segment. You'll configure:
- Name and Description for the segment
- User list (optional) - Upload a CSV or TXT file with user IDs separated by commas, or manually enter user IDs
- Rules (optional) - Define conditions on user attributes to include users in the segment. See Segment rules below.
Click Submit to create the segment.
You are not required to add the user list when initially creating the segment. If you need to include a segment in your targeting rule strategy but need to know the users who should be in the segment, you can create an empty segment and add users later.
After submitting, the segment will be available with a Not in use status. However, you will see a message UPLOADING under the segment's name on the list page, which informs you that the user list is uploading to the server in the background.
This process may take up to 1 minute to complete, depending on the amount of user IDs.
Please wait until the upload finishes before using the segment in your targeting rule strategy. Reload the list page to check if the uploading is finished.
Segment rules
In addition to the uploaded user list, you can define rules that include users in the segment based on their attributes. The attributes are the same end-user attributes you define when initializing the Bucketeer SDK.
A rule contains one or more conditions, each with an attribute key, an operator, and one or more values. Segment rules support the same comparison operators as flag targeting rules. See the Supported Operators table for the complete list.
- A user is included in the segment if their ID is in the user list OR they match any rule.
- Within a rule, all conditions are combined with AND — every condition must match.
- Across rules, the conditions are combined with OR — matching a single rule is enough.
For example, a segment with the user list [user-1] and the rules below includes user-1, every premium-plan user in Japan, and every user whose email starts with test@:
- Rule 1:
plan = premiumANDcountry = japan - Rule 2:
email starts with test@
Segment rules only support conditions based on user attributes. Conditions based on other segments or on feature flag evaluations are not available inside segment rules.
Because segments are shared, updating a segment's rules immediately affects all feature flags that use the segment — you don't need to update the flags themselves.
Rule-based segments require Bucketeer v2.3.0 or later.
If you use a server-side SDK with local evaluation enabled, the SDK must also support segment rules (Go server SDK v1.8.0 or later, Node.js server SDK v0.4.7 or later). Older server SDK versions only evaluate the segment's uploaded user list and ignore the rules. Client-side SDKs and server-side SDKs using remote evaluation are not affected, since the evaluation runs on the server.
Editing segments
To edit a segment:
- Navigate to the User Segments menu.
- Find and click on the desired segment's name.
You can update segments that are being used by feature flags, including the user list and the rules. However, if these flags are part of active experiments, changing the segment may affect result accuracy since it modifies which users are included in each variation.
Before updating a segment in use:
- Check which flags are using it (shown in the warning message)
- Consider the impact on any running experiments
- Verify that the changes won't compromise experiment validity
Note: You cannot delete a segment while it's being used by any feature flags. Remove it from all flags first.
You can update the Name, Description, user list, and rules. Note that the previously added user list is not showing due to the size of the ID list.
By updating the user ID list, you will override the current list in the database. If you want to add or remove users from the list, please download the list and edit it on your PC before submitting it.
Downloading an existing user list
After creating a User Segment, you can download the user's list. To do this, access the User Segment page, find the desired segment list and click on the action menu (three dots). After, select Download User Segment.
With the User Segment, you can updated the list and, after, upload the updated list to the same segment, if necessary.
Deleting segments
To delete a segment:
- Navigate to the User Segments menu.
- Find the desired segment, click the action button (three dots) on the list page, and select Delete User Segment.
You cannot delete a segment with an In use status. If you try to delete it, the Bucketeer will show all feature flags currently using the segment. Before deleting, you must remove it from all feature flags.