:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
feat(flags): make posthog.flag_evaluations queryable for every cloud org (#130342)
Phil Haackff368758f47f
diff --git a/docs/internal/sql-editor-schema-tree.md b/docs/internal/sql-editor-schema-tree.mdindex 2c61bad50fbd..79c37911ed65 100644--- a/docs/internal/sql-editor-schema-tree.md+++ b/docs/internal/sql-editor-schema-tree.md@@ -7,7 +7,7 @@ Search includes both categories, and table actions use the name shown in the treThe PostHog catalog includes `posthog.ai_events` for AI observability, `posthog.session_replay_events` for recordings, and `posthog.trace_spans` for tracing.`posthog.metrics` contains metric data points; join `posthog.metric_series` for their labels.-`posthog.flag_evaluations` appears when enabled for the organization.+`posthog.flag_evaluations` appears for every organization on PostHog Cloud. On a self-hosted instance it appears only when the organization's flag_evaluations mode reads that table.These tables come from the backend catalog without a separate sidebar allowlist.Namespace-only tables retain their `posthog.` prefix when requesting fields.diff --git a/frontend/src/scenes/feature-flags/flagEvaluationsTable.ts b/frontend/src/scenes/feature-flags/flagEvaluationsTable.tsindex 9cdd88305c98..17e5e68cbe1d 100644--- a/frontend/src/scenes/feature-flags/flagEvaluationsTable.ts+++ b/frontend/src/scenes/feature-flags/flagEvaluationsTable.ts@@ -5,8 +5,8 @@ import { FlagEvaluationsModeEnumApi } from '~/generated/core/api.schemas'import { CompareFilter, ResolvedDateRangeResponse } from '~/queries/schema/schema-general'import type { TeamPublicType, TeamType } from '~/types'-// Not a root table, so the `posthog.` prefix is part of the name. A team on the Events mode has no-// such table. Queries on it fail to resolve for that team.+// Not a root table, so the `posthog.` prefix is part of the name. On a self-hosted instance, a team on the+// Events mode has no such table. Queries on it fail to resolve for that team.export const FLAG_EVALUATIONS_TABLE = 'posthog.flag_evaluations'export const FEATURE_FLAG_CALLED_EVENT = '$feature_flag_called'diff --git a/posthog/models/data_deletion_request.py b/posthog/models/data_deletion_request.pyindex 2e5c1470ff1b..5262429d2e7f 100644--- a/posthog/models/data_deletion_request.py+++ b/posthog/models/data_deletion_request.py@@ -112,7 +112,7 @@ def compile_hogql_predicate(obj, use_new_events_schema: bool = False, hogql_tablraise ValidationError({"hogql_predicate": "team no longer exists; cannot validate the predicate."}) from excmodifiers = create_default_modifiers_for_team(team)modifiers.personsOnEventsMode = PersonsOnEventsMode.PERSON_ID_OVERRIDE_PROPERTIES_ON_EVENTS- # The organization mode that hides posthog.flag_evaluations from queries does not apply here.+ # A self-hosted organization on the Events mode has no posthog.flag_evaluations in its catalog.# The rows that table holds still have to be deletable.database = (None if on_events else Database.create_for(team=team, modifiers=modifiers, include_flag_evaluations_table=True)diff --git a/products/feature_flags/backend/facade/enums.py b/products/feature_flags/backend/facade/enums.pyindex e667b3701f89..23a506424679 100644--- a/products/feature_flags/backend/facade/enums.py+++ b/products/feature_flags/backend/facade/enums.py@@ -10,11 +10,10 @@ class FlagEvaluationsMode(LabeledIntEnum):allowlist includes."""- # Every reader of $feature_flag_called reads the events table. The flag_evaluations HogQL table stays hidden.+ # Every reader of $feature_flag_called reads the events table.EVENTS = 0, "Events"# The Usage tab, the per-project counts on a flag's Projects tab, and events lists filtered to only# $feature_flag_called read flag_evaluations. Other readers, such as experiment exposures, still read events.- # The HogQL table is visible.# Ingestion still writes every flag call to events, so FLAG_EVALUATIONS_READS_FORCE_EVENTS can move these# readers back to events.READ_FLAG_EVALUATIONS = 1, "Read flag evaluations"diff --git a/products/feature_flags/backend/facade/flags.py b/products/feature_flags/backend/facade/flags.pyindex 1f2621fdcff9..2cc6d2bcb9f6 100644--- a/products/feature_flags/backend/facade/flags.py+++ b/products/feature_flags/backend/facade/flags.py@@ -8,6 +8,7 @@ from uuid import UUIDfrom django.conf import settings+from posthog.cloud_utils import is_cloudfrom posthog.models.instance_setting import get_instance_settingfrom products.feature_flags.backend.facade.enums import FlagEvaluationsMode@@ -62,13 +63,19 @@ def hides_flag_calls_from_query_builders(organization_id: UUID) -> bool:def is_flag_evaluations_table_enabled(team: "Team") -> bool:"""Gate every surface that exposes `posthog.flag_evaluations` through here.- Reads true when the flag_evaluations mode of the team's organization reads that table. A self-hosted- production instance reads false by default. Local dev and end-to-end tests are the exception and read true.+ Reads true on PostHog Cloud for every organization, whatever its flag_evaluations mode. A team on EVENTS+ can query the table, but its flag-call readers still read events. Local dev and end-to-end tests also read+ true. A self-hosted instance reads true only when the organization's mode reads the table."""+ # PostHog Cloud ingestion forks every team's flag calls into flag_evaluations, so an organization on+ # EVENTS still has rows to query and export.+ if is_cloud():+ return True# Local and E2E organizations start on EVENTS because FLAG_EVALUATIONS_NEW_ORG_MODE defaults to 0.# Returning True keeps the table queryable there without setting a mode first.if settings.DEBUG or settings.E2E_TESTING:return True- # The Usage tab reads flag_evaluations for any mode above EVENTS. Its query fails when the table- # is missing from the catalog.+ # Self-hosted ingestion leaves the flag_evaluations fork off by default, so the table holds no rows there+ # until an operator turns the fork on. The Usage tab reads flag_evaluations for any mode above EVENTS, and+ # its query fails when the table is missing from the catalog.return get_organization_flag_evaluations_mode(team.organization_id) != FlagEvaluationsMode.EVENTSdiff --git a/products/feature_flags/backend/flag_evaluations_mode.py b/products/feature_flags/backend/flag_evaluations_mode.pyindex b9707006a921..79f78cda8758 100644--- a/products/feature_flags/backend/flag_evaluations_mode.py+++ b/products/feature_flags/backend/flag_evaluations_mode.py@@ -17,9 +17,9 @@ from products.feature_flags.backend.models.organization_feature_flags_config impFLAG_EVALUATIONS_MODES_HELP = ("0 reads events. 1 reads flag_evaluations for the flag Usage tab, the per-project counts on a flag's Projects "- "tab, and events lists filtered to only $feature_flag_called, such as the Activity page, and the table is "- "available in SQL. 2 reads the same way as 1, and ingestion stops writing $feature_flag_called to events for "- "teams in the ingestion allowlist."+ "tab, and events lists filtered to only $feature_flag_called, such as the Activity page. 2 reads the same way "+ "as 1, and ingestion stops writing $feature_flag_called to events for teams in the ingestion allowlist. "+ "On PostHog Cloud the table is available in SQL on every mode. Self-hosted, it is available on 1 and 2.")diff --git a/products/feature_flags/backend/management/commands/set_flag_evaluations_mode.py b/products/feature_flags/backend/management/commands/set_flag_evaluations_mode.pyindex 21f987e11356..386f4ac67225 100644--- a/products/feature_flags/backend/management/commands/set_flag_evaluations_mode.py+++ b/products/feature_flags/backend/management/commands/set_flag_evaluations_mode.py@@ -43,11 +43,7 @@ class Command(BaseCommand):type=int,required=True,choices=FlagEvaluationsMode.values,- help=(- f"{FLAG_EVALUATIONS_MODES_HELP} "- "flag_evaluations holds rows only from the day ingestion started writing them "- "(2026-09-09 for PostHog Cloud), so on mode 1 or 2 the Usage tab shows no data for earlier days."- ),+ help=FLAG_EVALUATIONS_MODES_HELP,)selector = parser.add_mutually_exclusive_group(required=True)selector.add_argument(diff --git a/products/feature_flags/backend/test/test_organization_feature_flags_config.py b/products/feature_flags/backend/test/test_organization_feature_flags_config.pyindex c549e0e7f0bd..b0a9e41cb894 100644--- a/products/feature_flags/backend/test/test_organization_feature_flags_config.py+++ b/products/feature_flags/backend/test/test_organization_feature_flags_config.py@@ -1,6 +1,6 @@from posthog.test.base import BaseTest-from parameterized import parameterized+from parameterized import param, parameterizedfrom posthog.models.instance_setting import override_instance_configfrom posthog.models.organization import Organization@@ -44,19 +44,29 @@ class TestOrganizationFeatureFlagsConfig(BaseTest):class TestFlagEvaluationsTableGate(BaseTest):@parameterized.expand([- ("events", FlagEvaluationsMode.EVENTS, False, False),- ("read_flag_evaluations", FlagEvaluationsMode.READ_FLAG_EVALUATIONS, False, True),- ("flag_evaluations_only", FlagEvaluationsMode.FLAG_EVALUATIONS_ONLY, False, True),- ("no_config_row", None, False, False),- (- "read_flag_evaluations_while_reads_are_forced_to_events",+ param("self_hosted_events", FlagEvaluationsMode.EVENTS, expected=False),+ param("self_hosted_read_flag_evaluations", FlagEvaluationsMode.READ_FLAG_EVALUATIONS, expected=True),+ param("self_hosted_flag_evaluations_only", FlagEvaluationsMode.FLAG_EVALUATIONS_ONLY, expected=True),+ param("self_hosted_no_config_row", None, expected=False),+ param(+ "self_hosted_read_flag_evaluations_while_reads_are_forced_to_events",FlagEvaluationsMode.READ_FLAG_EVALUATIONS,- True,- True,+ expected=True,+ reads_forced_to_events=True,),+ param("cloud_events", FlagEvaluationsMode.EVENTS, expected=True, cloud=True),+ param("cloud_no_config_row", None, expected=True, cloud=True),])- def test_table_is_enabled_by_the_organization_mode(self, _name, mode, reads_forced_to_events, expected):+ def test_table_is_enabled_on_cloud_or_by_the_organization_mode(+ self,+ _name: str,+ mode: FlagEvaluationsMode | None,+ *,+ expected: bool,+ cloud: bool = False,+ reads_forced_to_events: bool = False,+ ) -> None:config = OrganizationFeatureFlagsConfig.objects.filter(organization=self.organization)if mode is None:config.delete()@@ -65,6 +75,7 @@ class TestFlagEvaluationsTableGate(BaseTest):with (self.settings(DEBUG=False, E2E_TESTING=False),+ self.is_cloud(cloud),override_instance_config("FLAG_EVALUATIONS_READS_FORCE_EVENTS", reads_forced_to_events),):self.assertEqual(is_flag_evaluations_table_enabled(self.team), expected)diff --git a/products/feature_flags/frontend/generated/api.schemas.ts b/products/feature_flags/frontend/generated/api.schemas.tsindex f605a9301a92..6782613d48c1 100644--- a/products/feature_flags/frontend/generated/api.schemas.ts+++ b/products/feature_flags/frontend/generated/api.schemas.ts@@ -209,7 +209,7 @@ export interface StaffTeamConfigApi {max_feature_flags_override: number | null/** The flag-count limit actually enforced for this team: the override when one is set, otherwise the global MAX_FEATURE_FLAGS_PER_TEAM setting. */effective_max_feature_flags: number- /** Which table the $feature_flag_called data of this team's organization is read from. Every team of an organization shares one mode. 0 reads events. 1 reads flag_evaluations for the flag Usage tab, the per-project counts on a flag's Projects tab, and events lists filtered to only $feature_flag_called, such as the Activity page, and the table is available in SQL. 2 reads the same way as 1, and ingestion stops writing $feature_flag_called to events for teams in the ingestion allowlist. This is the stored mode: while the FLAG_EVALUATIONS_READS_FORCE_EVENTS instance setting is on, an organization on 1 reads events anyway.+ /** Which table the $feature_flag_called data of this team's organization is read from. Every team of an organization shares one mode. 0 reads events. 1 reads flag_evaluations for the flag Usage tab, the per-project counts on a flag's Projects tab, and events lists filtered to only $feature_flag_called, such as the Activity page. 2 reads the same way as 1, and ingestion stops writing $feature_flag_called to events for teams in the ingestion allowlist. On PostHog Cloud the table is available in SQL on every mode. Self-hosted, it is available on 1 and 2. This is the stored mode: while the FLAG_EVALUATIONS_READS_FORCE_EVENTS instance setting is on, an organization on 1 reads events anyway.** * `0` - Events* * `1` - Read flag evaluations@@ -244,7 +244,7 @@ export interface StaffTeamConfigMutationApi {}export interface StaffFlagEvaluationsModeMutationApi {- /** Target flag_evaluations mode. 0 reads events. 1 reads flag_evaluations for the flag Usage tab, the per-project counts on a flag's Projects tab, and events lists filtered to only $feature_flag_called, such as the Activity page, and the table is available in SQL. 2 reads the same way as 1, and ingestion stops writing $feature_flag_called to events for teams in the ingestion allowlist.+ /** Target flag_evaluations mode. 0 reads events. 1 reads flag_evaluations for the flag Usage tab, the per-project counts on a flag's Projects tab, and events lists filtered to only $feature_flag_called, such as the Activity page. 2 reads the same way as 1, and ingestion stops writing $feature_flag_called to events for teams in the ingestion allowlist. On PostHog Cloud the table is available in SQL on every mode. Self-hosted, it is available on 1 and 2.** * `0` - Events* * `1` - Read flag evaluationsdiff --git a/products/feature_flags/frontend/generated/api.zod.ts b/products/feature_flags/frontend/generated/api.zod.tsindex 2c91b25c55b0..94595b6e9e12 100644--- a/products/feature_flags/frontend/generated/api.zod.ts+++ b/products/feature_flags/frontend/generated/api.zod.ts@@ -139,7 +139,7 @@ export const FeatureFlagsStaffTeamConfigSetFlagEvaluationsModeCreateBody = /* @_flag_evaluations_mode: zod.union([zod.literal(0), zod.literal(1), zod.literal(2)]).describe(- "Target flag_evaluations mode. 0 reads events. 1 reads flag_evaluations for the flag Usage tab, the per-project counts on a flag's Projects tab, and events lists filtered to only $feature_flag_called, such as the Activity page, and the table is available in SQL. 2 reads the same way as 1, and ingestion stops writing $feature_flag_called to events for teams in the ingestion allowlist.\n\n\* `0` - Events\n\* `1` - Read flag evaluations\n\* `2` - Flag evaluations only"+ "Target flag_evaluations mode. 0 reads events. 1 reads flag_evaluations for the flag Usage tab, the per-project counts on a flag's Projects tab, and events lists filtered to only $feature_flag_called, such as the Activity page. 2 reads the same way as 1, and ingestion stops writing $feature_flag_called to events for teams in the ingestion allowlist. On PostHog Cloud the table is available in SQL on every mode. Self-hosted, it is available on 1 and 2.\n\n\* `0` - Events\n\* `1` - Read flag evaluations\n\* `2` - Flag evaluations only"),team_ids: zod.array(zod.number())diff --git a/products/feature_flags/frontend/staff/StaffFlagEvaluationsModeModal.tsx b/products/feature_flags/frontend/staff/StaffFlagEvaluationsModeModal.tsxindex 52a3ecefda2e..295315f440c0 100644--- a/products/feature_flags/frontend/staff/StaffFlagEvaluationsModeModal.tsx+++ b/products/feature_flags/frontend/staff/StaffFlagEvaluationsModeModal.tsx@@ -22,8 +22,8 @@ const FLAG_CALL_READERS =const MODE_DESCRIPTIONS: Record<FlagEvaluationsModeEnumApi, string> = {0: `${FLAG_CALL_READERS} read the events table.`,- 1: `${FLAG_CALL_READERS} read the flag_evaluations table, and the table is available in SQL. While the FLAG_EVALUATIONS_READS_FORCE_EVENTS instance setting is on, they read the events table instead.`,- 2: `${FLAG_CALL_READERS} read the flag_evaluations table, and the table is available in SQL. For teams in the ingestion allowlist, ingestion also stops writing $feature_flag_called to the events table.`,+ 1: `${FLAG_CALL_READERS} read the flag_evaluations table. While the FLAG_EVALUATIONS_READS_FORCE_EVENTS instance setting is on, they read the events table instead.`,+ 2: `${FLAG_CALL_READERS} read the flag_evaluations table. For teams in the ingestion allowlist, ingestion also stops writing $feature_flag_called to the events table.`,}export function StaffFlagEvaluationsModeModal(): JSX.Element {diff --git a/products/posthog_ai/skills/querying-posthog-data/references/models-flags-experiments.md.j2 b/products/posthog_ai/skills/querying-posthog-data/references/models-flags-experiments.md.j2index f1ab35d343e5..38881c06cb7b 100644--- a/products/posthog_ai/skills/querying-posthog-data/references/models-flags-experiments.md.j2+++ b/products/posthog_ai/skills/querying-posthog-data/references/models-flags-experiments.md.j2@@ -58,7 +58,7 @@ PostHog is moving these calls from `events` to `posthog.flag_evaluations`, one oMode | Where the flag calls are | `posthog.flag_evaluations`--- | --- | ----0 | `events` | Unknown table+0 | `events`, and `posthog.flag_evaluations` on PostHog Cloud | Queryable on PostHog Cloud only1 | `events` and `posthog.flag_evaluations` | Queryable2 | `posthog.flag_evaluations` only, for 90 days | Queryable@@ -80,7 +80,7 @@ On mode 2, these shapes can go wrong:### `posthog.flag_evaluations`-One row per flag call. Query it directly only on modes 1 and 2.+One row per flag call. On PostHog Cloud it is queryable on every mode. Self-hosted, it is queryable only on modes 1 and 2.Filter on `flag_key` rather than `properties.$feature_flag`: `flag_key` is in the table's sort key.{{ schema_columns('posthog.flag_evaluations') }}diff --git a/services/mcp/src/api/generated.ts b/services/mcp/src/api/generated.tsindex 93336ad42b5e..bea7768536b4 100644--- a/services/mcp/src/api/generated.ts+++ b/services/mcp/src/api/generated.ts@@ -108743,7 +108743,7 @@ export namespace Schemas {}export interface StaffFlagEvaluationsModeMutation {- /** Target flag_evaluations mode. 0 reads events. 1 reads flag_evaluations for the flag Usage tab, the per-project counts on a flag's Projects tab, and events lists filtered to only $feature_flag_called, such as the Activity page, and the table is available in SQL. 2 reads the same way as 1, and ingestion stops writing $feature_flag_called to events for teams in the ingestion allowlist.+ /** Target flag_evaluations mode. 0 reads events. 1 reads flag_evaluations for the flag Usage tab, the per-project counts on a flag's Projects tab, and events lists filtered to only $feature_flag_called, such as the Activity page. 2 reads the same way as 1, and ingestion stops writing $feature_flag_called to events for teams in the ingestion allowlist. On PostHog Cloud the table is available in SQL on every mode. Self-hosted, it is available on 1 and 2.** * `0` - Events* * `1` - Read flag evaluations@@ -108825,7 +108825,7 @@ export namespace Schemas {max_feature_flags_override: number | null;/** The flag-count limit actually enforced for this team: the override when one is set, otherwise the global MAX_FEATURE_FLAGS_PER_TEAM setting. */effective_max_feature_flags: number;- /** Which table the $feature_flag_called data of this team's organization is read from. Every team of an organization shares one mode. 0 reads events. 1 reads flag_evaluations for the flag Usage tab, the per-project counts on a flag's Projects tab, and events lists filtered to only $feature_flag_called, such as the Activity page, and the table is available in SQL. 2 reads the same way as 1, and ingestion stops writing $feature_flag_called to events for teams in the ingestion allowlist. This is the stored mode: while the FLAG_EVALUATIONS_READS_FORCE_EVENTS instance setting is on, an organization on 1 reads events anyway.+ /** Which table the $feature_flag_called data of this team's organization is read from. Every team of an organization shares one mode. 0 reads events. 1 reads flag_evaluations for the flag Usage tab, the per-project counts on a flag's Projects tab, and events lists filtered to only $feature_flag_called, such as the Activity page. 2 reads the same way as 1, and ingestion stops writing $feature_flag_called to events for teams in the ingestion allowlist. On PostHog Cloud the table is available in SQL on every mode. Self-hosted, it is available on 1 and 2. This is the stored mode: while the FLAG_EVALUATIONS_READS_FORCE_EVENTS instance setting is on, an organization on 1 reads events anyway.** * `0` - Events* * `1` - Read flag evaluations