From 48812b38ed1e1dbe3f713e3a118f118eb4633608 Mon Sep 17 00:00:00 2001 From: "xhuang@statsig.com" Date: Sat, 7 Feb 2026 06:28:11 +0000 Subject: [PATCH 1/3] [DOCS-155] Add accurate evaluation order documentation based on code analysis --- sdks/how-evaluation-works.mdx | 57 ++++++++++++++++++++++++++++++++++- 1 file changed, 56 insertions(+), 1 deletion(-) diff --git a/sdks/how-evaluation-works.mdx b/sdks/how-evaluation-works.mdx index 55ff77870..eb45bcde2 100644 --- a/sdks/how-evaluation-works.mdx +++ b/sdks/how-evaluation-works.mdx @@ -22,6 +22,61 @@ For more details, check our open-source SDKs [here](https://github.com/statsig-i This is not generally recommended, but for advanced use cases - e.g. a series of related experiments that needs to reuse the control and test buckets, we now expose the ability to copy and set the salts used for deterministic hashing. This is meant to be used with care and is only available to Project Administrators. It is available in the Overflow (...) menu in Experiments. +## Evaluation Order + +When evaluating gates, experiments, and layers, the SDK iterates through a list of rules generated by the server. Rules are evaluated sequentially and the first matching rule determines the result. Overrides always take precedence because they appear first in the rule list. + +### Experiments + +When you call `getExperiment`, evaluation follows this order: + +1. **ID overrides** — Specific user/unit IDs mapped to a group +2. **Conditional overrides** — Segment or gate-based overrides, evaluated in order +3. **Layer holdouts** — If the experiment is in a layer, layer-level holdout gates are checked +4. **Holdout gates** — Experiment-level holdout gates; users in a holdout receive default values +5. **Experiment exclusion** — Mutual exclusion segments that prevent users from being in multiple experiments +6. **Start status** — If the experiment is not started, users receive default values (with optional non-production environment exceptions) +7. **Layer allocation** — For experiments in a layer, the user's bucket (based on the layer's universe salt) must fall within the experiment's allocated segments. This is checked **before** targeting. +8. **Targeting gate** — Users who fail the targeting gate receive default values. This is checked **after** layer allocation. +9. **Group assignment** — The user's bucket (based on the experiment salt) determines which group they fall into. Groups are cumulative ranges across 1000 buckets. + + +A common misconception is that targeting is evaluated before allocation. In Statsig, layer allocation is checked first, then targeting, then group bucketing. For a standalone experiment (not in a layer), layer allocation effectively passes all users through. + + + +Each step uses the hash-based bucketing described above. Layer allocation and group assignment use different salts, so a user's position in the layer is independent of their group assignment within the experiment. + + +### Layers + +When you call `getLayer`, evaluation follows this order: + +1. **Override rules** — ID overrides from all experiments in the layer +2. **Layer holdout gates** — Holdout gates attached to the layer +3. **Experiment allocation** — Each experiment in the layer has a `configDelegate` rule. The user's bucket determines which experiment they are delegated to. +4. **Delegated experiment evaluation** — Once delegated, the experiment's own evaluation runs (start status, targeting gate, group bucketing as described above) + +If no experiment allocation rule matches, the user receives the layer's default values. + +### Holdouts + +Holdout gates evaluate in this order: + +1. **Experiment exclusion** — Exclusion segments (if applicable) +2. **ID overrides** — Specific user/unit IDs +3. **Population targeting gate** — If the holdout has a targeting gate, users who fail it are not held out +4. **Holdout percentage** — The pass percentage on the holdout rule determines the holdout rate + +### Gates + +When you call `checkGate`, evaluation follows this order: + +1. **ID overrides** — Specific user/unit IDs mapped to pass/fail +2. **Conditional overrides** — Segment or gate-based overrides +3. **Holdout rules** — If the gate has holdouts attached +4. **Rules** — The gate's targeting rules, evaluated in the order they appear in the console. Each rule has its own conditions and pass percentage. + ## When Evaluation Happens Evaluation happens when the gate or experiment is checked on Server SDKs. To be able to do this, Server SDKs hold the entire ruleset of your project in memory - a representation of each gate or experiment in JSON. On client SDKs, we evaluate all of the gates/experiments when you call initialize - on our servers. @@ -38,4 +93,4 @@ A common assumption is that Statsig tracks of a list of all ids and what group t ## Evaluation of null/empty unitIDs -Note, we do not apply any filtering/ business logic before we assign an individual userID. This means that even a null or empty unitID will be bucketed depending on the salt. \ No newline at end of file +Note, we do not apply any filtering/ business logic before we assign an individual userID. This means that even a null or empty unitID will be bucketed depending on the salt. From 397344a17f892c66d5fb15f8e0bc39ff3ae347b9 Mon Sep 17 00:00:00 2001 From: xhuang-statsig Date: Mon, 9 Feb 2026 16:15:37 -0800 Subject: [PATCH 2/3] Update how-evaluation-works.mdx --- sdks/how-evaluation-works.mdx | 34 +++++++++++++++------------------- 1 file changed, 15 insertions(+), 19 deletions(-) diff --git a/sdks/how-evaluation-works.mdx b/sdks/how-evaluation-works.mdx index eb45bcde2..b05bac662 100644 --- a/sdks/how-evaluation-works.mdx +++ b/sdks/how-evaluation-works.mdx @@ -26,9 +26,13 @@ This is not generally recommended, but for advanced use cases - e.g. a series of When evaluating gates, experiments, and layers, the SDK iterates through a list of rules generated by the server. Rules are evaluated sequentially and the first matching rule determines the result. Overrides always take precedence because they appear first in the rule list. + +Each step uses the hash-based bucketing described above. Layer allocation and group assignment use different salts, so a user's position in the layer is independent of their group assignment within the experiment. + + ### Experiments -When you call `getExperiment`, evaluation follows this order: +When an experiment is evaluated (you call `getExperiment`), it follows this evaluation order: 1. **ID overrides** — Specific user/unit IDs mapped to a group 2. **Conditional overrides** — Segment or gate-based overrides, evaluated in order @@ -40,17 +44,9 @@ When you call `getExperiment`, evaluation follows this order: 8. **Targeting gate** — Users who fail the targeting gate receive default values. This is checked **after** layer allocation. 9. **Group assignment** — The user's bucket (based on the experiment salt) determines which group they fall into. Groups are cumulative ranges across 1000 buckets. - -A common misconception is that targeting is evaluated before allocation. In Statsig, layer allocation is checked first, then targeting, then group bucketing. For a standalone experiment (not in a layer), layer allocation effectively passes all users through. - - - -Each step uses the hash-based bucketing described above. Layer allocation and group assignment use different salts, so a user's position in the layer is independent of their group assignment within the experiment. - - ### Layers -When you call `getLayer`, evaluation follows this order: +When a layer is evaluated (you call `getLayer`), it follows this evaluation order: 1. **Override rules** — ID overrides from all experiments in the layer 2. **Layer holdout gates** — Holdout gates attached to the layer @@ -59,6 +55,15 @@ When you call `getLayer`, evaluation follows this order: If no experiment allocation rule matches, the user receives the layer's default values. +### Gates + +When a feature gate is evaluated (you call `checkGate`), it follows this evaluation order: + +1. **ID overrides** — Specific user/unit IDs mapped to pass/fail +2. **Conditional overrides** — Segment or gate-based overrides +3. **Holdout rules** — If the gate has holdouts attached +4. **Rules** — The gate's targeting rules, evaluated in the order they appear in the console. Each rule has its own conditions and pass percentage. + ### Holdouts Holdout gates evaluate in this order: @@ -68,15 +73,6 @@ Holdout gates evaluate in this order: 3. **Population targeting gate** — If the holdout has a targeting gate, users who fail it are not held out 4. **Holdout percentage** — The pass percentage on the holdout rule determines the holdout rate -### Gates - -When you call `checkGate`, evaluation follows this order: - -1. **ID overrides** — Specific user/unit IDs mapped to pass/fail -2. **Conditional overrides** — Segment or gate-based overrides -3. **Holdout rules** — If the gate has holdouts attached -4. **Rules** — The gate's targeting rules, evaluated in the order they appear in the console. Each rule has its own conditions and pass percentage. - ## When Evaluation Happens Evaluation happens when the gate or experiment is checked on Server SDKs. To be able to do this, Server SDKs hold the entire ruleset of your project in memory - a representation of each gate or experiment in JSON. On client SDKs, we evaluate all of the gates/experiments when you call initialize - on our servers. From 7ed9ab92b1c2b2fb79d8254b20b1599a3d3e1152 Mon Sep 17 00:00:00 2001 From: xhuang-statsig Date: Mon, 9 Feb 2026 16:16:27 -0800 Subject: [PATCH 3/3] Update how-evaluation-works.mdx --- sdks/how-evaluation-works.mdx | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/sdks/how-evaluation-works.mdx b/sdks/how-evaluation-works.mdx index b05bac662..7f5e2f797 100644 --- a/sdks/how-evaluation-works.mdx +++ b/sdks/how-evaluation-works.mdx @@ -55,15 +55,6 @@ When a layer is evaluated (you call `getLayer`), it follows this evaluation orde If no experiment allocation rule matches, the user receives the layer's default values. -### Gates - -When a feature gate is evaluated (you call `checkGate`), it follows this evaluation order: - -1. **ID overrides** — Specific user/unit IDs mapped to pass/fail -2. **Conditional overrides** — Segment or gate-based overrides -3. **Holdout rules** — If the gate has holdouts attached -4. **Rules** — The gate's targeting rules, evaluated in the order they appear in the console. Each rule has its own conditions and pass percentage. - ### Holdouts Holdout gates evaluate in this order: @@ -73,6 +64,15 @@ Holdout gates evaluate in this order: 3. **Population targeting gate** — If the holdout has a targeting gate, users who fail it are not held out 4. **Holdout percentage** — The pass percentage on the holdout rule determines the holdout rate +### Gates + +When a feature gate is evaluated (you call `checkGate`), it follows this evaluation order: + +1. **ID overrides** — Specific user/unit IDs mapped to pass/fail +2. **Conditional overrides** — Segment or gate-based overrides +3. **Holdout rules** — If the gate has holdouts attached +4. **Rules** — The gate's targeting rules, evaluated in the order they appear in the console. Each rule has its own conditions and pass percentage. + ## When Evaluation Happens Evaluation happens when the gate or experiment is checked on Server SDKs. To be able to do this, Server SDKs hold the entire ruleset of your project in memory - a representation of each gate or experiment in JSON. On client SDKs, we evaluate all of the gates/experiments when you call initialize - on our servers.