/Docs

Big-Segment Store

Standard audience segments are serialised directly into the datafile so the SDK can evaluate them offline without any external call. When a segment contains hundreds of thousands or millions of members, that embedded list becomes impractical. A big-segment store moves membership data out of the datafile and into an external store that the SDK queries at evaluation time.

What it is

A big segment is any audience segment flagged as bigSegment in the platform. Instead of listing member keys inline in the datafile, the datafile carries only segment metadata — key, context kind, and which storage backend holds membership. The evaluator detects the bigSegment audience condition type and calls your configured BigSegmentStore implementation instead of performing an inline scan.

The BigSegmentStore interface is synchronous on the hot path. Implementations should pre-warm their cache on startup and refresh it on a configurable interval rather than blocking each evaluation on a network call:

ts
1interface BigSegmentStore {
2  /** Sync read — must be hot-path safe. Pre-warm before serving traffic. */
3  isMember(segmentKey: string, contextKey: string): boolean
4  /** Bulk membership check for a context — used during evaluation. */
5  membership(contextKey: string): Map<string, boolean>
6  /** Health probe — returns false if the store is stale or unavailable. */
7  isHealthy(): boolean
8}

When to use it

Switch a segment to big-segment mode when its member list would make the datafile unwieldy. Practical thresholds:

  • Over 50 000 member keys — at this size, the embedded JSON starts to add measurable latency to SDK initialisation and increases CDN egress costs.
  • Frequently mutated lists — if membership changes faster than your datafile polling interval (default 60 seconds), an external store lets you serve fresh membership without waiting for a full datafile republish.
  • Regulated data — if the member keys are PII-adjacent (e.g., email addresses), keeping them out of the CDN-hosted datafile reduces your data surface.
Warning
Big segments require an external store that must be available at evaluation time. If isHealthy() returns false, the SDK logs a warning and treats the segment as having zero members — the audience condition evaluates to false. Plan your fallback behaviour accordingly.

How it works

Membership data is populated by a separate batch pipeline — your ingestion or CRM system writes to the store. The SDK only reads. A vs B ships two reference implementations via @avsbhq/utils/storage:

ts
1import { createRedisBigSegmentStore } from '@avsbhq/utils/storage'
2import { createClient } from 'redis'
3

4const redis = createClient({ url: process.env.REDIS_URL })
5await redis.connect()
6

7const bigSegmentStore = createRedisBigSegmentStore({
8  client: redis,
9  prefix: 'avsb:segments:',
10  refreshInterval: 30_000,   // re-warm cache every 30 s
11})

For DynamoDB-backed deployments:

ts
1import { createDynamoDBBigSegmentStore } from '@avsbhq/utils/storage'
2import { DynamoDBClient } from '@aws-sdk/client-dynamodb'
3

4const bigSegmentStore = createDynamoDBBigSegmentStore({
5  client: new DynamoDBClient({ region: 'us-east-1' }),
6  tableName: 'avsb-big-segments',
7  refreshInterval: 60_000,
8})

Per-SDK usage

@avsbhq/node
ts
1import { AvsbServer } from '@avsbhq/node'
2import { createRedisBigSegmentStore } from '@avsbhq/utils/storage'
3import { createClient } from 'redis'
4

5const redis = createClient({ url: process.env.REDIS_URL })
6await redis.connect()
7

8const server = new AvsbServer({
9  sdkKey: process.env.AVSB_SDK_KEY,
10  bigSegmentStore: createRedisBigSegmentStore({ client: redis }),
11})
12

13await server.onReady()
14

15// Evaluation is transparent — big-segment checks happen inside getFlag
16const flag = server.getFlag('enterprise-rollout', false, context)
avsb-python
python
1from avsb import AvsbServer
2from avsb.storage import create_redis_big_segment_store
3import redis
4

5r = redis.Redis.from_url(os.environ["REDIS_URL"])
6

7server = AvsbServer(
8    sdk_key=os.environ["AVSB_SDK_KEY"],
9    big_segment_store=create_redis_big_segment_store(client=r),
10)
11server.wait_for_ready()
12

13flag = server.get_flag("enterprise-rollout", False, context)
avsb-java
java
1import cloud.avsb.AvsbServer;
2import cloud.avsb.storage.RedisBigSegmentStore;
3import redis.clients.jedis.JedisPool;
4

5JedisPool pool = new JedisPool(System.getenv("REDIS_URL"));
6

7AvsbServer server = AvsbServer.builder()
8    .sdkKey(System.getenv("AVSB_SDK_KEY"))
9    .bigSegmentStore(new RedisBigSegmentStore(pool, "avsb:segments:"))
10    .build();
11server.blockUntilReady(Duration.ofSeconds(5));
12

13Flag<Boolean> flag = server.getFlag("enterprise-rollout", false, ctx);
avsb-go
go
1import (
2    "github.com/avsbhq/avsb-go"
3    "github.com/avsbhq/avsb-go/storage"
4    "github.com/redis/go-redis/v9"
5)
6

7rdb := redis.NewClient(&redis.Options{Addr: os.Getenv("REDIS_ADDR")})
8

9client, _ := avsb.NewServer(avsb.Options{
10    SDKKey:          os.Getenv("AVSB_SDK_KEY"),
11    BigSegmentStore: storage.NewRedisBigSegmentStore(rdb, "avsb:segments:"),
12})
13client.WaitForReady(context.Background())
14

15flag := client.GetFlag("enterprise-rollout", false, ctx)