No results for ""
EXPAND ALL
  • Home
  • API docs

GIVE DOCS FEEDBACK

The Contexts list

Read time: 8 minutes
Last edited: Mar 22, 2024

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 contexts and attributes, read Context attributes.

Try it in your SDK: Evaluating flags

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

To learn how to retrieve expected flag variations for contexts programmatically, read How to use REST API to fetch variations served by a flag.

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.

Configure your SDK: User and context 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 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. Click the filter icon and filter the list by context kind or attribute:
The "Filter by" dialog on the "Contexts" list, with context kind filters called out.
The "Filter by" dialog on the "Contexts" list, with context kind filters called out.
  1. Alternatively, 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 Springfield

Searches 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 formatted 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
after

Returns 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"
anyOf

Returns 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"
contains

Returns 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"]
equals

Returns 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"]
exists

Returns 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
notEquals

Returns 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"]
startsWith

Returns true if 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:

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 an SDK sends an identify event or evaluates a feature flag for that context. Each time an SDK 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 an SDK 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.

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.

If you want to increase this limit, 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