@malloydata/malloy 0.0.435 → 0.0.436

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

@@ -2,7 +2,7 @@ import type { BuildIdOptions } from '../../model';
 import type { LogMessage } from '../../lang';
 import type { PersistNode } from '../../model/persist_utils';
 import type { Model, PersistSource } from './core';
-import type { ConnectionBuild } from './types';
+import type { BuildTargets } from './types';
 /**
  * A walk node with its source already resolved.
  *
@@ -47,9 +47,8 @@ export declare function resolvePersistWalk(model: Model, tagParseLog: LogMessage
  *
  * @param walk A resolved walk from {@link resolvePersistWalk}, in order
  * @param connectionDigests One digest per connection named by a persist source
- * @param buildIdOpts What the BuildID's SQL is compiled under. The compiler
- *   recomputes the same key at serve time through `buildIdOptions()`; supply a
- *   different `virtualMap` here and the table is built under a key nothing
- *   looks up.
+ * @param buildIdOpts What every BuildID's SQL is generated under.
+ *   `BuildTarget.buildSQL` generates its SQL under the same options, and
+ *   `persistedTableFor` recomputes the key under a query's.
  */
-export declare function mkBuildTargets(walk: ResolvedNode[], connectionDigests: Record<string, string>, buildIdOpts: BuildIdOptions): ConnectionBuild[];
+export declare function mkBuildTargets(walk: ResolvedNode[], connectionDigests: Record<string, string>, buildIdOpts: BuildIdOptions): Pick<BuildTargets, 'connections' | 'unbuildable'>;

package/dist/api/foundation/build_targets.js

@@ -6,6 +6,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolvePersistWalk = resolvePersistWalk;
 exports.mkBuildTargets = mkBuildTargets;
+const model_1 = require("../../model");
+const given_binding_1 = require("../../model/given_binding");
 /**
  * Read a key this function's own construction guarantees is present.
  *
@@ -38,6 +40,54 @@ function resolvePersistWalk(model, tagParseLog) {
     }
     return resolved;
 }
+/**
+ * Describes a given that `source` reads and this build has no value for.
+ * Names it by the name this model surfaces it under, since that is the name a
+ * builder supplies a value by: under `import { T is TENANT }` it is `T`.
+ */
+function unvaluedGivenProblem(source, use) {
+    var _a, _b, _c, _d, _e;
+    const modelDef = source._model._modelDef;
+    const surfaced = Object.entries(modelDef.contents).find(([, entry]) => entry.type === 'given' && entry.id === use.id);
+    const name = (_d = (_a = surfaced === null || surfaced === void 0 ? void 0 : surfaced[0]) !== null && _a !== void 0 ? _a : (_c = (_b = modelDef.givens) === null || _b === void 0 ? void 0 : _b[use.id]) === null || _c === void 0 ? void 0 : _c.name) !== null && _d !== void 0 ? _d : use.id;
+    return {
+        severity: 'error',
+        code: 'runtime-persist-given-no-value',
+        at: (_e = use.at) !== null && _e !== void 0 ? _e : source.location,
+        message: `Persisted source '${source.sourceID}' reads given '${name}', which ` +
+            `has no value in this build and no default. Supply '${name}' to the ` +
+            'build, or give it a default at its declaration.',
+    };
+}
+/**
+ * Generates the SQL that keys `source`'s table, or returns why no key can be
+ * computed. A `MalloyCompileError` is a problem with the source; any other
+ * error is the compiler's own and propagates.
+ */
+function buildIdSQL(source, opts) {
+    var _a;
+    const reads = (0, model_1.givenUsageOfRelation)(source._sourceDef);
+    const givens = source._model._modelDef.givens;
+    const unvalued = reads.find(use => (0, given_binding_1.lookupGivenValue)(opts.resolvedGivens, givens, use.id) === undefined);
+    if (unvalued !== undefined) {
+        return { problem: unvaluedGivenProblem(source, unvalued) };
+    }
+    try {
+        return { sql: source._compileSQL(opts), readsGivens: reads.length > 0 };
+    }
+    catch (e) {
+        if (!(e instanceof model_1.MalloyCompileError))
+            throw e;
+        return {
+            problem: {
+                message: e.message,
+                severity: 'error',
+                code: e.code,
+                at: (_a = e.at) !== null && _a !== void 0 ? _a : source.location,
+            },
+        };
+    }
+}
 /** A BuildID is a hex digest, so it cannot contain the separator. */
 function targetKey(connectionName, buildId) {
     return `${connectionName}:${buildId}`;
@@ -75,14 +125,14 @@ function addUnique(into, seen, keys) {
  *
  * @param walk A resolved walk from {@link resolvePersistWalk}, in order
  * @param connectionDigests One digest per connection named by a persist source
- * @param buildIdOpts What the BuildID's SQL is compiled under. The compiler
- *   recomputes the same key at serve time through `buildIdOptions()`; supply a
- *   different `virtualMap` here and the table is built under a key nothing
- *   looks up.
+ * @param buildIdOpts What every BuildID's SQL is generated under.
+ *   `BuildTarget.buildSQL` generates its SQL under the same options, and
+ *   `persistedTableFor` recomputes the key under a query's.
  */
 function mkBuildTargets(walk, connectionDigests, buildIdOpts) {
     var _a;
     const targets = new Map();
+    const unbuildable = [];
     // What each source hands to whoever referenced it: its own target if it is
     // one, otherwise whatever it was a route to.
     const contributes = new Map();
@@ -105,7 +155,15 @@ function mkBuildTargets(walk, connectionDigests, buildIdOpts) {
                 `BuildID of '${node.sourceID}'. Supply a digest for every connection ` +
                 'named by a persist source.');
         }
-        const sql = source.getSQL(buildIdOpts);
+        const keyed = buildIdSQL(source, buildIdOpts);
+        if ('problem' in keyed) {
+            // No key, so no table: pass its dependencies up as a route does.
+            // Whatever reads it inlines its SQL and ends up here too.
+            unbuildable.push({ source, problem: keyed.problem });
+            contributes.set(node.sourceID, childKeys);
+            continue;
+        }
+        const { sql, readsGivens } = keyed;
         const buildId = source.makeBuildId(digest, sql);
         const key = targetKey(connectionName, buildId);
         let target = targets.get(key);
@@ -114,6 +172,7 @@ function mkBuildTargets(walk, connectionDigests, buildIdOpts) {
                 buildId,
                 connectionName,
                 sql,
+                readsGivens,
                 sources: [],
                 dependsOn: new Set(),
             };
@@ -164,10 +223,19 @@ function mkBuildTargets(walk, connectionDigests, buildIdOpts) {
     // point both ways round a diamond.
     const built = new Map();
     for (const [key, partial] of targets) {
+        // Every source on a target compiles to the same SQL, so any of them can
+        // produce the build SQL; the manifest is the only thing the builder adds.
+        const [source] = partial.sources;
         built.set(key, {
             buildId: partial.buildId,
             connectionName: partial.connectionName,
             sql: partial.sql,
+            buildSQL: (manifest) => source._compileSQL({
+                ...buildIdOpts,
+                buildManifest: manifest,
+                connectionDigests,
+            }),
+            readsGivens: partial.readsGivens,
             sources: partial.sources,
             dependsOn: [],
         });
@@ -220,6 +288,6 @@ function mkBuildTargets(walk, connectionDigests, buildIdOpts) {
     for (const [connectionName, connectionTargets] of byConnection) {
         connections.push({ connectionName, targets: connectionTargets });
     }
-    return connections;
+    return { connections, unbuildable };
 }
 //# sourceMappingURL=build_targets.js.map

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

@@ -1,5 +1,5 @@
 import type { LogMessage } from '../../lang';
-import type { BuildID, CompiledQuery, ConstantExpr, DocumentLocation, BooleanFieldDef, JSONFieldDef, NumberFieldDef, StringFieldDef, FilterCondition, Given as InternalGiven, GivenID, GivenTypeDef, Query as InternalQuery, Pipeline, ModelDef, DocumentPosition as ModelDocumentPosition, NamedQueryDef, StructDef, TurtleDef, NativeUnsupportedFieldDef, ImportLocation, AnnotationsDef, ModelAnnotationEntry, ModelID, NamedModelObject, AtomicFieldDef, DateFieldDef, ATimestampFieldDef, SourceDef, Argument, SourceComponentInfo, DocumentReference, PersistableSourceDef } from '../../model';
+import type { BuildID, CompiledQuery, ConstantExpr, DocumentLocation, BooleanFieldDef, JSONFieldDef, NumberFieldDef, StringFieldDef, FilterCondition, Given as InternalGiven, GivenID, GivenTypeDef, Query as InternalQuery, Pipeline, ModelDef, DocumentPosition as ModelDocumentPosition, NamedQueryDef, StructDef, TurtleDef, NativeUnsupportedFieldDef, ImportLocation, AnnotationsDef, ModelAnnotationEntry, ModelID, NamedModelObject, AtomicFieldDef, DateFieldDef, ATimestampFieldDef, SourceDef, Argument, SourceComponentInfo, DocumentReference, PersistableSourceDef, PrepareResultOptions } from '../../model';
 import { QueryModel } from '../../model';
 import type { Dialect } from '../../dialect';
 import type { BuildGraph, CompileQueryOptions } from './types';
@@ -603,6 +603,8 @@ export declare class PersistSource implements Taggable {
      * @param connectionDigest - Digest from connection.getDigest()
      * @param sql - The SQL for this source (from getSQL())
      * @return The BuildID for manifest lookup
+     * @deprecated `BuildTarget.buildId` is already computed, under the build's
+     *   own givens and `virtualMap`. Used only with `Model.getBuildPlan`.
      */
     makeBuildId(connectionDigest: string, sql: string): BuildID;
     /**
@@ -613,12 +615,22 @@ export declare class PersistSource implements Taggable {
      *
      * @param options - Compile options. `buildManifest` and `connectionDigests`
      *   substitute already-built dependencies, giving the SQL to execute.
-     *   Anything that changes the SQL without them — `virtualMap` — must match
-     *   what the compiler will use, or the table is built under a key nothing
-     *   looks up.
      * @return The SQL string for this source.
+     * @deprecated Read `BuildTarget.sql` and call `BuildTarget.buildSQL()`. This
+     *   generates SQL under whatever `options` say, so it can disagree with the key
+     *   the build computed; the target's methods cannot. Used only with
+     *   `Model.getBuildPlan`.
      */
     getSQL(options?: CompileQueryOptions): string;
+    /**
+     * This source's SQL under `opts`: the bare `SELECT`, not finalized, because
+     * `persistedTableFor` hashes the same unfinalized SELECT to look the table
+     * up, and a dialect with a final stage (Postgres) would hash differently.
+     *
+     * @internal `opts` is whatever the caller passes; `BuildTarget.sql` and
+     *   `buildSQL()` pass the build's own.
+     */
+    _compileSQL(opts: PrepareResultOptions): string;
     /**
      * Get the underlying persistable source definition.
      */

package/dist/api/foundation/core.js

@@ -1347,6 +1347,8 @@ class PersistSource {
      * @param connectionDigest - Digest from connection.getDigest()
      * @param sql - The SQL for this source (from getSQL())
      * @return The BuildID for manifest lookup
+     * @deprecated `BuildTarget.buildId` is already computed, under the build's
+     *   own givens and `virtualMap`. Used only with `Model.getBuildPlan`.
      */
     makeBuildId(connectionDigest, sql) {
         return (0, source_def_utils_1.mkBuildID)(connectionDigest, sql);
@@ -1359,26 +1361,33 @@ class PersistSource {
      *
      * @param options - Compile options. `buildManifest` and `connectionDigests`
      *   substitute already-built dependencies, giving the SQL to execute.
-     *   Anything that changes the SQL without them — `virtualMap` — must match
-     *   what the compiler will use, or the table is built under a key nothing
-     *   looks up.
      * @return The SQL string for this source.
+     * @deprecated Read `BuildTarget.sql` and call `BuildTarget.buildSQL()`. This
+     *   generates SQL under whatever `options` say, so it can disagree with the key
+     *   the build computed; the target's methods cannot. Used only with
+     *   `Model.getBuildPlan`.
      */
     getSQL(options) {
+        return this._compileSQL({
+            ...options,
+            resolvedGivens: (0, given_binding_1.bindGivens)(options === null || options === void 0 ? void 0 : options.givens, this.model._modelDef),
+        });
+    }
+    /**
+     * This source's SQL under `opts`: the bare `SELECT`, not finalized, because
+     * `persistedTableFor` hashes the same unfinalized SELECT to look the table
+     * up, and a dialect with a final stage (Postgres) would hash differently.
+     *
+     * @internal `opts` is whatever the caller passes; `BuildTarget.sql` and
+     *   `buildSQL()` pass the build's own.
+     */
+    _compileSQL(opts) {
         const sd = this.persistableDef;
         const queryModel = this.model.queryModel;
-        // Compile with finalize=false so this SQL is the bare source SELECT.
-        // The build-time key (makeBuildId over this SQL) must equal the serve-time
-        // manifest lookup key, which persistedTableFor recomputes from the same
-        // unfinalized SELECT; finalizing would diverge the two on dialects with a
-        // final stage (Postgres) and mis-materialize the table.
         if (sd.type === 'sql_select') {
-            return (0, model_1.getCompiledSQL)(sd, options !== null && options !== void 0 ? options : {}, (query, opts) => queryModel.compileQuery(query, opts, false).sql);
-        }
-        else {
-            const compiled = queryModel.compileQuery(sd.query, options, false);
-            return compiled.sql;
+            return (0, model_1.getCompiledSQL)(sd, opts, (query, o) => queryModel.compileQuery(query, o, false).sql);
         }
+        return queryModel.compileQuery(sd.query, opts, false).sql;
     }
     /**
      * Get the underlying persistable source definition.
@@ -1503,18 +1512,9 @@ class PreparedQuery extends PipelineBase {
      */
     getPreparedResult(options) {
         const queryModel = this._model.queryModel;
-        // Build the resolved-givens map in two phases:
-        //   1. caller-supplied values (resolveSuppliedGivens)
-        //   2. inline-given defaults eager-evaluated against the map
-        // Result is undefined when no values land — preserves the previous
-        // "no givens path" downstream.
-        const resolved = (options === null || options === void 0 ? void 0 : options.givens)
-            ? (0, given_binding_1.resolveSuppliedGivens)(options.givens, this._modelDef)
-            : new Map();
-        (0, given_binding_1.evaluateInlineGivens)(resolved, this._modelDef);
         const prepareResultOptions = {
             ...options,
-            resolvedGivens: resolved.size > 0 ? resolved : undefined,
+            resolvedGivens: (0, given_binding_1.bindGivens)(options === null || options === void 0 ? void 0 : options.givens, this._modelDef),
         };
         const translatedQuery = queryModel.compileQuery(this._query, prepareResultOptions);
         return new PreparedResult({

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

@@ -1,4 +1,4 @@
-export type { Taggable, Loggable, ParseOptions, CompileOptions, CompileQueryOptions, BuildNode, BuildGraph, BuildTarget, BuildTargets, ConnectionBuild, } from './types';
+export type { Taggable, Loggable, ParseOptions, CompileOptions, CompileQueryOptions, BuildNode, BuildGraph, BuildTarget, BuildTargetOptions, BuildTargets, ConnectionBuild, UnbuildableSource, } from './types';
 export { EMPTY_BUILD_MANIFEST } from './types';
 export { EmptyURLReader, InMemoryURLReader, FixedConnectionMap, hashForInvalidationKey, isInternalURL, readURL, getInvalidationKey, } from './readers';
 export type { ModelCache, CachedModel } from './cache';

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

@@ -6,7 +6,7 @@ import type { Dialect } from '../../dialect';
 import type { RunSQLOptions } from '../../run_sql_options';
 import type { CacheManager } from './cache';
 import type { MalloyConfig } from './config';
-import type { ParseOptions, CompileOptions, CompileQueryOptions, BuildTargets } from './types';
+import type { ParseOptions, CompileOptions, CompileQueryOptions, BuildTargets, BuildTargetOptions } from './types';
 import type { PreparedResult, Explore } from './core';
 import { Model, PreparedQuery } from './core';
 import type { DataRecord, Result } from './result';
@@ -102,6 +102,18 @@ export declare class Runtime {
      * the cached promise.
      */
     getGivens(): Promise<ReadonlyMap<string, GivenValue>>;
+    /**
+     * The given values one compile runs under: the config file's, then the
+     * constructor's, then `perCall`, each winning per key over the one before.
+     * Undefined when no layer supplies anything.
+     *
+     * A per-call value for a finalized given is refused before anything else
+     * happens: finalizing means the Runtime decides, and that holds for a build
+     * as it does for a query.
+     *
+     * @internal Accessed from QueryMaterializer and getBuildTargets.
+     */
+    _givensFor(perCall: Record<string, GivenValue> | undefined): Promise<Record<string, GivenValue> | undefined>;
     /**
      * Surface names of givens locked at the runtime layer (the resolved set
      * the `config.finalizeGivens` directive produced). Per-query supply for
@@ -292,10 +304,17 @@ export declare class Runtime {
      * in dependency order and each carries its own `dependsOn`. See
      * {@link BuildTargets}.
      *
+     * The build generates SQL under this Runtime's givens and `virtualMap`, with
+     * `options` layered over them, exactly as a query would; a persisted table
+     * is therefore found by the queries that run under the same values. A
+     * source whose SQL needs a value this build does not have is reported in
+     * `unbuildable`, not thrown.
+     *
      * @param model A compiled model with `##! experimental.persistence`
+     * @param options Given values and a `virtualMap` for this build
      * @return The targets to build, with any annotation parse messages
      */
-    getBuildTargets(model: Model): Promise<BuildTargets>;
+    getBuildTargets(model: Model, options?: BuildTargetOptions): Promise<BuildTargets>;
 }
 export declare class ConnectionRuntime extends Runtime {
     readonly rawConnections: Connection[];

package/dist/api/foundation/runtime.js

@@ -6,6 +6,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ExploreMaterializer = exports.PreparedResultMaterializer = exports.QueryMaterializer = exports.ModelMaterializer = exports.SingleConnectionRuntime = exports.ConnectionRuntime = exports.Runtime = void 0;
 const model_1 = require("../../model");
+const given_binding_1 = require("../../model/given_binding");
 const dialect_1 = require("../../dialect");
 const validate_table_path_1 = require("../../connection/validate_table_path");
 const config_1 = require("./config");
@@ -141,6 +142,33 @@ class Runtime {
             merged.set(k, v);
         return merged;
     }
+    /**
+     * The given values one compile runs under: the config file's, then the
+     * constructor's, then `perCall`, each winning per key over the one before.
+     * Undefined when no layer supplies anything.
+     *
+     * A per-call value for a finalized given is refused before anything else
+     * happens: finalizing means the Runtime decides, and that holds for a build
+     * as it does for a query.
+     *
+     * @internal Accessed from QueryMaterializer and getBuildTargets.
+     */
+    async _givensFor(perCall) {
+        if (this._finalizedGivensSet.size > 0 && perCall) {
+            for (const name of Object.keys(perCall)) {
+                if (this._finalizedGivensSet.has(name)) {
+                    throw new model_1.MalloyCompileError(`Cannot supply given '${name}' per call: it is finalized at ` +
+                        'the runtime layer via `config.finalizeGivens`.', 'runtime-given-finalized', undefined);
+                }
+            }
+        }
+        const fileGivens = await this._resolveGivens();
+        const constructorGivens = mapToRecord(this._constructorGivensMap);
+        const haveAny = fileGivens || constructorGivens || perCall;
+        return haveAny
+            ? { ...fileGivens, ...constructorGivens, ...perCall }
+            : undefined;
+    }
     /**
      * Surface names of givens locked at the runtime layer (the resolved set
      * the `config.finalizeGivens` directive produced). Per-query supply for
@@ -481,10 +509,18 @@ class Runtime {
      * in dependency order and each carries its own `dependsOn`. See
      * {@link BuildTargets}.
      *
+     * The build generates SQL under this Runtime's givens and `virtualMap`, with
+     * `options` layered over them, exactly as a query would; a persisted table
+     * is therefore found by the queries that run under the same values. A
+     * source whose SQL needs a value this build does not have is reported in
+     * `unbuildable`, not thrown.
+     *
      * @param model A compiled model with `##! experimental.persistence`
+     * @param options Given values and a `virtualMap` for this build
      * @return The targets to build, with any annotation parse messages
      */
-    async getBuildTargets(model) {
+    async getBuildTargets(model, options) {
+        var _a;
         const tagParseLog = [];
         const walk = (0, build_targets_1.resolvePersistWalk)(model, tagParseLog);
         const connectionDigests = (0, model_1.mkSafeRecord)();
@@ -497,12 +533,12 @@ class Runtime {
                 connectionDigests[connectionName] = connection.getDigest();
             }
         }
-        return {
-            connections: (0, build_targets_1.mkBuildTargets)(walk, connectionDigests, {
-                virtualMap: this.virtualMap,
-            }),
-            tagParseLog,
-        };
+        const givens = await this._givensFor(options === null || options === void 0 ? void 0 : options.givens);
+        const { connections, unbuildable } = (0, build_targets_1.mkBuildTargets)(walk, connectionDigests, {
+            virtualMap: (_a = options === null || options === void 0 ? void 0 : options.virtualMap) !== null && _a !== void 0 ? _a : this.virtualMap,
+            resolvedGivens: (0, given_binding_1.bindGivens)(givens, model._modelDef),
+        });
+        return { connections, tagParseLog, unbuildable };
     }
 }
 exports.Runtime = Runtime;
@@ -1045,31 +1081,8 @@ class QueryMaterializer extends FluentState {
                 }
             }
             const virtualMap = (_b = mergedOptions.virtualMap) !== null && _b !== void 0 ? _b : this.runtime.virtualMap;
-            // Per-query supply for a finalized given is rejected at API entry
-            // — the finalized-givens set is the runtime's "this can't be
-            // overridden by the caller" guarantee. Fail before any IO so misuse
-            // is loud.
+            const mergedGivens = await this.runtime._givensFor(mergedOptions.givens);
             const finalizedSet = this.runtime._finalizedGivens;
-            if (finalizedSet.size > 0 && mergedOptions.givens) {
-                for (const name of Object.keys(mergedOptions.givens)) {
-                    if (finalizedSet.has(name)) {
-                        throw new model_1.MalloyCompileError(`Cannot supply given '${name}' per-query: it is finalized at ` +
-                            'the runtime layer via `config.finalizeGivens`.', 'runtime-given-finalized', undefined);
-                    }
-                }
-            }
-            // Three layers of givens, merged per-key in precedence order:
-            //   1. config.givensURL file (lazy + cached)
-            //   2. Runtime constructor `givens:` option
-            //   3. Per-query supply via `.run({givens: ...})`
-            // Higher-numbered layers win on collision. Each layer is optional;
-            // the merge collapses to undefined when all three are absent.
-            const fileGivens = await this.runtime._resolveGivens();
-            const constructorGivens = mapToRecord(this.runtime._constructorGivens);
-            const haveAny = fileGivens || constructorGivens || mergedOptions.givens;
-            const mergedGivens = haveAny
-                ? { ...fileGivens, ...constructorGivens, ...mergedOptions.givens }
-                : undefined;
             // Query-scoped validation: of the givens THIS query references,
             // any that are finalized must have a value somewhere (file or
             // constructor). One config covers a project; individual files

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

@@ -107,11 +107,23 @@ export interface BuildTarget {
      * The SQL the BuildID is computed from: fully inlined, no manifest
      * substitution, so it is the same string whatever else has been built.
      *
-     * It is not the SQL to execute. That one substitutes the tables built so far
-     * — `source.getSQL({buildManifest, connectionDigests})` — so it can only be
-     * computed as the build walks, and only by the builder holding the manifest.
+     * It is not the SQL to execute; that is {@link buildSQL}.
      */
     sql: string;
+    /**
+     * The SQL to execute, for a `CREATE TABLE`. Dependencies already in
+     * `manifest` are read from their tables rather than recomputed, which is
+     * why it is a call made as the build proceeds and not a string computed up
+     * front. Generated under the same givens and `virtualMap` as `sql`, so the
+     * table that is built is the one the key describes.
+     */
+    buildSQL(manifest: BuildManifest): string;
+    /**
+     * True when the SQL reads a given, supplied or defaulted. The table is then
+     * one of possibly several for this source, one per value, and a builder
+     * naming it by `name=` alone would build every variant under one name.
+     */
+    readsGivens: boolean;
     /** Targets that must exist before this one can be built */
     dependsOn: BuildTarget[];
     /** Every persist source in the model that maps onto this artifact */
@@ -152,6 +164,32 @@ export interface ConnectionBuild {
     /** Every table to build, dependencies before dependents */
     targets: BuildTarget[];
 }
+/**
+ * A persist source with no BuildID, because its SQL cannot be written: it
+ * reads a given that has no value in this build, a virtual source the build's
+ * `virtualMap` has no entry for, or anything else the compiler reports as a
+ * problem with the source rather than with itself. A source that reads it
+ * inlines its SQL, so is reported here too.
+ */
+export interface UnbuildableSource {
+    source: PersistSource;
+    /** Why no BuildID could be computed, as a query would report it */
+    problem: LogMessage;
+}
+/**
+ * What a build generates SQL under, over the Runtime's own values.
+ *
+ * `givens` layers over the Runtime's file and constructor givens the way a
+ * query's do, and a finalized given is refused here the same way. Running
+ * `getBuildTargets` once per set of values is how a model whose persisted
+ * sources read a given gets one table per value.
+ */
+export interface BuildTargetOptions {
+    /** Given values for this build, by surface name, over the Runtime's */
+    givens?: Record<string, GivenValue>;
+    /** Which table each virtual source reads; the Runtime's when omitted */
+    virtualMap?: VirtualMap;
+}
 /**
  * The build schedule for a model.
  *
@@ -165,4 +203,6 @@ export interface BuildTargets {
     connections: ConnectionBuild[];
     /** Errors and warnings from parsing `#@` annotations on persistable sources */
     tagParseLog: LogMessage[];
+    /** Persist sources with no table to build, each with the reason */
+    unbuildable: UnbuildableSource[];
 }

package/dist/connection/dbmeta.d.ts

@@ -0,0 +1,29 @@
+import type { AnnotationsDef } from '../model/malloy_types';
+import type { ConnectionPropertyDefinition } from './registry';
+/**
+ * The annotation route a connection writes database metadata to:
+ * `#(dbmeta) description="..."`.
+ */
+export declare const DBMETA_ROUTE = "dbmeta";
+/**
+ * The connection property that turns on database metadata. Connections that
+ * support it register this definition, so the option has the same name and
+ * meaning on every backend. Off unless set.
+ */
+export declare const dbmetaProperty: ConnectionPropertyDefinition;
+/**
+ * Metadata a connection read from the database for one table or column.
+ * Keys are normalized across databases: whatever a database calls it (a
+ * description, a COMMENT), it arrives here as `description`.
+ */
+export interface DbMeta {
+    description?: string | null;
+}
+/**
+ * The `#(dbmeta)` annotation for a table or column, as a fragment to spread
+ * into its field or table def: `{annotations}`, or `{}` when there is nothing
+ * to say.
+ */
+export declare function dbmetaAnnotations(meta: DbMeta): {
+    annotations?: AnnotationsDef;
+};

package/dist/connection/dbmeta.js

@@ -0,0 +1,46 @@
+"use strict";
+/*
+ * Copyright Contributors to the Malloy project
+ * SPDX-License-Identifier: MIT
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dbmetaProperty = exports.DBMETA_ROUTE = void 0;
+exports.dbmetaAnnotations = dbmetaAnnotations;
+const malloy_tag_1 = require("@malloydata/malloy-tag");
+/**
+ * The annotation route a connection writes database metadata to:
+ * `#(dbmeta) description="..."`.
+ */
+exports.DBMETA_ROUTE = 'dbmeta';
+const DBMETA_LOCATION = {
+    url: `internal://${exports.DBMETA_ROUTE}`,
+    range: { start: { line: 0, character: 0 }, end: { line: 0, character: 0 } },
+};
+/**
+ * The connection property that turns on database metadata. Connections that
+ * support it register this definition, so the option has the same name and
+ * meaning on every backend. Off unless set.
+ */
+exports.dbmetaProperty = {
+    name: 'dbmeta',
+    displayName: 'Database Metadata',
+    type: 'boolean',
+    optional: true,
+    advanced: true,
+    description: 'Copy table and column descriptions from the database onto the schema, ' +
+        'as #(dbmeta) description annotations.',
+};
+/**
+ * The `#(dbmeta)` annotation for a table or column, as a fragment to spread
+ * into its field or table def: `{annotations}`, or `{}` when there is nothing
+ * to say.
+ */
+function dbmetaAnnotations(meta) {
+    var _a;
+    const description = (_a = meta.description) === null || _a === void 0 ? void 0 : _a.trim();
+    if (!description)
+        return {};
+    const text = `#(${exports.DBMETA_ROUTE}) description=${(0, malloy_tag_1.quoteString)(description)}\n`;
+    return { annotations: { notes: [{ text, at: DBMETA_LOCATION }] } };
+}
+//# sourceMappingURL=dbmeta.js.map

package/dist/connection/index.d.ts

@@ -1,3 +1,4 @@
 export * from './types';
 export * from './base_connection';
 export * from './registry';
+export * from './dbmeta';

package/dist/connection/index.js

@@ -17,4 +17,5 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./types"), exports);
 __exportStar(require("./base_connection"), exports);
 __exportStar(require("./registry"), exports);
+__exportStar(require("./dbmeta"), exports);
 //# sourceMappingURL=index.js.map

package/dist/dialect/databricks/databricks.d.ts

@@ -1,5 +1,5 @@
-import type { Sampling, MeasureTimeExpr, RegexMatchExpr, TimeExtractExpr, TypecastExpr, BasicAtomicTypeDef, AtomicTypeDef, ArrayLiteralNode, RecordLiteralNode } from '../../model/malloy_types';
-import type { BooleanTypeSupport, CompiledOrderBy, DialectFieldList, FieldReferenceType, LateralJoinExpression, OrderByClauseType, OrderByRequest, QueryInfo } from '../dialect';
+import type { Sampling, MeasureTimeExpr, RegexMatchExpr, TypecastExpr, BasicAtomicTypeDef, AtomicTypeDef, ArrayLiteralNode, RecordLiteralNode, ATimestampTypeDef, TimestampUnit, ExtractUnit } from '../../model/malloy_types';
+import type { CivilTime, BooleanTypeSupport, CompiledOrderBy, DialectFieldList, FieldReferenceType, LateralJoinExpression, OrderByClauseType, OrderByRequest, QueryInfo } from '../dialect';
 import { Dialect } from '../dialect';
 import type { DialectFunctionOverloadDef } from '../functions';
 export declare class DatabricksDialect extends Dialect {
@@ -66,18 +66,17 @@ export declare class DatabricksDialect extends Dialect {
     sqlSelectAliasAsStruct(alias: string, fieldList: DialectFieldList): string;
     sqlCreateTableAsSelect(tableName: string, sql: string): string;
     sqlNowExpr(): string;
-    sqlConvertToCivilTime(expr: string, timezone: string, _typeDef: AtomicTypeDef): {
-        sql: string;
-        typeDef: AtomicTypeDef;
-    };
-    sqlConvertFromCivilTime(expr: string, timezone: string, _destTypeDef: AtomicTypeDef): string;
-    sqlTruncate(expr: string, unit: string, _typeDef: AtomicTypeDef, _inCivilTime: boolean, _timezone?: string): string;
-    sqlOffsetTime(expr: string, op: '+' | '-', magnitude: string, unit: string, _typeDef: AtomicTypeDef, _inCivilTime: boolean, _timezone?: string): string;
-    sqlTimeExtractExpr(qi: QueryInfo, te: TimeExtractExpr): string;
-    sqlCast(qi: QueryInfo, cast: TypecastExpr): string;
+    sqlConvertToCivilTime(expr: string, timezone: string, _typeDef: ATimestampTypeDef): string;
+    sqlConvertFromCivilTime(expr: string, timezone: string, _destTypeDef: ATimestampTypeDef): string;
+    sqlTruncate(expr: string, unit: TimestampUnit, _civilType: CivilTime): string;
+    sqlOffsetTime(expr: string, op: '+' | '-', magnitude: string, unit: TimestampUnit, _civilType: CivilTime): string;
+    sqlCivilExtract(expr: string, units: ExtractUnit, _civilType: CivilTime): string;
+    sqlCivilToDate(expr: string): string;
+    sqlDateToCivil(expr: string): string;
+    sqlCast(_qi: QueryInfo, cast: TypecastExpr): string;
     sqlRegexpMatch(df: RegexMatchExpr): string;
     sqlDateLiteral(_qi: QueryInfo, literal: string): string;
-    sqlTimestampLiteral(qi: QueryInfo, literal: string, timezone: string | undefined): string;
+    sqlCivilLiteral(literal: string): string;
     sqlTimestamptzLiteral(_qi: QueryInfo, _literal: string, _timezone: string): string;
     sqlMeasureTimeExpr(df: MeasureTimeExpr): string;
     sqlSampleTable(tableSQL: string, sample: Sampling | undefined): string;