@google-cloud/kcmd 0.1.0 → 0.2.1

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

@@ -16,12 +16,19 @@
 //   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.
+//   getHiveCatalog reads a Hive catalog. Its tables are written with
+//   `databases/`.
 // - 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.
+//   lack. When it is refused, the entry is looked up in each region the
+//   instance has replicas in, which getInstance lists, in the order listed,
+//   until one finds it: the default leader's region is one of them, and the
+//   list marks no leader (live, 2026-11-04). The instance's
+//   `resourceLocation`, such as `us`, is not a Dataplex region. 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
@@ -34,8 +41,10 @@
 // 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.
+// is missing. A refused Spanner instance config read is the exception: the
+// entry is then looked up in each replica region the instance lists. 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.
@@ -65,10 +74,11 @@ const resolve_profiles_1 = require("./resolve_profiles");
 // - 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.
+// may sit in, and reads each instance once and each catalog at most once
+// through each API; 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). Never
+// throws.
 async function sourceEntryErrors(model, readers) {
     const uses = [];
     const use = (entity, profile, source) => {
@@ -149,24 +159,40 @@ async function problemOf(table, located, readers) {
         `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.`;
+            ''}${locations.unfound ?? ''} 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).
+// Said when reading an instance config is refused and the instance lists no
+// replica regions to look in instead (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.';
+// Said when reading an instance is refused: a Spanner database role gives
+// spanner.instances.get only when granted on the instance or its project
+// (from review on #630, 2026-11-04).
+const INSTANCE_REFUSED_HINT = ' The Spanner database roles include ' +
+    'spanner.instances.get, but a role granted on one database does not ' +
+    'apply to its instance.';
+// Said when a BigLake catalog read fails in a way a retry cannot fix and the
+// other kind of catalog's API finds the catalog. The status alone does not
+// tell: live, the Hive API answers 400 for an Iceberg REST catalog id with a
+// hyphen and for a Hive catalog id in capitals.
+const HIVE_FORM_HINT = ` A table in a Hive catalog is written with 'databases/<database>'.`;
+const ICEBERG_FORM_HINT = ` A table in an Iceberg REST catalog is written ` +
+    `with 'namespaces/<namespace>'.`;
 // 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.
+// them, in lower case, in the order to look in: one for a BigQuery or AlloyDB
+// table; one for a Spanner table, or one per replica region of its instance
+// when reading its config is refused; and one per replica for a BigLake table.
+// `cache` keeps each instance's read and each catalog's read through each
+// API, so each is made once; each table is read once already.
 async function locationsOf(table, readers, cache) {
     const once = (key, readIt) => {
         if (!cache.has(key))
@@ -184,16 +210,23 @@ async function locationsOf(table, readers, cache) {
                 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 'biglake': {
+            const readCatalog = (hive) => once(`biglake/${project}/${table.catalog}/${hive}`, () => hive ? readers.biglake.getHiveCatalog(project, table.catalog) :
+                readers.biglake.getCatalog(project, table.catalog));
+            const kind = table.hive ? 'Hive catalog' : 'catalog';
+            const what = `reading the region of ${kind} '${table.catalog}'`;
+            // When the read fails and the other API finds the catalog, the source
+            // names a table in the other kind of catalog.
+            const otherForm = async () => 'result' in await (0, catalog_entry_1.read)(what, () => readCatalog(!table.hive)) ?
+                (table.hive ? ICEBERG_FORM_HINT : HIVE_FORM_HINT) :
+                '';
+            const res = await readLocation(what, `a ${kind}`, () => readCatalog(table.hive), otherForm);
+            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));
+                const instance = await readLocation(what, 'an instance', () => readers.spanner.getInstance(project, table.instance), status => status === 403 ? INSTANCE_REFUSED_HINT : '');
                 if ('problem' in instance)
                     return instance;
                 const configName = instance.result.config;
@@ -207,7 +240,23 @@ async function locationsOf(table, readers, cache) {
                 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);
+                const res = await (0, catalog_entry_1.read)(configWhat, () => readers.spanner.getInstanceConfig(configName));
+                // The default leader's region is one of the instance's replica
+                // regions, so when the config read is refused, each is looked in.
+                if ('unreadable' in res && res.status === 403) {
+                    const regions = (instance.result.replicaComputeCapacity ?? [])
+                        .map(r => r.replicaSelection?.location)
+                        .filter((l) => !!l);
+                    if (regions.length) {
+                        return {
+                            result: regions,
+                            unfound: ` Instance config '${configName}' could not be read ` +
+                                `(HTTP 403), so the entry was looked up in each of the ` +
+                                `instance's replica regions: ${regions.join(', ')}.`,
+                        };
+                    }
+                }
+                const config = await checked(res, configWhat, 'an instance config', status => status === 403 ? 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)
@@ -216,22 +265,31 @@ async function locationsOf(table, readers, cache) {
             });
     }
 }
-// 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
+// Makes the location read `call`, which `what` names, and judges its answer
+// with checked.
+async function readLocation(what, kind, call, hintFor) {
+    return checked(await (0, catalog_entry_1.read)(what, call), what, kind, hintFor);
+}
+// What the location read `what` gave in `res`. 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);
+// message. When a retry cannot pass, `hintFor` gives a sentence to add for the
+// status.
+async function checked(res, what, kind, hintFor = () => '') {
     if ('result' in res)
         return res;
+    const { status } = res;
+    const hint = status === undefined || (0, api_1.isTransientStatus)(status) ?
+        '' :
+        await hintFor(status);
     if ('error' in res)
-        return failedProblem(res);
+        return failedProblem(res, hint);
     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 ` +
+                `404).${hint} Fix the source, or pass --skip-source-check.` :
+            `could not be checked: ${what} was refused (HTTP 403).${res.message ? ` ${res.message}` : ''}${hint} The ` +
                 `source's catalog entry was not looked up. Fix the access or ` +
                 `the source, or pass --skip-source-check.`,
     };
@@ -265,13 +323,14 @@ function located(location, what, 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) {
+// table ID, never will, so the source must change, and `hint` follows the
+// service's answer.
+function failedProblem(res, hint = '') {
     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.`,
+            problem: `could not be checked: ${res.error}${hint} Fix the source, ` +
+                `or pass --skip-source-check.`,
         };
 }
 // The problem for a read that failed with `detail`, which may pass on retry.

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

@@ -1,17 +1,23 @@
 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 unusedName(text: string, base: string): string;
+export declare function withoutQualifier(expression: string, qualifier: string, dialect?: string): string;
+export declare function withSiblingsSpliced(expression: string, qualifier: string, siblings: ReadonlyMap<string, string>): string;
+export declare function qualifiedColumns(expression: string, qualifier: string, dialect?: string): string[] | undefined;
+export declare function selfReferenceMessage(owner: string, cycle: string[], where?: string): string;
+export declare function requalified(expression: string, from: string, to: string, dialect?: string): string;
+export declare function measureEntities(expression: string, entityNames: ReadonlyArray<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 columnsForSource(text: string, dialect: string, impliedDialect?: string | null): 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 singleAggregate(expression: string, dialect: string): {
+    fn: string;
+    operand: string;
+    distinct: boolean;
+} | undefined;
 export declare function isSingleAggregate(expression: string, dialect: string): boolean;
 export declare function isColumnName(value: unknown): boolean;

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

@@ -2,87 +2,209 @@
 // Helpers for reading and rewriting entity-qualified SQL expressions across the
 // semantic-model layer.
 //
-// Expressions reference columns as `<Entity>.<column>`. The SQL parser
+// An expression names a field of its entity as `<Entity>.<field>`, and a
+// column of its table without a qualifier. The SQL parser
 // (`columnReferences`, `entitiesReached`, `fieldsReadOn`) reads column and
 // entity references across dialects for the loader, validator, profile checks,
-// pull reader, and transpiler. The graph generators still use the literal-
-// aware regex helpers (`referencedEntityNames`, `stripQualifier`).
+// pull reader, and transpiler. The graph generators read them with the parser
+// too: `measureEntities` places a measure, `singleAggregate` finds its
+// aggregate, `withoutQualifier` makes an expression table-local,
+// `qualifiedColumns` finds the sibling fields it names and
+// `withSiblingsSpliced` puts their SQL in their place, and `requalified` moves
+// an inherited expression onto the entity inheriting it.
 //
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SUPPORTED_AGGREGATES = exports.STRING_LITERAL = void 0;
-exports.escapeRegExp = escapeRegExp;
-exports.blankStringLiterals = blankStringLiterals;
-exports.mapOutsideStringLiterals = mapOutsideStringLiterals;
-exports.referencedEntityNames = referencedEntityNames;
-exports.stripQualifier = stripQualifier;
+exports.SUPPORTED_AGGREGATES = void 0;
+exports.unusedName = unusedName;
+exports.withoutQualifier = withoutQualifier;
+exports.withSiblingsSpliced = withSiblingsSpliced;
+exports.qualifiedColumns = qualifiedColumns;
+exports.selfReferenceMessage = selfReferenceMessage;
+exports.requalified = requalified;
+exports.measureEntities = measureEntities;
 exports.sqlWithoutComments = sqlWithoutComments;
 exports.fieldBindingWithoutComments = fieldBindingWithoutComments;
 exports.columnReferences = columnReferences;
 exports.columnsForSource = columnsForSource;
 exports.entitiesReached = entitiesReached;
 exports.fieldsReadOn = fieldsReadOn;
+exports.singleAggregate = singleAggregate;
 exports.isSingleAggregate = isSingleAggregate;
 exports.isColumnName = isColumnName;
 const ir_1 = require("./ir");
+const sql_identifiers_1 = require("./sql_identifiers");
 const sql_parser_1 = require("./sql_parser");
-// Matches a single- or double-quoted SQL string literal, honoring backslash
-// escapes. (Triple-quoted / raw literals are uncommon in these expressions and
-// are treated as ordinary text.)
-exports.STRING_LITERAL = /'(?:\\.|[^'\\])*'|"(?:\\.|[^"\\])*"/g;
-// Escapes a string so it can be embedded literally in a RegExp.
-function escapeRegExp(s) {
-    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
-// Replaces string-literal contents with blanks of equal length, so scanning sees
-// literal-free text without shifting any offsets.
-function blankStringLiterals(expression) {
-    return expression.replace(exports.STRING_LITERAL, m => ' '.repeat(m.length));
-}
-// Applies `fn` only to the parts of `expression` that lie outside string
-// literals, leaving each literal verbatim.
-function mapOutsideStringLiterals(expression, fn) {
+// The dialect a graph generator reads `dialect` in: an ANSI_SQL text, or a
+// text with no dialect, is read as BigQuery.
+function graphReading(dialect) {
+    return !dialect || dialect === 'ANSI_SQL' ? 'BIGQUERY' : dialect;
+}
+// Each `<name>.` qualifier that `expression`, read in `dialect`, writes before
+// a column, for a name in `names`, as indexes into the text's tokens, in the
+// order written. A name matches case-sensitively, bare or quoted as the
+// dialect quotes an identifier, and not after a dot, so the second `orders` in
+// the struct path `orders.orders.id` is not one. The SQL parser decides which
+// candidates are qualifiers, so a string literal, a comment or a function
+// namespace such as `NET.` in `NET.HOST(orders.url)` holds none. The parser
+// reads each candidate as a placeholder name, so one it reserves as a keyword,
+// such as `Date` in `Date.days`, still reads as a qualifier. When the parser
+// cannot read the text even so, every candidate is taken as a qualifier.
+// Undefined when the engine cannot tokenize the text.
+function qualifiersIn(expression, names, dialect) {
+    const tokens = (0, sql_parser_1.sqlTokens)(expression, dialect);
+    if (!tokens)
+        return undefined;
+    const chars = Array.from(expression);
+    const asWritten = (t) => chars.slice(t.span.start, t.span.end).join('');
+    const candidates = [];
+    tokens.forEach((t, i) => {
+        if (names.has(t.text) && tokens[i + 1]?.token_type === 'DOT' &&
+            tokens[i - 1]?.token_type !== 'DOT' &&
+            (t.token_type === 'QUOTED_IDENTIFIER' || asWritten(t) === t.text)) {
+            candidates.push(i);
+        }
+    });
+    if (!candidates.length)
+        return { tokens, at: [] };
+    // A placeholder stem the text does not hold.
+    const stem = unusedName(expression, 'kcmd_qualifier_');
+    let text = '';
+    let end = 0;
+    candidates.forEach((i, k) => {
+        text += chars.slice(end, tokens[i].span.start).join('') + stem + k;
+        end = tokens[i].span.end;
+    });
+    text += chars.slice(end).join('');
+    const columns = columnReferences(text, dialect);
+    const at = !columns ? candidates : candidates.filter((_, k) => columns.some(c => c.qualifier?.toLowerCase() === stem + k));
+    return { tokens, at };
+}
+// `base`, a lowercase name, with underscores added until `text` does not hold
+// it in any case.
+function unusedName(text, base) {
+    let name = base;
+    while (text.toLowerCase().includes(name))
+        name += '_';
+    return name;
+}
+// `expression` without each `<qualifier>.` it writes before a column (see
+// qualifiersIn), so it reads the columns of the qualifier's own table. The
+// rest of the text stays as written. The text is read in `dialect`; an
+// ANSI_SQL text, or one with no dialect, is read as BigQuery, as the graph
+// generators read it. Returns `expression` itself when it writes no such
+// qualifier or the engine cannot tokenize it.
+function withoutQualifier(expression, qualifier, dialect) {
+    return spliced(expression, qualifier, graphReading(dialect), new Map());
+}
+// `expression`, BigQuery SQL on `qualifier`'s table, as withoutQualifier gives
+// it, except that each `<qualifier>.<field>` whose field `siblings` holds is
+// replaced, whole, by the SQL it maps to, as given. The graph generators put
+// the SQL of each sibling field an expression names in its place so (see
+// graph_ddl.fieldSql).
+function withSiblingsSpliced(expression, qualifier, siblings) {
+    return spliced(expression, qualifier, 'BIGQUERY', siblings);
+}
+// `expression`, read in `dialect`, without each `<qualifier>.` it writes
+// before a column (see qualifiersIn), and with each `<qualifier>.<column>`
+// whose column `replacements` holds replaced, whole, by the SQL it maps to.
+function spliced(expression, qualifier, dialect, replacements) {
+    const read = qualifiersIn(expression, new Set([qualifier]), dialect);
+    if (!read?.at.length)
+        return expression;
+    const { tokens, at } = read;
+    const chars = Array.from(expression);
     let out = '';
-    let last = 0;
-    for (const m of expression.matchAll(exports.STRING_LITERAL)) {
-        out += fn(expression.slice(last, m.index));
-        out += m[0];
-        last = m.index + m[0].length;
+    let end = 0;
+    for (const i of at) {
+        out += chars.slice(end, tokens[i].span.start).join('');
+        const column = tokens[i + 2];
+        const replacement = column && replacements.get(nameOf(column, chars));
+        if (replacement !== undefined) {
+            out += replacement;
+            end = column.span.end;
+        }
+        else {
+            // The qualifier, its dot, and what lies between the dot and the column.
+            end = column?.span.start ?? tokens[i + 1].span.end;
+        }
     }
-    out += fn(expression.slice(last));
-    return out;
-}
-// Builds a regex matching an `<entity>.` qualifier, including the BigQuery
-// backtick-quoted form (`` `entity`. ``). A negative lookbehind keeps the name
-// from matching inside a larger identifier (e.g. `customer_orders.`) or after a
-// dot in a struct path (e.g. `orders.customer.id`), and the optional backticks
-// let it match whether or not the identifier is quoted.
-function entityQualifier(name, flags = '') {
-    return new RegExp(`(?<![\\w\`.])\`?${escapeRegExp(name)}\`?\\.`, flags);
-}
-// Returns the entity names whose `<name>.` qualifier appears in an expression,
-// in the order they first appear, ignoring text inside string literals.
-// Matching is case-sensitive (the emitter's behavior).
-function referencedEntityNames(expression, entityNames) {
-    const scannable = blankStringLiterals(expression);
-    const hits = [];
-    for (const name of entityNames) {
-        const m = entityQualifier(name).exec(scannable);
-        if (m)
-            hits.push({ name, at: m.index });
+    return out + chars.slice(end).join('');
+}
+// The column written after each `<qualifier>.` that `expression` writes before
+// a column (see qualifiersIn), without its quotes, in the order written, so
+// ``orders.a + `orders`.`b`.c`` gives `a` and `b`. The text is read in
+// `dialect`, as withoutQualifier reads it, so a qualifier the parser reserves,
+// such as `Date` in `Date.days`, gives its column too. Undefined when the
+// engine cannot tokenize the text.
+function qualifiedColumns(expression, qualifier, dialect) {
+    const read = qualifiersIn(expression, new Set([qualifier]), graphReading(dialect));
+    if (!read)
+        return undefined;
+    const chars = Array.from(expression);
+    return read.at.filter(i => read.tokens[i + 2])
+        .map(i => nameOf(read.tokens[i + 2], chars));
+}
+// The name token `t` of the text whose characters are `chars` gives, as
+// written, without its quotes.
+function nameOf(t, chars) {
+    return t.token_type === 'QUOTED_IDENTIFIER' ?
+        t.text :
+        chars.slice(t.span.start, t.span.end).join('');
+}
+// The error for a field of `owner` that names itself. `cycle` starts at that
+// field and runs through the fields it names back to it, and `where` follows
+// the field's name, as ` in model 'm' (doc)` does. The graph renders a field
+// that names a sibling field from that sibling's own SQL (see
+// graph_ddl.fieldSql), so a field that reaches itself has none.
+function selfReferenceMessage(owner, cycle, where = '') {
+    const [field, ...through] = cycle;
+    return `field '${owner}.${field}'${where} names itself` +
+        (through.length ?
+            ` through ${through.map(n => `'${owner}.${n}'`).join(', ')}` :
+            '') +
+        `; a field expression may name other fields of its entity, but not ` +
+        `itself, directly or through other fields` +
+        (through.length ? '' :
+            `; to read the column of that name, write it ` +
+                `without the qualifier: '${(0, sql_identifiers_1.quoteIfReserved)(field)}'`);
+}
+// `expression` with each `<from>.` qualifier it writes before a column (see
+// qualifiersIn) renamed `<to>.`, quoted as it was written. The rest of the
+// text stays as written. The text is read in `dialect`, as withoutQualifier
+// reads it. Returns `expression` itself when it writes no such qualifier or
+// the engine cannot tokenize it.
+function requalified(expression, from, to, dialect) {
+    const read = qualifiersIn(expression, new Set([from]), graphReading(dialect));
+    if (!read?.at.length)
+        return expression;
+    const { tokens, at } = read;
+    const chars = Array.from(expression);
+    let out = '';
+    let end = 0;
+    for (const i of at) {
+        const { start, end: after } = tokens[i].span;
+        out += chars.slice(end, start).join('') +
+            chars.slice(start, after).join('').replace(from, () => to);
+        end = after;
     }
-    return hits.sort((a, b) => a.at - b.at).map(h => h.name);
+    return out + chars.slice(end).join('');
 }
-// Removes the `<entity>.` qualifier (bare or backtick-quoted) so an expression
-// references table-local columns, without touching text inside string literals.
-function stripQualifier(expression, entity) {
-    const re = entityQualifier(entity, 'g');
-    return mapOutsideStringLiterals(expression, seg => seg.replace(re, ''));
+// The entities from `entityNames` whose qualifier a metric's BigQuery SQL
+// `expression` writes before a column (see qualifiersIn), deduplicated in the
+// order written, or else `entity`, the metric's anchor, when given. The
+// BigQuery generator places the metric's measure on the entity this gives
+// when it gives one, and a BigQuery push rejects a metric it gives several or
+// none for (see validate.ts).
+function measureEntities(expression, entityNames, entity) {
+    const read = qualifiersIn(expression, new Set(entityNames), 'BIGQUERY');
+    const reached = [...new Set(read?.at.map(i => read.tokens[i].text) ?? [])];
+    return reached.length || !entity ? reached : [entity];
 }
 // `text`, written in `dialect`, with its comments removed. An ANSI_SQL text, or
 // a text with no dialect, is read as BigQuery, as the loader and the graph
 // generators read it.
 function sqlWithoutComments(text, dialect) {
-    return (0, sql_parser_1.withoutComments)(text, !dialect || dialect === 'ANSI_SQL' ? 'BIGQUERY' : dialect);
+    return (0, sql_parser_1.withoutComments)(text, graphReading(dialect));
 }
 // `field`'s binding, as fieldBinding gives it, with its comments removed.
 // Undefined when the field is unbound. The target text is read in
@@ -124,8 +246,11 @@ function columnReferences(expression, dialect) {
 // an `ANSI_SQL` entry as its own SQL. When the sources do not imply a single
 // dialect, the generic parser reads the text, and any bare identifier that
 // BigQuery's parser does not also read as a bare column (such as a `MONTH`
-// date part or a double-quoted string literal) is filtered out.
+// date part or a double-quoted string literal) is filtered out. When their
+// dialect is null, which no lookup read, an `ANSI_SQL` text is not read.
 function columnsForSource(text, dialect, impliedDialect) {
+    if (dialect === 'ANSI_SQL' && impliedDialect === null)
+        return undefined;
     if (dialect === 'ANSI_SQL' && impliedDialect) {
         return columnReferences(text, impliedDialect);
     }
@@ -165,15 +290,18 @@ function fieldsReadOn(columns, entityName) {
 // The aggregates BigQuery accepts in a MEASURE, its complete list. BigQuery
 // rejects any other there, such as COUNTIF or APPROX_COUNT_DISTINCT.
 exports.SUPPORTED_AGGREGATES = ['SUM', 'AVG', 'COUNT', 'MIN', 'MAX'];
-// Whether `expression`, read in `dialect`, is one of SUPPORTED_AGGREGATES over
-// one operand, or COUNT(*), with at most DISTINCT or ALL. The operand holds no
-// other aggregate, window or subquery.
-function isSingleAggregate(expression, dialect) {
+// When `expression`, read in `dialect`, is one of SUPPORTED_AGGREGATES over
+// one operand, or COUNT(*), with at most DISTINCT or ALL, and the operand holds
+// no other aggregate, window or subquery: the function's name as written, the
+// operand as written without the parentheses around it (so
+// `COUNT(DISTINCT(x))` gives `x`), and whether the call is DISTINCT. COUNT(*)
+// gives the operand `*`. Undefined otherwise.
+function singleAggregate(expression, dialect) {
     const node = unwrapped((0, sql_parser_1.sqlExpressionTree)(expression, dialect));
     const kind = node && Object.keys(node).length === 1 ? Object.keys(node)[0] :
         undefined;
     if (!kind || !exports.SUPPORTED_AGGREGATES.includes(kind.toUpperCase())) {
-        return false;
+        return undefined;
     }
     const call = node[kind];
     const star = kind === 'count' && call.star === true && !call.this;
@@ -181,12 +309,57 @@ function isSingleAggregate(expression, dialect) {
     if (!star &&
         (!operand || operand.star || operand.tuple ||
             nestsAggregateOrSubquery(operand))) {
-        return false;
+        return undefined;
     }
     // The parser keeps the call's name in `name` or `original_name`.
     const known = new Set(['this', 'star', 'distinct', 'name', 'original_name']);
-    return Object.entries(call).every(([key, v]) => known.has(key) || v === null || v === undefined ||
-        v === false || (Array.isArray(v) && v.length === 0));
+    if (!Object.entries(call).every(([key, v]) => known.has(key) || v === null || v === undefined ||
+        v === false || (Array.isArray(v) && v.length === 0))) {
+        return undefined;
+    }
+    // The call as written: its name, `(`, DISTINCT or ALL if written, the
+    // operand and `)`, inside any parentheses around the whole call.
+    const tokens = unparenthesized((0, sql_parser_1.sqlTokens)(expression, dialect) ?? []);
+    if (tokens.length < 4 || tokens[1].token_type !== 'L_PAREN' ||
+        tokens[tokens.length - 1].token_type !== 'R_PAREN') {
+        return undefined;
+    }
+    let inner = tokens.slice(2, -1);
+    if (inner[0]?.token_type === 'DISTINCT' || inner[0]?.token_type === 'ALL') {
+        inner = inner.slice(1);
+    }
+    inner = unparenthesized(inner);
+    if (!inner.length)
+        return undefined;
+    const chars = Array.from(expression);
+    return {
+        fn: tokens[0].text,
+        operand: chars.slice(inner[0].span.start, inner[inner.length - 1].span.end)
+            .join(''),
+        distinct: call.distinct === true,
+    };
+}
+// Whether `expression`, read in `dialect`, is a single aggregate (see
+// singleAggregate), the form a BigQuery measure takes.
+function isSingleAggregate(expression, dialect) {
+    return singleAggregate(expression, dialect) !== undefined;
+}
+// `tokens` without the parentheses around all of them.
+function unparenthesized(tokens) {
+    while (tokens.length >= 2 && tokens[0].token_type === 'L_PAREN') {
+        let depth = 0;
+        let closesAt = -1;
+        for (let i = 0; i < tokens.length && closesAt < 0; i++) {
+            if (tokens[i].token_type === 'L_PAREN')
+                depth++;
+            if (tokens[i].token_type === 'R_PAREN' && --depth === 0)
+                closesAt = i;
+        }
+        if (closesAt !== tokens.length - 1)
+            break;
+        tokens = tokens.slice(1, -1);
+    }
+    return tokens;
 }
 // The parser's tree `node` without the parentheses and comments around it.
 function unwrapped(node) {