@google-cloud/kcmd 0.1.0 → 0.2.0

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

@@ -1,7 +1,7 @@
 "use strict";
 // The dialect of a Cloud SQL table written as its resource name, or of a
 // third-party table written as its entry name, read from the table's
-// Knowledge Catalog entry.
+// Knowledge Catalog entry, and the dialect of a Spanner table's database.
 //
 // The resource name cannot say the dialect: a MySQL table has no schema, but a
 // PostgreSQL table and a SQL Server table have the same shape. Dataplex keeps an
@@ -16,9 +16,12 @@
 // fullyQualifiedName, so its parts say whether the entry is a table's or, for
 // example, a schema's.
 //
-// This is the only place kcmd makes a network call to learn a dialect. A
-// command looks every such source up once, before it loads the model, and
-// passes the dialects to the load (LoadOptions.sourceDialects).
+// Knowledge Catalog's Spanner entries leave their dialect empty, so a Spanner
+// table's dialect is its database's `databaseDialect`, read by databases.get.
+//
+// This is the only place kcmd looks up a source's dialect. A command looks
+// every such source up once, before it loads the model, and passes the
+// dialects to the load (LoadOptions.sourceDialects).
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -54,10 +57,12 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.sourceDialects = sourceDialects;
+exports.tableFqnParts = tableFqnParts;
 exports.sourcesToLookUp = sourcesToLookUp;
 const yaml = __importStar(require("yaml"));
 const loader_1 = require("./loader");
 const catalog_entry_1 = require("./catalog_entry");
+const parameters_1 = require("./parameters");
 const yaml_options_1 = require("./yaml_options");
 // The dialect each entrySource.system gives, in lower case.
 const DIALECT_OF_ENTRY_SYSTEM = new Map([...loader_1.DIALECT_OF_FQN_PREFIX, ['postgres', 'POSTGRES']]);
@@ -70,14 +75,16 @@ const TABLE_FQN_PARTS = new Map([
     ['postgresql', ['host', 'database', 'schema', 'table']],
     ['sqlserver', ['host', 'database', 'schema', 'table']],
 ]);
-// Looks up the dialect of every Cloud SQL and third-party table the model and
-// profile files `texts` write (see sourcesToLookUp), once per table, in
-// parallel. With `thirdParty` false, looks up Cloud SQL tables only. Makes no
-// call when they write none. Never throws: a lookup that fails is reported in
-// `errors`.
-async function sourceDialects(texts, catalog, { thirdParty = true } = {}) {
-    // Keyed as dialectLookupKey gives, so both spellings of one table are one
-    // lookup.
+// Looks up, once each and in parallel, the dialect of every Cloud SQL and
+// third-party table the files `texts` write (see sourcesToLookUp), and of every
+// Spanner database they name. Without `spanner`, a Spanner database gives
+// SPANNER, the dialect kcmd's Spanner store speaks, with no call.
+// `thirdParty: false` skips third-party tables. Never throws: a failed lookup
+// goes to `errors`.
+async function sourceDialects(texts, catalog, { thirdParty = true, spanner } = {}) {
+    // Keyed as dialectLookupKey gives, so both spellings of one table, and the
+    // tables of one Spanner database, are one lookup. A database's lookup names
+    // the first of its tables.
     const lookups = new Map();
     for (const source of sourcesToLookUp(texts)) {
         const table = (0, loader_1.cloudSqlTableOf)(source);
@@ -87,32 +94,42 @@ async function sourceDialects(texts, catalog, { thirdParty = true } = {}) {
         const entry = thirdParty ? (0, loader_1.thirdPartyEntryOf)(source) : undefined;
         if (entry)
             lookups.set(entry.name, () => thirdPartyDialect(catalog, entry));
+        const database = (0, loader_1.spannerDatabaseOf)(source);
+        if (database && !lookups.has(database)) {
+            lookups.set(database, spanner ? () => spannerDialect(spanner, database, source) :
+                async () => ({ dialect: 'SPANNER' }));
+        }
     }
     const dialects = new Map();
     const databases = new Map();
     const errors = [];
+    const unread = [];
     await Promise.all([...lookups].map(async ([key, lookUp]) => {
         const got = await lookUp();
         if ('error' in got)
             errors.push(got.error);
         else
             dialects.set(key, got.dialect);
+        if ('unread' in got)
+            unread.push(got.error);
         if ('database' in got && got.database)
             databases.set(key, got.database);
     }));
     errors.sort();
-    return { dialects, databases, errors };
+    unread.sort();
+    return { dialects, databases, errors, unread };
 }
 // The dialect of a Cloud SQL table, by its entry's type.
 async function cloudSqlDialect(catalog, table) {
     const at = `source '${table.resourceName}'`;
     const res = await (0, catalog_entry_1.lookupSystemEntry)(catalog, 'cloudsql', table.project, table.location, table.resourceName);
     if ('error' in res)
-        return { error: `${at}: ${res.error}` };
+        return { error: `${at}: ${res.error}`, unread: true };
     // Dataplex answers 403 both when the entry does not exist and when the
     // caller may not read it, so the message names both causes.
     if ('unreadable' in res) {
         return {
+            unread: true,
             error: `${at}: kcmd reads a Cloud SQL table's dialect from its ` +
                 `Knowledge Catalog entry, and could not read it. Turn on Dataplex ` +
                 `integration for instance '${table.instance}' (gcloud sql ` +
@@ -131,6 +148,27 @@ async function cloudSqlDialect(catalog, table) {
             `not a Cloud SQL table or view type kcmd knows (${Object.keys(loader_1.DIALECT_OF_ENTRY_TYPE).join(', ')}).`,
     };
 }
+// The dialect of the Spanner database `database`, which `source` names a
+// table of, by its databaseDialect.
+async function spannerDialect(spanner, database, source) {
+    const [, , project, , instance, , name] = database.split('/');
+    const failed = (why) => ({
+        unread: true,
+        error: `source '${source}': kcmd reads its Spanner database's SQL ` +
+            `dialect, and could not read database ${project}/${instance}/${name}: ${why}`,
+    });
+    try {
+        const res = await spanner.getDatabase(project, instance, name);
+        if (res.status !== 200) {
+            return failed((0, parameters_1.storeMessage)(res.message, res.status));
+        }
+        const postgres = res.result?.databaseDialect === 'POSTGRESQL';
+        return { dialect: postgres ? 'POSTGRES' : 'SPANNER' };
+    }
+    catch (err) {
+        return failed(err?.message ?? String(err));
+    }
+}
 // The dialect of a third-party table, by its entry's fullyQualifiedName or
 // entrySource.system, and the database the fullyQualifiedName names. An entry
 // whose fullyQualifiedName names no table or view is rejected.
@@ -138,9 +176,10 @@ async function thirdPartyDialect(catalog, { project, location, name }) {
     const at = `source '${name}'`;
     const res = await (0, catalog_entry_1.read)('looking up its Knowledge Catalog entry', () => catalog.lookupEntry(project, location, name));
     if ('error' in res)
-        return { error: `${at}: ${res.error}` };
+        return { error: `${at}: ${res.error}`, unread: true };
     if ('unreadable' in res) {
         return {
+            unread: true,
             error: `${at} names no table Knowledge Catalog knows about. The entry ` +
                 `may not exist, or you may not be allowed to read it. kcmd reads a ` +
                 `third-party table's dialect from its entry, so add the table to ` +
@@ -177,14 +216,12 @@ async function thirdPartyDialect(catalog, { project, location, name }) {
             `fullyQualifiedName.`,
     };
 }
-// The database the fullyQualifiedName `fqn` of a third-party table or view
-// names: a Snowflake account, a MySQL or SQL Server host, a PostgreSQL host
-// and database, or a Databricks metastore. Each account and host is in lower
-// case. Undefined when `fqn` names no table or view. Such a name has another
-// number of parts than TABLE_FQN_PARTS gives, or a subtype, such as the
-// `routine:` of a routine. Dataplex reads a `databricks:table:` or
-// `databricks:view:` name as the same table as the `databricks:` name.
-function databaseOfFqn(fqn) {
+// The prefix of the fullyQualifiedName `fqn` of a third-party table or view,
+// and its unquoted parts, such as `snowflake` and ['acme', 'retail', 'public',
+// 'orders'] for `snowflake:acme.retail.public.orders`. Undefined when `fqn`
+// has another number of parts than TABLE_FQN_PARTS gives, or a subtype other
+// than Databricks' `table:` and `view:`.
+function tableFqnParts(fqn) {
     // The subtype holds no backtick, so a colon inside a quoted host and port
     // stays in the path. A colon in an unquoted database, schema or table
     // name stays in its segment when it comes after the name's first backtick.
@@ -195,19 +232,31 @@ function databaseOfFqn(fqn) {
         (prefix === 'databricks' && (subtype === 'table' || subtype === 'view'));
     if (!parts || !tableSubtype || seg.length !== parts.length)
         return undefined;
+    return { prefix, parts: seg };
+}
+// The database the fullyQualifiedName `fqn` of a third-party table or view
+// names: a Snowflake account, a MySQL or SQL Server host, a PostgreSQL host
+// and database, or a Databricks metastore. Each account and host is in lower
+// case. Undefined when `fqn` names no table or view.
+function databaseOfFqn(fqn) {
+    const table = tableFqnParts(fqn);
+    if (!table)
+        return undefined;
+    const { prefix, parts } = table;
     const n = prefix === 'postgresql' ? 2 : 1;
     // A Snowflake account and a host name ignore letter case.
     if (prefix !== 'databricks')
-        seg[0] = seg[0].toLowerCase();
-    return [prefix, ...seg.slice(0, n)].join('/');
+        parts[0] = parts[0].toLowerCase();
+    return [prefix, ...parts.slice(0, n)].join('/');
 }
-// Every Cloud SQL table and third-party entry the model and profile files
-// `texts` write. A Cloud SQL table counts as a resource name or resource URI
-// anywhere, JSON strings included. An entry name counts as a `source` value in
-// the YAML or in a GOOGLE block's JSON `data`, unless it sits in ai_context,
-// an action parameter's default or another vendor's block. Values are read
-// from the parsed YAML, so a name in a comment is not collected. A file that
-// does not parse collects nothing; the load reports it.
+// Every Cloud SQL table, Spanner table and third-party entry the model and
+// profile files `texts` write. A Cloud SQL table counts as a resource name or
+// resource URI anywhere, JSON strings included. A Spanner table or an entry
+// name counts as a `source` value in the YAML or in a GOOGLE block's JSON
+// `data`, unless it sits in ai_context, an action parameter's default or
+// another vendor's block. Values are read from the parsed YAML, so a name in a
+// comment is not collected. A file that does not parse collects nothing; the
+// load reports it.
 function sourcesToLookUp(texts) {
     const found = new Set();
     // `key` names the member that holds `value`. `opaque` marks a value whose
@@ -217,7 +266,8 @@ function sourcesToLookUp(texts) {
     const visit = (value, key, opaque = false) => {
         if (typeof value === 'string') {
             if ((0, loader_1.cloudSqlTableOf)(value) ||
-                (key === 'source' && !opaque && (0, loader_1.thirdPartyEntryOf)(value))) {
+                (key === 'source' && !opaque &&
+                    ((0, loader_1.thirdPartyEntryOf)(value) || (0, loader_1.spannerDatabaseOf)(value)))) {
                 found.add(value.trim());
             }
             else if (/^\s*[[{]/.test(value)) {

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

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

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

@@ -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;