Repository navigation
feat(flags): support known-absent property keys in local evaluation - #261
Open
marandaneto wants to merge 6 commits into
Open
marandaneto wants to merge 6 commits into
marandaneto wants to merge 6 commits into
Conversation
Contributor
posthog-elixir Compliance ReportDate: 2026-11-20T09:52:15.527262+00:00 ✅ All Tests Passed!47/47 tests passed Capture Tests✅ 30/30 tests passed View Details
Feature_Flags Tests✅ 17/17 tests passed View Details
|
marandaneto
marked this pull request as ready for review
November 20, 2026 10:29
PR overviewNo security issues were found in this pull request. Reviews
|
7 of 25 tasks
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
💡 Motivation and Context
Local feature flag evaluation treats a property key missing from
person_propertiesorgroup_propertiesas unknown. That is the right default, because the SDK can't tell "this person has noplan" apart from "the caller didn't passplan". But it means callers have no way to say "this person definitely doesn't haveplan". A flag with anis_not_setcondition onplancan't resolve locally and falls back to/flags. The local result and the/flagsresult could also disagree.This PR adds an optional way to list property keys the caller knows are absent. It follows the cross-SDK spec in PostHog/sdk-specs#233 and the backend support in PostHog/posthog#138239.
Closes part of PostHog/posthog#88947.
New options
Every flag evaluation entry point that takes a body accepts two new optional keys. That covers
evaluate_flags/2,get_feature_flag_result/4,check/3,flags/2andflags_for/2, plus bodies built fromPostHog.set_context/2.:person_property_keys_known_absentis a list of person property keys.:group_property_keys_known_absentis a map from group type to a list of group property keys.Keys can be strings or atoms.
Local evaluation
is_not_set,is_not,not_icontains,not_starts_with,not_ends_withandnot_regexmatch without a/flagscall.is_setand every other operator do not match. That includesexact, the search and regex operators, numeric comparisons, allsemver_*operators (includingsemver_neq) and the date operators.distinct_idfor person properties and$group_keyfor group properties.__posthog_person_metadata__are ignored.icontains_multion a listed key still falls back to/flags.negation. Static cohorts and holdouts are unchanged.unsupported not_between in a dynamic cohort leaf on a listed key stays inconclusivecovers a cohort leaf, with and withoutnegation./flagsrequest bodyWhen the SDK calls
/flagsand the caller listed keys, the request sendsperson_property_keys_known_absent: [...]andgroup_property_keys_known_absent: %{group_type => [...]}. This happens on local fallback and on remote-only calls. A field is left out when the caller didn't provide it or it is empty. Group types with an empty list are dropped.Validation and the 1000-key limit
Each list holds at most 1000 keys. Duplicates count, and each group type is counted on its own. A longer list returns
{:error, %PostHog.Error{}}. The SDK does not truncate the list and does not send a request. The same error is returned for values of the wrong type. That covers a non-list, non-string keys, invalid UTF-8, improper lists, and a group type given both as an atom and as a string. String-keyed bodies passed toflags/2are checked the same way as atom-keyed ones.Not included
$feature_enrollmenthandling. This SDK doesn't evaluate enrollment conditions locally. That work is tracked in Support local feature enrollment evaluation across server SDKs posthog#138580.icontains_multi,not_icontains_multi,betweenandnot_betweenoperators. This SDK doesn't support them yet, so they still fall back to/flagseven for a listed key. That work is tracked in Support icontains_multi and between operators in SDK local flag evaluation posthog#138581.feature_flags_local_evaluation_v1, so it doesn't declarefeature_flags_known_absent_v1either.Links
💚 How did you test it?
New tests in
test/posthog/feature_flags/known_absent_property_keys_test.exscover:distinct_idand$group_key/flagsbody including the fields on fallback and leaving them out when empty or not providedflags/2not_betweenin a dynamic cohort leaf on a listed key staying inconclusive withunsupported_definition, with and withoutnegationI ran these locally. All passed.
mix test: 1131 passed, 18 excluded (integration tests, which need a real API key, were not run). One earlier full run had a single failure that did not come back in three later runs.mix format --check-formattedmix compile --warnings-as-errorsmix credo --strictmix posthog.public_api --checkCI now runs SDK test harness 1.34.0 (47 of 47 compliance tests passed). The
feature_flags_known_absentsuite does not run, because the adapter declares onlycapture_v0andencoding_gzip, notfeature_flags_local_evaluation_v1orfeature_flags_known_absent_v1.📝 Checklist
If releasing new changes
sampo addto generate a changeset file🤖 Agent context
Autonomy: Human-driven (agent-assisted)
Written with Pi agents (Claude) as one lane of a change across several SDKs. An automated review (autoreview, GPT model) ran three rounds. The first two rounds found input validation gaps: string-keyed bodies, improper lists, invalid group type keys, invalid UTF-8, and duplicate group types. Those are fixed in follow-up commits. The third round asked to reject a
nillist for one group type. I kept that case as "nothing listed" to match how a top-levelnilor an empty list is handled.