feat(webapp,tsql): hide the per-key metrics table from user-facing query surfaces

TableSchema gains a hidden flag: hidden tables stay fully queryable
through the engine (the concurrency-keys tab keeps working, tenancy and
the merge guard still apply) but are excluded from the query editor
autocomplete, the Query page schema and examples panels, the AI query
generator context, and the schema API. queue_metrics_by_key is hidden
until the per-key surface is settled.

Author: ericallam

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

@@ -72,7 +72,7 @@ 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 { querySchemas } from "~/v3/querySchemas";
+import { visibleQuerySchemas } from "~/v3/querySchemas";
 
 /** Convert a Date or ISO string to ISO string format */
 function toISOString(value: Date | string): string {
@@ -245,7 +245,7 @@ const QueryEditorForm = forwardRef<
       <TSQLEditor
         defaultValue={query}
         onChange={setQuery}
-        schema={querySchemas}
+        schema={visibleQuerySchemas}
         linterEnabled={true}
         showCopyButton={true}
         showClearButton={true}

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

@@ -3,7 +3,7 @@ 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 { querySchemas } from "~/v3/querySchemas";
+import { visibleQuerySchemas } from "~/v3/querySchemas";
 import { TryableCodeBlock } from "./TRQLGuideContent";
 
 // Example queries for the Examples tab
@@ -211,14 +211,14 @@ LIMIT 20`,
   },
 ];
 
-const tableOptions = querySchemas.map((s) => ({ label: s.name, value: s.name }));
+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(querySchemas[0].name);
+  const [selectedTable, setSelectedTable] = useState(visibleQuerySchemas[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

@@ -4,7 +4,7 @@ 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 { querySchemas } from "~/v3/querySchemas";
+import { visibleQuerySchemas } from "~/v3/querySchemas";
 
 function ColumnHelpItem({ col }: { col: ColumnSchema }) {
   return (
@@ -43,11 +43,11 @@ function ColumnHelpItem({ col }: { col: ColumnSchema }) {
   );
 }
 
-const tableOptions = querySchemas.map((s) => ({ label: s.name, value: s.name }));
+const tableOptions = visibleQuerySchemas.map((s) => ({ label: s.name, value: s.name }));
 
 export function TableSchemaContent() {
-  const [selectedTable, setSelectedTable] = useState(querySchemas[0].name);
-  const table = querySchemas.find((s) => s.name === selectedTable) ?? querySchemas[0];
+  const [selectedTable, setSelectedTable] = useState(visibleQuerySchemas[0].name);
+  const table = visibleQuerySchemas.find((s) => s.name === selectedTable) ?? visibleQuerySchemas[0];
 
   return (
     <div>

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

@@ -1,7 +1,7 @@
 import { json } from "@remix-run/server-runtime";
 import type { ColumnSchema, TableSchema } from "@internal/tsql";
 import { createLoaderApiRoute } from "~/services/routeBuilders/apiBuilder.server";
-import { querySchemas } from "~/v3/querySchemas";
+import { visibleQuerySchemas } from "~/v3/querySchemas";
 
 function serializeColumn(col: ColumnSchema) {
   const result: Record<string, unknown> = {
@@ -51,7 +51,7 @@ export const loader = createLoaderApiRoute(
     },
   },
   async () => {
-    const tables = querySchemas.map(serializeTable);
+    const tables = visibleQuerySchemas.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 { querySchemas } from "~/v3/querySchemas";
+import { visibleQuerySchemas } from "~/v3/querySchemas";
 
 const RequestSchema = z.object({
   prompt: z.string().min(1, "Prompt is required"),
@@ -85,7 +85,7 @@ export async function action({ request, params }: ActionFunctionArgs) {
   const { prompt, mode, currentQuery } = submission.data;
 
   const service = new AIQueryService(
-    querySchemas,
+    visibleQuerySchemas,
     openai(env.AI_RUN_FILTER_MODEL ?? "gpt-4o-mini")
   );
 

apps/webapp/app/v3/querySchemas.ts

@@ -1309,6 +1309,7 @@ export const queueMetricsByKeySchema: TableSchema = {
   name: "queue_metrics_by_key",
   clickhouseName: "trigger_dev.queue_metrics_ck_v1",
   description: "Per-concurrency-key queue metrics: backlog, throughput, and wait by key",
+  hidden: true,
   timeConstraint: "bucket_start",
   tenantColumns: {
     organizationId: "organization_id",
@@ -1444,6 +1445,9 @@ 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);
+
 /**
  * Default query for the query editor
  */

internal-packages/tsql/src/query/schema.ts

@@ -431,6 +431,11 @@ export interface TableSchema {
    * so repeated auto-refresh queries share cache entries.
    */
   queryCache?: { ttlSeconds: number; alignSeconds: number };
+  /**
+   * Excluded from user-facing listings (query editor, schema docs, schema API) by
+   * callers; the engine still compiles queries against it.
+   */
+  hidden?: boolean;
 }
 
 /**