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.

fix(data-warehouse): say when a queried table has not finished its first sync (#128400)

Tom Owersd8192cb0aeda
diff --git a/posthog/hogql/database/database.py b/posthog/hogql/database/database.py
index 8044d7dbc3e5..6dcd61cdae7c 100644
--- a/posthog/hogql/database/database.py
+++ b/posthog/hogql/database/database.py
@@ -870,6 +870,11 @@ class Database(BaseModel):
# lets a foreign key replace only these (see _ensure_foreign_keys_built), never the id/timestamp
# mappings event modifiers write, which the eager path preserved.
_deferred_overridable_expression_field_ids: set[int] = set()
+ # Team whose not-yet-synced warehouse tables explain an unknown table name. Set only at the end of
+ # the build, so build-time lookups never query Postgres. The names load on the first unknown table.
+ _first_sync_lookup_team_id: int | None = None
+ # Name -> whether the first sync failed. None until loaded.
+ _tables_awaiting_first_sync: dict[str, bool] | None = None
_timezone: str | None
_week_start_day: WeekStartDay | None
@@ -912,6 +917,8 @@ class Database(BaseModel):
self._revenue_views_build_lock = threading.Lock()
self._revenue_view_trigger_names = None
self._deferred_overridable_expression_field_ids = set()
+ self._first_sync_lookup_team_id = None
+ self._tables_awaiting_first_sync = None
self._serialization_errors: dict[str, str] = {} # table_key -> error_message
self.user_access_control: Optional[UserAccessControl] = None
@@ -991,6 +998,9 @@ class Database(BaseModel):
table_name = ".".join(table_name)
if self.is_table_access_denied(table_name):
raise TableAccessDeniedError(table_name) from e
+ first_sync_failed = self._first_sync_status(table_name)
+ if first_sync_failed is not None:
+ raise QueryError(_awaiting_first_sync_message(table_name, failed=first_sync_failed)) from e
suggestions = self._suggest_table_names(table_name)
suffix = f" Did you mean: {', '.join(suggestions)}?" if suggestions else ""
raise QueryError(f"Unknown table `{table_name}`.{suffix}") from e
@@ -1098,6 +1108,27 @@ class Database(BaseModel):
self._foreign_keys_built = True
self._deferred_foreign_key_tables = []
+ def _first_sync_status(self, name: str) -> bool | None:
+ """Whether the first sync of the table under this name failed, or None if no sync will create it.
+
+ Loads the team's not-yet-synced names once per database, so lookups that fail in a loop cost
+ one Postgres query at most. A load failure leaves the plain unknown-table error in place.
+ """
+ if self._first_sync_lookup_team_id is None:
+ return None
+ if self._tables_awaiting_first_sync is None:
+ from products.warehouse_sources.backend.facade.api import tables_awaiting_first_sync # noqa: PLC0415
+
+ awaiting: dict[str, bool] = {}
+ try:
+ for table in tables_awaiting_first_sync(self._first_sync_lookup_team_id):
+ for key in (table.names.row_name, table.names.queryable_key):
+ awaiting[key] = awaiting.get(key, False) or table.first_sync_failed
+ except Exception as e:
+ capture_exception(e)
+ self._tables_awaiting_first_sync = awaiting
+ return self._tables_awaiting_first_sync.get(name)
+
def _suggest_table_names(self, name: str, *, limit: int = 3) -> list[str]:
"""Return up to `limit` close matches for a mistyped table name.
@@ -3084,9 +3115,26 @@ class Database(BaseModel):
database._foreign_key_trigger_names = {name.lower() for name in trigger_names}
database._foreign_keys_built = False
+ # Direct connections query the source itself, so no sync creates their tables.
+ if not database._is_direct_query():
+ database._first_sync_lookup_team_id = team_id
+
return database
+def _awaiting_first_sync_message(table_name: str, *, failed: bool) -> str:
+ # Keeps the "Unknown table `x`" prefix, because callers match on it to classify the error.
+ if failed:
+ return (
+ f"Unknown table `{table_name}`: its first sync failed, so the table does not exist yet. "
+ "Open the source page to see why."
+ )
+ return (
+ f"Unknown table `{table_name}`: its first sync has not finished, so the table does not exist yet. "
+ "Check the sync status on the source page."
+ )
+
+
def get_data_warehouse_table_name(source: ExternalDataSource | None, table_name: str):
if source is None:
return table_name
diff --git a/posthog/hogql/database/test/test_database.py b/posthog/hogql/database/test/test_database.py
index 4889861f227d..06e0295fb741 100644
--- a/posthog/hogql/database/test/test_database.py
+++ b/posthog/hogql/database/test/test_database.py
@@ -855,6 +855,119 @@ class TestDatabase(BaseTest, QueryMatchingTest):
assert field.type == "string"
assert field.schema_valid is True
+ @parameterized.expand(
+ [
+ param("running_by_dotted_name", schema={"status": "Running"}, queried="stripe.charges", hint="running"),
+ param("running_by_row_name", schema={"status": "Running"}, queried="stripe_charges", hint="running"),
+ param("never_started", schema={"status": None}, queried="stripe.charges", hint="running"),
+ param("failed", schema={"status": "Failed"}, queried="stripe.charges", hint="failed"),
+ param(
+ "prefixed_source_with_dotted_schema",
+ prefix="dev_",
+ schema={"name": "public.orders", "status": "Running"},
+ queried="stripe.dev.public__orders",
+ hint="running",
+ ),
+ param("sync_turned_off", schema={"status": "Failed", "should_sync": False}, queried="stripe.charges"),
+ param("deleted_schema", schema={"status": "Running", "deleted": True}, queried="stripe.charges"),
+ param(
+ "first_sync_complete_without_table",
+ schema={"status": "Completed", "initial_sync_complete": True},
+ queried="stripe.charges",
+ ),
+ param("other_teams_schema", schema={"status": "Running"}, queried="stripe.charges", other_team=True),
+ param("unrelated_name", schema={"status": "Running"}, queried="stripe.refunds"),
+ param(
+ "typo_of_synced_table_keeps_suggestion",
+ schema={"status": "Running"},
+ queried="stripe.invoice",
+ expected_message="Unknown table `stripe.invoice`. Did you mean: stripe.invoices?",
+ ),
+ ]
+ )
+ def test_unknown_table_says_when_first_sync_has_not_created_it(
+ self,
+ _name: str,
+ schema: dict[str, Any],
+ queried: str,
+ hint: str | None = None,
+ prefix: str | None = None,
+ other_team: bool = False,
+ expected_message: str | None = None,
+ ):
+ credential = DataWarehouseCredential.objects.create(access_key="k", access_secret="s", team=self.team)
+ own_source = ExternalDataSource.objects.create(
+ team=self.team,
+ source_id="own",
+ connection_id="own",
+ status=ExternalDataSource.Status.COMPLETED,
+ source_type=ExternalDataSourceType.STRIPE,
+ prefix=prefix,
+ )
+ synced_table = DataWarehouseTable.objects.create(
+ name="stripe_invoices",
+ format="Parquet",
+ team=self.team,
+ external_data_source=own_source,
+ credential=credential,
+ url_pattern="https://bucket.s3/data/*",
+ columns={"id": {"hogql": "StringDatabaseField", "clickhouse": "Nullable(String)", "schema_valid": True}},
+ )
+ ExternalDataSchema.objects.create(team=self.team, name="invoices", source=own_source, table=synced_table)
+
+ schema_team = self.team
+ if other_team:
+ schema_team = Team.objects.create(organization=Organization.objects.create(name="other_org"))
+ pending_source = (
+ ExternalDataSource.objects.create(
+ team=schema_team,
+ source_id="other",
+ connection_id="other",
+ status=ExternalDataSource.Status.COMPLETED,
+ source_type=ExternalDataSourceType.STRIPE,
+ )
+ if other_team
+ else own_source
+ )
+ ExternalDataSchema.objects.create(
+ team=schema_team, source=pending_source, **{"name": "charges", "should_sync": True, **schema}
+ )
+
+ database = Database.create_for(team=self.team)
+
+ assert database.get_table(f"{'stripe.dev' if prefix else 'stripe'}.invoices").name is not None
+ with self.assertRaises(QueryError) as error:
+ database.get_table(queried)
+
+ if expected_message is None:
+ expected_message = {
+ None: f"Unknown table `{queried}`.",
+ "running": f"Unknown table `{queried}`: its first sync has not finished, so the table does not exist "
+ "yet. Check the sync status on the source page.",
+ "failed": f"Unknown table `{queried}`: its first sync failed, so the table does not exist yet. "
+ "Open the source page to see why.",
+ }[hint]
+ assert str(error.exception) == expected_message
+
+ def test_unknown_table_loads_first_sync_names_once_and_never_during_build(self):
+ source = ExternalDataSource.objects.create(
+ team=self.team,
+ source_id="own",
+ connection_id="own",
+ status=ExternalDataSource.Status.COMPLETED,
+ source_type=ExternalDataSourceType.STRIPE,
+ )
+ ExternalDataSchema.objects.create(team=self.team, name="charges", source=source, status="Running")
+
+ sources = Database._fetch_sources(team=self.team)
+ with self.assertNumQueries(0):
+ database = Database._build_from_sources(sources)
+
+ with self.assertNumQueries(1):
+ for name in ["stripe.charges", "stripe.refunds", "stripe.charges", "nope"]:
+ with self.assertRaises(QueryError):
+ database.get_table(name)
+
def _create_warehouse_table(self, *, name, url_pattern, source=None, credential=None):
return DataWarehouseTable.objects.create(
name=name,
diff --git a/products/warehouse_sources/backend/facade/api.py b/products/warehouse_sources/backend/facade/api.py
index 07e8d403abba..ce68f71dd070 100644
--- a/products/warehouse_sources/backend/facade/api.py
+++ b/products/warehouse_sources/backend/facade/api.py
@@ -98,6 +98,7 @@ __all__ = [
"allowed_table_ids",
"denied_table_ids",
"pending_source_ids_for_tables",
+ "tables_awaiting_first_sync",
"all_queryable_tables",
"all_queryable_table_columns",
"list_tables_for_source",
@@ -584,6 +585,60 @@ def pending_source_ids_for_tables(team_id: int, table_ids: Collection[UUID] | No
return found
+def tables_awaiting_first_sync(team_id: int) -> list[contracts.TableAwaitingFirstSync]:
+ """Every table a live, syncing schema of this team will create, but has not created yet. One query.
+
+ The names are built the way the first sync builds them, so they match what a query writes for
+ the table once it exists. Direct-access sources are skipped, because they never create tables.
+ """
+ from posthog.hogql.database.database import ( # noqa: PLC0415 -- keeps HogQL off this module's import path
+ get_data_warehouse_table_name,
+ )
+
+ from products.warehouse_sources.backend.temporal.data_imports.pipelines.helpers import ( # noqa: PLC0415 -- keeps the import pipeline off this module's import path
+ build_table_name,
+ resolve_table_and_folder_names,
+ )
+
+ schemas = (
+ _ExternalDataSchema.objects.filter(
+ team_id=team_id,
+ source__team_id=team_id,
+ source__access_method=_ExternalDataSource.AccessMethod.WAREHOUSE,
+ table__isnull=True,
+ should_sync=True,
+ initial_sync_complete=False,
+ )
+ .exclude(deleted=True)
+ .exclude(source__deleted=True)
+ .select_related("source")
+ .only(
+ "name",
+ "status",
+ "s3_folder_name",
+ "sync_type_config",
+ "source__id",
+ "source__source_type",
+ "source__prefix",
+ "source__access_method",
+ )
+ )
+ pending: list[contracts.TableAwaitingFirstSync] = []
+ for schema in schemas:
+ storage_name = resolve_table_and_folder_names(schema.name, schema.resolved_s3_folder_name).table_storage_name
+ row_name = build_table_name(schema.source, storage_name)
+ pending.append(
+ contracts.TableAwaitingFirstSync(
+ names=contracts.TableNames(
+ row_name=row_name,
+ queryable_key=get_data_warehouse_table_name(schema.source, row_name),
+ ),
+ first_sync_failed=schema.status == _ExternalDataSchema.Status.FAILED,
+ )
+ )
+ return pending
+
+
def denied_table_ids(team_id: int, user_access_control: "UserAccessControl") -> frozenset[UUID]:
"""Every table this caller may not view.
diff --git a/products/warehouse_sources/backend/facade/contracts.py b/products/warehouse_sources/backend/facade/contracts.py
index 7b5d07f4db23..1c3501aaa573 100644
--- a/products/warehouse_sources/backend/facade/contracts.py
+++ b/products/warehouse_sources/backend/facade/contracts.py
@@ -266,6 +266,18 @@ class TableNames:
queryable_key: str
+@dataclass(frozen=True)
+class TableAwaitingFirstSync:
+ """A table that a synced schema will create, but whose first sync has not created yet.
+
+ ``names`` holds the names a query can write for it once it exists.
+ ``first_sync_failed`` is true when the latest sync attempt failed.
+ """
+
+ names: TableNames
+ first_sync_failed: bool
+
+
WAREHOUSE_OBJECT_TABLE = "table"
WAREHOUSE_OBJECT_VIEW = "view"