Repository navigation
feat(server): support known-absent property keys in local evaluation - #993
Open
marandaneto wants to merge 5 commits into
Open
marandaneto wants to merge 5 commits into
marandaneto wants to merge 5 commits into
Conversation
Contributor
posthog-android Compliance ReportDate: 2026-11-20T10:06:40.307803+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:28
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
During local evaluation, the server SDK treats a property key that the caller left out as unknown. A filter on that key can't be decided locally, so the SDK calls
/flagsinstead. A caller has no way to say "this person definitely doesn't haveplan". This causes extra remote calls. It also means local results and the/flagsfallback could disagree about missing properties.This PR adds an optional list of property keys the caller knows are absent. It follows the cross-SDK spec in PostHog/sdk-specs#233.
New public input
PostHogEvaluateFlagsOptions,PostHogFeatureFlagOptionsandPostHogFeatureFlagResultOptionseach get two new optional fields and builder methods:personPropertyKeysKnownAbsent, a list of person property keys.groupPropertyKeysKnownAbsent, a map from group type name to a list of group property keys.These options already feed
evaluateFlags,getFeatureFlag,isFeatureEnabled,getFeatureFlagPayloadandgetFeatureFlagResult. When nothing is listed, every call behaves exactly as before.PostHogCaptureOptionsdoes not get the new fields. To attach flags evaluated with known-absent keys to an event, evaluate a snapshot with these options and pass it tocapture.Local evaluation behavior
/flagsfallback.is_not_set,is_not,not_icontains,not_starts_with,not_ends_withandnot_regexmatch.is_setand every other supported operator do not match. This includesexact,icontains,regex, the numeric operators, allsemver_*operators and the date operators.distinct_idin person properties.icontains_multiandbetween, still fall back to/flagseven when the key is listed. Malformed filter values stay unresolved as today. An invalidnot_regexpattern does not match.FlagEvaluatorTest.testKnownAbsentCohortLeafChecksOperatorSupportBeforeTheTableandPostHogKnownAbsentPropertyKeysTest("an unsupported operator in a cohort leaf on a listed key falls back before known absence") cover a cohort leafplan not_between [1, 2]on a listed key, with and withoutnegation, and check that it stays unresolved withunsupported_definitionand falls back to/flags.__posthog_person_metadata__are ignored.negationis applied. Static cohort membership and holdouts are unchanged./flagsrequest bodyWhen a call with listed keys falls back to
/flags, the request body includesperson_property_keys_known_absent(a list of strings) andgroup_property_keys_known_absent(an object from group type to a list of strings). A field is left out when the caller didn't provide it or it is empty. Calls without listed keys send the same body as before.To support this,
PostHogApi.flagsin the coreposthogmodule gets a new overload that takes the two lists. The existingflagsmethod keeps its JVM signature, so aposthog-serverbuilt against an older core still works. The Android client does not use the new overload.Over 1000 keys
Each list can hold at most 1000 keys. Duplicates count, and the limit applies to each group type separately. If a list is over the limit, the SDK logs a warning and evaluates nothing. It sends no request and never truncates the list. The call returns its normal "unavailable" result.
evaluateFlagsreturns an empty snapshot.getFeatureFlag,getFeatureFlagPayloadandisFeatureEnabledreturn the default value.getFeatureFlagResultreturnsnull.Not included
$feature_enrollment/<flag key>as known absent. Only posthog-python evaluates feature enrollment locally. Other SDKs are 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 locally yet, so they keep falling back to/flags. They are tracked in Support icontains_multi and between operators in SDK local flag evaluation posthog#138581.feature_flags_local_evaluation_v1, so the harness wouldn't run the new suite against it.💚 How did you test it?
New tests:
FlagEvaluatorTestcovers the result for every operator on a listed key, an omitted key that isn't listed, unsupported operators and malformed filters on a listed key, cohort negation, flag dependencies, the metadata prefix and empty lists, and the 1000-key limit with duplicates.PostHogKnownAbsentPropertyKeysTestruns the full client against MockWebServer. It covers a listed key overriding a supplied value with no/flagscall, overriding thedistinct_idthe SDK adds, group-type scoping, the/flagsbody with and without listed keys, separate caching for getters, fallback for an unsupported operator, and the over-limit behavior for every entry point.PostHogFlagsRequestTestchecks that the body includes the new fields when provided and leaves them out when they are null or empty.Commands run locally with JDK 17:
./gradlew :posthog:test :posthog-server:test spotlessCheck :posthog:apiCheck :posthog-server:apiCheckpassed.CI now runs SDK test harness 1.34.0. It passed 47 of 47 tests in CI and locally with
docker composeinsdk_compliance_adapter. The newnon_utc_event_timestamp_is_converted_to_utctest exposed that the adapter ignored thetimestampon/capture, so the adapter now passes it tocapture. The known-absent suite doesn't run because the adapter doesn't declarefeature_flags_local_evaluation_v1orfeature_flags_known_absent_v1.Not run locally: Android instrumented tests and the Compose survey tests.
📝 Checklist
If releasing new changes
pnpm changesetto generate a changeset file🤖 Agent context
Autonomy: Human-driven (agent-assisted)
Pi coding agent (Claude) implemented this from the spec in PostHog/sdk-specs#233 as part of the same change across several SDKs. Before pushing, an automated review ran with a different model,
openai-codex/gpt-6.2-astra.PostHogApi.flagschanged its JVM signature. Aposthog-serverbuilt against an older core would fail at runtime if only core was upgraded. The old signature now stays, and the new parameters are in a separate overload.$feature_flag_error: unknown_errorin$feature_flag_called. A local check showedmainalready does this for any getter that resolves locally on a cold cache, with no listed keys. The new code path matches the existing behavior. A fix belongs in a separate PR.The new options are on all three options classes so that the deprecated per-flag getters stay consistent with
evaluateFlags.