@malloy-publisher/server 0.0.233 → 0.0.235

package/package.json

@@ -1,7 +1,7 @@
 {
    "name": "@malloy-publisher/server",
    "description": "Malloy Publisher Server",
-   "version": "0.0.233",
+   "version": "0.0.235",
    "main": "dist/server.mjs",
    "bin": {
       "malloy-publisher": "dist/server.mjs"
@@ -36,17 +36,17 @@
       "@azure/storage-blob": "^12.26.0",
       "@duckdb/node-api": "1.5.3-r.2",
       "@google-cloud/storage": "^7.16.0",
-      "@malloydata/db-bigquery": "^0.0.426",
-      "@malloydata/db-databricks": "^0.0.426",
-      "@malloydata/db-duckdb": "^0.0.426",
-      "@malloydata/db-mysql": "^0.0.426",
-      "@malloydata/db-postgres": "^0.0.426",
-      "@malloydata/db-publisher": "^0.0.426",
-      "@malloydata/db-snowflake": "^0.0.426",
-      "@malloydata/db-trino": "^0.0.426",
-      "@malloydata/malloy": "^0.0.426",
-      "@malloydata/malloy-sql": "^0.0.426",
-      "@malloydata/render-validator": "^0.0.426",
+      "@malloydata/db-bigquery": "^0.0.427",
+      "@malloydata/db-databricks": "^0.0.427",
+      "@malloydata/db-duckdb": "^0.0.427",
+      "@malloydata/db-mysql": "^0.0.427",
+      "@malloydata/db-postgres": "^0.0.427",
+      "@malloydata/db-publisher": "^0.0.427",
+      "@malloydata/db-snowflake": "^0.0.427",
+      "@malloydata/db-trino": "^0.0.427",
+      "@malloydata/malloy": "^0.0.427",
+      "@malloydata/malloy-sql": "^0.0.427",
+      "@malloydata/render-validator": "^0.0.427",
       "@modelcontextprotocol/sdk": "^1.13.2",
       "@opentelemetry/api": "^1.9.0",
       "@opentelemetry/auto-instrumentations-node": "^0.57.0",

package/src/config.ts

@@ -189,7 +189,7 @@ function parseFloatEnv(name: string): number | undefined {
    return value;
 }
 
-function parseBoolEnv(name: string): boolean | undefined {
+export function parseBoolEnv(name: string): boolean | undefined {
    const raw = process.env[name];
    if (raw === undefined || raw.trim() === "") return undefined;
    const normalised = raw.trim().toLowerCase();
@@ -615,6 +615,40 @@ export const getPersistCollisionEnforce = (): boolean =>
    // prevent. A typo throws at startup, like every other flag here.
    parseBoolEnv("PERSIST_COLLISION_ENFORCE") ?? false;
 
+/**
+ * Whether the publisher attaches per-query metadata at all, from
+ * `PUBLISHER_QUERY_METADATA` (default `off`).
+ *
+ * Ships dark for a release, like `PERSIST_STORAGE_MODE` before it, and for the
+ * same reason: this is the rare feature that touches EVERY statement the server
+ * sends. On a backend with no native tag facility the bag rides as a leading SQL
+ * comment, so `on` changes the text of the statement (never its meaning or its
+ * results) and puts the bag in query logs and `pg_stat_activity`.
+ *
+ * The risk that decides the default is upstream, not here. Malloy validates the
+ * bag at dispatch and THROWS on one it cannot render, and the contract it
+ * validates against is mirrored in `service/query_metadata.ts` against a pinned
+ * version. Every mitigation on this path — clamping, shedding, never throwing —
+ * is downstream of that mirror being right, so a tightened upstream limit would
+ * surface as failing customer queries on a path nobody opted into. `off` for a
+ * release means a deployment turns attribution on deliberately, having read
+ * what it does to its statements.
+ *
+ * Case-insensitive; loud-fails on an unrecognized value, so a typo cannot
+ * silently leave a deployment that asked for attribution without it.
+ */
+export type QueryMetadataMode = "on" | "off";
+
+export const getQueryMetadataMode = (): QueryMetadataMode => {
+   const raw = process.env.PUBLISHER_QUERY_METADATA;
+   if (raw === undefined || raw.trim() === "") return "off";
+   const value = raw.trim().toLowerCase();
+   if (value === "on" || value === "off") return value;
+   throw new Error(
+      `PUBLISHER_QUERY_METADATA must be on | off (got ${JSON.stringify(raw)})`,
+   );
+};
+
 function substituteEnvVars(value: string): string {
    const envVarPattern = /\$\{([A-Z_][A-Z0-9_]*)\}/g;
 

package/src/controller/connection.controller.spec.ts

@@ -60,6 +60,52 @@ function buildController(
    return { controller, runSQL, assertCanAdmitQuery };
 }
 
+describe("ConnectionController connection queryMetadata", () => {
+   afterEach(() => sinon.restore());
+
+   it("rejects a connection default the contract cannot render", async () => {
+      // The connection is the one metadata layer whose author is right here, so
+      // it is the one that can be told. `cost-centre` is the natural spelling
+      // and would otherwise be dropped at dispatch, leaving every statement on
+      // the connection missing the property its operator configured.
+      const { controller } = buildController(sinon.stub().resolves());
+      await expect(
+         controller.addConnection("env", "warehouse", {
+            name: "warehouse",
+            type: "postgres",
+            queryMetadata: { "cost-centre": "eng" },
+         }),
+      ).rejects.toThrow(/queryMetadata is invalid/);
+   });
+
+   it("rejects an enforced bag the contract cannot render", async () => {
+      const { controller } = buildController(sinon.stub().resolves());
+      await expect(
+         controller.addConnection("env", "warehouse", {
+            name: "warehouse",
+            type: "postgres",
+            queryMetadataEnforced: { "org.id": "acme" },
+         }),
+      ).rejects.toThrow(/queryMetadataEnforced is invalid/);
+   });
+
+   it("accepts a conforming connection default", async () => {
+      const { controller } = buildController(sinon.stub().resolves());
+      const addConnection = sinon.stub().resolves();
+      (
+         controller as unknown as {
+            connectionService: { addConnection: sinon.SinonStub };
+         }
+      ).connectionService = { addConnection } as never;
+      await controller.addConnection("env", "warehouse", {
+         name: "warehouse",
+         type: "postgres",
+         queryMetadata: { cost_centre: "eng" },
+      });
+      expect(addConnection.calledOnce).toBe(true);
+   });
+});
+
 describe("ConnectionController.getConnectionQueryData row cap", () => {
    const originalEnv = process.env.PUBLISHER_MAX_QUERY_ROWS;
 

package/src/controller/connection.controller.ts

@@ -21,6 +21,15 @@ import {
    getSchemasForConnection,
    listTablesForSchema,
 } from "../service/db_utils";
+import {
+   mergeQueryMetadata,
+   mintCorrelationId,
+   parseQueryClass,
+   parseSuppliedQueryMetadata,
+   queryMetadataViolations,
+   type QueryClass,
+   type QueryMetadata,
+} from "../service/query_metadata";
 import type { Environment } from "../service/environment";
 import { EnvironmentStore } from "../service/environment_store";
 import { isStreamingConnection, streamSqlWithBudget } from "../stream_helpers";
@@ -112,6 +121,22 @@ function validateAdminAuthoredConnection(
    } catch (error) {
       throw new BadRequestError((error as Error).message);
    }
+
+   // The connection is the one metadata layer whose author is right here, so it
+   // is the one that can be told. A property the contract rejects (a hyphen in
+   // `cost-centre` is the natural spelling and the first thing anyone tries)
+   // would otherwise be dropped at dispatch and only ever surface as a metric —
+   // every statement on the connection missing the property its operator
+   // believes they configured. Config LOAD warns instead of throwing (see
+   // assembleEnvironmentConnections): a tag must never fail an environment.
+   for (const field of ["queryMetadata", "queryMetadataEnforced"] as const) {
+      const violations = queryMetadataViolations(connectionConfig[field]);
+      if (violations.length > 0) {
+         throw new BadRequestError(
+            `Connection "${connectionName}" ${field} is invalid: ${violations.join("; ")}`,
+         );
+      }
+   }
 }
 
 export class ConnectionController {
@@ -140,6 +165,43 @@ export class ConnectionController {
       return environment.getApiConnection(connectionName);
    }
 
+   /**
+    * A connection's default per-query metadata, or null when it declares none.
+    * Fails open: metadata is observability, so a connection whose config can't be
+    * read contributes no default rather than failing the query the caller asked
+    * for.
+    */
+   private async connectionQueryMetadata(
+      environmentName: string,
+      connectionName: string,
+   ): Promise<{
+      default: QueryMetadata | null;
+      enforced: QueryMetadata | null;
+   }> {
+      try {
+         const environment = await this.environmentStore.getEnvironment(
+            environmentName,
+            false,
+         );
+         const connection = this.getApiConnectionForLookup(
+            environment,
+            connectionName,
+         );
+         return {
+            default: connection.queryMetadata ?? null,
+            enforced: connection.queryMetadataEnforced ?? null,
+         };
+      } catch (error) {
+         // Fails open like every other metadata path, but not invisibly: the
+         // layer lost here is the enforced one, and no metric covers it.
+         logger.debug("No query-metadata layers for connection", {
+            connectionName,
+            error,
+         });
+         return { default: null, enforced: null };
+      }
+   }
+
    private async getMalloyConnection(
       environmentName: string,
       connectionName: string,
@@ -453,6 +515,12 @@ export class ConnectionController {
       sqlStatement: string,
       options: string,
       packageName?: string,
+      /**
+       * The request's per-query metadata fields, unvalidated — this controller is
+       * the boundary that turns a bad bag into a 400 rather than letting the
+       * connector refuse the statement at dispatch.
+       */
+      metadata?: { queryMetadata?: unknown; queryClass?: unknown },
    ): Promise<ApiQueryData> {
       // Express parses repeated query parameters (?sqlStatement=a&sqlStatement=b)
       // and array-shaped JSON bodies as `string[]`, not `string`. The route
@@ -512,6 +580,41 @@ export class ConnectionController {
          runSQLOptions.abortSignal = undefined;
       }
 
+      // Per-query metadata. Validated here, not clamped: a raw-SQL caller gets a
+      // 400 telling it which property is wrong instead of a statement the
+      // connector refuses at dispatch. `options` is forwarded as RunSQLOptions, so
+      // a bag can also arrive inside it — validate that one too, and let the
+      // documented field win.
+      const suppliedMetadata =
+         metadata?.queryMetadata ?? runSQLOptions.queryMetadata;
+      let requestMetadata: QueryMetadata | undefined;
+      let queryClass: QueryClass | undefined;
+      try {
+         requestMetadata = parseSuppliedQueryMetadata(suppliedMetadata);
+         queryClass = parseQueryClass(metadata?.queryClass);
+      } catch (error) {
+         throw new BadRequestError((error as Error).message);
+      }
+      const connectionLayers = await this.connectionQueryMetadata(
+         environmentName,
+         connectionName,
+      );
+      const resolvedMetadata = mergeQueryMetadata({
+         connection: connectionLayers.default,
+         enforced: connectionLayers.enforced,
+         request: requestMetadata,
+         context: {
+            // Raw SQL against a connection is platform maintenance unless the
+            // caller says otherwise — it is not a modeled query.
+            queryClass: queryClass ?? "ops",
+            environment: environmentName,
+            package: packageName,
+            correlationId: mintCorrelationId(),
+         },
+      });
+      runSQLOptions.queryMetadata = resolvedMetadata.metadata;
+      const queryCorrelationId = resolvedMetadata.metadata?.query_id ?? null;
+
       // Bound the response with two layered caps:
       //
       //   - Row cap (PUBLISHER_MAX_QUERY_ROWS) — pushed to the driver as
@@ -572,7 +675,7 @@ export class ConnectionController {
                throw new ConnectionError((error as Error).message);
             }
          }, getQueryTimeoutMs());
-         return { data: JSON.stringify(streamed) };
+         return { data: JSON.stringify(streamed), queryCorrelationId };
       }
 
       const result = await runWithQueryTimeout(async (signal) => {
@@ -601,7 +704,7 @@ export class ConnectionController {
          );
       }
 
-      return { data: JSON.stringify(result) };
+      return { data: JSON.stringify(result), queryCorrelationId };
    }
 
    public async getConnectionTemporaryTable(

package/src/controller/materialization.controller.spec.ts

@@ -265,4 +265,29 @@ describe("MaterializationController.createMaterialization validation", () => {
          }),
       ).rejects.toThrow(BadRequestError);
    });
+
+   it("rejects a runId the metadata contract cannot carry", async () => {
+      // runId becomes the `run_id` property on every statement of the build, so
+      // an over-long or unrenderable value is silently truncated and rewritten
+      // at dispatch — leaving the caller holding an id that joins to nothing.
+      // The neighbouring `trigger` is enum-validated; this is the same kind of
+      // boundary and gets the same treatment.
+      const { controller } = build();
+      await expect(
+         controller.createMaterialization("env", "pkg", {
+            runContext: { runId: "x".repeat(300) },
+         }),
+      ).rejects.toThrow(BadRequestError);
+      await expect(
+         controller.createMaterialization("env", "pkg", {
+            runContext: { runId: 'has "quotes"' },
+         }),
+      ).rejects.toThrow(BadRequestError);
+   });
+
+   it("still accepts a conforming runId", async () => {
+      expect(
+         await parse({ runContext: { trigger: "publish", runId: "run-42" } }),
+      ).toEqual({ runContext: { trigger: "publish", runId: "run-42" } });
+   });
 });

package/src/controller/materialization.controller.ts

@@ -1,9 +1,15 @@
+import type { components } from "../api";
 import { BadRequestError } from "../errors";
 import {
    BuildInstruction,
    ManifestReference,
 } from "../storage/DatabaseInterface";
 import { MaterializationService } from "../service/materialization_service";
+import { queryMetadataViolations } from "../service/query_metadata";
+
+type RunContext = components["schemas"]["RunContext"];
+
+const RUN_TRIGGERS = ["publish", "on_demand", "scheduler"] as const;
 
 export class MaterializationController {
    constructor(private materializationService: MaterializationService) {}
@@ -31,6 +37,7 @@ export class MaterializationController {
       buildInstructions?: BuildInstruction[];
       referenceManifest?: ManifestReference[];
       strictUpstreams?: boolean;
+      runContext?: RunContext;
    } {
       const result: {
          forceRefresh?: boolean;
@@ -38,7 +45,11 @@ export class MaterializationController {
          buildInstructions?: BuildInstruction[];
          referenceManifest?: ManifestReference[];
          strictUpstreams?: boolean;
+         runContext?: RunContext;
       } = {};
+      if (body.runContext !== undefined && body.runContext !== null) {
+         result.runContext = this.validateRunContext(body.runContext);
+      }
       if (
          body.buildInstructions !== undefined &&
          body.buildInstructions !== null
@@ -72,6 +83,55 @@ export class MaterializationController {
       return result;
    }
 
+   /**
+    * Validate `runContext`, the caller's observability context for one run.
+    * `trigger` is a closed enum here even though it feeds a metadata property:
+    * the whole point is that a reader can group runs by how they started, which a
+    * free-form value would quietly break.
+    *
+    * Note this is NOT the service-level `trigger` the parser above deliberately
+    * refuses. That one decides whether the run counts as scheduled; this one only
+    * labels the statements the run issues, so accepting `publish` from a caller
+    * forges nothing.
+    */
+   private validateRunContext(raw: unknown): RunContext {
+      if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+         throw new BadRequestError("runContext must be an object");
+      }
+      const obj = raw as Record<string, unknown>;
+      const context: RunContext = {};
+      if (obj.trigger !== undefined && obj.trigger !== null) {
+         if (
+            typeof obj.trigger !== "string" ||
+            !RUN_TRIGGERS.includes(obj.trigger as (typeof RUN_TRIGGERS)[number])
+         ) {
+            throw new BadRequestError(
+               `runContext.trigger must be one of ${RUN_TRIGGERS.join(" | ")}`,
+            );
+         }
+         context.trigger = obj.trigger as RunContext["trigger"];
+      }
+      if (obj.runId !== undefined && obj.runId !== null) {
+         if (typeof obj.runId !== "string") {
+            throw new BadRequestError("runContext.runId must be a string");
+         }
+         // Held to the metadata contract like any other caller-supplied
+         // property: it becomes the `run_id` on every statement of the build,
+         // and a value the contract rejects would otherwise be truncated and
+         // rewritten in silence — leaving the caller with an id it cannot join
+         // on and no way to know why.
+         const violations = queryMetadataViolations({ run_id: obj.runId });
+         if (violations.length > 0) {
+            throw new BadRequestError(
+               `runContext.runId is attached to every statement as the run_id ` +
+                  `property: ${violations.join("; ")}`,
+            );
+         }
+         context.runId = obj.runId;
+      }
+      return context;
+   }
+
    /**
     * Validate the orchestrated `buildInstructions` payload (BuildInstructions:
     * `{ sources: BuildInstruction[], referenceManifest?, strictUpstreams? }`)

package/src/controller/model.controller.ts

@@ -1,6 +1,7 @@
 import { components } from "../api";
 import { getQueryTimeoutMs } from "../config";
 import { ModelNotFoundError } from "../errors";
+import { logger } from "../logger";
 import { runWithQueryTimeout } from "../query_timeout";
 import { EnvironmentStore } from "../service/environment_store";
 import type { FilterParams } from "../service/filter";
@@ -133,6 +134,29 @@ export class ModelController {
                bypassFilters,
                givens,
                abortSignal,
+               {
+                  environment: environmentName,
+                  // The environment owns the connection configs, so the default
+                  // and enforced layers are read here rather than from the model.
+                  connectionMetadata: (connectionName) => {
+                     try {
+                        const connection =
+                           environment.getApiConnection(connectionName);
+                        return {
+                           default: connection.queryMetadata,
+                           enforced: connection.queryMetadataEnforced,
+                        };
+                     } catch (error) {
+                        // Fails open, and says so: what an unreadable
+                        // connection costs is the enforced layer.
+                        logger.debug(
+                           "No query-metadata layers for connection",
+                           { connectionName, error },
+                        );
+                        return null;
+                     }
+                  },
+               },
             ),
          getQueryTimeoutMs(),
       );

package/src/controller/query.controller.ts

@@ -2,8 +2,16 @@ import { validateRenderTags } from "@malloydata/render-validator";
 import { components } from "../api";
 import { getQueryTimeoutMs } from "../config";
 import { API_PREFIX } from "../constants";
-import { ModelNotFoundError } from "../errors";
+import { BadRequestError, ModelNotFoundError } from "../errors";
 import { bigIntReplacer } from "../json_utils";
+import { logger } from "../logger";
+import {
+   mintCorrelationId,
+   parseQueryClass,
+   parseSuppliedQueryMetadata,
+   type QueryClass,
+   type QueryMetadata,
+} from "../service/query_metadata";
 import { runWithQueryTimeout } from "../query_timeout";
 import { EnvironmentStore } from "../service/environment_store";
 import type { FilterParams } from "../service/filter";
@@ -29,7 +37,26 @@ export class QueryController {
       filterParams?: FilterParams,
       bypassFilters?: boolean,
       givens?: Record<string, GivenValue>,
+      /**
+       * The request's per-query metadata fields, unvalidated — this controller is
+       * the boundary that turns a bad bag into a 400 rather than letting the
+       * connector refuse the statement at dispatch.
+       */
+      metadata?: {
+         queryMetadata?: unknown;
+         queryClass?: unknown;
+         versionId?: string;
+      },
    ): Promise<ApiQuery> {
+      let requestMetadata: QueryMetadata | undefined;
+      let queryClass: QueryClass | undefined;
+      try {
+         requestMetadata = parseSuppliedQueryMetadata(metadata?.queryMetadata);
+         queryClass = parseQueryClass(metadata?.queryClass);
+      } catch (error) {
+         throw new BadRequestError((error as Error).message);
+      }
+
       const environment = await this.environmentStore.getEnvironment(
          environmentName,
          false,
@@ -46,20 +73,60 @@ export class QueryController {
       if (!model) {
          throw new ModelNotFoundError(`${modelPath} does not exist`);
       } else {
-         const { result, compactResult, rowLimit, rowLimitSource } =
-            await runWithQueryTimeout(
-               (abortSignal) =>
-                  model.getQueryResults(
-                     sourceName,
-                     queryName,
-                     query,
-                     filterParams,
-                     bypassFilters,
-                     givens,
-                     abortSignal,
-                  ),
-               getQueryTimeoutMs(),
-            );
+         const {
+            result,
+            compactResult,
+            rowLimit,
+            rowLimitSource,
+            queryCorrelationId,
+         } = await runWithQueryTimeout(
+            (abortSignal) =>
+               model.getQueryResults(
+                  sourceName,
+                  queryName,
+                  query,
+                  filterParams,
+                  bypassFilters,
+                  givens,
+                  abortSignal,
+                  {
+                     request: requestMetadata,
+                     queryClass,
+                     environment: environmentName,
+                     // Always undefined today: the route 501s any versionId
+                     // before this runs. Wired so that lifting that rejection
+                     // is the whole change.
+                     version: metadata?.versionId,
+                     // Minted here because this is the boundary that returns
+                     // it; a path with nowhere to put it does not mint one.
+                     correlationId: mintCorrelationId(),
+                     // The environment owns the connection configs, so the
+                     // default and enforced layers are read here rather than
+                     // from the model.
+                     connectionMetadata: (connectionName) => {
+                        try {
+                           const connection =
+                              environment.getApiConnection(connectionName);
+                           return {
+                              default: connection.queryMetadata,
+                              enforced: connection.queryMetadataEnforced,
+                           };
+                        } catch (error) {
+                           // Failing open is right — a tag must not fail a
+                           // query — but this is the one drop with no metric
+                           // behind it, and what it costs is the ENFORCED
+                           // layer. Log it so it is diagnosable.
+                           logger.debug(
+                              "No query-metadata layers for connection",
+                              { connectionName, error },
+                           );
+                           return null;
+                        }
+                     },
+                  },
+               ),
+            getQueryTimeoutMs(),
+         );
          const renderLogs = validateRenderTags(result);
          return {
             result: compactJson
@@ -78,6 +145,7 @@ export class QueryController {
             // deliberate `limit:`/`top:` from the silently-applied default, and
             // so cannot reproduce the MCP envelope's _limit_hit.
             queryRowLimitSource: rowLimitSource,
+            queryCorrelationId,
          } as ApiQuery;
       }
    }

package/src/mcp/handler_utils.ts

@@ -19,6 +19,7 @@ import {
    type ErrorDetails,
 } from "./error_messages";
 import type { Model } from "../service/model";
+import type { Environment } from "../service/environment";
 import { logger } from "../logger";
 
 /**
@@ -116,6 +117,11 @@ export function classifyToolError(
 /**
  * Fetches and validates the Package and Model instances needed for query execution.
  * Handles errors related to package/model access and initial compilation.
+ *
+ * The resolved Environment comes back with the model because a query needs it for
+ * more than the lookup: it owns the connection configs the per-query metadata
+ * layers are read from.
+ *
  * @returns An object containing the Model instance or a pre-formatted ErrorDetails object.
  */
 export async function getModelForQuery(
@@ -123,7 +129,9 @@ export async function getModelForQuery(
    environmentName: string,
    packageName: string,
    modelPath: string,
-): Promise<{ model: Model } | { error: ErrorDetails }> {
+): Promise<
+   { model: Model; environment: Environment } | { error: ErrorDetails }
+> {
    try {
       const environment = await environmentStore.getEnvironment(
          environmentName,
@@ -143,7 +151,7 @@ export async function getModelForQuery(
       }
       // Attempt to get the model definition early to catch initial compilation errors
       await model.getModel(); // This might throw ModelCompilationError
-      return { model };
+      return { model, environment };
    } catch (error) {
       // Handle errors during package/model access or initial compilation
       let errorDetails: ErrorDetails;

package/src/mcp/query_envelope.ts

@@ -65,6 +65,14 @@ export interface QueryEnvelope {
    _rows_truncated?: boolean;
    _total_rows?: number;
    _returned_rows?: number;
+   /**
+    * The `query_id` property attached to this query's statements: the join key
+    * into the backend's own query record (`QUERY_HISTORY`, `JOBS.labels`, the
+    * statement text). Publisher-side and new to both products, like the two
+    * `_limit_...` fields. Absent when nothing was attached, which is every query
+    * on a deployment that has not enabled query metadata.
+    */
+   _query_id?: string;
    warning?: string;
    renderLogErrors?: string[];
 }
@@ -97,6 +105,7 @@ export function buildQueryEnvelope(
    renderLogErrors: string[] = [],
    limit = MAX_RESULT_CHARS,
    rowLimitSource: QueryRowLimitSource = "server_default",
+   queryCorrelationId: string | null = null,
 ): QueryEnvelope {
    const rowCount = Array.isArray(rows) ? rows.length : 0;
    // Equality, not >=: the cap is pushed into the SQL, so the database cannot
@@ -132,6 +141,7 @@ export function buildQueryEnvelope(
       _query_row_limit: rowLimit,
       _limit_source: rowLimitSource,
       _limit_hit: limitHit,
+      ...(queryCorrelationId !== null && { _query_id: queryCorrelationId }),
       ...(renderLogErrors.length > 0 && { renderLogErrors }),
    };