@google-cloud/kcmd 0.0.0-stage → 0.1.0

package/build/ts/kcmd/semantic/converters/owl/to_ir.js

@@ -0,0 +1,390 @@
+"use strict";
+// OwlModel -> Semantic Model IR mapping.
+//
+// This is the whole OWL -> OSI policy layer. The parser (parse.ts) is
+// mechanical; every decision about how an ontology becomes a semantic model
+// lives here, in one place, so the mapping is easy to read and to evolve.
+//
+// The mapping (see the user guide's table). Each line is one construct, kept
+// short so a comment reflow cannot run the columns together:
+//   owl:Class                     -> dataset (entity), no source (logical)
+//   owl:DatatypeProperty          -> field on each domain class's dataset
+//   owl:ObjectProperty            -> relationship (edge), domain -> range
+//   rdfs:range xsd:*              -> field datatype (see XSD_DATATYPES)
+//   owl:hasKey                    -> dataset primary_key
+//   owl:InverseFunctionalProperty -> dataset unique_keys (or primary_key)
+//   rdfs:subClassOf               -> dataset extends (entity inheritance)
+//   rdfs:label                    -> field label / synonym (no label slot)
+//   rdfs:comment/skos:definition/dcterms:/dc: -> description
+//   skos:example                  -> ai_context.examples
+//   owl:Ontology header           -> model description / ai_context
+//
+// The importer is IMPORT-ONLY: it maps the constructs above and DROPS every
+// other OWL construct rather than carrying it. Facts with no native OSI home --
+// rdfs:subPropertyOf, owl:inverseOf, owl:equivalentClass / owl:disjointWith /
+// owl:equivalentProperty / owl:propertyDisjointWith, the property
+// characteristics (symmetric, transitive, ...), owl:oneOf,
+// owl:propertyChainAxiom, the owl:AllDisjoint* / owl:AllDifferent set axioms,
+// rdfs:seeAlso / isDefinedBy, and owl:deprecated / versionInfo -- are NOT
+// imported. An earlier version carried them verbatim in a GOOGLE custom
+// extension; that was removed so an imported model is a clean OSI model with no
+// opaque carrier. The user guide's table documents what maps and what drops.
+//
+// The result is a purely LOGICAL model: an ontology declares meaning, not
+// physical tables, so entities carry no source, fields no expression, and
+// relationships no join columns -- only the logical shape (entities, fields,
+// keys, and edges by direction). `kcmd push` publishes it as-is.
+// A BigQuery or Spanner Graph deploy needs each edge's join columns added to
+// the model (logical grain the model owns) plus a physical binding (sources,
+// field columns) and a deployment target; that binding is a separate step (a
+// binding profile, see the user guide, "Going from ontology to a running
+// graph").
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.owlToIr = owlToIr;
+// --- Datatype mapping. ------------------------------------------------------
+const XSD = 'http://www.w3.org/2001/XMLSchema#';
+// The xsd:* ranges we map to an OSI datatype. Everything else falls back to
+// Opaque (a valid, lossless "unknown logical type" per the IR). Kept as a table
+// so adding ranges is a one-line change; the user guide documents this set.
+//
+// The OSI DataType vocabulary is closed (String / Integer / Decimal / Float /
+// Boolean / Date / Time / DateTime / DateTimeTz / Opaque), so several xsd types
+// collapse onto one OSI type (e.g. every bounded/unsigned integer -> Integer,
+// float and double -> Float): the logical type is preserved, physical width is
+// not (it belongs to the bound source, not the ontology).
+const XSD_DATATYPES = {
+    // Text.
+    [`${XSD}string`]: 'String',
+    [`${XSD}normalizedString`]: 'String',
+    [`${XSD}token`]: 'String',
+    [`${XSD}language`]: 'String',
+    [`${XSD}Name`]: 'String',
+    [`${XSD}NCName`]: 'String',
+    [`${XSD}anyURI`]: 'String',
+    // Integers (all widths / signednesses collapse to Integer).
+    [`${XSD}integer`]: 'Integer',
+    [`${XSD}int`]: 'Integer',
+    [`${XSD}long`]: 'Integer',
+    [`${XSD}short`]: 'Integer',
+    [`${XSD}byte`]: 'Integer',
+    [`${XSD}nonNegativeInteger`]: 'Integer',
+    [`${XSD}nonPositiveInteger`]: 'Integer',
+    [`${XSD}positiveInteger`]: 'Integer',
+    [`${XSD}negativeInteger`]: 'Integer',
+    [`${XSD}unsignedLong`]: 'Integer',
+    [`${XSD}unsignedInt`]: 'Integer',
+    [`${XSD}unsignedShort`]: 'Integer',
+    [`${XSD}unsignedByte`]: 'Integer',
+    // Exact and approximate numerics.
+    [`${XSD}decimal`]: 'Decimal',
+    [`${XSD}float`]: 'Float',
+    [`${XSD}double`]: 'Float',
+    // Boolean.
+    [`${XSD}boolean`]: 'Boolean',
+    // Temporal.
+    [`${XSD}date`]: 'Date',
+    [`${XSD}time`]: 'Time',
+    [`${XSD}dateTime`]: 'DateTime',
+    [`${XSD}dateTimeStamp`]: 'DateTimeTz',
+};
+function datatypeFor(rangeIri) {
+    if (rangeIri && XSD_DATATYPES[rangeIri])
+        return XSD_DATATYPES[rangeIri];
+    return 'Opaque';
+}
+// The temporal OSI datatypes. A field of one of these is a time dimension by
+// OSI's own rule (see ir.isTimeDimension), so the mapper marks it with a
+// dimension block; OWL itself has no dimension concept.
+const TEMPORAL_TYPES = new Set(['Date', 'Time', 'DateTime', 'DateTimeTz']);
+// --- Label / synonym policy. ------------------------------------------------
+// True when an rdfs:label carries nothing over the term's own name -- e.g. a
+// class named `Customer` labeled "Customer", or an object property `placedBy`
+// labeled "placed by". Compared case-insensitively with non-alphanumerics
+// stripped, so a spaced/cased human rendering of the same name is treated as
+// redundant and dropped rather than duplicated as a label or synonym.
+function isRedundantLabel(label, name) {
+    const norm = (s) => s.toLowerCase().replace(/[^a-z0-9]/g, '');
+    return norm(label) === norm(name);
+}
+// Drops synonyms that merely respace/recase the term's own name -- the same
+// redundancy rule the primary label gets -- so an alternate label identical to
+// the name is not emitted as a synonym.
+function nonRedundant(names, name) {
+    return names.filter(s => !isRedundantLabel(s, name));
+}
+// The display label for a FIELD: the OSI `label` slot exists only on fields, so
+// a datatype property's rdfs:label lands here -- unless it is redundant with
+// the field name, in which case it is dropped.
+function fieldLabel(label, name) {
+    if (label && !isRedundantLabel(label, name))
+        return label;
+    return undefined;
+}
+// The ai_context for a term that has NO label slot (classes, relationships): a
+// non-redundant rdfs:label becomes an alternate name, joined with any explicit
+// synonyms (extra labels / skos labels) and examples. Returns undefined when
+// there is nothing, so no empty ai_context is emitted.
+function synonymAiContext(label, name, synonyms, examples) {
+    const names = [];
+    if (label && !isRedundantLabel(label, name))
+        names.push(label);
+    names.push(...nonRedundant(synonyms, name));
+    return buildAiContext(undefined, names, examples);
+}
+// The ai_context for a FIELD (which already consumed its primary label into the
+// `label` slot): only the explicit synonyms and examples remain. Undefined when
+// empty.
+function fieldAiContext(synonyms, name, examples) {
+    return buildAiContext(undefined, nonRedundant(synonyms, name), examples);
+}
+// The ai_context for a RELATIONSHIP. Unlike datasets/fields, the OSI
+// relationship has no `description` slot (see the Apache OSI schema), so an
+// object property's comment is carried as ai_context `instructions`, and its
+// non-redundant label/synonyms/examples as the remaining fields. Undefined when
+// all are empty.
+function relationshipAiContext(label, name, synonyms, comment, examples) {
+    const names = [];
+    if (label && !isRedundantLabel(label, name))
+        names.push(label);
+    names.push(...nonRedundant(synonyms, name));
+    return buildAiContext(comment, names, examples);
+}
+// The ai_context for the MODEL, from the ontology header: labels/synonyms and
+// examples (the description rides in the model `description`, not here).
+function ontologyAiContext(ontology, modelName) {
+    if (!ontology)
+        return undefined;
+    return buildAiContext(undefined, nonRedundant(ontology.synonyms, modelName), ontology.examples);
+}
+// Assembles an AiContext from its parts, deduping names/examples and dropping
+// empties, and returns undefined when nothing is left -- the single place the
+// {instructions, synonyms, examples} shape is built.
+function buildAiContext(instructions, synonyms, examples) {
+    const ai = {};
+    if (instructions)
+        ai.instructions = instructions;
+    if (synonyms.length)
+        ai.synonyms = dedupe(synonyms);
+    if (examples.length)
+        ai.examples = dedupe(examples);
+    return ai.instructions || ai.synonyms || ai.examples ? ai : undefined;
+}
+function dedupe(items) {
+    return [...new Set(items)];
+}
+function arraysEqual(a, b) {
+    return a.length === b.length && a.every((v, i) => v === b[i]);
+}
+// --- Mapping. ---------------------------------------------------------------
+/**
+ * Maps a parsed OwlModel to a Semantic Model IR (see ../../ir.ts).
+ *
+ * `modelName` names the resulting semantic model (the CLI derives it from the
+ * source filename). The IR it returns serializes, via osi_converter, to the
+ * OSI YAML shown in the user guide.
+ */
+function owlToIr(owl, modelName) {
+    const warnings = [];
+    const classNames = new Set(owl.classes.map(c => c.localName));
+    // Entities, one per class, in class-declaration order. Fields are attached in
+    // datatype-property-declaration order below. Two classes can share a local
+    // name (e.g. same name in different namespaces); OSI dataset names must be
+    // unique, so the first wins and the rest are warned and skipped rather than
+    // silently emitting a duplicate the loader would reject.
+    const entitiesByName = new Map();
+    const entities = [];
+    for (const c of owl.classes) {
+        if (entitiesByName.has(c.localName)) {
+            warnings.push(`class '${c.localName}' is declared more than once (same local name, ` +
+                `possibly across namespaces); keeping the first and skipping the rest.`);
+            continue;
+        }
+        const entity = {
+            name: c.localName,
+            // No source: a class is a logical entity. A binding profile supplies the
+            // backing table before a graph deploy; KC push needs none.
+            dataSource: '',
+            keys: dedupe(c.keys), // owl:hasKey -> primary_key (grain)
+            description: c.comment,
+            aiContext: synonymAiContext(c.label, c.localName, c.synonyms, c.examples),
+            fields: [],
+        };
+        // rdfs:subClassOf -> entity-level `extends`. Kept AS DECLARED (parent
+        // local names, deduped); parents are not flattened here -- a later
+        // resolution pass expands inherited fields (see ir.ts Entity.extends). Only
+        // parents defined as an owl:Class in this ontology are kept: an unknown
+        // parent (a typo, or a superclass imported from another ontology) cannot be
+        // resolved, and the loader hard-fails on an unknown supertype, so it is
+        // DROPPED here with a warning rather than emitted into a model that could
+        // not be pushed.
+        if (c.subClassOf.length) {
+            const parents = dedupe(c.subClassOf);
+            const known = parents.filter(name => classNames.has(name));
+            const unknown = parents.filter(name => !classNames.has(name));
+            if (known.length)
+                entity.extends = known;
+            if (unknown.length) {
+                warnings.push(`class '${c.localName}' declares rdfs:subClassOf a non-class ` +
+                    `superclass (${unknown.join(', ')}); dropped, as it is not an owl:Class in ` +
+                    `this ontology and cannot be resolved.`);
+            }
+        }
+        entitiesByName.set(c.localName, entity);
+        entities.push(entity);
+    }
+    // Datatype properties -> fields on each domain's entity. A property with more
+    // than one domain appears on each; one with none has nowhere to live.
+    let datatypePropertiesConverted = 0;
+    for (const p of owl.datatypeProperties) {
+        if (!p.domains.length) {
+            warnings.push(`datatype property '${p.localName}' has no rdfs:domain; skipped ` +
+                `(a field must belong to a class).`);
+            continue;
+        }
+        // A property counts as converted once if it produces at least one field,
+        // regardless of how many domains it lands on.
+        let produced = false;
+        for (const domain of p.domains) {
+            const entity = entitiesByName.get(domain);
+            if (!entity) {
+                warnings.push(`datatype property '${p.localName}' has domain '${domain}', ` +
+                    `which is not an owl:Class in this ontology; skipped.`);
+                continue;
+            }
+            if (entity.fields.some(f => f.name === p.localName)) {
+                warnings.push(`datatype property '${p.localName}' on '${domain}' duplicates an ` +
+                    `existing field name; skipped (field names must be unique).`);
+                continue;
+            }
+            const type = datatypeFor(p.rangeIri);
+            const field = {
+                name: p.localName,
+                // No expression: the field is logical. A binding profile maps it to a
+                // column when a real source is bound.
+                type,
+                // A temporal field is a time dimension by OSI's own rule; mark it so
+                // downstream (BigQuery Graph, BI) treats it as one.
+                dimension: TEMPORAL_TYPES.has(type) ? { isTime: true } : undefined,
+                label: fieldLabel(p.label, p.localName),
+                description: p.comment,
+                aiContext: fieldAiContext(p.synonyms, p.localName, p.examples),
+            };
+            entity.fields.push(field);
+            produced = true;
+            // An inverse-functional property uniquely identifies its subject -> a
+            // unique_keys constraint, unless it is already the primary key.
+            if (p.inverseFunctional && !arraysEqual(entity.keys, [p.localName])) {
+                (entity.uniqueKeys ??= []).push([p.localName]);
+            }
+        }
+        if (produced)
+            datatypePropertiesConverted++;
+    }
+    // Reconcile each entity's keys with the fields that actually exist. Both
+    // corrections are fail-soft (warn, never throw), matching the converter's
+    // per-element policy:
+    //   1. owl:hasKey may name a property that is not a datatype property on the
+    //      class (undeclared, or declared only on a different domain). That
+    //      column has no field, so it would name a phantom column that only
+    //      errors later at graph generation. Drop the ENTIRE primary_key, not
+    //      just the phantom member -- keeping the survivors would silently narrow
+    //      a composite key to a possibly non-unique one, changing the grain.
+    //   2. A class with no usable owl:hasKey but exactly one single-column
+    //      inverse-functional property still has a natural identifier; promote
+    //      that unique key to the primary_key so the entity has a grain.
+    //      (Ambiguous cases -- several unique keys, or a composite one -- are
+    //      left alone.)
+    for (const entity of entities) {
+        const fieldNames = new Set(entity.fields.map(f => f.name));
+        const missing = entity.keys.filter(k => !fieldNames.has(k));
+        if (missing.length) {
+            warnings.push(`class '${entity.name}' owl:hasKey names ${missing.map(m => `'${m}'`).join(', ')} which ${missing.length > 1 ? 'are' : 'is'} not a datatype property on ` +
+                `the class; dropping the entire primary_key (keeping only the ` +
+                `remaining columns would change the entity's grain).`);
+            entity.keys = [];
+        }
+        if (!entity.keys.length && entity.uniqueKeys?.length === 1 &&
+            entity.uniqueKeys[0].length === 1) {
+            entity.keys = [...entity.uniqueKeys[0]];
+            entity.uniqueKeys = undefined;
+            warnings.push(`class '${entity.name}' has no usable owl:hasKey; using the ` +
+                `inverse-functional property '${entity.keys[0]}' as its primary_key.`);
+        }
+    }
+    // Object properties -> relationships (edges). Both endpoints must be known
+    // classes. The edge is logical: it carries only its direction (source entity
+    // -> destination entity), no join columns. The foreign-key / key columns are
+    // added to the model (logical grain, not a binding) before a graph deploy.
+    const relationships = [];
+    for (const p of owl.objectProperties) {
+        const domain = p.domains[0];
+        const range = p.ranges[0];
+        if (!domain || !range) {
+            warnings.push(`object property '${p.localName}' is missing an rdfs:domain or ` +
+                `rdfs:range; skipped (a relationship needs both endpoints).`);
+            continue;
+        }
+        // A relationship maps ONE source to ONE destination. Multiple domains or
+        // ranges mean an intersection in OWL, which has no clean single-edge shape,
+        // so keep the first of each and say what was dropped rather than losing it
+        // silently.
+        const ignored = [
+            ...p.domains.slice(1).map(d => `domain '${d}'`),
+            ...p.ranges.slice(1).map(r => `range '${r}'`),
+        ];
+        if (ignored.length) {
+            warnings.push(`object property '${p.localName}' declares more than one endpoint ` +
+                `(${ignored.join(', ')}); a relationship maps one source to one ` +
+                `destination, so only domain '${domain}' -> range '${range}' is kept.`);
+        }
+        if (!classNames.has(domain) || !classNames.has(range)) {
+            warnings.push(`object property '${p.localName}' references a non-class endpoint ` +
+                `(domain '${domain}', range '${range}'); skipped.`);
+            continue;
+        }
+        if (relationships.some(r => r.name === p.localName)) {
+            warnings.push(`object property '${p.localName}' duplicates an existing relationship ` +
+                `name; skipped (relationship names must be unique).`);
+            continue;
+        }
+        const relationship = {
+            name: p.localName,
+            // A logical edge: direction only, no join columns. The source
+            // foreign-key and destination key columns are added to the model (logical
+            // grain, not a binding) before a graph deploy.
+            source: { entity: domain, columns: [] },
+            destination: { entity: range, columns: [] },
+            // No `description`: the OSI relationship has no such slot, so the comment
+            // rides in ai_context.instructions (see relationshipAiContext).
+            aiContext: relationshipAiContext(p.label, p.localName, p.synonyms, p.comment, p.examples),
+        };
+        relationships.push(relationship);
+    }
+    const model = {
+        name: modelName,
+        description: modelDescription(owl),
+        aiContext: ontologyAiContext(owl.ontology, modelName),
+        entities,
+        relationships,
+        metrics: [],
+    };
+    return {
+        model,
+        warnings,
+        stats: {
+            classes: entities.length,
+            datatypeProperties: datatypePropertiesConverted,
+            objectProperties: relationships.length,
+        },
+    };
+}
+// The model description: the ontology header's own description when it has one,
+// otherwise a provenance line naming the source base IRI. An owl:versionInfo is
+// appended as provenance in either case.
+function modelDescription(owl) {
+    const base = owl.ontology?.comment ??
+        (owl.baseIri ? `Imported from OWL ontology ${owl.baseIri}` :
+            'Imported from OWL ontology');
+    const version = owl.ontology?.version;
+    return version ? `${base} (ontology version ${version})` : base;
+}

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

@@ -0,0 +1,20 @@
+import { BigQueryClient } from '../gcp/bigquery';
+import * as context from '../gcp/context';
+import { BigQueryGraphTarget, bigQueryGraphTargets, googleDeploymentTargets } from './deployment_target';
+import { LoadedModel } from './loader';
+export { bigQueryGraphTargets, googleDeploymentTargets };
+export type { BigQueryGraphTarget };
+export interface DeployOptions {
+    validateOnly?: boolean;
+    maxQueryPolls?: number;
+    pollBackoffMs?: number;
+}
+export interface DeployResult {
+    success: boolean;
+    details?: string;
+    ddl: string[];
+    warnings: string[];
+    deployed: number;
+}
+export declare function datasetLocation(bigQuery: BigQueryClient, target: BigQueryGraphTarget, warnings: string[]): Promise<string | undefined>;
+export declare function deployBigQuery(models: LoadedModel[], ctx: context.ApiContext, options?: DeployOptions): Promise<DeployResult>;

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

@@ -0,0 +1,226 @@
+"use strict";
+// Deploys a semantic model's BigQuery Graph.
+//
+// This is the BigQuery leg of `kcmd push` for the semantic-model scope: it
+// consumes models already parsed into the semantic IR (see loadSemanticModels,
+// shared with the Knowledge Catalog leg so a multi-destination push parses each
+// document once), lowers each to `CREATE OR REPLACE PROPERTY GRAPH` DDL
+// (generator), and executes that DDL against the BigQuery project named by the
+// model's GOOGLE deployment target.
+//
+// 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.googleDeploymentTargets = exports.bigQueryGraphTargets = void 0;
+exports.datasetLocation = datasetLocation;
+exports.deployBigQuery = deployBigQuery;
+const bigquery_1 = require("../gcp/bigquery");
+const bigquery_2 = require("./bigquery");
+// The GOOGLE deployment-target reader lives in its own module so both deploy
+// legs (BigQuery, Spanner) and the push-time validator share one parse. The
+// BigQuery-facing views are re-exported here so existing importers
+// (validate.ts, knowledge_catalog.ts, and the deploy tests) keep their
+// historical import path.
+const deployment_target_1 = require("./deployment_target");
+Object.defineProperty(exports, "bigQueryGraphTargets", { enumerable: true, get: function () { return deployment_target_1.bigQueryGraphTargets; } });
+Object.defineProperty(exports, "googleDeploymentTargets", { enumerable: true, get: function () { return deployment_target_1.googleDeploymentTargets; } });
+// Upper bound on getQueryResults polls before we give up on a job that never
+// reports completion (each poll long-polls the server for up to 10s).
+const MAX_QUERY_POLLS = 30;
+// Pause between polls. getQueryResults long-polls server-side, so this is a
+// backstop for the case where it returns promptly (which would otherwise fire
+// MAX_QUERY_POLLS requests back-to-back with no pause).
+const POLL_BACKOFF_MS = 1000;
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+// Waits for a jobs.query response to reach completion and reports any terminal
+// error. jobs.query can return before a slow DDL statement finishes; in that
+// case the response carries `jobComplete: false` and a job reference, and we
+// poll getQueryResults until the job is done. Errors are only judged once the
+// job has actually completed.
+async function awaitQueryDone(bigQuery, project, started, maxPolls, backoffMs) {
+    if (started.status !== 200) {
+        return { ok: false, error: started.message || String(started.status) };
+    }
+    let result = started.result;
+    // A 200 with no body is not a verified success: without jobComplete/errors we
+    // cannot confirm the DDL ran, so treat the missing body as a failure rather
+    // than falling through to the `{ok: true}` return below.
+    if (!result) {
+        return {
+            ok: false,
+            error: started.message || 'query returned status 200 with no response body',
+        };
+    }
+    const jobId = result?.jobReference?.jobId;
+    const location = result?.jobReference?.location;
+    let polls = 0;
+    while (result?.jobComplete === false && jobId && polls < maxPolls) {
+        if (polls > 0) {
+            await sleep(backoffMs);
+        }
+        polls++;
+        const res = await bigQuery.getQueryResults(project, jobId, location);
+        if (res.status !== 200) {
+            return { ok: false, error: res.message || String(res.status) };
+        }
+        result = res.result;
+    }
+    if (result?.jobComplete === false) {
+        // Distinguish "polled to exhaustion" from "never had a job to poll": with
+        // no jobId the loop above ran zero times, so a "did not complete after N
+        // polls" message would be misleading.
+        return {
+            ok: false,
+            error: jobId ?
+                `job ${jobId} did not complete after ${maxPolls} polls` :
+                'query did not complete and returned no job reference to poll',
+        };
+    }
+    // errors[] mixes fatal errors and non-fatal warnings. When it is populated,
+    // consult the job's status.errorResult -- the definitive fatal signal -- so a
+    // deploy that only produced warnings is not reported as a failure.
+    const errors = result?.errors;
+    if (errors && errors.length) {
+        if (jobId) {
+            const job = await bigQuery.getJob(project, jobId, location);
+            if (job.status !== 200) {
+                return { ok: false, error: job.message || String(job.status) };
+            }
+            const fatal = job.result?.status?.errorResult;
+            return fatal ? { ok: false, error: fatal.message } : { ok: true };
+        }
+        // No job reference to disambiguate; treat the errors as fatal.
+        return { ok: false, error: errors.map(e => e.message).join('; ') };
+    }
+    return { ok: true };
+}
+// Looks up a dataset's BigQuery location so the query job, its result polls,
+// and the job lookup all agree on a region. jobs.query would otherwise infer
+// the location from the referenced tables, which can pick the wrong region for
+// a non-US dataset.
+//
+// A 404 is a precise, free pre-flight: a typo'd dataset in the deployment
+// target would otherwise surface later as a murkier DDL error, so we fail fast
+// on it. Other failures (e.g. a 403 when the caller lacks
+// bigquery.datasets.get) are non-fatal: fall back to letting BigQuery infer the
+// location, but record a warning so the degraded path is visible -- otherwise a
+// silent fallback can route a non-US CREATE to the wrong region and fail later
+// with an opaque location error.
+async function datasetLocation(bigQuery, target, warnings) {
+    const res = await bigQuery.getDataset(target.project, target.dataset);
+    if (res.status === 200) {
+        return res.result?.location;
+    }
+    if (res.status === 404) {
+        throw new Error(`dataset ${target.project}.${target.dataset} not found`);
+    }
+    warnings.push(`could not read location of dataset ${target.project}.${target.dataset} (${res.message || res.status}); ` +
+        `letting BigQuery infer the query location`);
+    return undefined;
+}
+// Deploys the BigQuery 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 Knowledge Catalog leg; each carries its originating document
+// name for diagnostics.
+async function deployBigQuery(models, ctx, options = {}) {
+    const bigQuery = new bigquery_1.BigQueryClient(ctx);
+    const ddl = [];
+    const warnings = [];
+    let deployed = 0;
+    let modelsSeen = 0;
+    const fail = (details) => ({ success: false, details, ddl, warnings, deployed });
+    const maxPolls = options.maxQueryPolls ?? MAX_QUERY_POLLS;
+    const backoffMs = options.pollBackoffMs ?? POLL_BACKOFF_MS;
+    // A model can declare several graphs in one dataset; cache the location so we
+    // issue one datasets.get per dataset rather than one per target.
+    const locationCache = new Map();
+    const locationFor = async (target) => {
+        const key = `${target.project}/${target.dataset}`;
+        if (locationCache.has(key)) {
+            return locationCache.get(key);
+        }
+        const loc = await datasetLocation(bigQuery, target, warnings);
+        locationCache.set(key, loc);
+        return loc;
+    };
+    for (const { document, model } of models) {
+        modelsSeen++;
+        let targets;
+        let malformed;
+        try {
+            ({ targets, malformed } = (0, deployment_target_1.bigQueryGraphTargets)(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" -- that sends the author hunting for an extension they
+            // already wrote. Name the URIs that failed to parse.
+            if (malformed.length) {
+                return fail(`Model '${model.name}' (${document}) declares BigQuery Graph ` +
+                    `deploymentTarget(s) that could not be parsed: ` +
+                    `${malformed.join(', ')}. Expected ${deployment_target_1.BQ_GRAPH_FORM}.`);
+            }
+            return fail(`Model '${model.name}' (${document}) declares no BigQuery Graph ` +
+                `deploymentTarget in a GOOGLE custom_extension; nothing to deploy.`);
+        }
+        // Malformed targets alongside valid ones: surface them so a typo'd URI is
+        // not silently dropped when the deploy otherwise succeeds.
+        for (const bad of malformed) {
+            warnings.push(`[${model.name}] ignoring unparseable BigQuery Graph target: ${bad}`);
+        }
+        for (const target of targets) {
+            const gen = (0, bigquery_2.generatePropertyGraph)(model, {
+                project: target.project,
+                dataset: target.dataset,
+                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;
+            }
+            let location;
+            try {
+                location = await locationFor(target);
+            }
+            catch (err) {
+                return fail(`Failed to deploy '${target.graphName}': ${err.message || err}`);
+            }
+            const started = await bigQuery.query(target.project, gen.ddl, location);
+            const outcome = await awaitQueryDone(bigQuery, target.project, started, maxPolls, backoffMs);
+            if (!outcome.ok) {
+                // These are CREATE OR REPLACE statements executed one at a time, so
+                // any graphs already deployed in this run have mutated production 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++;
+        }
+    }
+    // A parsed document always yields at least one model (the loader enforces
+    // `semantic_model` min 1), so modelsSeen is 0 only when no documents were
+    // found at all. validateOnly mutates nothing, so an empty workspace is a
+    // clean no-op there (exit 0); a real push treats "nothing to deploy" as a
+    // configuration error worth flagging.
+    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 };
+}