@google-cloud/kcmd 0.0.0-stage → 0.1.0

package/build/ts/kcmd/semantic/source_dialect.d.ts

@@ -0,0 +1,10 @@
+import { EntryLookup } from './catalog_entry';
+export interface SourceDialects {
+    dialects: Map<string, string>;
+    databases: Map<string, string>;
+    errors: string[];
+}
+export declare function sourceDialects(texts: Iterable<string>, catalog: EntryLookup, { thirdParty }?: {
+    thirdParty?: boolean | undefined;
+}): Promise<SourceDialects>;
+export declare function sourcesToLookUp(texts: Iterable<string>): string[];

package/build/ts/kcmd/semantic/source_dialect.js

@@ -0,0 +1,261 @@
+"use strict";
+// The dialect of a Cloud SQL table written as its resource name, or of a
+// third-party table written as its entry name, read from the table's
+// Knowledge Catalog entry.
+//
+// The resource name cannot say the dialect: a MySQL table has no schema, but a
+// PostgreSQL table and a SQL Server table have the same shape. Dataplex keeps an
+// entry for each table of an instance with Dataplex integration on, in the
+// system entry group `@cloudsql`, and the entry's id is the table's resource
+// name. Its entry type names the engine.
+//
+// A third-party table's entry names its system twice: in the prefix of its
+// fullyQualifiedName, which Dataplex checks, and in entrySource.system, which
+// is free text. So the prefix decides, and the system only when the entry has
+// no fullyQualifiedName. Dataplex also checks the rest of the
+// fullyQualifiedName, so its parts say whether the entry is a table's or, for
+// example, a schema's.
+//
+// This is the only place kcmd makes a network call to learn a dialect. A
+// command looks every such source up once, before it loads the model, and
+// passes the dialects to the load (LoadOptions.sourceDialects).
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sourceDialects = sourceDialects;
+exports.sourcesToLookUp = sourcesToLookUp;
+const yaml = __importStar(require("yaml"));
+const loader_1 = require("./loader");
+const catalog_entry_1 = require("./catalog_entry");
+const yaml_options_1 = require("./yaml_options");
+// The dialect each entrySource.system gives, in lower case.
+const DIALECT_OF_ENTRY_SYSTEM = new Map([...loader_1.DIALECT_OF_FQN_PREFIX, ['postgres', 'POSTGRES']]);
+// The parts of a table's fullyQualifiedName after each prefix, as Dataplex
+// reads it. A view's name has the same parts as a table's.
+const TABLE_FQN_PARTS = new Map([
+    ['snowflake', ['account', 'database', 'schema', 'table']],
+    ['databricks', ['metastore', 'catalog', 'schema', 'table']],
+    ['mysql', ['host', 'schema', 'table']],
+    ['postgresql', ['host', 'database', 'schema', 'table']],
+    ['sqlserver', ['host', 'database', 'schema', 'table']],
+]);
+// Looks up the dialect of every Cloud SQL and third-party table the model and
+// profile files `texts` write (see sourcesToLookUp), once per table, in
+// parallel. With `thirdParty` false, looks up Cloud SQL tables only. Makes no
+// call when they write none. Never throws: a lookup that fails is reported in
+// `errors`.
+async function sourceDialects(texts, catalog, { thirdParty = true } = {}) {
+    // Keyed as dialectLookupKey gives, so both spellings of one table are one
+    // lookup.
+    const lookups = new Map();
+    for (const source of sourcesToLookUp(texts)) {
+        const table = (0, loader_1.cloudSqlTableOf)(source);
+        if (table) {
+            lookups.set(table.resourceName, () => cloudSqlDialect(catalog, table));
+        }
+        const entry = thirdParty ? (0, loader_1.thirdPartyEntryOf)(source) : undefined;
+        if (entry)
+            lookups.set(entry.name, () => thirdPartyDialect(catalog, entry));
+    }
+    const dialects = new Map();
+    const databases = new Map();
+    const errors = [];
+    await Promise.all([...lookups].map(async ([key, lookUp]) => {
+        const got = await lookUp();
+        if ('error' in got)
+            errors.push(got.error);
+        else
+            dialects.set(key, got.dialect);
+        if ('database' in got && got.database)
+            databases.set(key, got.database);
+    }));
+    errors.sort();
+    return { dialects, databases, errors };
+}
+// The dialect of a Cloud SQL table, by its entry's type.
+async function cloudSqlDialect(catalog, table) {
+    const at = `source '${table.resourceName}'`;
+    const res = await (0, catalog_entry_1.lookupSystemEntry)(catalog, 'cloudsql', table.project, table.location, table.resourceName);
+    if ('error' in res)
+        return { error: `${at}: ${res.error}` };
+    // Dataplex answers 403 both when the entry does not exist and when the
+    // caller may not read it, so the message names both causes.
+    if ('unreadable' in res) {
+        return {
+            error: `${at}: kcmd reads a Cloud SQL table's dialect from its ` +
+                `Knowledge Catalog entry, and could not read it. Turn on Dataplex ` +
+                `integration for instance '${table.instance}' (gcloud sql ` +
+                `instances patch ${table.instance} --enable-dataplex-integration ` +
+                `--project ${table.project}) and wait for the table to appear in ` +
+                `the catalog, or check that you can read the table. If integration ` +
+                `is on, check the name: the project ID, the instance's region, and ` +
+                `a schema only for PostgreSQL and SQL Server.`,
+        };
+    }
+    // The type comes back as a full name; its last part says the engine.
+    const type = (res.result.entryType ?? '').split('/').pop() ?? '';
+    const dialect = loader_1.DIALECT_OF_ENTRY_TYPE[type];
+    return dialect ? { dialect } : {
+        error: `${at}: its Knowledge Catalog entry has type '${type}', which is ` +
+            `not a Cloud SQL table or view type kcmd knows (${Object.keys(loader_1.DIALECT_OF_ENTRY_TYPE).join(', ')}).`,
+    };
+}
+// The dialect of a third-party table, by its entry's fullyQualifiedName or
+// entrySource.system, and the database the fullyQualifiedName names. An entry
+// whose fullyQualifiedName names no table or view is rejected.
+async function thirdPartyDialect(catalog, { project, location, name }) {
+    const at = `source '${name}'`;
+    const res = await (0, catalog_entry_1.read)('looking up its Knowledge Catalog entry', () => catalog.lookupEntry(project, location, name));
+    if ('error' in res)
+        return { error: `${at}: ${res.error}` };
+    if ('unreadable' in res) {
+        return {
+            error: `${at} names no table Knowledge Catalog knows about. The entry ` +
+                `may not exist, or you may not be allowed to read it. kcmd reads a ` +
+                `third-party table's dialect from its entry, so add the table to ` +
+                `Knowledge Catalog, or fix the source.`,
+        };
+    }
+    const { fullyQualifiedName: fqn, entrySource } = res.result;
+    const system = entrySource?.system;
+    const prefix = fqn?.match(/^([a-z]+):/)?.[1] ?? '';
+    const dialect = fqn ? loader_1.DIALECT_OF_FQN_PREFIX.get(prefix) :
+        DIALECT_OF_ENTRY_SYSTEM.get(system?.toLowerCase() ?? '');
+    if (dialect && fqn) {
+        const database = databaseOfFqn(fqn);
+        if (database)
+            return { dialect, database };
+        const parts = TABLE_FQN_PARTS.get(prefix).map(p => `<${p}>`).join('.');
+        return {
+            error: `${at}: its Knowledge Catalog entry has fullyQualifiedName ` +
+                `'${fqn}', which names no table or view. A table's ` +
+                `fullyQualifiedName has the form ${prefix}:${parts}. Write the ` +
+                `entry name of the table's own entry.`,
+        };
+    }
+    if (dialect)
+        return { dialect };
+    const has = fqn ? `fullyQualifiedName '${fqn}'` :
+        system ? `entrySource.system '${system}' and no fullyQualifiedName` :
+            'neither a fullyQualifiedName nor an entrySource.system';
+    return {
+        error: `${at}: kcmd cannot tell the table's SQL dialect from its ` +
+            `Knowledge Catalog entry, which has ${has}. kcmd reads the prefix of ` +
+            `the entry's fullyQualifiedName (snowflake:, databricks:, mysql:, ` +
+            `postgresql: or sqlserver:), or entrySource.system when there is no ` +
+            `fullyQualifiedName.`,
+    };
+}
+// The database the fullyQualifiedName `fqn` of a third-party table or view
+// names: a Snowflake account, a MySQL or SQL Server host, a PostgreSQL host
+// and database, or a Databricks metastore. Each account and host is in lower
+// case. Undefined when `fqn` names no table or view. Such a name has another
+// number of parts than TABLE_FQN_PARTS gives, or a subtype, such as the
+// `routine:` of a routine. Dataplex reads a `databricks:table:` or
+// `databricks:view:` name as the same table as the `databricks:` name.
+function databaseOfFqn(fqn) {
+    // The subtype holds no backtick, so a colon inside a quoted host and port
+    // stays in the path. A colon in an unquoted database, schema or table
+    // name stays in its segment when it comes after the name's first backtick.
+    const [, prefix, subtype, path] = fqn.match(/^([a-z]+):(?:([a-z0-9_-]+):)?(.*)$/s) ?? [];
+    const parts = TABLE_FQN_PARTS.get(prefix ?? '');
+    const seg = (0, loader_1.catalogNameSegments)(path ?? '', true);
+    const tableSubtype = subtype === undefined ||
+        (prefix === 'databricks' && (subtype === 'table' || subtype === 'view'));
+    if (!parts || !tableSubtype || seg.length !== parts.length)
+        return undefined;
+    const n = prefix === 'postgresql' ? 2 : 1;
+    // A Snowflake account and a host name ignore letter case.
+    if (prefix !== 'databricks')
+        seg[0] = seg[0].toLowerCase();
+    return [prefix, ...seg.slice(0, n)].join('/');
+}
+// Every Cloud SQL table and third-party entry the model and profile files
+// `texts` write. A Cloud SQL table counts as a resource name or resource URI
+// anywhere, JSON strings included. An entry name counts as a `source` value in
+// the YAML or in a GOOGLE block's JSON `data`, unless it sits in ai_context,
+// an action parameter's default or another vendor's block. Values are read
+// from the parsed YAML, so a name in a comment is not collected. A file that
+// does not parse collects nothing; the load reports it.
+function sourcesToLookUp(texts) {
+    const found = new Set();
+    // `key` names the member that holds `value`. `opaque` marks a value whose
+    // `source` names no table: one inside ai_context, an action parameter's
+    // default or another vendor's block, or in JSON written anywhere but a
+    // `data` member.
+    const visit = (value, key, opaque = false) => {
+        if (typeof value === 'string') {
+            if ((0, loader_1.cloudSqlTableOf)(value) ||
+                (key === 'source' && !opaque && (0, loader_1.thirdPartyEntryOf)(value))) {
+                found.add(value.trim());
+            }
+            else if (/^\s*[[{]/.test(value)) {
+                try {
+                    visit(JSON.parse(value), undefined, opaque || key !== 'data');
+                }
+                catch {
+                    // Not JSON: an ordinary string.
+                }
+            }
+        }
+        else if (Array.isArray(value)) {
+            value.forEach(v => visit(v, undefined, opaque));
+        }
+        else if (value && typeof value === 'object') {
+            const vendor = 'vendor_name' in value && !(0, loader_1.isGoogleVendor)(value.vendor_name);
+            for (const [k, v] of Object.entries(value)) {
+                visit(v, k, opaque || vendor || k === 'ai_context' || k === 'default');
+            }
+        }
+    };
+    for (const text of texts) {
+        // Parsed as the loader parses, so both read the same values.
+        for (const doc of yaml.parseAllDocuments(text, yaml_options_1.YAML_OPTIONS)) {
+            if (doc.errors.length)
+                continue;
+            // Reading the values can still fail: on an alias whose anchor is not
+            // set, on more aliases than a load expands, or, while walking them, on
+            // an alias that refers to itself, which makes the values cyclic. The
+            // load reports that file in its own words, so the rest of it is skipped
+            // here rather than stopping the command.
+            try {
+                visit(doc.toJS());
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    return [...found];
+}

package/build/ts/kcmd/semantic/source_entries.d.ts

@@ -0,0 +1,12 @@
+import type { BigLakeClient } from '../gcp/biglake';
+import type { BigQueryClient } from '../gcp/bigquery';
+import type { SpannerClient } from '../gcp/spanner';
+import { EntryLookup } from './catalog_entry';
+import type { SemanticModel } from './ir';
+export interface SourceReaders {
+    catalog: EntryLookup;
+    bigquery: Pick<BigQueryClient, 'getTable'>;
+    biglake: Pick<BigLakeClient, 'getCatalog'>;
+    spanner: Pick<SpannerClient, 'getInstance' | 'getInstanceConfig'>;
+}
+export declare function sourceEntryErrors(model: Pick<SemanticModel, 'name' | 'entities' | 'profiles'>, readers: SourceReaders): Promise<string[]>;

package/build/ts/kcmd/semantic/source_entries.js

@@ -0,0 +1,282 @@
+"use strict";
+// Checks that Knowledge Catalog has an entry for every table a push reads
+// (b/568769073), so a source that names no table stops the push before it
+// writes anything. The same reads find each profile whose BigQuery and
+// BigLake tables share no location (b/578688979).
+//
+// Each first-party table's entry sits in its system's entry group, with its
+// resource name as the entry id, in the table's own location:
+//
+// - BigQuery: the table's location, which getTable reads, such as `US`. The
+//   table read needs only access to the table, not to its dataset.
+// - BigLake: the region of one of the catalog's replicas, which getCatalog
+//   reads: `us-central1` for a regional catalog. A federated catalog lists
+//   one replica, such as `US`, with no state. A US catalog of Cloud Storage
+//   tables keeps a table's entry in the region that was its primary when the
+//   table was created, so after a failover an older table's entry can sit in
+//   a former primary's region, now a secondary's. The entry is looked up in
+//   each replica's region, the primary's first, until one finds it.
+// - Spanner: the default leader region of the instance's config, which
+//   getInstance reads the config's name from. A regional config is named for
+//   its region, `regional-us-central1` for us-central1, so it is not read;
+//   any other config is, with getInstanceConfig: `nam3` gives us-east4. That
+//   read needs spanner.instanceConfigs.get, which the Spanner database roles
+//   lack. A database's own default leader does not move the entry.
+// - AlloyDB: the location the source names.
+//
+// Dataplex keeps locations in lower case. A lookup in the wrong location
+// answers 403, as a missing entry does (live, 2026-10-27), so each location
+// must be read, not guessed. Every read is a direct lookup: Dataplex search
+// misses entries a lookup finds, and is not exact.
+//
+// When a location read answers 404, the source names a table, catalog or
+// instance that does not exist. When it answers 403, the read was refused and
+// the entry was never looked up, so the message says which read it was, and
+// what the service said: Spanner answers 403 for a project the caller may not
+// read, whether or not the instance exists, so a 403 does not say the table
+// is missing. A read that fails another way says to try again when a retry
+// may pass (a thrown call, a 429 or a 5xx), and to fix the source otherwise.
+//
+// A Cloud SQL or third-party source is not looked up here: sourceDialects
+// already looks up its entry directly, and fails the push when it is missing.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sourceEntryErrors = sourceEntryErrors;
+const api_1 = require("../gcp/api");
+const catalog_entry_1 = require("./catalog_entry");
+const loader_1 = require("./loader");
+const resolve_profiles_1 = require("./resolve_profiles");
+// One message for each entity, in the inline bindings (named `default`) or in
+// a profile, whose source names a table with no Knowledge Catalog entry, in
+// that order. Then one message for each of those profiles whose BigQuery and
+// BigLake tables share no location (b/578688979): BigQuery runs each query in
+// one location, so no query through the profile can join them.
+//
+// A named profile is judged by its own sources, since push requires it to
+// bind every concrete entity. A BigLake table can be queried in any replica
+// region of its catalog. A table whose location could not be read is
+// reported above and left out.
+//
+// Seen live in kc-looker-external, for a US catalog whose replicas are
+// us-central1 (primary) and us-east1:
+// - A job in US cannot read its tables (2026-11-03).
+// - Once a table has replicated, which took a few minutes, a job in either
+//   region can read it, join it with a dataset in that region, and create a
+//   property graph over both (2026-11-04).
+// - A job with no location runs in the primary.
+//
+// Reads each table's location and looks its entry up once per location it
+// may sit in, and reads each catalog and instance once; tables are checked in
+// parallel, and a table's locations in turn. Skips an abstract entity, an
+// entity with no source, and a source that names no table this module knows
+// (a Cloud SQL or third-party table, or a legacy bare name). Never throws.
+async function sourceEntryErrors(model, readers) {
+    const uses = [];
+    const use = (entity, profile, source) => {
+        const table = source ? (0, loader_1.sourceTableOf)(source) : undefined;
+        if (table)
+            uses.push({ entity, profile, table });
+    };
+    for (const e of model.entities) {
+        if (!e.abstract)
+            use(e.name, resolve_profiles_1.DEFAULT_PROFILE, (0, loader_1.writtenSource)(e));
+    }
+    for (const p of model.profiles ?? []) {
+        for (const b of p.entities)
+            use(b.name, p.name, b.source);
+    }
+    const catalogAndInstanceReads = new Map();
+    const locations = new Map();
+    const problems = new Map();
+    for (const { table } of uses) {
+        if (!problems.has(table.resourceName)) {
+            const located = locationsOf(table, readers, catalogAndInstanceReads);
+            locations.set(table.resourceName, located);
+            problems.set(table.resourceName, problemOf(table, located, readers));
+        }
+    }
+    const errors = [];
+    // By profile, each list of regions BigQuery can query one of its tables in,
+    // keyed by the list, with the entities bound to such tables, in the order
+    // bound.
+    const placed = new Map();
+    for (const { entity, profile, table } of uses) {
+        const problem = await problems.get(table.resourceName);
+        if (problem) {
+            errors.push(`entity '${entity}' in profile '${profile}': source '${table.resourceName}' ${problem}`);
+        }
+        if (table.system !== 'bigquery' && table.system !== 'biglake')
+            continue;
+        const located = await locations.get(table.resourceName);
+        if (!('result' in located))
+            continue;
+        const regions = located.result;
+        const key = regions.join(' ');
+        const at = placed.get(profile) ?? new Map();
+        at.set(key, { regions, entities: [...at.get(key)?.entities ?? [], entity] });
+        placed.set(profile, at);
+    }
+    for (const [profile, at] of placed) {
+        const [first, ...rest] = at.values();
+        if (first.regions.some(r => rest.every(g => g.regions.includes(r)))) {
+            continue;
+        }
+        const listed = [...at.values()].map(({ regions, entities }) => `${regions.map(shown).join(' or ')} (${entities.map(e => `'${e}'`).join(', ')})`);
+        errors.push(`profile '${profile}' of model '${model.name}' binds tables that ` +
+            `share no BigQuery location: ${listed.join(', ')}. ` +
+            `BigQuery runs each query in one location, so no query can join ` +
+            `them. Bind them to tables that share a location, or pass ` +
+            `--skip-source-check.`);
+    }
+    return errors;
+}
+// What is wrong with `table`'s source, or undefined when its catalog entry
+// is there. `located` is what locationsOf gave for `table`. Looks the entry
+// up in each of its locations in turn, and stops at the first that finds it:
+// a lookup in the wrong location answers 403, so trying each cannot pass a
+// missing entry.
+async function problemOf(table, located, readers) {
+    const locations = await located;
+    if ('problem' in locations)
+        return locations.problem;
+    for (const location of locations.result) {
+        const res = await (0, catalog_entry_1.lookupSystemEntry)(readers.catalog, table.system, table.project, location, table.resourceName);
+        if ('result' in res)
+            return undefined;
+        if ('error' in res)
+            return failedProblem(res).problem;
+    }
+    return `names no table Knowledge Catalog knows about. The table may not ` +
+        `exist, or you may not be allowed to read its catalog entry.${table.system === 'alloydb' ?
+            ' A new AlloyDB cluster can take hours to appear in the ' +
+                'catalog after Dataplex integration is turned on.' :
+            ''} Fix the source, or pass --skip-source-check.`;
+}
+// `location`, which is kept in lower case, as BigQuery writes it: a
+// multi-region, which has no hyphen, in upper case (`US`, `EU`).
+function shown(location) {
+    return location.includes('-') ? location : location.toUpperCase();
+}
+// Said when reading an instance config is refused (live on
+// bigquery-public-data and dataplex-staging-types, 2026-10-27: Spanner answers
+// 403 naming this permission, even for a Google-managed config such as nam3).
+const CONFIG_REFUSED_HINT = ' Reading it needs the permission ' +
+    'spanner.instanceConfigs.get on the project, which roles/spanner.viewer ' +
+    'includes and the Spanner database roles do not.';
+// The locations where `table`'s catalog entry may sit, as Dataplex writes
+// them, in lower case, in the order to look in: one for a BigQuery, Spanner
+// or AlloyDB table, and one per replica for a BigLake table. `cache` keeps
+// each catalog and instance's read, so each is read once; each table is read
+// once already.
+async function locationsOf(table, readers, cache) {
+    const once = (key, readIt) => {
+        if (!cache.has(key))
+            cache.set(key, readIt());
+        return cache.get(key);
+    };
+    const { project } = table;
+    switch (table.system) {
+        case 'alloydb':
+            return { result: [table.location] };
+        case 'bigquery': {
+            const what = `reading table '${project}.${table.dataset}.${table.table}'`;
+            const res = await readLocation(what, 'a table', () => readers.bigquery.getTable(project, table.dataset, table.table));
+            return 'result' in res ?
+                located(res.result.location, what, 'no location') :
+                res;
+        }
+        case 'biglake':
+            return once(`biglake/${project}/${table.catalog}`, async () => {
+                const what = `reading the region of catalog '${table.catalog}'`;
+                const res = await readLocation(what, 'a catalog', () => readers.biglake.getCatalog(project, table.catalog));
+                return 'result' in res ? replicaRegions(res.result, what) : res;
+            });
+        case 'spanner':
+            return once(`spanner/${project}/${table.instance}`, async () => {
+                const what = `reading instance '${table.instance}'`;
+                const instance = await readLocation(what, 'an instance', () => readers.spanner.getInstance(project, table.instance));
+                if ('problem' in instance)
+                    return instance;
+                const configName = instance.result.config;
+                if (!configName) {
+                    return transientProblem(`${what} gave no instance config.`);
+                }
+                // A regional config keeps every replica, so its leader, in the region
+                // it is named for: `regional-us-central1` leads in us-central1 (live,
+                // 2026-10-27).
+                const region = configName.match(/\/instanceConfigs\/regional-(.+)$/);
+                if (region)
+                    return { result: [region[1]] };
+                const configWhat = `reading instance config '${configName}'`;
+                const config = await readLocation(configWhat, 'an instance config', () => readers.spanner.getInstanceConfig(configName), CONFIG_REFUSED_HINT);
+                // A config marks exactly one replica as its default leader.
+                return 'result' in config ?
+                    located(config.result.replicas?.find(r => r.defaultLeaderLocation)
+                        ?.location, configWhat, 'no default leader') :
+                    config;
+            });
+    }
+}
+// Makes the location read `call`, which `what` names. A 404 says the source
+// names `kind`, such as `a table`, that does not exist (the services answer
+// 404 for a missing table, dataset, catalog or instance; live, 2026-10-27 and
+// 2026-11-03). A 403 says the read was refused, followed by the service's
+// message and `refusedHint`.
+async function readLocation(what, kind, call, refusedHint = '') {
+    const res = await (0, catalog_entry_1.read)(what, call);
+    if ('result' in res)
+        return res;
+    if ('error' in res)
+        return failedProblem(res);
+    return {
+        problem: res.status === 404 ?
+            `names ${kind} that does not exist: ${what} found nothing (HTTP ` +
+                `404). Fix the source, or pass --skip-source-check.` :
+            `could not be checked: ${what} was refused (HTTP 403).${res.message ? ` ${res.message}` : ''}${refusedHint} The ` +
+                `source's catalog entry was not looked up. Fix the access or ` +
+                `the source, or pass --skip-source-check.`,
+    };
+}
+// The regions of `catalog`'s replicas, in the order to look in: a replica
+// marked STATE_PRIMARY first, then one in another primary state, such as
+// STATE_PRIMARY_IN_PROGRESS, then the rest, each group in the order the
+// replicas come. A regional or federated catalog lists one replica with no
+// state.
+//
+// After a failover, a table's entry stays only in the region that was the
+// catalog's primary when the table was created, until the table is next
+// written; for a few seconds during a failover the new primary reads
+// STATE_PRIMARY_IN_PROGRESS, so no replica is STATE_PRIMARY (from review on
+// #623, 2026-11-03; not tested live by us).
+function replicaRegions(catalog, what) {
+    const rank = (state = '') => state === 'STATE_PRIMARY' ? 0 : state.includes('PRIMARY') ? 1 : 2;
+    const regions = (catalog.replicas ?? [])
+        .filter(r => r.region)
+        .sort((a, b) => rank(a.state) - rank(b.state))
+        .map(r => r.region.toLowerCase());
+    return regions.length ? { result: regions } :
+        transientProblem(`${what} gave no region.`);
+}
+// `location` in lower case, or a problem when the read `what` gave none.
+// The services have always given one; this keeps a response without it from
+// stopping the push with a crash.
+function located(location, what, missing) {
+    return location ? { result: [location.toLowerCase()] } :
+        transientProblem(`${what} gave ${missing}.`);
+}
+// The problem for the failed read `res`. A thrown call, a 429 or a 5xx may
+// pass on retry; any other status, such as BigQuery's 400 for an invalid
+// table ID, never will, so the source must change.
+function failedProblem(res) {
+    return res.status === undefined || (0, api_1.isTransientStatus)(res.status) ?
+        transientProblem(res.error) :
+        {
+            problem: `could not be checked: ${res.error} Fix the source, or ` +
+                `pass --skip-source-check.`,
+        };
+}
+// The problem for a read that failed with `detail`, which may pass on retry.
+function transientProblem(detail) {
+    return {
+        problem: `could not be checked; try again, or pass --skip-source-check: ${detail}`,
+    };
+}

package/build/ts/kcmd/semantic/spanner.d.ts

@@ -0,0 +1,18 @@
+import { GenerateResult } from './graph_ddl';
+import { SemanticModel } from './ir';
+export interface GenerateOptions {
+    graphName?: string;
+}
+export type { GenerateResult };
+/**
+ * Generates the Spanner Graph DDL for a semantic model.
+ *
+ * The generated statement references the entities' existing Spanner tables; it
+ * does not create them. Returns the DDL plus any warnings collected while
+ * mapping the IR (e.g. metrics dropped because Spanner Graph has no measure).
+ *
+ * Throws when the model yields no valid node table -- it declares no entities,
+ * or every entity lacks a KEY -- since a property graph with an empty NODE
+ * TABLES block is invalid DDL that Spanner would reject.
+ */
+export declare function generateSpannerPropertyGraph(model: SemanticModel, opts?: GenerateOptions): GenerateResult;

package/build/ts/kcmd/semantic/spanner.js

@@ -0,0 +1,60 @@
+"use strict";
+// Generates Spanner Graph DDL from the Semantic Model IR.
+//
+// The shared GoogleSQL generator (./graph_ddl) writes the graph structure. This
+// module supplies its Spanner engine: bare table and graph names, no measures,
+// no per-element OPTIONS, and a field's SPANNER text, else its ANSI_SQL text.
+//
+// See:
+// https://docs.cloud.google.com/spanner/docs/reference/standard-sql/graph-schema-statements
+//
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateSpannerPropertyGraph = generateSpannerPropertyGraph;
+const binding_1 = require("./binding");
+const graph_ddl_1 = require("./graph_ddl");
+const ir_1 = require("./ir");
+const sql_expr_utils_1 = require("./sql_expr_utils");
+const sql_identifiers_1 = require("./sql_identifiers");
+/**
+ * Generates the Spanner Graph DDL for a semantic model.
+ *
+ * The generated statement references the entities' existing Spanner tables; it
+ * does not create them. Returns the DDL plus any warnings collected while
+ * mapping the IR (e.g. metrics dropped because Spanner Graph has no measure).
+ *
+ * Throws when the model yields no valid node table -- it declares no entities,
+ * or every entity lacks a KEY -- since a property graph with an empty NODE
+ * TABLES block is invalid DDL that Spanner would reject.
+ */
+function generateSpannerPropertyGraph(model, opts = {}) {
+    return (0, graph_ddl_1.generateGraphDdl)(model, spannerEngine(opts));
+}
+// The Spanner engine for the shared generator.
+function spannerEngine(opts) {
+    return {
+        name: 'Spanner',
+        table: binding_1.spannerTable,
+        graphName: model => (0, sql_identifiers_1.quoteIdentifier)(opts.graphName ?? model.name),
+        placeMetrics: (metrics, _input, warnings) => skipMetrics(metrics, warnings),
+        elementOptions: () => undefined,
+        fieldOptions: () => undefined,
+        dialect: 'SPANNER',
+        fieldExpression,
+    };
+}
+// Warns that each metric is dropped, since Spanner Graph has no MEASURE.
+function skipMetrics(metrics, warnings) {
+    for (const metric of metrics) {
+        warnings.push(`metric '${metric.name}' is not emitted: Spanner Graph has no ` +
+            `MEASURE, so model-level metrics have no home in it`);
+    }
+    return new Map();
+}
+// The field's SPANNER text, else its ANSI_SQL text, read as Spanner SQL with
+// its comments removed. A line comment left in would swallow the ` AS <name>`
+// and comma the DDL writes after the expression.
+function fieldExpression(f) {
+    const text = (0, ir_1.expressionForDialect)(f, 'SPANNER');
+    return text === undefined ? undefined :
+        (0, sql_expr_utils_1.sqlWithoutComments)(text, 'SPANNER');
+}

package/build/ts/kcmd/semantic/sql_expr_utils.d.ts

@@ -0,0 +1,17 @@
+import { Field } from './ir';
+import { SqlColumn } from './sql_parser';
+export declare const STRING_LITERAL: RegExp;
+export declare function escapeRegExp(s: string): string;
+export declare function blankStringLiterals(expression: string): string;
+export declare function mapOutsideStringLiterals(expression: string, fn: (segment: string) => string): string;
+export declare function referencedEntityNames(expression: string, entityNames: string[]): string[];
+export declare function stripQualifier(expression: string, entity: string): string;
+export declare function sqlWithoutComments(text: string, dialect?: string): string;
+export declare function fieldBindingWithoutComments(field: Pick<Field, 'expression' | 'importedExpression' | 'importedDialect'>, targetDialect?: string): string | undefined;
+export declare function columnReferences(expression: string, dialect: string): ReadonlyArray<SqlColumn> | undefined;
+export declare function columnsForSource(text: string, dialect: string, impliedDialect?: string): ReadonlyArray<SqlColumn> | undefined;
+export declare function entitiesReached(columns: ReadonlyArray<SqlColumn>, entityNames: ReadonlyArray<string> | ReadonlySet<string>): string[];
+export declare function fieldsReadOn(columns: ReadonlyArray<SqlColumn>, entityName: string): string[];
+export declare const SUPPORTED_AGGREGATES: string[];
+export declare function isSingleAggregate(expression: string, dialect: string): boolean;
+export declare function isColumnName(value: unknown): boolean;