@google-cloud/kcmd 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,15 @@
+import * as context from '../gcp/context';
+import { LoadedModel } from './loader';
+export interface DeployOptions {
+    validateOnly?: boolean;
+    maxOperationPolls?: number;
+    pollBackoffMs?: number;
+}
+export interface DeployResult {
+    success: boolean;
+    details?: string;
+    ddl: string[];
+    warnings: string[];
+    deployed: number;
+}
+export declare function deploySpanner(models: LoadedModel[], ctx: context.ApiContext, options?: DeployOptions): Promise<DeployResult>;

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

@@ -0,0 +1,150 @@
+"use strict";
+// Deploys a semantic model's Spanner Graph.
+//
+// This is the Spanner leg of `kcmd push` for the semantic-model scope, a
+// sibling to deploy_bigquery: it consumes models already parsed into the
+// semantic IR (see loadSemanticModels, shared across legs so a multi-destination
+// push parses each document once), lowers each to `CREATE OR REPLACE PROPERTY
+// GRAPH` DDL (generator: ./spanner), and applies that DDL to the Spanner
+// database named by the model's GOOGLE deployment target.
+//
+// Spanner DDL is asynchronous: updateDatabaseDdl returns a long-running
+// operation which this leg polls to completion, unlike the BigQuery leg's
+// jobs.query.
+//
+// This is a library module: it emits no console output. The generated DDL and
+// any loader/generator warnings are returned in `DeployResult` for the CLI
+// (src/tool/commands.ts) to print.
+//
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deploySpanner = deploySpanner;
+const spanner_1 = require("../gcp/spanner");
+const deployment_target_1 = require("./deployment_target");
+const spanner_2 = require("./spanner");
+// Upper bound on getOperation polls before we give up on an operation that
+// never reports completion.
+const MAX_OPERATION_POLLS = 60;
+// Pause between polls of a running operation.
+const POLL_BACKOFF_MS = 1000;
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+// Waits for an updateDatabaseDdl long-running operation to complete and reports
+// any terminal error. The initial POST returns an Operation (usually not yet
+// `done`); we poll getOperation on its `name` until it is, then judge success
+// by its `error` field.
+async function awaitOperationDone(spanner, started, maxPolls, backoffMs) {
+    if (started.status !== 200) {
+        return { ok: false, error: started.message || String(started.status) };
+    }
+    let op = started.result;
+    if (!op) {
+        return {
+            ok: false,
+            error: started.message ||
+                'updateDatabaseDdl returned status 200 with no operation body',
+        };
+    }
+    const opName = op.name;
+    let polls = 0;
+    while (!op?.done && opName && polls < maxPolls) {
+        if (polls > 0) {
+            await sleep(backoffMs);
+        }
+        polls++;
+        const res = await spanner.getOperation(opName);
+        if (res.status !== 200) {
+            return { ok: false, error: res.message || String(res.status) };
+        }
+        op = res.result;
+    }
+    if (!op?.done) {
+        return {
+            ok: false,
+            error: opName ?
+                `operation ${opName} did not complete after ${maxPolls} polls` :
+                'updateDatabaseDdl returned no operation name to poll',
+        };
+    }
+    if (op.error) {
+        return { ok: false, error: op.error.message || `code ${op.error.code}` };
+    }
+    return { ok: true };
+}
+// Deploys the Spanner Graph for each pre-loaded model. Emits no console output;
+// the generated DDL and any warnings are returned for the caller to print. The
+// models are parsed once by the caller (loadSemanticModels) and shared with the
+// other legs; each carries its originating document name for diagnostics.
+async function deploySpanner(models, ctx, options = {}) {
+    const spanner = new spanner_1.SpannerClient(ctx);
+    const ddl = [];
+    const warnings = [];
+    let deployed = 0;
+    let modelsSeen = 0;
+    const fail = (details) => ({ success: false, details, ddl, warnings, deployed });
+    const maxPolls = options.maxOperationPolls ?? MAX_OPERATION_POLLS;
+    const backoffMs = options.pollBackoffMs ?? POLL_BACKOFF_MS;
+    for (const { document, model } of models) {
+        modelsSeen++;
+        let targets;
+        let malformed;
+        try {
+            ({ targets, malformed } = (0, deployment_target_1.spannerGraphTargets)(model));
+        }
+        catch (err) {
+            return fail(`Model '${model.name}' (${document}): ${err.message || err}`);
+        }
+        if (!targets.length) {
+            // A malformed-but-present target must not be reported as "none declared".
+            if (malformed.length) {
+                return fail(`Model '${model.name}' (${document}) declares Spanner Graph ` +
+                    `deploymentTarget(s) that could not be parsed: ` +
+                    `${malformed.join(', ')}. Expected ${deployment_target_1.SPANNER_GRAPH_FORM}.`);
+            }
+            return fail(`Model '${model.name}' (${document}) declares no Spanner Graph ` +
+                `deploymentTarget in a GOOGLE custom_extension; nothing to deploy.`);
+        }
+        for (const bad of malformed) {
+            warnings.push(`[${model.name}] ignoring unparseable Spanner Graph target: ${bad}`);
+        }
+        for (const target of targets) {
+            const gen = (0, spanner_2.generateSpannerPropertyGraph)(model, {
+                graphName: target.graphName,
+            });
+            for (const w of gen.warnings) {
+                warnings.push(`[${model.name} -> ${target.graphName}] ${w}`);
+            }
+            ddl.push(`-- ${target.uri}\n${gen.ddl}`);
+            if (options.validateOnly) {
+                continue;
+            }
+            // updateDatabaseDdl takes each statement WITHOUT a trailing semicolon:
+            // Spanner's DDL parser rejects one ("Expecting 'EOF' but found ';'" --
+            // verified live), unlike BigQuery's jobs.query, which accepts it. The
+            // generator terminates its DDL with `;` for the printed/golden artifact,
+            // so strip it here for the wire statement only.
+            const statement = gen.ddl.replace(/;\s*$/, '');
+            const started = await spanner.updateDatabaseDdl(target.project, target.instance, target.database, [statement]);
+            const outcome = await awaitOperationDone(spanner, started, maxPolls, backoffMs);
+            if (!outcome.ok) {
+                // CREATE OR REPLACE statements are applied one graph at a time, so any
+                // graphs already deployed in this run have mutated the database and are
+                // not rolled back. Surface that alongside the failing target.
+                const partial = deployed ?
+                    ` (${deployed} graph(s) already deployed in this run; ` +
+                        `CREATE OR REPLACE changes are not rolled back)` :
+                    '';
+                return fail(`Failed to deploy '${target.graphName}': ${outcome.error}${partial}`);
+            }
+            deployed++;
+        }
+    }
+    if (!modelsSeen) {
+        if (options.validateOnly) {
+            warnings.push('No semantic model documents found; nothing to validate.');
+            return { success: true, ddl, warnings, deployed };
+        }
+        return fail('No semantic model documents found; nothing to deploy.');
+    }
+    return { success: true, ddl, warnings, deployed };
+}

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

@@ -0,0 +1,93 @@
+import { CustomExtension, DeploymentSpec, SemanticModel } from './ir';
+export declare const BQ_GRAPH_FORM = "bigquery.googleapis.com/projects/<p>/datasets/<d>/propertyGraphs/<g>";
+export declare const SPANNER_GRAPH_FORM = "spanner.googleapis.com/projects/<p>/instances/<i>/databases/<db>/graphs/<g>";
+export declare const ALLOYDB_FORM = "alloydb.googleapis.com/projects/<p>/locations/<l>/clusters/<c>/databases/<db>";
+export interface BigQueryGraphTarget {
+    project: string;
+    dataset: string;
+    graphName: string;
+    uri: string;
+}
+export interface SpannerGraphTarget {
+    project: string;
+    instance: string;
+    database: string;
+    graphName: string;
+    uri: string;
+}
+export interface AlloyDbTarget {
+    project: string;
+    location: string;
+    cluster: string;
+    database: string;
+    uri: string;
+}
+export interface GoogleDeploymentTargets {
+    uris: string[];
+    bigQuery: BigQueryGraphTarget[];
+    spanner: SpannerGraphTarget[];
+    alloyDb: AlloyDbTarget[];
+    malformed: string[];
+}
+export type ParsedDeploymentTarget = {
+    engine: 'bigquery';
+    coordinates: BigQueryGraphTarget;
+} | {
+    engine: 'spanner';
+    coordinates: SpannerGraphTarget;
+} | {
+    engine: 'alloydb';
+    coordinates: AlloyDbTarget;
+};
+export type ResolvedDeployment = ParsedDeploymentTarget & {
+    name: string;
+    profile: string;
+};
+/** Why a deployment's target is not accepted in a `deployments:` list. */
+export declare function deploymentTargetError(model: SemanticModel, d: DeploymentSpec): string;
+/** Why a target in a GOOGLE block's `deploymentTargets` is not accepted. */
+export declare function googleBlockTargetError(model: SemanticModel, target: string): string;
+/**
+ * Why a push would reject `target`, or undefined when it accepts it. `at` says
+ * where it is written.
+ */
+export declare function targetProblem(at: string, target: string): string | undefined;
+/**
+ * The deployment names a `--deployment` flag selects, or undefined when the
+ * flag is absent or negated. The flag is repeated or comma-separated. It
+ * arrives as a string, as an array of them, or as a boolean when
+ * it is absent or negated. Pieces are trimmed, empty ones dropped, and a
+ * repeated name kept once, at its first position. Throws when any occurrence
+ * of the flag names no deployment. A bare occurrence in an array
+ * arrives as `true` and names none.
+ */
+export declare function parseDeploymentSelection(raw?: string | boolean | Array<string | boolean>): string[] | undefined;
+/**
+ * A model's deployments with each target parsed into its engine and
+ * coordinates. Returns every deployment in declaration order, or only the
+ * `selected` names, in the order given. Fails on a selected name the model
+ * does not declare, and on a target in no accepted form.
+ */
+export declare function resolveModelDeployments(model: SemanticModel, selected?: string[]): {
+    deployments: ResolvedDeployment[];
+} | {
+    error: string;
+};
+export declare function googleBlockTargets(exts: readonly CustomExtension[] | undefined, modelName: string): string[];
+export declare function unnamedDeployments(targets: readonly string[]): Array<{
+    name: string;
+    target: string;
+}>;
+export declare function googleDeploymentTargets(model: SemanticModel): GoogleDeploymentTargets;
+export declare function bigQueryGraphTargets(model: SemanticModel): {
+    targets: BigQueryGraphTarget[];
+    malformed: string[];
+};
+export declare function spannerGraphTargets(model: SemanticModel): {
+    targets: SpannerGraphTarget[];
+    malformed: string[];
+};
+export declare function alloyDbTargets(model: SemanticModel): {
+    targets: AlloyDbTarget[];
+    malformed: string[];
+};

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

@@ -0,0 +1,379 @@
+"use strict";
+// Reads where a model deploys and classifies each declared target.
+//
+// A semantic model names where it deploys with its `deployments:` list. Each
+// entry has a name, a target and optionally the binding profile it uses. The
+// loader also folds every target into `deploymentTargets` in a GOOGLE
+// `custom_extensions` block, which is also where a vanilla document's GOOGLE
+// block carries them. Three destination types are recognized here, each a
+// GCP resource name, written with no leading `//`:
+//
+//   BigQuery Graph:
+//     bigquery.googleapis.com/projects/<p>/datasets/<d>/propertyGraphs/<g>
+//   Spanner Graph:
+//     spanner.googleapis.com/projects/<p>/instances/<i>/databases/<db>/graphs/<g>
+//   AlloyDB database:
+//     alloydb.googleapis.com/projects/<p>/locations/<l>/clusters/<c>/databases/<db>
+//
+// The first two name a GRAPH; the third names a DATABASE, and the difference is
+// not an oversight. AlloyDB has no property-graph DDL, so there is no graph to
+// address and a URI pretending otherwise would name something that cannot be
+// created. What an AlloyDB target says is where the model's rows live -- which
+// is the whole of what a runtime needs in order to read an entity and carry out
+// an action. A model bound to it deploys to Knowledge Catalog and runs; it does
+// not deploy a graph, and push says so in a note rather than reporting the URI
+// as a typo.
+//
+// The deploy legs (deploy_bigquery, deploy_spanner) and the push-time validator
+// all derive their targets from this one reader, so a multi-destination push
+// parses each model's targets once rather than once per reader.
+//
+// The capture groups are restricted to valid identifier characters: the
+// components are interpolated into DDL unescaped (see the generators), so a
+// permissive `[^/]+` would let backticks or semicolons through. A URI that
+// matches neither destination type is collected as `malformed` (rejected by the
+// validator and named in errors) rather than silently skipped.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ALLOYDB_FORM = exports.SPANNER_GRAPH_FORM = exports.BQ_GRAPH_FORM = void 0;
+exports.deploymentTargetError = deploymentTargetError;
+exports.googleBlockTargetError = googleBlockTargetError;
+exports.targetProblem = targetProblem;
+exports.parseDeploymentSelection = parseDeploymentSelection;
+exports.resolveModelDeployments = resolveModelDeployments;
+exports.googleBlockTargets = googleBlockTargets;
+exports.unnamedDeployments = unnamedDeployments;
+exports.googleDeploymentTargets = googleDeploymentTargets;
+exports.bigQueryGraphTargets = bigQueryGraphTargets;
+exports.spannerGraphTargets = spannerGraphTargets;
+exports.alloyDbTargets = alloyDbTargets;
+const loader_1 = require("./loader");
+const resolve_profiles_1 = require("./resolve_profiles");
+// Our own vendor tag in the Ossie `custom_extensions` list.
+const GOOGLE_VENDOR = 'GOOGLE';
+// A BigQuery Graph deployment target.
+const BQ_GRAPH_TARGET = /^\/\/bigquery\.googleapis\.com\/projects\/([A-Za-z0-9_-]+)\/datasets\/([A-Za-z0-9_-]+)\/propertyGraphs\/([A-Za-z0-9_-]+)$/;
+// A Spanner Graph deployment target, named as Dataplex names the graph's
+// entry: `graphs/<g>`, where a BigQuery graph is `propertyGraphs/<g>`.
+// Instance and database ids follow Spanner's resource-id grammar (lowercase
+// letters, digits, hyphens); the graph name is a GoogleSQL identifier. As with
+// BigQuery, the segments are interpolated into DDL (the graph name) and into
+// the Spanner Admin API path (project/instance/database), so the character
+// classes stay strict.
+const SPANNER_GRAPH_TARGET = /^\/\/spanner\.googleapis\.com\/projects\/([A-Za-z0-9_-]+)\/instances\/([A-Za-z0-9_-]+)\/databases\/([A-Za-z0-9_-]+)\/graphs\/([A-Za-z0-9_-]+)$/;
+// A Spanner graph written with BigQuery's `propertyGraphs` segment, which names
+// no Dataplex entry. Push rejects it and names the `graphs` form. Its segments
+// follow SPANNER_GRAPH_TARGET's, so the name it suggests is accepted.
+const SPANNER_PROPERTY_GRAPH = /^(spanner\.googleapis\.com\/projects\/[A-Za-z0-9_-]+\/instances\/[A-Za-z0-9_-]+\/databases\/[A-Za-z0-9_-]+)\/propertyGraphs\/([A-Za-z0-9_-]+)$/;
+// An AlloyDB database. A database belongs to its cluster, and AlloyDB locates
+// a cluster by region, which is why there is a `locations` segment here and
+// none in the Spanner target. A database name is a PostgreSQL identifier, and
+// the strict class serves the same purpose as it does above: the name is
+// interpolated into a connection string and into generated SQL, so a
+// permissive class would let a quote character through.
+const ALLOYDB_TARGET = /^\/\/alloydb\.googleapis\.com\/projects\/([A-Za-z0-9_-]+)\/locations\/([A-Za-z0-9_-]+)\/clusters\/([A-Za-z0-9_-]+)\/databases\/([A-Za-z0-9_-]+)$/;
+// The instance-based AlloyDB URI kcmd used before. It names no real resource,
+// and no target parses as it. It exists only so targetError can name the
+// cluster-based form to write instead.
+const LEGACY_ALLOYDB_TARGET = /^\/\/alloydb\.googleapis\.com\/projects\/([A-Za-z0-9_-]+)\/locations\/([A-Za-z0-9_-]+)\/clusters\/([A-Za-z0-9_-]+)\/instances\/([A-Za-z0-9_-]+)\/databases\/([A-Za-z0-9_-]+)$/;
+// The GCP resource name form of each destination type, for messages.
+exports.BQ_GRAPH_FORM = 'bigquery.googleapis.com/projects/<p>/datasets/<d>/propertyGraphs/<g>';
+exports.SPANNER_GRAPH_FORM = 'spanner.googleapis.com/projects/<p>/instances/<i>/databases/<db>/graphs/<g>';
+exports.ALLOYDB_FORM = 'alloydb.googleapis.com/projects/<p>/locations/<l>/clusters/<c>/databases/<db>';
+// The Knowledge Catalog name prefixes of a graph or an AlloyDB database, each
+// with the resource name form to write instead. kcmd accepts no catalog name as
+// a target. `bigquery:propertygraph:` is a deprecated synonym for
+// `bigquery:graph:`.
+const CATALOG_PREFIXES = [
+    ['bigquery:graph:', exports.BQ_GRAPH_FORM],
+    ['bigquery:propertygraph:', exports.BQ_GRAPH_FORM],
+    ['spanner:graph:', exports.SPANNER_GRAPH_FORM],
+    ['alloydb:', exports.ALLOYDB_FORM],
+];
+// Parses a deployment target written as a GCP resource name. Returns undefined
+// for any other form, the resource URI with its leading `//` included. `uri`
+// in the result is the target as written.
+function parseTarget(uri) {
+    if (uri.startsWith('//'))
+        return undefined;
+    const resource = (0, loader_1.asResourceUri)(uri);
+    const bq = resource.match(BQ_GRAPH_TARGET);
+    if (bq) {
+        return {
+            engine: 'bigquery',
+            coordinates: { project: bq[1], dataset: bq[2], graphName: bq[3], uri },
+        };
+    }
+    const sp = resource.match(SPANNER_GRAPH_TARGET);
+    if (sp) {
+        return {
+            engine: 'spanner',
+            coordinates: {
+                project: sp[1],
+                instance: sp[2],
+                database: sp[3],
+                graphName: sp[4],
+                uri,
+            },
+        };
+    }
+    const ad = resource.match(ALLOYDB_TARGET);
+    if (ad) {
+        return {
+            engine: 'alloydb',
+            coordinates: {
+                project: ad[1],
+                location: ad[2],
+                cluster: ad[3],
+                database: ad[4],
+                uri,
+            },
+        };
+    }
+    return undefined;
+}
+// The cluster-based URI of the database a legacy instance-based AlloyDB URI
+// names.
+function clusterUri(legacy) {
+    return `//alloydb.googleapis.com/projects/${legacy[1]}/locations/${legacy[2]}/clusters/${legacy[3]}/databases/${legacy[5]}`;
+}
+/** Why a deployment's target is not accepted in a `deployments:` list. */
+function deploymentTargetError(model, d) {
+    return targetError(`Model '${model.name}': deployment '${d.name}' targets '${d.target}'`, d.target);
+}
+/** Why a target in a GOOGLE block's `deploymentTargets` is not accepted. */
+function googleBlockTargetError(model, target) {
+    return targetError(`Model '${model.name}': the GOOGLE custom_extension's ` +
+        `'deploymentTargets' lists '${target}'`, target);
+}
+// The Dataplex name of a Spanner graph `target` names with `propertyGraphs`,
+// or undefined for any other target.
+function spannerGraphName(target) {
+    const m = (0, loader_1.asResourceName)(target).match(SPANNER_PROPERTY_GRAPH);
+    return m ? `${m[1]}/graphs/${m[2]}` : undefined;
+}
+/**
+ * Why a push would reject `target`, or undefined when it accepts it. `at` says
+ * where it is written.
+ */
+function targetProblem(at, target) {
+    return parseTarget(target) ? undefined : targetError(at, target);
+}
+/** Why `target` is not accepted. `at` says where it is written. */
+function targetError(at, target) {
+    const legacy = (0, loader_1.asResourceUri)(target).match(LEGACY_ALLOYDB_TARGET);
+    if (legacy) {
+        return `${at}, the instance-based AlloyDB name, which names no real ` +
+            `resource. An AlloyDB database belongs to its cluster; write '${(0, loader_1.asResourceName)(clusterUri(legacy))}'.`;
+    }
+    const name = (0, loader_1.asResourceName)(target);
+    if (name !== target && parseTarget(name)) {
+        return `${at}, which is ${(0, loader_1.resourceUriFix)(target)}.`;
+    }
+    const graph = spannerGraphName(target);
+    if (graph) {
+        return `${at}, which names a Spanner graph by 'propertyGraphs'; write ` +
+            `its Dataplex name: '${graph}'.`;
+    }
+    const form = CATALOG_PREFIXES.find(([prefix]) => target.startsWith(prefix))?.[1];
+    if (form) {
+        return `${at}, which is a Knowledge Catalog name. Write the GCP resource ` +
+            `name instead: '${form}'.`;
+    }
+    return `${at}, which is not a BigQuery graph, a Spanner graph or an ` +
+        `AlloyDB database. Write a GCP resource name: '${exports.BQ_GRAPH_FORM}', '${exports.SPANNER_GRAPH_FORM}' or '${exports.ALLOYDB_FORM}'.`;
+}
+/**
+ * The deployment names a `--deployment` flag selects, or undefined when the
+ * flag is absent or negated. The flag is repeated or comma-separated. It
+ * arrives as a string, as an array of them, or as a boolean when
+ * it is absent or negated. Pieces are trimmed, empty ones dropped, and a
+ * repeated name kept once, at its first position. Throws when any occurrence
+ * of the flag names no deployment. A bare occurrence in an array
+ * arrives as `true` and names none.
+ */
+function parseDeploymentSelection(raw) {
+    if (raw === undefined || typeof raw === 'boolean')
+        return undefined;
+    const noNames = `--deployment names no deployment; give one or more ` +
+        `deployment names, comma-separated.`;
+    const names = [];
+    const parts = Array.isArray(raw) ? raw : [raw];
+    for (const part of parts) {
+        const pieces = typeof part === 'boolean' ?
+            [] :
+            String(part).split(',').map(p => p.trim()).filter(p => p);
+        if (!pieces.length)
+            throw new Error(noNames);
+        for (const name of pieces) {
+            if (!names.includes(name))
+                names.push(name);
+        }
+    }
+    if (!names.length)
+        throw new Error(noNames);
+    return names;
+}
+/**
+ * A model's deployments with each target parsed into its engine and
+ * coordinates. Returns every deployment in declaration order, or only the
+ * `selected` names, in the order given. Fails on a selected name the model
+ * does not declare, and on a target in no accepted form.
+ */
+function resolveModelDeployments(model, selected) {
+    const declared = model.deployments ?? [];
+    let chosen = declared;
+    if (selected !== undefined) {
+        const byName = new Map(declared.map(d => [d.name, d]));
+        chosen = [];
+        for (const name of selected) {
+            const d = byName.get(name);
+            if (!d) {
+                const available = declared.length ? declared.map(x => x.name).join(', ') : 'none';
+                return {
+                    error: `Model '${model.name}' has no deployment named '${name}' (available: ${available}).`,
+                };
+            }
+            chosen.push(d);
+        }
+    }
+    const deployments = [];
+    for (const d of chosen) {
+        const parsed = parseTarget(d.target);
+        if (!parsed)
+            return { error: deploymentTargetError(model, d) };
+        deployments.push({
+            ...parsed,
+            name: d.name,
+            profile: d.profile ?? resolve_profiles_1.DEFAULT_PROFILE,
+        });
+    }
+    return { deployments };
+}
+// Memoizes the parse per model object so the several callers within one push
+// (validation, source-project lookup, per-leg routing, each deploy leg) share a
+// single parse rather than re-running JSON.parse + the regexes once per reader.
+// Keyed by model identity: the IR object is stable through a push (the loader
+// and inheritance passes each hand on a fixed set of objects) and
+// neither its deployments nor its customExtensions are mutated after loading.
+// A caller that narrows `deployments` builds a new model object. The returned
+// value is read-only by convention -- no caller mutates its arrays.
+const targetsCache = new WeakMap();
+// The targets in a model's GOOGLE custom_extension(s). The extension `data` is
+// an opaque, vendor-serialized JSON string (the loader keeps it verbatim); we
+// own its `deploymentTargets` shape. Throws on malformed extension JSON.
+function extensionTargets(model) {
+    return googleBlockTargets(model.customExtensions, model.name);
+}
+// The targets listed in the GOOGLE blocks among `exts`, in order. A string
+// target is trimmed, and a blank one is dropped. A padded target is the same
+// target, so trimming here keeps the duplicate check and the stored list in
+// step. An entry that is not a string is kept as its JSON text, which parses
+// as no supported destination. Throws when a GOOGLE block's data is not valid
+// JSON.
+function googleBlockTargets(exts, modelName) {
+    const uris = [];
+    for (const ext of exts ?? []) {
+        if (ext.vendorName !== GOOGLE_VENDOR) {
+            continue;
+        }
+        let data;
+        try {
+            data = JSON.parse(ext.data);
+        }
+        catch {
+            throw new Error(`Model '${modelName}': GOOGLE custom_extension 'data' is not valid JSON.`);
+        }
+        const list = data?.deploymentTargets;
+        if (!Array.isArray(list)) {
+            continue;
+        }
+        for (const uri of list) {
+            if (typeof uri !== 'string') {
+                uris.push(JSON.stringify(uri));
+            }
+            else if (uri.trim() !== '') {
+                uris.push(uri.trim());
+            }
+        }
+    }
+    return uris;
+}
+// Deployments for targets whose names are not known: a pull reads only the
+// targets back from the catalog. One target is `default`; several are
+// `deployment_1`, `deployment_2`, and so on. Targets are trimmed, and blank
+// ones dropped. A repeated target is dropped too, so the list loads as a
+// `deployments:` list.
+function unnamedDeployments(targets) {
+    const seen = new Set();
+    const kept = targets.map(t => t.trim()).filter(t => {
+        if (t === '' || seen.has(t))
+            return false;
+        seen.add(t);
+        return true;
+    });
+    return kept.map((target, i) => ({
+        name: kept.length === 1 ? 'default' : `deployment_${i + 1}`,
+        target,
+    }));
+}
+// Reads a model's deployment targets in a single pass and returns the facts
+// every caller derives from them. The targets come from `model.deployments`
+// when the model has it, and otherwise from its GOOGLE custom_extension(s).
+// Never both: in the Google flavor, the loader's GOOGLE block holds a copy of
+// the list. Throws on malformed extension JSON.
+function googleDeploymentTargets(model) {
+    const cached = targetsCache.get(model);
+    if (cached)
+        return cached;
+    const uris = model.deployments !== undefined ?
+        model.deployments.map(d => d.target) :
+        extensionTargets(model);
+    const bigQuery = [];
+    const spanner = [];
+    const alloyDb = [];
+    const malformed = [];
+    for (const uri of uris) {
+        const parsed = parseTarget(uri);
+        if (parsed?.engine === 'bigquery') {
+            bigQuery.push(parsed.coordinates);
+        }
+        else if (parsed?.engine === 'spanner') {
+            spanner.push(parsed.coordinates);
+        }
+        else if (parsed?.engine === 'alloydb') {
+            alloyDb.push(parsed.coordinates);
+        }
+        else {
+            // Matches no supported destination type: collect it as malformed
+            // (rejected by the validator) rather than silently ignoring it.
+            malformed.push(uri);
+        }
+    }
+    const result = { uris, bigQuery, spanner, alloyDb, malformed };
+    targetsCache.set(model, result);
+    return result;
+}
+// The BigQuery Graph deployment targets a model declares, plus any URIs that
+// parse as no supported destination type. A view over googleDeploymentTargets,
+// preserving the historical shape the BigQuery leg and Knowledge Catalog leg
+// consume. Note `malformed` excludes a valid Spanner Graph or AlloyDB target:
+// each is a recognized destination, just not a BigQuery one, so neither is
+// reported as a BigQuery typo.
+function bigQueryGraphTargets(model) {
+    const { bigQuery, malformed } = googleDeploymentTargets(model);
+    return { targets: bigQuery, malformed };
+}
+// The Spanner Graph deployment targets a model declares, plus any URIs that
+// parse as no supported destination type. Symmetric to bigQueryGraphTargets.
+function spannerGraphTargets(model) {
+    const { spanner, malformed } = googleDeploymentTargets(model);
+    return { targets: spanner, malformed };
+}
+// The AlloyDB database targets a model declares. Symmetric to the two above in
+// shape, but there is no deploy leg behind it: an AlloyDB target is a store to
+// run against, not a graph to create, so the only callers are store resolution
+// and the messages that explain why a graph push has nothing to do.
+function alloyDbTargets(model) {
+    const { alloyDb, malformed } = googleDeploymentTargets(model);
+    return { targets: alloyDb, malformed };
+}

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

@@ -0,0 +1,34 @@
+import { AiContext, Entity, Field, Metric, SemanticModel, SqlDialect } from './ir';
+export interface GenerateResult {
+    ddl: string;
+    warnings: string[];
+}
+export interface MetricPlacementInput {
+    entityByName: ReadonlyMap<string, Entity>;
+    skipped: ReadonlySet<string>;
+    ancestorsUsed: ReadonlySet<string>;
+}
+export interface GraphEngine {
+    name: string;
+    table(dataSource: string, warnings: string[], context: string): string;
+    graphName(model: SemanticModel): string;
+    placeMetrics(metrics: Metric[], input: MetricPlacementInput, warnings: string[]): Map<string, string[]>;
+    elementOptions(description: string | undefined, ai: AiContext | undefined): string | undefined;
+    fieldOptions(field: Field): string | undefined;
+    dialect: SqlDialect;
+    fieldExpression(field: Field): string | undefined;
+}
+/**
+ * Generates the property-graph DDL for a semantic model on one engine.
+ *
+ * The generated statement references the entities' existing base tables; it
+ * does not create them. Returns the DDL plus any warnings collected while
+ * mapping the IR (e.g. metrics that could not be placed on a single table).
+ *
+ * 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 the engine would reject.
+ */
+export declare function generateGraphDdl(model: SemanticModel, engine: GraphEngine): GenerateResult;
+export declare function nodeKey(entity: Pick<Entity, 'keys' | 'uniqueKeys'>): string[];
+export declare function physicalColumn(column: string): string;