Contexts

Contexts are people, services, machines, or other resources that encounter feature flags in your product. Contexts are identified by their kind, which describes the type of resources encountering flags, and by their key. Each unique combination of one or more contexts that have encountered a feature flag in your product is called a context instance.

When you use the LaunchDarkly SDK to evaluate a flag, you provide a context to that call. LaunchDarkly records the key and attributes of each context instance. You can view these in the LaunchDarkly user interface from the Contexts list, or use the Context APIs. To learn more, read Contexts.

LaunchDarkly provides APIs for you to:

• retrieve contexts, context instances, and context attribute names and values
• search for contexts or context instances
• delete context instances
• fetch context kinds
• create and update context kinds

To learn more about context kinds, read Context kinds.

Contexts are always scoped within a project and an environment. Each environment has its own set of context instance records.

Several of the endpoints in the contexts API require a context instance ID or application ID. Both of these IDs are returned as part of the Search for context instances response. The context instance ID is the id field of each element in the items array. The application ID is the applicationId field of each element in the items array. By default, the application ID is set to the SDK you are using. In the LaunchDarkly UI, the application ID and application version appear on the context details page in the “From source” field. You can change the application ID as part of your SDK configuration. To learn more, read Application metadata configuration.

Filtering contexts and context instances

When you search for contexts or context instances, you can filter on certain fields using the filter parameter either as a query parameter or as a request body parameter.

The filter parameter supports the following operators: after, anyOf, before, contains, equals, exists, notEquals, startsWith.

Expand for details on operators and syntax

after

Returns contexts or context instances if any of the values in a field, which should be dates, are after the provided time. For example:

• myField after "2022-09-21T19:03:15+00:00"

anyOf

Returns contexts or context instances if any of the values in a field match any of the values in the match value. For example:

• myField anyOf [44]
• myField anyOf ["phone","tablet"]
• myField anyOf [true]"

before

Returns contexts or context instances if any of the values in a field, which should be dates, are before the provided time. For example:

• myField before "2022-09-21T19:03:15+00:00"

contains

Returns contexts or context instances if all the match values are found in the list of values in this field. For example:

• myListField contains 44
• myListField contains ["phone","tablet"]
• myListField contains true

equals

Returns contexts or context instances if there is an exact match on the entire field. For example:

• myField equals 44
• myField equals "device"
• myField equals true
• myField equals [1,2,3,4]
• myField equals ["hello","goodbye"]

exists

Returns contexts or context instances if the field matches the specified existence. For example:

• myField exists true
• myField exists false
• *.name exists true

notEquals

Returns contexts or context instances if there is not an exact match on the entire field. For example:

• myField notEquals 44
• myField notEquals "device"
• myField notEquals true
• myField notEquals [1,2,3,4]
• myField notEquals ["hello","goodbye"]

startsWith

Returns contexts or context instances if the value in a field, which should be a singular string, begins with the provided substring. For example:

• myField startsWith "do"

You can also combine filters in the following ways:

• Use a comma (,) as an AND operator
• Use a vertical bar (|) as an OR operator
• Use parentheses () to group filters

For example:

• myField notEquals 0, myField notEquals 1 returns contexts or context instances where myField is not 0 and is not 1
• myFirstField equals "device",(mySecondField equals "iPhone"|mySecondField equals "iPad") returns contexts or context instances where myFirstField is equal to “device” and mySecondField is equal to either “iPhone” or “iPad”

Supported fields and operators

You can only filter certain fields in contexts and context instances when using the filter parameter. Additionally, you can only filter some fields with certain operators.

When you search for contexts, the filter parameter supports the following fields and operators:

When searching for context instances, the filter parameter supports the following fields and operators