Lantern

Appearance

Query Console ​

  • Status: in progress, opened 2026-08-24. Built 2026-08-24, bug-fixed and design-verified 2026-08-27.
  • Issue: #958: feat(admin/analytics): promote Query Console to its own surface and teach it to query Firestore
  • Launch plan: docs/business/launches/PROTOTYPE.md, Phase 2 (Build), "Analytics hardening". The row does NOT exist yet: the PM lane guard blocks a write to the launch pages, so the row text is drafted and waiting on the operator or a builder session. (Was ALPHA.md Phase 1 before the 2026-08-31 timeline shift moved Build into Prototype.)

What is this? ​

The Query Console becomes its own Analytics surface, and learns to query Firestore as well as BigQuery. ​

  • It is currently a tab buried under Analytics > BigQuery, which makes it read as a BigQuery feature rather than the place you go to ask the data a question.
  • BigQuery only holds events. Anything about current state (an offer awaiting moderation, a merchant profile, a feature flag) lives in Firestore and is reachable from no console at all.
  • The operator's framing on 2026-08-24: "This essentially could also become a users custom report builder essentially." That is the direction this surface is pointed, and it is why the structured builder was chosen over raw SQL.

Firestore gets a structured query builder, not SQL. ​

  • Firestore has no query language, so "the same way we do with BigQuery" cannot mean a SQL box. It means collection plus filters plus order plus limit, executed server side against a field allowlist.
  • The rejected alternative was installing the Firebase Stream Firestore to BigQuery extension. It would have given real SQL with zero new UI, and it was turned down because it keeps a second live copy of user documents outside Firestore, which cuts against the prefer-losing-data-over-leaking-it axiom.

The Assistant gets grounded in the same task. ​

  • The Assistant has no BigQuery awareness at all: its system prompt at services/api/assistant/src/services/anthropic.js contains the word BigQuery zero times, and none of its six tools can read a schema.
  • Asked for a query on 2026-08-24 it produced your-project.firestore_export.offers, which is a generic placeholder project plus the default dataset name of a Firebase extension this project has never installed. Neither exists.
  • Its own guardrail says never invent file paths, function names, or Firestore field names. BigQuery tables are not on that list, so the rule did not cover the thing it got wrong.
  • It also already had a correct route to the answer and did not take it: query_firestore allowlists offers with title, status, merchantId, venueId, audience, startsAt, expiresAt.

What is the current state? ​

Slices 1 to 4 are built. Slice 5, grounding the Assistant, is not. ​

  • The console is its own Analytics line item, it has a BigQuery and Firestore tab strip, the structured Firestore endpoint is on analytics-api, and the builder UI works. Slice 5 in planning.md has not been started.
  • The allowlist was settled and now carries a per-collection decision on the document KEY as well as the fields.

A 2026-08-24 code review filed two bugs, and both are fixed as of 2026-08-27. ​

The design verification found the surface mechanically compliant and functionally undiscoverable, and the second half is now fixed. ​

  • design.md has the audit. Tokens, dropdowns, icons and structure all passed. What was missing was any statement of what each source is FOR, what question a field answers, or why an absent collection is absent.
  • The operator's own example made the case: "how many lanterns are lit at venue X" IS answerable, via venues.activeLanternCount, and nothing led anyone to it.
  • Fixed on 2026-08-27 as slice 6 in planning.md: a Firestore rail, descriptions inside the pickers, the refused collections with reasons, saved inquiries, and a reference doc linked first in the tab strip.

The console reads as broken on a stack proxied to the deployed analytics-api. ​

  • These endpoints exist only on this branch, so ANALYTICS_API_ORIGIN pointing at Cloud Run answers 404 and the Firestore tab shows a failure. Point it at a local analytics-api and it works. Detail in implementation.md.

What is already verified about the ground truth ​

  • The nine BigQuery datasets in lantern-app-dev are analytics, billing_attrib, billing_export_gcp, billing_exports_gcp, billing_marts, billing_norm, billing_raw, logs, ops. There is no firestore_export and no Firestore export of any kind.
  • analytics holds five objects: ad_delivery_daily, event_counts_daily, events, plus the recent_system_events and recent_user_events views.
  • analytics.events is day partitioned on timestamp and REJECTS any query without a filter on it. Any console guidance or Assistant prompt has to say so, because the failure message names partition elimination rather than a missing filter.
  • Offer-shaped events in the last 90 days are sponsored_offer_filled (155), offer_claimed (5), offer_redeemed (2). There is no submission or moderation state in BigQuery, so the question that started this cannot be answered there at all.

Built with VitePress

Copyright © 2026 Lantern