@malloydata/malloy 0.0.425 → 0.0.426

package/dist/api/foundation/compile.js

@@ -374,7 +374,11 @@ class Malloy {
             connection = await connections.lookupConnection(connectionName);
         }
         if (sqlStruct) {
-            const data = await connection.runSQL(sqlStruct.selectStr);
+            // Only the metadata: a SQL block's rowLimit/abortSignal handling is what
+            // it was, and changing that is not this feature's business.
+            const data = await connection.runSQL(sqlStruct.selectStr, {
+                queryMetadata: options === null || options === void 0 ? void 0 : options.queryMetadata,
+            });
             return new result_1.Result({
                 structs: [sqlStruct],
                 sql: sqlStruct.selectStr,

package/dist/api/foundation/runtime.d.ts

@@ -546,9 +546,7 @@ export declare class PreparedResultMaterializer extends FluentState<PreparedResu
      * @return A promise to the query result data.
      */
     run(options?: RunSQLOptions): Promise<Result>;
-    runStream(options?: {
-        rowLimit?: number;
-    }): AsyncIterableIterator<DataRecord>;
+    runStream(options?: RunSQLOptions): AsyncIterableIterator<DataRecord>;
     /**
      * Materialize this loaded prepared result.
      *

package/dist/api/foundation/runtime.js

@@ -586,33 +586,37 @@ class ModelMaterializer extends FluentState {
      * or loading further related objects.
      */
     loadQuery(query, options) {
-        const { refreshSchemaCache, noThrowOnError } = options || {};
+        // `options` spans three interfaces. The parse/compile half is spent here,
+        // compiling the query text; the `CompileQueryOptions` half belongs to the
+        // materializer, which applies it when the query is turned into SQL — so it
+        // has to reach `makeQueryMaterializer` as well, or a `buildManifest` (or
+        // `givens`, or `defaultRowLimit`) passed here is silently ignored.
+        //
+        // Split by naming the parse/compile keys rather than the query ones, so a
+        // query option added later is carried rather than quietly dropped.
+        // `restrictedMode` and `method` are named to hold them back: this entry
+        // point has never honored them, and `loadRestrictedQuery` is how a caller
+        // asks for restricted compilation.
+        const { importBaseURL, testEnvironment, refreshSchemaCache, noThrowOnError, restrictedMode: _restrictedMode, method: _method, ...callQueryOptions } = options !== null && options !== void 0 ? options : {};
+        const compileQueryOptions = {
+            ...this.compileQueryOptions,
+            ...callQueryOptions,
+        };
         return this.makeQueryMaterializer(async () => {
-            const urlReader = this.runtime.urlReader;
-            const connections = this.runtime.connections;
-            if (this.runtime.isTestRuntime) {
-                if (options === undefined) {
-                    options = { testEnvironment: true };
-                }
-                else {
-                    options = { ...options, testEnvironment: true };
-                }
-            }
             const compilable = query instanceof URL ? { url: query } : { source: query };
-            const model = await this.getModel();
             const queryModel = await compile_1.Malloy.compile({
                 ...compilable,
-                urlReader,
-                connections,
-                model,
+                urlReader: this.runtime.urlReader,
+                connections: this.runtime.connections,
+                model: await this.getModel(),
                 refreshSchemaCache,
                 noThrowOnError,
-                importBaseURL: options === null || options === void 0 ? void 0 : options.importBaseURL,
-                testEnvironment: options === null || options === void 0 ? void 0 : options.testEnvironment,
-                ...this.compileQueryOptions,
+                importBaseURL,
+                testEnvironment: testEnvironment || this.runtime.isTestRuntime,
+                ...compileQueryOptions,
             });
             return queryModel.preparedQuery;
-        });
+        }, compileQueryOptions);
     }
     /**
      * Load a Malloy query whose text comes from an untrusted source — an

package/dist/connection/base_connection.d.ts

@@ -1,5 +1,6 @@
 import type { SQLSourceRequest } from '../lang/translate-response';
 import type { MalloyQueryData, QueryRunStats, SQLSourceDef, StructDef, TableSourceDef } from '../model/malloy_types';
+import type { QueryMetadata } from '../query_metadata';
 import type { RunSQLOptions } from '../run_sql_options';
 import type { Connection, FetchSchemaOptions, PersistSQLResults, PooledConnection, StreamingConnection } from './types';
 export interface SchemaFound<T extends StructDef> {
@@ -36,6 +37,28 @@ export declare abstract class BaseConnection implements Connection {
         error: string;
         structDef?: undefined;
     }>;
+    /**
+     * The validated bag, or undefined when there is nothing to apply. For
+     * connectors with a native key-value mechanism, e.g. BigQuery job labels.
+     */
+    protected queryMetadataBag(meta: QueryMetadata | undefined): QueryMetadata | undefined;
+    /**
+     * The metadata as a single SQL comment line, empty when there is nothing to
+     * apply. For a connector which has to place the comment itself rather than
+     * simply prepending it — see {@link sqlWithQueryMetadata}.
+     *
+     * ```
+     * -- NAME1="val1" NAME2="val2"
+     * ```
+     */
+    protected queryMetadataComment(meta: QueryMetadata | undefined): string;
+    /**
+     * `sql` with the metadata prepended as a leading comment, or `sql` unchanged
+     * when there is nothing to apply. For connectors with no native per-query
+     * mechanism. The contract guarantees the rendered comment is safe: no
+     * embedded quote, no newline.
+     */
+    protected sqlWithQueryMetadata(sql: string, meta: QueryMetadata | undefined): string;
     isPool(): this is PooledConnection;
     canPersist(): this is PersistSQLResults;
     canStream(): this is StreamingConnection;

package/dist/connection/base_connection.js

@@ -6,6 +6,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BaseConnection = void 0;
 const sql_block_1 = require("../model/sql_block");
+const query_metadata_1 = require("../query_metadata");
 const validate_table_path_1 = require("./validate_table_path");
 class BaseConnection {
     constructor() {
@@ -72,6 +73,49 @@ class BaseConnection {
         }
         return { error: 'Unknown schema fetch error' };
     }
+    /*
+     * Applying `RunSQLOptions.queryMetadata`. A connector uses whichever of these
+     * fits its backend: a native key-value mechanism takes the bag, everything
+     * else prepends the comment. They validate, so a bag that violates the
+     * contract throws rather than reaching the database in some mangled form.
+     */
+    /**
+     * The validated bag, or undefined when there is nothing to apply. For
+     * connectors with a native key-value mechanism, e.g. BigQuery job labels.
+     */
+    queryMetadataBag(meta) {
+        if (meta === undefined)
+            return undefined;
+        (0, query_metadata_1.validateQueryMetadata)(meta);
+        return Object.keys(meta).length > 0 ? meta : undefined;
+    }
+    /**
+     * The metadata as a single SQL comment line, empty when there is nothing to
+     * apply. For a connector which has to place the comment itself rather than
+     * simply prepending it — see {@link sqlWithQueryMetadata}.
+     *
+     * ```
+     * -- NAME1="val1" NAME2="val2"
+     * ```
+     */
+    queryMetadataComment(meta) {
+        const bag = this.queryMetadataBag(meta);
+        if (bag === undefined)
+            return '';
+        const rendered = Object.keys(bag)
+            .map(key => `${key}="${bag[key]}"`)
+            .join(' ');
+        return `-- ${rendered}\n`;
+    }
+    /**
+     * `sql` with the metadata prepended as a leading comment, or `sql` unchanged
+     * when there is nothing to apply. For connectors with no native per-query
+     * mechanism. The contract guarantees the rendered comment is safe: no
+     * embedded quote, no newline.
+     */
+    sqlWithQueryMetadata(sql, meta) {
+        return this.queryMetadataComment(meta) + sql;
+    }
     isPool() {
         return false;
     }

package/dist/index.d.ts

@@ -10,6 +10,7 @@ export type { Overlay, ConfigOverlays } from './api/foundation';
 export type { FilesystemContext, MalloyConfigOptions } from './api/foundation';
 export type { RuntimeContext } from './api/foundation';
 export type { QueryOptionsReader, RunSQLOptions } from './run_sql_options';
+export type { QueryMetadata } from './query_metadata';
 export type { EventStream, ModelString, ModelURL, QueryString, QueryURL, URLReader, InvalidationKey, } from './runtime_types';
 export type { Connection, ConnectionConfig, ConnectionParameterValue, FetchSchemaOptions, InfoConnection, LookupConnection, PersistSQLResults, PooledConnection, TestableConnection, StreamingConnection, } from './connection/types';
 export { registerConnectionType, getConnectionProperties, getConnectionTypeDisplayName, getRegisteredConnectionTypes, createConnectionsFromConfig, } from './connection/registry';

package/dist/query_metadata.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Dialect-agnostic metadata attached per query to the statements a connection
+ * issues, for the backend's own bookkeeping (cost attribution, workload
+ * classification, tracing): a small bag of string-valued properties.
+ *
+ * Each connector applies it through a per-query mechanism — Snowflake's
+ * per-statement `QUERY_TAG` and BigQuery's per-job labels natively, others as a
+ * leading SQL comment. It never affects query results or data identity.
+ *
+ * This is the only name in this file which is public API; a connector reaches
+ * the machinery for applying a bag through `BaseConnection`.
+ */
+export type QueryMetadata = Record<string, string>;
+/** The ways `meta` violates the contract (empty = conforming). */
+export declare function queryMetadataProblems(meta: QueryMetadata): string[];
+/** Validate query metadata, throwing if the bag is invalid. */
+export declare function validateQueryMetadata(meta: QueryMetadata): void;

package/dist/query_metadata.js

@@ -0,0 +1,60 @@
+"use strict";
+/*
+ * Copyright Contributors to the Malloy project
+ * SPDX-License-Identifier: MIT
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.queryMetadataProblems = queryMetadataProblems;
+exports.validateQueryMetadata = validateQueryMetadata;
+// Contract for a bag that is usable across every backend and always safe to
+// render (including into the `-- NAME="value"` comment form):
+//   - names: ASCII alphanumerics and underscore
+//   - values: printable ASCII, excluding the double-quote
+//   - a small number of properties
+// Connectors may transform within these rules (e.g. BigQuery lowercases keys).
+const QUERY_METADATA_MAX_KEY_LENGTH = 128;
+const QUERY_METADATA_MAX_VALUE_LENGTH = 256;
+const QUERY_METADATA_MAX_PROPERTIES = 20;
+const KEY_RE = /^[A-Za-z0-9_]+$/;
+// Printable ASCII (0x20–0x7e), excluding the double-quote (0x22) that would
+// break the `NAME="value"` comment form. Also excludes control characters.
+function isValidValue(s) {
+    for (let i = 0; i < s.length; i++) {
+        const code = s.charCodeAt(i);
+        if (code < 0x20 || code > 0x7e || code === 0x22)
+            return false;
+    }
+    return true;
+}
+/** The ways `meta` violates the contract (empty = conforming). */
+function queryMetadataProblems(meta) {
+    const problems = [];
+    const keys = Object.keys(meta);
+    if (keys.length > QUERY_METADATA_MAX_PROPERTIES) {
+        problems.push(`more than ${QUERY_METADATA_MAX_PROPERTIES} properties`);
+    }
+    for (const key of keys) {
+        if (!KEY_RE.test(key)) {
+            problems.push(`property name '${key}' must be ASCII alphanumerics and underscore`);
+        }
+        if (key.length > QUERY_METADATA_MAX_KEY_LENGTH) {
+            problems.push(`property name '${key}' exceeds ${QUERY_METADATA_MAX_KEY_LENGTH} characters`);
+        }
+        const value = meta[key];
+        if (!isValidValue(value)) {
+            problems.push(`property '${key}' value contains characters outside printable ASCII (or ")`);
+        }
+        if (value.length > QUERY_METADATA_MAX_VALUE_LENGTH) {
+            problems.push(`property '${key}' value exceeds ${QUERY_METADATA_MAX_VALUE_LENGTH} characters`);
+        }
+    }
+    return problems;
+}
+/** Validate query metadata, throwing if the bag is invalid. */
+function validateQueryMetadata(meta) {
+    const problems = queryMetadataProblems(meta);
+    if (problems.length > 0) {
+        throw new Error(`Invalid query metadata: ${problems.join('; ')}`);
+    }
+}
+//# sourceMappingURL=query_metadata.js.map

package/dist/run_sql_options.d.ts

@@ -1,5 +1,12 @@
+import type { QueryMetadata } from './query_metadata';
 export interface RunSQLOptions {
     rowLimit?: number;
     abortSignal?: AbortSignal;
+    /**
+     * Optional per-query metadata (a small bag of string-valued properties)
+     * attached to the query for the backend's own bookkeeping — applied by the
+     * connector according to its capabilities. See {@link QueryMetadata}.
+     */
+    queryMetadata?: QueryMetadata;
 }
 export type QueryOptionsReader = RunSQLOptions | (() => RunSQLOptions);

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const MALLOY_VERSION = "0.0.425";
+export declare const MALLOY_VERSION = "0.0.426";

package/dist/version.js

@@ -2,5 +2,5 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MALLOY_VERSION = void 0;
 // generated with 'generate-version-file' script; do not edit manually
-exports.MALLOY_VERSION = '0.0.425';
+exports.MALLOY_VERSION = '0.0.426';
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@malloydata/malloy",
-  "version": "0.0.425",
+  "version": "0.0.426",
   "license": "MIT",
   "exports": {
     ".": "./dist/index.js",
@@ -51,9 +51,9 @@
     "generate-version-file": "VERSION=$(npm pkg get version --workspaces=false | tr -d \\\")\necho \"// generated with 'generate-version-file' script; do not edit manually\\nexport const MALLOY_VERSION = '$VERSION';\" > src/version.ts"
   },
   "dependencies": {
-    "@malloydata/malloy-filter": "0.0.425",
-    "@malloydata/malloy-interfaces": "0.0.425",
-    "@malloydata/malloy-tag": "0.0.425",
+    "@malloydata/malloy-filter": "0.0.426",
+    "@malloydata/malloy-interfaces": "0.0.426",
+    "@malloydata/malloy-tag": "0.0.426",
     "@noble/hashes": "^1.8.0",
     "antlr4ts": "^0.5.0-alpha.4",
     "assert": "^2.0.0",