Skip to content

feat(server): support known-absent property keys in local evaluation - #993

Open
marandaneto wants to merge 5 commits into
mainfrom
feat/flags-known-absent-property-keys
Open

marandaneto wants to merge 5 commits into
mainfrom
feat/flags-known-absent-property-keys

Conversation

@marandaneto

@marandaneto marandaneto commented Nov 19, 2026 •

Copy link
Copy Markdown
Member

💡 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 /flags instead. A caller has no way to say "this person definitely doesn't have plan". This causes extra remote calls. It also means local results and the /flags fallback 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, PostHogFeatureFlagOptions and PostHogFeatureFlagResultOptions each 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, getFeatureFlagPayload and getFeatureFlagResult. When nothing is listed, every call behaves exactly as before.

val flags =
    posthog.evaluateFlags(
        "user-1",
        PostHogEvaluateFlagsOptions.builder()
            .personProperty("email", "user@example.com")
            .personPropertyKeysKnownAbsent(listOf("plan"))
            .group("organization", "org-1")
            .groupPropertyKeysKnownAbsent("organization", listOf("tier"))
            .build(),
    )

PostHogCaptureOptions does 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 to capture.

Local evaluation behavior

  • A filter on a listed key is decided locally with no /flags fallback. is_not_set, is_not, not_icontains, not_starts_with, not_ends_with and not_regex match. is_set and every other supported operator do not match. This includes exact, icontains, regex, the numeric operators, all semver_* operators and the date operators.
  • A listed key counts as absent even when the caller also passed a value for it. It also overrides values the SDK adds itself, such as distinct_id in person properties.
  • A key that is left out and not listed still can't be decided locally, as today.
  • Operators the SDK doesn't support, such as icontains_multi and between, still fall back to /flags even when the key is listed. Malformed filter values stay unresolved as today. An invalid not_regex pattern does not match.
  • Operator support is checked before the known-absent table, in flag conditions and in dynamic-cohort leaves, as the latest spec revision requires (docs(flags): specify known-absent property keys sdk-specs#233). FlagEvaluatorTest.testKnownAbsentCohortLeafChecksOperatorSupportBeforeTheTable and PostHogKnownAbsentPropertyKeysTest ("an unsupported operator in a cohort leaf on a listed key falls back before known absence") cover a cohort leaf plan not_between [1, 2] on a listed key, with and without negation, and check that it stays unresolved with unsupported_definition and falls back to /flags.
  • Person keys that start with __posthog_person_metadata__ are ignored.
  • Group keys only apply to their own group type.
  • In dynamic cohorts, a property on a listed key gets the result above before the cohort's negation is applied. Static cohort membership and holdouts are unchanged.
  • Flag dependencies are evaluated with the same listed keys.
  • Remote results are cached separately for each set of listed keys. A call with listed keys never reuses a cached result for the same person without them.

/flags request body

When a call with listed keys falls back to /flags, the request body includes person_property_keys_known_absent (a list of strings) and group_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.flags in the core posthog module gets a new overload that takes the two lists. The existing flags method keeps its JVM signature, so a posthog-server built 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. evaluateFlags returns an empty snapshot. getFeatureFlag, getFeatureFlagPayload and isFeatureEnabled return the default value. getFeatureFlagResult returns null.

Not included

💚 How did you test it?

New tests:

  • FlagEvaluatorTest covers 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.
  • PostHogKnownAbsentPropertyKeysTest runs the full client against MockWebServer. It covers a listed key overriding a supplied value with no /flags call, overriding the distinct_id the SDK adds, group-type scoping, the /flags body with and without listed keys, separate caching for getters, fallback for an unsupported operator, and the over-limit behavior for every entry point.
  • PostHogFlagsRequestTest checks 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:apiCheck passed.
  • After the cohort-leaf tests were added, the new tests passed on their first run with no production change. The same command passed again with 1839 tests and 0 failures.

CI now runs SDK test harness 1.34.0. It passed 47 of 47 tests in CI and locally with docker compose in sdk_compliance_adapter. The new non_utc_event_timestamp_is_converted_to_utc test exposed that the adapter ignored the timestamp on /capture, so the adapter now passes it to capture. The known-absent suite doesn't run because the adapter doesn't declare feature_flags_local_evaluation_v1 or feature_flags_known_absent_v1.

Not run locally: Android instrumented tests and the Compose survey tests.

📝 Checklist

  • All commits are signed (see Commit signing)
  • I reviewed the submitted code.
  • I added tests to verify the changes.
  • I updated the docs if needed.
  • No breaking change or entry added to the changelog.

If releasing new changes

  • Ran pnpm changeset to 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.

  • Accepted: adding parameters to PostHogApi.flags changed its JVM signature. A posthog-server built 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.
  • Not changed here: the review said a successful local lookup can report $feature_flag_error: unknown_error in $feature_flag_called. A local check showed main already 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.

@marandaneto marandaneto self-assigned this Nov 19, 2026
@github-actions

github-actions Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

posthog-android Compliance Report

Date: 2026-11-20T10:06:40.307803+00:00
Duration: 118932ms

✅ All Tests Passed!

47/47 tests passed


Capture Tests

✅ 30/30 tests passed

View Details
Test Status Duration
Format Validation.Event Has Required Fields ✅ 352ms
Format Validation.Event Has Uuid ✅ 29ms
Format Validation.Event Has Lib Properties ✅ 27ms
Format Validation.Distinct Id Is String ✅ 24ms
Format Validation.Token Is Present ✅ 23ms
Format Validation.Custom Properties Preserved ✅ 28ms
Format Validation.Event Has Timestamp ✅ 25ms
Format Validation.Non Utc Event Timestamp Is Converted To Utc ✅ 26ms
Retry Behavior.Retries On 503 ✅ 7026ms
Retry Behavior.Does Not Retry On 400 ✅ 4021ms
Retry Behavior.Does Not Retry On 401 ✅ 4021ms
Retry Behavior.Respects Retry After Header ✅ 7024ms
Retry Behavior.Implements Backoff ✅ 17036ms
Retry Behavior.Retries On 500 ✅ 7020ms
Retry Behavior.Retries On 502 ✅ 7017ms
Retry Behavior.Retries On 504 ✅ 7018ms
Retry Behavior.Max Retries Respected ✅ 17033ms
Deduplication.Generates Unique Uuids ✅ 40ms
Deduplication.Preserves Uuid On Retry ✅ 7016ms
Deduplication.Preserves Uuid And Timestamp On Retry ✅ 12026ms
Deduplication.Preserves Uuid And Timestamp On Batch Retry ✅ 7021ms
Deduplication.No Duplicate Events In Batch ✅ 36ms
Deduplication.Different Events Have Different Uuids ✅ 27ms
Compression.Sends Gzip When Enabled ✅ 20ms
Batch Format.Uses Proper Batch Structure ✅ 18ms
Batch Format.Flush With No Events Sends Nothing ✅ 13ms
Batch Format.Multiple Events Batched Together ✅ 32ms
Error Handling.Does Not Retry On 403 ✅ 4022ms
Error Handling.Does Not Retry On 413 ✅ 4023ms
Error Handling.Retries On 408 ✅ 5025ms

Feature_Flags Tests

✅ 17/17 tests passed

View Details
Test Status Duration
Request Payload.Request With Person Properties Device Id ✅ 34ms
Request Payload.Flags Request Uses V2 Query Param ✅ 35ms
Request Payload.Flags Request Hits Flags Path Not Decide ✅ 26ms
Request Payload.Flags Request Omits Authorization Header ✅ 21ms
Request Payload.Token In Flags Body Matches Init ✅ 25ms
Request Payload.Groups Round Trip ✅ 21ms
Request Payload.Groups Default To Empty Object ✅ 21ms
Request Payload.Disable Geoip False Propagates As Geoip Disable False ✅ 22ms
Request Payload.Disable Geoip Omitted Defaults To False ✅ 23ms
Request Payload.Flag Keys To Evaluate Contains Only Requested Key ✅ 24ms
Request Lifecycle.No Flags Request On Init Alone ✅ 20ms
Request Lifecycle.No Flags Request On Normal Capture ✅ 24ms
Request Lifecycle.Two Flag Calls Produce Two Remote Requests ✅ 34ms
Request Lifecycle.Mock Response Value Is Returned To Caller ✅ 21ms
Retry Behavior.Retries Flags On 502 ✅ 326ms
Retry Behavior.Retries Flags On 504 ✅ 325ms
Side Effect Events.Get Feature Flag Captures Feature Flag Called Event ✅ 23ms

@marandaneto
marandaneto marked this pull request as ready for review November 20, 2026 10:28
@marandaneto
marandaneto requested a review from a team as a code owner November 20, 2026 10:28
@veria-ai

veria-ai Bot commented Nov 20, 2026 •

Copy link
Copy Markdown

PR overview

No security issues were found in this pull request.

Reviews

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant