feat(webapp): keep the queue-metrics tables unlisted until they are rolled out

The Query page, its schema docs, the schema API and the AI query context
listed queue_metrics and env_metrics as soon as this deployed, so the
tables were advertised to everyone while ingestion was still off and they
were empty. Listing them is now behind
QUEUE_METRICS_QUERY_TABLES_VISIBLE, off by default.

Listing only, matching how the existing hidden table already behaves: a
query that names one of these tables still compiles and runs, with
tenancy enforced as usual, so the dashboards and the health report keep
working while the tables are unlisted.

The filter is a pure function rather than a precomputed list, because
three of the five callers are browser components and that module cannot
reach for env.server. Server callers read the env var; client callers
read the flag through the existing features hook.

Author: ericallam

apps/webapp/app/components/query/QueryEditor.tsx

@@ -10,6 +10,7 @@ import {
   useCallback,
   useEffect,
   useImperativeHandle,
+  useMemo,
   useRef,
   useState,
   type ReactNode,
@@ -72,7 +73,8 @@ import type { action as titleAction } from "~/routes/resources.orgs.$organizatio
 import type { QueryScope } from "~/services/queryService.server";
 import { downloadFile, rowsToCSV, rowsToJSON } from "~/utils/dataExport";
 import { organizationBillingPath } from "~/utils/pathBuilder";
-import { visibleQuerySchemas } from "~/v3/querySchemas";
+import { listableQuerySchemas } from "~/v3/querySchemas";
+import { useFeatures } from "~/hooks/useFeatures";
 
 /** Convert a Date or ISO string to ISO string format */
 function toISOString(value: Date | string): string {
@@ -187,6 +189,11 @@ const QueryEditorForm = forwardRef<
   ref
 ) {
   const isLoading = fetcher.state === "submitting" || fetcher.state === "loading";
+  const { queueMetricsQueryTables } = useFeatures();
+  const schemas = useMemo(
+    () => listableQuerySchemas({ includeQueueMetrics: queueMetricsQueryTables }),
+    [queueMetricsQueryTables]
+  );
   const [query, setQuery] = useState(defaultQuery);
   const [scope, setScope] = useState<QueryScope>(defaultScope);
   const formRef = useRef<HTMLFormElement>(null);
@@ -245,7 +252,7 @@ const QueryEditorForm = forwardRef<
       <TSQLEditor
         defaultValue={query}
         onChange={setQuery}
-        schema={visibleQuerySchemas}
+        schema={schemas}
         linterEnabled={true}
         showCopyButton={true}
         showClearButton={true}

apps/webapp/app/env.server.ts

@@ -942,6 +942,12 @@ const EnvironmentSchema = z
     // Fraction (0..1) of ops that emit a gauge; counters are never sampled. Dial below 1
     // only if EngineCPU is too high in slow-path-heavy regions (hurts low-traffic queues).
     QUEUE_METRICS_GAUGE_SAMPLE_RATE: z.coerce.number().min(0).max(1).default(1),
+    /**
+     * Lists the queue-metrics tables in the Query page, its schema docs, the schema API and the
+     * AI query context. Off by default so the tables are not advertised before ingestion is
+     * enabled. Listing only: a query naming one of these tables still runs either way.
+     */
+    QUEUE_METRICS_QUERY_TABLES_VISIBLE: z.string().default("0"),
     RUN_ENGINE_WORKER_SHUTDOWN_TIMEOUT_MS: z.coerce.number().int().default(60_000),
     RUN_ENGINE_RETRY_WARM_START_THRESHOLD_MS: z.coerce.number().int().default(30_000),
     RUN_ENGINE_PROCESS_WORKER_QUEUE_DEBOUNCE_MS: z.coerce.number().int().default(200),

apps/webapp/app/features.server.ts

@@ -4,6 +4,7 @@ import { requestUrl } from "./utils/requestUrl.server";
 export type TriggerFeatures = {
   isManagedCloud: boolean;
   hasPrivateConnections: boolean;
+  queueMetricsQueryTables: boolean;
 };
 
 function isManagedCloud(host: string): boolean {
@@ -26,6 +27,7 @@ function featuresForHost(host: string): TriggerFeatures {
   return {
     isManagedCloud: isManagedCloud(host),
     hasPrivateConnections: hasPrivateConnections(host),
+    queueMetricsQueryTables: env.QUEUE_METRICS_QUERY_TABLES_VISIBLE === "1",
   };
 }
 

apps/webapp/app/hooks/useFeatures.ts

@@ -5,5 +5,11 @@ import type { TriggerFeatures } from "~/features.server";
 export function useFeatures(): TriggerFeatures {
   const routeMatch = useTypedRouteLoaderData<typeof loader>("root");
 
-  return routeMatch?.features ?? { isManagedCloud: false, hasPrivateConnections: false };
+  return (
+    routeMatch?.features ?? {
+      isManagedCloud: false,
+      hasPrivateConnections: false,
+      queueMetricsQueryTables: false,
+    }
+  );
 }

apps/webapp/app/routes/_app.orgs.$organizationSlug.projects.$projectParam.env.$envParam.query/ExamplesContent.tsx

@@ -1,9 +1,10 @@
-import { useState } from "react";
+import { useMemo, useState } from "react";
 import { Header3 } from "~/components/primitives/Headers";
 import { Paragraph } from "~/components/primitives/Paragraph";
 import SegmentedControl from "~/components/primitives/SegmentedControl";
 import type { QueryScope } from "~/services/queryService.server";
-import { visibleQuerySchemas } from "~/v3/querySchemas";
+import { listableQuerySchemas } from "~/v3/querySchemas";
+import { useFeatures } from "~/hooks/useFeatures";
 import { TryableCodeBlock } from "./TRQLGuideContent";
 
 // Example queries for the Examples tab
@@ -211,14 +212,21 @@ LIMIT 20`,
   },
 ];
 
-const tableOptions = visibleQuerySchemas.map((s) => ({ label: s.name, value: s.name }));
-
 export function ExamplesContent({
   onTryExample,
 }: {
   onTryExample: (query: string, scope: QueryScope) => void;
 }) {
-  const [selectedTable, setSelectedTable] = useState(visibleQuerySchemas[0].name);
+  const { queueMetricsQueryTables } = useFeatures();
+  const schemas = useMemo(
+    () => listableQuerySchemas({ includeQueueMetrics: queueMetricsQueryTables }),
+    [queueMetricsQueryTables]
+  );
+  const tableOptions = useMemo(
+    () => schemas.map((s) => ({ label: s.name, value: s.name })),
+    [schemas]
+  );
+  const [selectedTable, setSelectedTable] = useState(schemas[0].name);
   const filtered = exampleQueries.filter((e) => e.table === selectedTable);
 
   return (

apps/webapp/app/routes/_app.orgs.$organizationSlug.projects.$projectParam.env.$envParam.query/TableSchemaContent.tsx

@@ -1,10 +1,11 @@
 import type { ColumnSchema } from "@internal/tsql";
-import { useState } from "react";
+import { useMemo, useState } from "react";
 import { Badge } from "~/components/primitives/Badge";
 import { CopyableText } from "~/components/primitives/CopyableText";
 import { Paragraph } from "~/components/primitives/Paragraph";
 import SegmentedControl from "~/components/primitives/SegmentedControl";
-import { visibleQuerySchemas } from "~/v3/querySchemas";
+import { listableQuerySchemas } from "~/v3/querySchemas";
+import { useFeatures } from "~/hooks/useFeatures";
 
 function ColumnHelpItem({ col }: { col: ColumnSchema }) {
   return (
@@ -43,11 +44,18 @@ function ColumnHelpItem({ col }: { col: ColumnSchema }) {
   );
 }
 
-const tableOptions = visibleQuerySchemas.map((s) => ({ label: s.name, value: s.name }));
-
 export function TableSchemaContent() {
-  const [selectedTable, setSelectedTable] = useState(visibleQuerySchemas[0].name);
-  const table = visibleQuerySchemas.find((s) => s.name === selectedTable) ?? visibleQuerySchemas[0];
+  const { queueMetricsQueryTables } = useFeatures();
+  const schemas = useMemo(
+    () => listableQuerySchemas({ includeQueueMetrics: queueMetricsQueryTables }),
+    [queueMetricsQueryTables]
+  );
+  const tableOptions = useMemo(
+    () => schemas.map((s) => ({ label: s.name, value: s.name })),
+    [schemas]
+  );
+  const [selectedTable, setSelectedTable] = useState(schemas[0].name);
+  const table = schemas.find((s) => s.name === selectedTable) ?? schemas[0];
 
   return (
     <div>

apps/webapp/app/routes/api.v1.query.schema.ts

@@ -1,7 +1,8 @@
 import { json } from "@remix-run/server-runtime";
 import type { ColumnSchema, TableSchema } from "@internal/tsql";
 import { createLoaderApiRoute } from "~/services/routeBuilders/apiBuilder.server";
-import { visibleQuerySchemas } from "~/v3/querySchemas";
+import { listableQuerySchemas } from "~/v3/querySchemas";
+import { env } from "~/env.server";
 
 function serializeColumn(col: ColumnSchema) {
   const result: Record<string, unknown> = {
@@ -51,7 +52,9 @@ export const loader = createLoaderApiRoute(
     },
   },
   async () => {
-    const tables = visibleQuerySchemas.map(serializeTable);
+    const tables = listableQuerySchemas({
+      includeQueueMetrics: env.QUEUE_METRICS_QUERY_TABLES_VISIBLE === "1",
+    }).map(serializeTable);
     return json({ tables });
   }
 );

apps/webapp/app/routes/resources.orgs.$organizationSlug.projects.$projectParam.env.$envParam.query.ai-generate.tsx

@@ -8,7 +8,7 @@ import type { AITimeFilter } from "~/routes/_app.orgs.$organizationSlug.projects
 import { requireUserId } from "~/services/session.server";
 import { EnvironmentParamSchema } from "~/utils/pathBuilder";
 import { AIQueryService } from "~/v3/services/aiQueryService.server";
-import { visibleQuerySchemas } from "~/v3/querySchemas";
+import { listableQuerySchemas } from "~/v3/querySchemas";
 
 const RequestSchema = z.object({
   prompt: z.string().min(1, "Prompt is required"),
@@ -85,7 +85,9 @@ export async function action({ request, params }: ActionFunctionArgs) {
   const { prompt, mode, currentQuery } = submission.data;
 
   const service = new AIQueryService(
-    visibleQuerySchemas,
+    listableQuerySchemas({
+      includeQueueMetrics: env.QUEUE_METRICS_QUERY_TABLES_VISIBLE === "1",
+    }),
     openai(env.AI_RUN_FILTER_MODEL ?? "gpt-4o-mini")
   );
 

apps/webapp/app/v3/querySchemas.ts

@@ -1444,8 +1444,29 @@ export const querySchemas: TableSchema[] = [
   queueMetricsByKeySchema,
 ];
 
-/** Schemas shown in user-facing listings (editor autocomplete, schema docs, schema API). */
-export const visibleQuerySchemas: TableSchema[] = querySchemas.filter((s) => !s.hidden);
+/** Tables whose listing is deferred until queue metrics are rolled out. */
+const QUEUE_METRICS_TABLE_NAMES = new Set([
+  queueMetricsSchema.name,
+  envMetricsSchema.name,
+  queueMetricsByKeySchema.name,
+]);
+
+/**
+ * Schemas shown in user-facing listings (editor autocomplete, schema docs, schema API, AI query
+ * context). Listing only: `querySchemas` stays the compile-time set, so a query naming an unlisted
+ * table still runs, with tenancy enforced as usual.
+ *
+ * Server callers pass `env.QUEUE_METRICS_QUERY_TABLES_VISIBLE === "1"`; client callers read
+ * `queueMetricsQueryTables` from `useFeatures()`. This module is imported by browser code, so it
+ * must not reach for `env.server` itself.
+ */
+export function listableQuerySchemas(options: { includeQueueMetrics: boolean }): TableSchema[] {
+  return querySchemas.filter((s) => {
+    if (s.hidden) return false;
+    if (!options.includeQueueMetrics && QUEUE_METRICS_TABLE_NAMES.has(s.name)) return false;
+    return true;
+  });
+}
 
 /**
  * Default query for the query editor