Remote Groups are an Enterprise feature.
How It Works
A Remote Group has a name and an attribute, like an ID List, but the SDK payload doesn’t contain its IDs. Instead:- You upload a CSV of IDs to GrowthBook, or keep the IDs in your own storage.
- A loader writes the uploaded IDs to a fast lookup store, such as Redis. The GrowthBook Proxy includes one.
- Before evaluating features, your app (or the Proxy, for remote evaluation) looks up which Remote Groups the user is in, using a resolver.
- The SDK checks rules against that list of groups.
Creating a Remote Group
Go to SDK Configuration → Saved Groups, open the Remote Groups tab, and click Add Remote Group. Choose a name and the attribute the IDs belong to. The attribute must be astring or number; secureString attributes aren’t supported, because the lookup needs the raw value.
After you create the group, it opens on its own page, where you can upload IDs.
Uploading is optional. If your IDs already live in your own database or cache, skip the upload and write your own resolver.
Uploading IDs
Click Upload CSV on the group’s page and choose a file. GrowthBook checks the start of the file first, so common mistakes show up before the upload. The file then goes straight to your file storage (S3 or Google Cloud Storage), and GrowthBook checks every line in the background. The CSV needs:- One ID per line. A first line equal to the attribute name is treated as a header and skipped.
- No more than one column. Quotes, blank lines, a BOM and Windows line endings are handled.
- IDs up to 1,024 characters.
- Numbers only, for
numberattributes. - Up to 100 MB, which is about 3 to 5 million IDs.
Choosing the Version a Group Uses
Uploading a file doesn’t change what the group targets. The version a group uses is part of the Saved Group, so changing it goes through a draft, like any other Saved Group change, and is reviewed and published the same way. See Publishing & Approval Flows. After you upload a file, click Add to revision once it’s validated. To use another version, click Use next to it in the uploads table. The uploads table marks the version the group uses as Live. Click a version to see its details: file name, size, SHA-256 checksum, and which data stores have loaded it. You can download any version, and delete versions the group doesn’t use.ID Counts
The ID count on an upload counts every ID in the file. If the file contains duplicate IDs, each one is stored only once when it’s loaded, so a data store can report fewer IDs than the file has. A warning icon in the uploads table shows when that happens.Targeting with Remote Groups
Use a Remote Group in a rule like any other Saved Group: in a rule’s Saved Groups targeting, or with the is in the saved group and is not in the saved group operators in a condition. A Remote Group can also be used with anotherstring or number attribute. For example, a group of VIP account IDs on account_id can target users whose parent_account_id is a VIP account. The group’s IDs are matched against the other attribute’s value, so you don’t need to upload the same IDs twice. In the condition builder, these groups show the attribute their IDs belong to, such as VIP Accounts (account_id IDs).
In the SDK payload, this is a separate group with the ID <group id>:<attribute>, such as grp_abc123:parent_account_id. Resolvers look up the attribute’s value in the original group’s IDs.
Looking Up a User’s Groups
Rules check Remote Groups against the user’s list of group IDs, in the internal__gb_remoteGroupIds attribute. Set that list in one of these ways:
- With the GrowthBook Proxy: with remote evaluation, the Proxy (version 1.6.0 or later) loads uploaded IDs into Redis and looks up each user’s groups before evaluating. Your app doesn’t need to do anything.
- Custom lookups and storage: look up groups yourself, with the JavaScript SDK’s resolver, your own resolver and storage, or by setting the attribute in any SDK.
Using the REST API
Uploads use the same signed-URL flow as the app. First ask for an upload URL:signedUrl. When fields is set, send a form POST with those fields and the file last; otherwise PUT the file. Then record the upload:
status.type is valid or invalid:
currentUploadVersion in a revision, then publish it. Pass new as the revision version to open a draft:
currentUploadVersion directly with POST /saved-groups/{id}.
To delete an old upload, use DELETE /api/v1/saved-groups/{id}/uploads/{version}. The version the group uses, or one an open draft uses, can’t be deleted.
To load uploaded IDs into your own store, see With Your Own Loader.
