Skip to content

: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.

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.md
index 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 tre
The 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.ts
index 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.py
index 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_tabl
raise ValidationError({"hogql_predicate": "team no longer exists; cannot validate the predicate."}) from exc
modifiers = 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.py
index 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.py
index 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 UUID
from django.conf import settings
+from posthog.cloud_utils import is_cloud
from posthog.models.instance_setting import get_instance_setting
from 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.EVENTS
diff --git a/products/feature_flags/backend/flag_evaluations_mode.py b/products/feature_flags/backend/flag_evaluations_mode.py
index 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 imp
FLAG_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.py
index 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.py
index 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, parameterized
from posthog.models.instance_setting import override_instance_config
from 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.ts
index 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 evaluations
diff --git a/products/feature_flags/frontend/generated/api.zod.ts b/products/feature_flags/frontend/generated/api.zod.ts
index 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.tsx
index 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.j2
index 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 o
Mode | 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 only
1 | `events` and `posthog.flag_evaluations` | Queryable
2 | `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.ts
index 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