> ## Documentation Index
> Fetch the complete documentation index at: https://launchdarkly.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Big segments

<View title="Developer" />

<View title="Federal docs" />

<View title="EU docs" />

<Note>
  **Big segments are available to customers on select plans**

  [Segments synced from external tools](/docs/home/flags/synced-segments) and [larger list-based segments](/docs/home/flags/segment-types#larger-list-based-segments) are the two kinds of big segment. Big segments are available to customers on only select plans. To learn more, [read about our pricing](https://launchdarkly.com/pricing/). To upgrade your plan, [contact Sales](https://launchdarkly.com/contact-sales/).
</Note>

This topic explains how the big segments feature works in the LaunchDarkly SDKs that support it.

Big segments are segments that are either [synced from external tools](/docs/home/flags/synced-segments) or [list-based segments](/docs/home/flags/segment-types#larger-list-based-segments) that can contain an arbitrarily large number of contexts of any one context kind.

You can use big segments with client-side or server-side SDKs.

## Client-side SDKs

If you are using client-side SDKs, no additional SDK configuration is required.

However, if you use the Relay Proxy with client-side SDKs, then the Relay Proxy must be configured to use persistent storage. To learn more, read [Configuring the Relay Proxy for segments](/docs/sdk/relay-proxy/sdk-config#configuring-the-relay-proxy-for-segments).

## Server-side SDKs

If you are using server-side SDKs, big segments require a persistent store within your infrastructure. LaunchDarkly keeps the persistent store up to date and consults it during flag evaluation.

You can use either Redis or DynamoDB as your persistent store when you work with segments. LaunchDarkly keeps the persistent store up to date using either a persistent store integration or the Relay Proxy. You must decide which you want to use. Then you must either configure a persistent store integration, or configure the Relay Proxy. To learn how, read [SDK and integration configuration for segments](/docs/home/flags/segment-config).

Whether you use a persistent store integration or the Relay Proxy, you must also configure your server-side SDK. Server-side SDK configuration for big segments is comprised of two parts:

* **The specific database options to get the segment data**: These options include which database to use, and any other parameters supported by the SDK to configure that database. These are the same database options you specify when configuring server-side SDKs to use external databases as persistent feature stores, for example, key prefix or DynamoDB table name. However, note that if you are using a feature store for your SDK, you can use either the same or a different persistent store for your segments. To learn more about these database options, read [Storing data](/docs/sdk/features/storing-data).

<Warning>
  **Only certain types of database integrations support big segments**

  Only the Redis and DynamoDB integrations support big segments. If you use Redis, each Redis host needs enough RAM to load the full set of segments and flag configurations.
</Warning>

* **The general options for the SDK's big segments behavior**: The table below lists all the general options available. They are all optional and valid for all server-side SDKs and can be used for any supported database integration.

<table>
  <thead>
    <tr>
      <th>Config option</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        user or context cache size
      </td>

      <td>
        The maximum number of contexts whose segment status the SDK can cache. The segment status includes all of the segments the context is a part of. A higher value means that the SDK queries the database for recently-referenced contexts' segments statuses less often. If not specified, the default value is 1000.
      </td>
    </tr>

    <tr>
      <td>
        user or context cache time
      </td>

      <td>
        The maximum length of time that the SDK caches the segments status. If you do not specify a value, the default is five seconds.
      </td>
    </tr>

    <tr>
      <td>
        status poll interval
      </td>

      <td>
        The interval at which the SDK polls the persistent store to make sure it is available and to determine how long ago it was updated. If not specified, the default value is five seconds.
      </td>
    </tr>

    <tr>
      <td>
        stale after
      </td>

      <td>
        The maximum length of time between updates of persistent store data before the SDK considers the data out of date. If you do not specify a value, the default is two minutes.
      </td>
    </tr>
  </tbody>
</table>

In all the server-side SDK code examples below, the configuration is set as follows:

* using a Redis server at `your-redis:6379`
* with a key prefix of `example-client-side-id`
* cache size: 2000
* cache time: 30 seconds

<Note>
  **Using a persistent store for segments requires a specific key prefix**

  If you are using a persistent store integration, the value of the key prefix for the persistent store must be the client-side ID of your environment.

  Your environment's client-side ID is available on the **SDK keys** page under **Settings**. To learn more about key types, read [Keys](/docs/sdk/concepts/client-side-server-side#keys-and-credentials).
</Note>

This feature is available in the listed versions and later of the following server-side SDKs:

* [.NET (server-side)](#net-server-side): 6.2.0
* [C++ (server-side)](#c++-server-side): 3.13.0
* [Go](#go): 5.5.0
* [Java](#java): 5.7.0
* [Node.js (server-side)](#node-js-server-side): 6.2.0
* [PHP](#php): 6.4.0
* [Python](#python): 7.3.0
* [Ruby](#ruby): 6.3.0

<Note>
  **Newer versions of LaunchDarkly SDKs replace users with contexts**

  A context is a generalized way of referring to the people, services, machines, or other resources that encounter feature flags in your product. Contexts replace another data object in LaunchDarkly: "users."

  Creating contexts and evaluating flags based on them is supported in the latest major versions of [most of our SDKs](/docs/sdk). For these SDKs, the code samples on this page include the two most recent versions.
</Note>

## How big segment caching works

The SDK queries the Big Segment store once per unique context, not once globally. It then caches that context’s segment membership:

* Cache duration: 5 seconds by default, configurable with `DefaultBigSegmentsContextCacheTime`
* Cache size: Up to 1,000 contexts, managed with an LRU eviction policy and configurable with `DefaultBigSegmentsContextCacheSize`

When a cached result is used, the lookup typically takes only 1–10ms, excluding network latency—even for very large segments.

### .NET (server-side)

<Accordion title="Expand .NET (server-side) code sample">
  Persistent store support for big segments is available in version 6.2.0 and later:

  <CodeGroup>
    ```csharp title=".NET SDK v7.0+ (C#)" lines wrap theme={null}
    using LaunchDarkly.Sdk.Server;
    using LaunchDarkly.Sdk.Server.Integrations;
    var config = Configuration.Builder("YOUR_SDK_KEY")
        .BigSegments(
            Components.BigSegments(
                Redis.BigSegmentStore()
                    .HostAndPort("your-redis", 6379)
                    .Prefix("example-client-side-id")
            )
            .ContextCacheSize(2000)
            .ContextCacheTime(TimeSpan.FromSeconds(30))
        )
        .Build();
    var client = new LdClient(config);
    ```
  </CodeGroup>

  <Note>
    **Big segment stores and feature stores are configured separately**

    Big segment stores are required if you want to use big segments with a server-side SDK. In the .NET (server-side) SDK, big segment stores are defined with a `*BigSegmentStore` function, for example `Redis.BigSegmentStore()`, and with the `BigSegments` options.

    Feature stores are used if you want to cache flag data in an external database, rather than in local memory. In the .NET (server-side) SDK, feature stores are defined with a `*DataStore` function, and with the `DataStore` options. To learn more, read [Storing data](/docs/sdk/features/storing-data#net-server-side).
  </Note>

  To learn more about the available configuration options, read [`BigSegmentsConfigurationBuilder`](https://launchdarkly.github.io/dotnet-core/pkgs/sdk/server/api/LaunchDarkly.Sdk.Server.Integrations.BigSegmentsConfigurationBuilder.html).
</Accordion>

### C++ (server-side)

<Accordion title="Expand C++ (server-side) code sample">
  Persistent store support for big segments is available in version 3.13.0 and later.

  The C++ SDK supports Redis and DynamoDB big segment stores. Both integrations are part of the main SDK distribution, but are disabled by default to avoid bringing in unnecessary dependencies. To make the integration headers and libraries available for your build, set the CMake option `LD_BUILD_REDIS_SUPPORT=ON` for Redis, or `LD_BUILD_DYNAMODB_SUPPORT=ON` for DynamoDB.

  Here's how to configure a big segment store:

  <CodeGroup>
    ```cpp title="C++ SDK v3.0 (Redis, native)" maxLines=0 expandable lines wrap theme={null}
    // Make sure to include the Redis Big Segments store's header.
    #include <launchdarkly/server_side/integrations/redis/redis_big_segment_store.hpp>

    using namespace launchdarkly::server_side;

    ConfigBuilder config_builder(sdk_key);

    auto redis_store = integrations::RedisBigSegmentStore::Create("redis://localhost:6379", "my-key-prefix");

    if (!redis_store) {
        /* redis config is invalid, cannot proceed */
    }

    config_builder.BigSegments(
        config::builders::BigSegmentsBuilder(std::move(*redis_store))
            .ContextCacheSize(2000)
            .ContextCacheTime(std::chrono::seconds(30))
    );

    auto config = config_builder.Build();
    if (!config) {
        /* an error occurred, config is not valid */
    }
    ```

    ```c title="C++ SDK v3.0 (Redis, C binding)" maxLines=0 expandable lines wrap theme={null}
    // Stack allocate the result struct, which will hold the store pointer or
    // an error message.
    struct LDServerBigSegmentsRedisResult result;

    // Create the Redis Big Segments store, passing in arguments for the URI,
    // prefix, and pointer to the result.
    if (!LDServerBigSegmentsRedisStore_New("redis://localhost:6379", "my-key-prefix",
                                           &result)) {
        // Redis config is invalid, cannot proceed.
        // Error message is stored in result.error_message.
    }

    // Create a Big Segments builder from the store pointer.
    LDServerBigSegmentsBuilder bs_builder =
        LDServerBigSegmentsBuilder_New((LDServerBigSegmentStorePtr)result.store);

    LDServerBigSegmentsBuilder_ContextCacheSize(bs_builder, 2000);
    LDServerBigSegmentsBuilder_ContextCacheTimeMs(bs_builder, 30000);

    // Create a standard server-side SDK configuration builder.
    LDServerConfigBuilder cfg_builder = LDServerConfigBuilder_New("YOUR_SDK_KEY");

    // Tell the SDK config builder to use the Big Segments store that was just
    // configured.
    LDServerConfigBuilder_BigSegments(cfg_builder, bs_builder);

    LDServerConfig config;
    LDStatus status = LDServerConfigBuilder_Build(cfg_builder, &config);

    if (!LDStatus_Ok(status)) {
        // an error occurred, config is not valid
    }
    ```

    ```cpp title="C++ SDK v3.0 (DynamoDB, native)" maxLines=0 expandable lines wrap theme={null}
    // Make sure to include the DynamoDB Big Segments store's header.
    #include <launchdarkly/server_side/integrations/dynamodb/dynamodb_big_segment_store.hpp>

    using namespace launchdarkly::server_side;

    ConfigBuilder config_builder(sdk_key);

    auto dynamodb_store = integrations::DynamoDBBigSegmentStore::Create("my-table", "my-key-prefix");

    if (!dynamodb_store) {
        /* dynamodb config is invalid, cannot proceed */
    }

    config_builder.BigSegments(
        config::builders::BigSegmentsBuilder(std::move(*dynamodb_store))
            .ContextCacheSize(2000)
            .ContextCacheTime(std::chrono::seconds(30))
    );

    auto config = config_builder.Build();
    if (!config) {
        /* an error occurred, config is not valid */
    }
    ```

    ```c title="C++ SDK v3.0 (DynamoDB, C binding)" maxLines=0 expandable lines wrap theme={null}
    // Stack allocate the result struct, which will hold the store pointer or
    // an error message.
    struct LDServerBigSegmentsDynamoDBResult result;

    // Create the DynamoDB Big Segments store, passing in the table name, key
    // prefix, client options (NULL for the default AWS region and
    // credentials), and a pointer to the result.
    if (!LDServerBigSegmentsDynamoDBStore_New("my-table", "my-key-prefix", NULL,
                                              &result)) {
        // DynamoDB config is invalid, cannot proceed.
        // Error message is stored in result.error_message.
    }

    // Create a Big Segments builder from the store pointer.
    LDServerBigSegmentsBuilder bs_builder =
        LDServerBigSegmentsBuilder_New((LDServerBigSegmentStorePtr)result.store);

    LDServerBigSegmentsBuilder_ContextCacheSize(bs_builder, 2000);
    LDServerBigSegmentsBuilder_ContextCacheTimeMs(bs_builder, 30000);

    // Create a standard server-side SDK configuration builder.
    LDServerConfigBuilder cfg_builder = LDServerConfigBuilder_New("YOUR_SDK_KEY");

    // Tell the SDK config builder to use the Big Segments store that was just
    // configured.
    LDServerConfigBuilder_BigSegments(cfg_builder, bs_builder);

    LDServerConfig config;
    LDStatus status = LDServerConfigBuilder_Build(cfg_builder, &config);

    if (!LDStatus_Ok(status)) {
        // an error occurred, config is not valid
    }
    ```
  </CodeGroup>

  <Note>
    **Big segment stores and feature stores are configured separately**

    Big segment stores are required if you want to use big segments with a server-side SDK. In the C++ SDK, big segment stores are created with a `*BigSegmentStore::Create` function, for example `RedisBigSegmentStore::Create()`, and passed to the `BigSegmentsBuilder`.

    Feature stores are used if you want to cache flag data in an external database, rather than in local memory. In the C++ SDK, persistent feature stores are configured with a `LazyLoad` data source. To learn more, read [Storing data](/docs/sdk/features/storing-data#c++-server-side).
  </Note>

  To learn more about the available configuration options, read [`BigSegmentsBuilder`](https://launchdarkly.github.io/cpp-sdks/libs/server-sdk/docs/html/classlaunchdarkly_1_1server__side_1_1config_1_1builders_1_1BigSegmentsBuilder.html).
</Accordion>

### Go

<Accordion title="Expand Go code sample">
  Persistent store support for big segments is available in version 5.5.0 and later:

  <CodeGroup>
    ```go title="Go SDK v6+" expandable lines wrap theme={null}
    import (
        "time"

        ld "github.com/launchdarkly/go-server-sdk/v6"
        "github.com/launchdarkly/go-server-sdk/v6/ldcomponents"
        ldredis "github.com/launchdarkly/go-server-sdk-redis-redigo"
    )

    var config ld.Config
    config.BigSegments = ldcomponents.BigSegments(
        ldredis.BigSegmentStore().
            HostAndPort("your-redis", 6379).
            Prefix("example-client-side-id"),
        ).
        ContextCacheSize(2000).
        ContextCacheTime(30*time.Second)
    client, _ := ld.MakeCustomClient("YOUR_SDK_KEY", config, 5*time.Second)
    ```
  </CodeGroup>

  <Note>
    **Big segment stores and feature stores are configured separately**

    Big segment stores are required if you want to use big segments with a server-side SDK. In the Go SDK, big segment stores are defined with a `*BigSegmentStore` function, for example `ldredis.BigSegmentStore()`, and with the `BigSegments` options.

    Feature stores are used if you want to cache flag data in an external database, rather than in local memory. In the Go SDK, feature stores are defined with a `*DataStore` function, and with the `DataStore` options. To learn more, read [Storing data](/docs/sdk/features/storing-data#go).
  </Note>

  To learn more about the available configuration options, read [`BigSegmentsConfigurationBuilder`](https://pkg.go.dev/github.com/launchdarkly/go-server-sdk/v7/ldcomponents#BigSegmentsConfigurationBuilder).
</Accordion>

### Java

<Accordion title="Expand Java code sample">
  Persistent store support for big segments is available in version 5.7.0 and later:

  <CodeGroup>
    ```java title="Java" expandable lines wrap theme={null}
    import com.launchdarkly.sdk.server.*;
    import com.launchdarkly.sdk.server.integrations.*;

    import java.net.URI;
    import java.time.Duration;

    LDConfig config = new LDConfig.Builder()
        .bigSegments(
            Components.bigSegments(
                Redis.bigSegmentStore()
                    .uri(URI.create("redis://your-redis:6379"))
                    .prefix("example-client-side-id")
            )
            .userCacheSize(2000)
            .userCacheTime(Duration.ofSeconds(30))
        )
        .build();
    LDClient client = new LDClient("YOUR_SDK_KEY", config);
    ```
  </CodeGroup>

  To use either the Redis integration, as shown above, or the DynamoDB integration in the Java SDK, you must also install additional packages. To learn more, read [Redis](/docs/sdk/features/storing-data/redis#java) and [DynamoDB](/docs/sdk/features/storing-data/dynamodb#java).

  <Note>
    **Big segment stores and feature stores are configured separately**

    Big segment stores are required if you want to use big segments with a server-side SDK. In the Java SDK, big segment stores are defined with a `*bigSegmentStore` function, for example `Redis.bigSegmentStore()`, and with the `bigSegments` options.

    Feature stores are used if you want to cache flag data in an external database, rather than in local memory. In the Java SDK, feature stores are defined with a `*dataStore` function, and with the `dataStore` options. To learn more, read [Storing data](/docs/sdk/features/storing-data#java).
  </Note>

  To learn more about the available configuration options, read [`BigSegmentsConfigurationBuilder`](https://launchdarkly.github.io/java-core/lib/sdk/server/com/launchdarkly/sdk/server/integrations/BigSegmentsConfigurationBuilder.html).
</Accordion>

### Node.js (server-side)

<Accordion title="Expand Node.js (server-side) code sample">
  Persistent store support for big segments is available in version 6.2.0 and later:

  <CodeGroup>
    ```js title="Node.js SDK v8.x+ (JavaScript)" maxLines=0 expandable lines wrap theme={null}
    import { init } from '@launchdarkly/node-server-sdk';
    import { RedisBigSegmentStore } from '@launchdarkly/node-server-sdk-redis';

    const store = RedisBigSegmentStore({
      redisOpts: {
        host: 'your-redis',
        port: 6379
      },
      prefix: 'example-client-side-id'
    });

    const config = {
      bigSegments: {
        store: store,
        userCacheSize: 2000,
        userCacheTime: 30
      }
    };
    const client = init("YOUR_SDK_KEY", config);
    ```

    ```ts title="Node.js SDK v8.x+ (TypeScript)" maxLines=0 expandable lines wrap theme={null}
    import * as LaunchDarkly from '@launchdarkly/node-server-sdk';
    import { RedisBigSegmentStore } from '@launchdarkly/node-server-sdk-redis';

    const store = RedisBigSegmentStore({
      redisOpts: {
        host: 'your-redis',
        port: 6379
      },
      prefix: 'example-client-side-id'
    });

    const options: LaunchDarkly.LDOptions = {
      bigSegments: {
        store: store,
        userCacheSize: 2000,
        userCacheTime: 30
      }
    };
    const client = LaunchDarkly.init('YOUR_SDK_KEY', options);
    ```
  </CodeGroup>

  <Note>
    **Big segment stores and feature stores are configured separately**

    Big segment stores are required if you want to use big segments with a server-side SDK. In the Node.js (server-side) SDK, big segment stores are defined with a `*BigSegmentStore` function, for example `RedisBigSegmentStore`, and with the `bigSegments` options.

    Feature stores are used if you want to cache flag data in an external database, rather than in local memory. In the Node.js (server-side) SDK, feature stores are defined with a `*FeatureStore` function, and with the `featureStore` options. To learn more, read [Storing data](/docs/sdk/features/storing-data#node-js-server-side).
  </Note>

  To learn more about the available configuration options, read [`LDBigSegmentsOptions`](https://launchdarkly.github.io/js-core/packages/sdk/server-node/docs/interfaces/LDBigSegmentsOptions.html).
</Accordion>

### PHP

<Accordion title="Expand PHP code sample">
  Persistent store support for big segments is available in version 6.4.0 and later:

  <CodeGroup>
    ```php title="PHP" lines wrap theme={null}
    use LaunchDarkly\Types\BigSegmentsConfig;

    $redisClient = new Predis\Client([]);
    $logger = new Psr\Log\NullLogger();
    $bigSegmentsStore = LaunchDarkly\Integrations\Redis::bigSegmentsStore($redisClient, $logger);
    $bigSegmentsConfig = new BigSegmentsConfig(store: $bigSegmentsStore);

    $client = new LaunchDarkly\LDClient("YOUR_SDK_KEY", ['big_segments' => $bigSegmentsConfig]);
    ```
  </CodeGroup>

  The PHP SDK currently only supports a Redis integration. To use the Redis integration in the PHP SDK, you must also install additional packages. To learn more, read [Redis](/docs/sdk/features/storing-data/redis#php).

  <Note>
    **Big segment stores and feature stores are configured separately**

    Big segment stores are required if you want to use big segments with a server-side SDK. In the PHP SDK, big segment stores are accessed through the `BigSegmentsStore` interface, and set up with the `BigSegmentsConfig` options.

    Feature stores are used if you want to cache flag data in an external database, rather than in local memory. In the PHP SDK, feature stores are defined with a `feature_requester` option. To learn more, read [Storing data](/docs/sdk/features/storing-data#php).
  </Note>

  To learn more about the available configuration options, read [`BigSegmentsConfig`](https://launchdarkly.github.io/php-server-sdk/classes/LaunchDarkly-Types-BigSegmentsConfig.html).
</Accordion>

### Python

<Accordion title="Expand Python code sample">
  Persistent store support for big segments is available in version 7.3.0 and later:

  <CodeGroup>
    ```python title="Python" lines wrap theme={null}
    import ldclient
    from ldclient.config import Config, BigSegmentsConfig
    from ldclient.integrations import Redis

    store = Redis.new_big_segment_store(
        url='redis://your-redis:6379',
        prefix='example-client-side-id')

    config = Config("YOUR_SDK_KEY", big_segments=BigSegmentsConfig(store=store))
    ldclient.set_config(config)
    client = ldclient.get()
    ```
  </CodeGroup>

  To use either the Redis integration, as shown above, or the DynamoDB integration in the Python SDK, you must also install additional packages. To learn more, read [Redis](/docs/sdk/features/storing-data/redis#python) and [DynamoDB](/docs/sdk/features/storing-data/dynamodb#python).

  <Note>
    **Big segment stores and feature stores are configured separately**

    Big segment stores are required if you want to use big segments with a server-side SDK. In the Python SDK, big segment stores are defined with a `*BigSegmentStore` function, for example `RedisBigSegmentStore()`, and with the `bigSegments` options.

    Feature stores are used if you want to cache flag data in an external database, rather than in local memory. In the Python SDK, feature stores are defined with a `feature_store` option. To learn more, read [Storing data](/docs/sdk/features/storing-data#python).
  </Note>

  To learn more about the available configuration options, read [`BigSegmentsConfig`](https://launchdarkly-python-sdk.readthedocs.io/en/latest/api-main.html#ldclient.config.BigSegmentsConfig).
</Accordion>

### Ruby

<Accordion title="Expand Ruby code sample">
  Persistent store support for big segments is available in version 6.3.0 and later:

  <CodeGroup>
    ```ruby title="Ruby" lines wrap theme={null}
    store = LaunchDarkly::Integrations::Redis.new_big_segment_store(
      redis_url: 'redis://your-redis:6379',
      prefix: 'example-client-side-id'
    )

    config = LaunchDarkly::Config.new(
      big_segments: LaunchDarkly::BigSegmentsConfig.new(store: store)
    )

    client = LaunchDarkly::LDClient.new("YOUR_SDK_KEY", config)
    ```
  </CodeGroup>

  To use either the Redis integration, as shown above, or the DynamoDB integration in the Ruby SDK, you must also install additional gems. To learn more, read [Redis](/docs/sdk/features/storing-data/redis#ruby) and [DynamoDB](/docs/sdk/features/storing-data/dynamodb#ruby).

  <Note>
    **Big segment stores and feature stores are configured separately**

    Big segment stores are required if you want to use big segments with a server-side SDK. In the Ruby SDK, big segment stores are defined with a `*new_big_segment_store` function, for example `Redis.new_big_segment_store()`, and with the `big_segments` options.

    Feature stores are used if you want to cache flag data in an external database, rather than in local memory. In the Ruby SDK, feature stores are defined with a `*new_feature_store` function, and with the `feature_store` options. To learn more, read [Storing data](/docs/sdk/features/storing-data#ruby).
  </Note>

  To learn more about the available configuration options, read [`BigSegmentsConfig`](https://launchdarkly.github.io/ruby-server-sdk/LaunchDarkly/BigSegmentsConfig.html).
</Accordion>