Fractional Operation
OpenFeature allows clients to pass contextual information which can then be used during a flag evaluation. For example, a client could pass the email address of the user.
// Factional evaluation property name used in a targeting rule
"fractional": [
// Evaluation context property used to determine the split
// Note using `cat` and `$flagd.flagKey` is the suggested default to seed your hash value and prevent bucketing collisions
{
"cat": [
{ "var": "$flagd.flagKey" },
{ "var": "email" }
]
},
// Split definitions contain an array with a variant and relative weights
[
// Must match a variant defined in the flag definition
"red",
// The probability this variant is selected
50
],
[
// Must match a variant defined in the flag definition
"green",
// The probability this variant is selected
50
]
]
If not specified, the default weight for a variant is set to 1, so an alternative to the example above would be the following:
// Factional evaluation property name used in a targeting rule
"fractional": [
// Evaluation context property used to determine the split
// Note using `cat` and `$flagd.flagKey` is the suggested default to seed your hash value and prevent bucketing collisions
{
"cat": [
{ "var": "$flagd.flagKey" },
{ "var": "email" }
]
},
// Split definitions contain an array with a variant and relative weights
[
// Must match a variant defined in the flag definition
"red"
],
[
// Must match a variant defined in the flag definition
"green"
]
]
See the headerColor flag.
The defaultVariant is red, but it contains a targeting rule, meaning a fractional evaluation occurs for flag evaluation with a context object containing email and where that email value contains @faas.com.
In this case, 25% of the evaluations will receive red, 25% will receive blue, and so on.
Assignment is deterministic (sticky) based on the expression supplied as the first parameter ({ "cat": [{ "var": "$flagd.flagKey" }, { "var": "email" }]}, in this case).
The value retrieved by this expression is referred to as the "bucketing value" and must be a string.
Other primitive types can be used by casting the value using "cat" operator.
For example, a less deterministic distribution can be achieved using { "cat": [{ "var": "$flagd.timestamp" }]}.
The bucketing value expression can be omitted, in which case a concatenation of the targetingKey and the flagKey will be used.
The fractional operation is a custom JsonLogic operation which deterministically selects a variant based on
the defined distribution of each variant (as a relative weight).
This works by hashing (murmur3)
the given data point and using an algorithm leveraging pure integer arithmetic, with math.MaxInt32 (2,147,483,647) as the maximum weight sum.
This provides consistent, efficient, sub-percent granularity (down to ~0.00000005%) for high-throughput environments.
Whichever bucket this falls in decides which variant is selected.
As hashing is deterministic we can be sure to get the same result every time for the same data point.
The fractional operation can be added as part of a targeting definition.
The value is an array and the first element is a nested JsonLogic rule which resolves to the hash key.
This rule should typically consist of a seed concatenated with a session variable to use from the evaluation context.
This value should typically be something that remains consistent for the duration of a users session (e.g. email or session ID).
The seed is typically the flagKey so that experiments running across different flags are statistically independent, however, you can also specify another seed to either align or further decouple your allocations across different feature flags or use-cases.
The other elements in the array are nested arrays with the first element representing a variant and the second being the relative weight for this option.
There is no limit to the number of elements.
[!NOTE] Previous versions of the
fractionaloperation used percentage-based weights that had to sum to 100 and were limited to 1% precision.
Example
Flags defined as such:
{
"$schema": "https://flagd.dev/schema/v0/flags.json",
"flags": {
"headerColor": {
"variants": {
"red": "#FF0000",
"blue": "#0000FF",
"green": "#00FF00"
},
"defaultVariant": "red",
"state": "ENABLED",
"targeting": {
"fractional": [
{
"cat": [
{ "var": "$flagd.flagKey" },
{ "var": "email" }
]
},
[
"red",
50
],
[
"blue",
20
],
[
"green",
30
]
]
}
}
}
}
will return variant red 50% of the time, blue 20% of the time & green 30% of the time.
Command:
curl -X POST "localhost:8013/flagd.evaluation.v1.Service/ResolveString" -d '{"flagKey":"headerColor","context":{"email": "foo@bar.com"}}' -H "Content-Type: application/json"
Result:
Command:
curl -X POST "localhost:8013/flagd.evaluation.v1.Service/ResolveString" -d '{"flagKey":"headerColor","context":{"email": "foo@test.com"}}' -H "Content-Type: application/json"
Result:
Notice that rerunning either curl command will always return the same variant and value.
The only way to get a different value is to change the email or update the fractional configuration.
Nested Fractional Evaluation
The fractional operation supports nested JSONLogic expressions within its arguments, enabling advanced use cases.
Nested Conditional Variants
Conditional logic within each bucket:
"fractional": [
[
{
"if": [
{ "in": [{ "var": "locale" }, ["us", "ca"]] },
"red",
"grey"
]
},
25
],
[
"blue",
25
],
[
"green",
25
],
[
"grey",
25
]
]
Computed Weights with JSONLogic
Weight values can be JSONLogic expressions, enabling progressive rollouts and dynamic traffic splitting without a dedicated operator. This allows you to use arbitrary JSONLogic expressions to compute weights at runtime. This is especially useful for time-based weight calculations.
Time-Based Rollout Example
Use flagd's built-in $flagd.timestamp variable to create time-based progressive rollouts.
The timestamp is in Unix epoch seconds.
{
"fractional": [
["on", { "-": [{ "var": "$flagd.timestamp" }, 1743360000] }],
["off", { "-": [1743964800, { "var": "$flagd.timestamp" }] }]
]
}
As time advances, the weight of "on" grows and "off" shrinks, producing a deterministic progressive rollout.
This example:
- Starts on Mar 30, 2025 (timestamp
1743360000) - Completes on Apr 6, 2025 (timestamp
1743964800, 7 days later)
Environment-Based Rollout Example
Roll out differently based on environment:
"fractional": [
{ "var": "email" },
["new-feature", {
"if": [
{ "==": [{ "var": "environment" }, "production"] },
10,
{
"if": [
{ "==": [{ "var": "environment" }, "staging"] },
50,
100
]
}
]
}],
["control", {
"if": [
{ "==": [{ "var": "environment" }, "production"] },
90,
{
"if": [
{ "==": [{ "var": "environment" }, "staging"] },
50,
0
]
}
]
}]
]
High Precision Example
Use large weight values for sub-percent granularity in high-traffic environments:
This splits approximately 1/1,000,000 of traffic to canary and the remaining to control.
Migrating from legacy "fractionalEvaluation"
If you are using a legacy fractional evaluation (fractionalEvaluation), it's recommended you migrate to fractional.
The new fractional evaluator supports nested properties and JsonLogic expressions.
To migrate, simply use a JsonLogic variable declaration for the bucketing property, instead of a string:
old:
"fractionalEvaluation": [
"email",
[ "red", 25 ], [ "blue", 25 ], [ "green", 25 ], [ "yellow", 25 ]
]
new: