• Home
  • Integrations
  • SDKs
  • Guides
  • API docs
    No results for ""
    EXPAND ALL

    EDIT ON GITHUB

    The Contexts list

    Read time: 5 minutes
    Last edited: May 30, 2023

    Overview

    This topic explains what the Contexts list is, how it is populated, and how to use it.

    The Contexts list shows you all of the contexts that have encountered feature flags in your application. You can select any context to view its context detail page, which gives you a summary view of how the context experiences all of the features in your app, and lets you customize their experience from one screen. To learn more, read The context details page.

    Understanding the Contexts list

    The Contexts list populates automatically when different contexts encounter a feature flag and are evaluated by a LaunchDarkly SDK. The data in the list is populated from the data you send in variation calls, as well as data from identify calls. To learn more about evaluating contexts in the SDK, read Evaluating flags. To learn more about contexts and attributes, read Context attributes.

    Here is an image of the Contexts list:

    The "Contexts" list.
    The "Contexts" list.
    Multi-contexts appear individually in the Contexts list

    Your application may evaluate a feature flag for a multi-context, that is, one that contains multiple context kinds. For example, your application may send a multi-context that contains the "user," "organization," and "device" context kinds, all in one evaluation call in the LaunchDarkly SDK. When you do this, all three individual contexts appear separately in your Contexts list. You can use the context kind filters to search for them separately.

    From the list, you can filter contexts by name, kind, or attribute. You can also sort the list to identify the oldest or most recent contexts evaluated in your LaunchDarkly account. By default, the most recently active contexts appear first. Click the toggle arrow on the "Last seen" column to sort the list by least recently active contexts.

    If a context is re-evaluated, and its attributes change within five minutes of the previous evaluation, and the context key stays the same, the list deduplicates the context and does not reflect the latest evaluation. This does not affect variation calls, which always use the attribute values passed to them.

    The SDK does not use the attributes on the Contexts list to evaluate flags

    The SDK only evaluates flags based on the context you provide in the evaluation call. The SDK does not use the attributes shown on the Contexts list, and context attributes are not synchronized across SDK instances. You must provide all applicable attributes for each evaluation in the SDK for your targeting rules to apply correctly. To learn more, read Evaluating flags.

    To learn more about how the Contexts list is populated, and how you might exceed the 100,000,000 context limit, read Anonymous contexts.

    You can also use the REST API: Get contexts, Get context instances

    Creating contexts

    You cannot create contexts from the Contexts list in the LaunchDarkly user interface (UI). The list only includes contexts that have already been evaluated by a LaunchDarkly SDK.

    To learn how to configure contexts in your SDK, read Context and user configuration.

    Send the context name in the variation call

    You must send the context name in the variation call in the LaunchDarkly SDK for the name to display in the LaunchDarkly user interface (UI). To learn more, read Example: Contexts that affect Anna's experience.

    To learn how to create context kinds, read Creating context kinds.

    Filtering contexts

    You can filter contexts on the Contexts list by context kind, name, key, or attribute.

    To filter contexts:

    1. In the filter field, enter all or the beginning of a context kind, name, key, or attribute.
    • To filter by an attribute for a specific context kind, separate the context kind and its attribute with a period (.). For example, to search the "state" attribute of "user" contexts, use user.state.

    A search query for "user" context kinds.
    A search query for "user" context kinds.

    1. Press enter. Only contexts with matching attribute values now display on the Contexts list.

    You can also use the REST API: Search for contexts, Search for context instances

    Using advanced filter strings

    In addition to filtering by context kind, name, or attribute, you can create advanced filter strings to search for specific values in specific fields.

    This table contains examples of advanced filter strings and what they search for:

    Filter stringDescription
    location equals SpringfieldSearches for all context kinds for a location attribute with the value of "Springfield"
    organization.location anyOf ["Springfield","Midway"]Searches for all organization contexts that have a location attribute with the value of "Springfield" or "Midway"
    device.type startsWith "Samsung"Searches for all device contexts that have a type attribute that starts with "Samsung"

    Expand the advanced context filtering reference below to learn how to create filter strings on the Contexts list.

    Click to expand the advanced context filtering reference

    A filter string contains three elements:

    • Field: The field is the first part of the filter string. It is a field in the contexts that you want to filter based on.
      • If you're searching an attribute for a specific context kind, separate the context kind and its attribute with a period (.).
      • Field names are always strings. If they appear within double quotes ("), then they are encoded as if they were a JSON string. Unquoted strings must escape commas ,, pipes |, parentheses (), exclamation points !, slashes \, and whitespace by prefixing the character with \.
    • Operator: The operator is the second part of the filter string. It describes the conditions by which the filter identifies the match value. To learn about all of the available operators, view the "Operators" table below.
    • Match value: The match value is the third part of the filter string. It describes the values that the filter will identify.
      • A match value must be in the same format as a JSON value or an unquoted string. Unquoted strings must escape commas ,, pipes |, parentheses (), exclamation points !, slashes \, and whitespace by prefixing the character with \.

    Operators

    This table lists all of the available operators and related examples:

    OperatorDescriptionExample
    afterReturns true if any of the values in a field, which should be dates, are after or equal to the provided datetime. Valid match values should be numbers in unix epoch milliseconds, or date time strings in RFC-3339 format.user.signup after "2022-09-21T19:03:15+00:00"
    anyOfReturns true if any of the values in a field match any of the values in the match value. This operator is only available for the following fields: applicationId, id, key, kind, kindKey, kindKeys.applicationId anyOf [44]
    kind anyOf ["device","org"]
    key anyOf [1,2,3,4]
    beforeReturns true if any of the values in a field, which should be dates, are before or equal to the provided datetime. Valid match values should be numbers in unix epoch milliseconds, or date time strings in RFC-3339 format.user.signup before "2022-09-21T19:03:15+00:00"
    containsReturns true if all the match values are also found in the values of the field. This operator is only available for the following fields: kindKeys, kinds.kindKeys contains ["Sandy","Jesse"]
    kinds contains ["s"]
    equalsReturns true if there is an exact match on the entire field.organization.number equals 44
    "kind" equals "device"
    device.option equals true
    organization.number equals [1,2,3,4]
    user.name equals ["Sandy", "Jesse"]
    existsReturns true if the field matches the specified existence. For example, if you pass true and the field exists, this returns the context. This operator is available for `name` and for custom attributes.organization.name exists true
    device.option exists false
    notEqualsReturns true if there is not an exact match on the entire field.organization.number notEquals 44
    "user.name" notEquals Sandy
    device.option notEquals true
    organization.number notEquals [1,2,3,4]
    user.name notEquals ["Sandy", "Jesse"]
    startsWithReturns true the value in a field, which should be a singular string, begins with the provided substring.user.name startsWith San
    device.os startsWith "iOS"

    Customizing the Contexts list

    You can customize which attributes appear on the Contexts list. To start, click the Attributes button.

    Here is a screenshot of the Attributes button on the list:

    The "Contexts" list with the "Show attributes" button called out.
    The "Contexts" list with the "Show attributes" button called out.

    The Attributes menu lets you choose attributes to appear on the Contexts list. After you choose specific attributes, that view persists when you visit the list in the future.

    Modifying feature flags for a context instance

    Click a context to manage the feature flags that apply to it, view the context instances that have encountered your flags, view the segments that the context is in, and view a full list of context attributes. To learn more, read The context details page.

    Context storage

    The Contexts list shows only cached context information. A context will appear on the list for 30 days after a flag sends an identify or flag evaluation event for them. Each time a flag sends a new event for the context, the 30-day period starts over.

    After 30 days with no new identify or flag evaluation events, contexts age out of the system and their information no longer appears on the list. After a context ages out of the system, it will reappear on the list if a flag sends an identify or flag evaluation event for it again.

    If you want to keep contexts on the list for longer than 30 days between flags sending identify or flag evaluation events, you can manually call identify for all of the contexts that you wish to retain. To learn how to do this in your SDK, read Identifying and changing contexts.

    Accounts are limited to 100,000,000 context instances. If you reach the context instance limit flag evaluations will still work for new contexts, but LaunchDarkly will begin deleting the oldest context instances on the list to make room for new context instances, even if they are not yet more than 30 days old. LaunchDarkly continues to delete old context instances as new ones are added to keep the list at no more than 100,000,000. To learn more, read Account usage metrics.

    If you want to increase your client-side monthly context instance (MCI) limit to include more contexts from your client-side SDKs on the list, contact Support.

    Removing a context instance

    You can delete individual context instances from the Contexts list by clicking the overflow menu and choosing "Delete instance." Deleting a context instance deletes all versions of that instance.

    The overflow menu only appears if there is exactly one context instance, due to the risks of deleting multiple instances at once.

    You can also delete context instances from the context details page. To learn how, read Deleting a context instance.

    To learn more about context instances, read Context instances.

    You can also use the REST API: Delete context instances