Cohort Dimension Support in Superposition

[knutties]

Problem statement

Superposition has moved towards strict equality in contexts to support completely unambiguous resolution while performing operations. This removes the operator flexibility that was earlier available in constructing context expressions. This flexibility allowed users to construct context expressions like dimension1 in ['val1' , 'va2']. As mentioned earlier, this flexibility causes ambiguous resolution behaviour as Superposition does not yet assign priority to operators (it does only for dimensions).

So the problem statement at hand is how to bring back this feature while retaining the unambiguous resolution semantics.

Proposed Solution

To solve this problem, we introduce a concept called Cohort Dimensions. Cohort Dimensions are dimensions which are derived out of existing dimensions (we will refer to the existing dimensions as Primary Dimensions going forward.). Cohort dimensions have the following characteristics:

• Each cohort dimension is defined in terms a one Primary Dimension.
• Each cohort dimension consists of one or more variants (just like experiments). Variants are values that the cohort dimensions can take. Each variant is defined by logical expressions involving the primary dimension. These logical expressions can have ranges, pattern matches, array membership etc.
• Each cohort dimension will have a default variant auto-created.
• Cohort dimension variants are an ordered set - the user is expected to order them because the matching of primary dimension to the cohort dimension will happen in the order that the user has declared and the first matching variant will be assigned as the value of cohort dimension.
• During resolution of a config, cohort dimensions are computed from primary dimensions and added to the context for final resolution.
• For the purpose of creating experiments and overrides - cohort dimensions behave the same way as primary dimensions.
• Once a cohort dimension is created from a primary dimension, a dependency relationship is established between primary and the corresponding cohort dimension. The primary dimension depends on the cohort dimension i.e. whenever the primary dimension is introduced in an experiment or an override - the cohort dimension is automatically added to the experiment or override with its value filled in.
• The cohort dimension should be lower in priority to the primary dimension (is this really needed ?? - what happens if this constraint is not there)
• Changes in cohort variant definitions are not protected by experimentation - they will be binary roll-outs i.e. a full-flip of configuration values will happen if the cohort variant definitions change.

Technical implementation

[Datron]

Some thoughts -

• Cohorts don't seem to derive a dimension, rather abstracts a context so it can be reused again and again. We should define cohorts in terms of context, this way you can define a cohort recursively (a cohort abstracting a cohort)
• If we have a cohort that is defined with multiple enums - lets say user cohort has admin, qa, default. Can I define a context with both admin and qa? I'm assuming the cohort definition will have to contain a 3rd enum - admin_qa which encompasses both admin and QA
• Inside a cohort enum, what are the constraints on the operators that can be used inside the enum definition?

[knutties]

We should define cohorts in terms of context, this way you can define a cohort recursively (a cohort abstracting a cohort)

That is an interesting way to look at it. Context is a slightly wider concept than dimension. By definition a dimension expression is a context - and cohorts are a set of arms each with its own dimension expression involving the same dimension.

Atleast the reason for calling it dimension is that it appears so in the experiments and overrides - which is the main part of Superposition.

If we have a cohort that is defined with multiple enums - lets say user cohort has admin, qa, default. Can I define a context with both admin and qa

No - it is a dimension for the purposes of an experiment/override - in a context - one dimension can appear only once - the same applies to cohort dimensions. In your example - yes a third enum would be required - typically cohorts should have variants which capture mutually exclusive sets - but not necessary. That is left to users to decide. If they overlap then the user will have to order the variants appropriately.

Inside a cohort enum, what are the constraints on the operators that can be used inside the enum definition?

I think we can allow all the operators that are supported today - I don't see why we cannot. Atleast that is where we should start off till we see that an operator cannot be supported.

[Datron]

Table structure

CREATE TABLE IF NOT EXISTS cohorts(
id BIGINT PRIMARY KEY,
name TEXT NOT NULL,
description TEXT NOT NULL,
change_reason TEXT NOT NULL,
definition JSON NOT NULL,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP NOT NULL,
created_by TEXT NOT NULL,
last_modified_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP NOT NULL,
last_modified_by TEXT NOT NULL
)

The definition JSON field represents the cohorts enums. For example, a cohort defined as:

Cohort users
admin -> user_id in ['kara', 'ankit']
qa -> user_id in ['c', 'd']

Will be written as a map to the DB

{
	"admin": {
		"and": [
			"in": [
				{"var": ["user_id"]},
				["kara", "ankit"]
			]
		]
	},
	"qa": {
		"and": [
			"in": [
				{"var": ["user_id"]},
				["c", "d"]
			]
		]
	} 
}

Why write it like this? It makes matching enums a lookup in a map and lets us append the jsonlogic to an existing context or amend it after evaluation in contexts without jsonlogic.

API Design

API	request	response	description
GET /cohorts	None, will take filters and pagination params as query params per standard	list of cohorts	cohorts listing API
POST /cohorts	takes cohort name, description, change reason and definition	created cohort object or error	create a new cohort
PUT /cohorts/{id}	Update cohort definition, description or change reason	updated cohort object or error	update a cohort
GET /cohorts/{id}	None	fetched cohort object or error	fetch a cohort
DELETE /cohorts/{id}	None	deleted cohort object or error	delete a cohort

[knutties]

@Datron - do we need the and and the in - or is it basically the same strategy to help with adding conditions later ?

[knutties]

id BIGINT PRIMARY KEY,
name TEXT NOT NULL,

cohort name itself is id ? I am assuming it will become a dimension as well - the uniqueness need to be across two tables in this case.

[Datron]

Our discussion so far:

Cohorts can be a type of dimension, and stored as a dimension with a column to differentiate between a cohort dimension and regular dimension. The cohort dimensions will have the following:

• A weight defined for the cohort
• it will derive based a single dimension
• the cohort will have a set of enums
• every enum maps to a context in jsonlogic

The evaluation happens as follows, taking an example:

Cohort Users
admin -> user_id in ['a', 'b']
qa -> user_id in ['c', 'd', 'e']

Assume the application is querying with the context -> user_id == 'a'

• First do a cohort computation step where the user_id is matched against all cohorts that derive it, find the first cohort enum that matches the given dimension value
• Plug the discovered cohort dimensions into the evaluation context
• Run the config resolution as usual

Some questions still left

• Should underlying dimension depend on cohort dimension? (dependent dimensions)
• Should the priority of cohort dimension be lower than the underlying dimension?

[Datron]

If cohorts behave as a dimension, can autocomplete and validation functions work on it?