@google-cloud/kcmd 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,258 @@
+import * as z from 'zod';
+import { DialectExpression, Entity, Executor, Field, Metric, ProfileSpec, SemanticModel } from './ir';
+import { DeclaredConcept } from './resolve_inheritance';
+export interface LoadOptions {
+    dialect?: string;
+    bindingOptional?: boolean;
+    sourceDialects?: ReadonlyMap<string, string>;
+    warnUnacceptedSource?: boolean;
+    fieldTextChecked?: boolean;
+}
+export interface LoadResult {
+    models: SemanticModel[];
+    warnings: string[];
+}
+export declare class SemanticModelError extends Error {
+}
+export declare const HALF_BOUND_JOIN_PROBLEM: string;
+export declare function joinLengthProblem(from: number, to: number): string;
+export declare function joinLengthMessage(relationship: string, from: number, to: number): string;
+export declare function undefinedEndpointProblem(side: 'from' | 'to', dataset: string): string;
+export declare const DEFAULT_DIALECT = "BIGQUERY";
+export declare const OSSIE_VERSION = "0.2.0.dev0";
+export declare const GOOGLE_VERSION = "0.2.0.dev0/google";
+/**
+ * The declared format version, as stored on the IR
+ * (`SemanticModel.version`).
+ */
+export type FormatVersion = NonNullable<SemanticModel['version']>;
+export declare function isFormatVersion(v: string): v is FormatVersion;
+/**
+ * The location of an IR construct in documents of a given format version:
+ * - `'native'`: a direct key on the YAML object (`deployments:`, `extends:`)
+ * - `'file'`: a `<model>.profile.<name>.yaml` sidecar file (`profiles`)
+ * - `'block'`: a `GOOGLE` `custom_extensions` block on the owning YAML object
+ * - `'none'`: unsupported in this format version (rejected on load, warned and
+ *   omitted on write)
+ */
+export type ConstructPlacement = 'native' | 'file' | 'block' | 'none';
+type Placements<K extends string> = Readonly<Record<K, ConstructPlacement>>;
+/**
+ * The construct placements for a single format version, grouped by owning YAML
+ * object level.
+ */
+export interface ConstructPlacements {
+    readonly model: Placements<'profiles' | 'deployments' | 'actions' | 'constraints'>;
+    readonly dataset: Placements<'extends' | 'abstract'>;
+    readonly relationship: Placements<'description'>;
+    readonly metric: Placements<'entity'>;
+}
+/**
+ * Where each format version places each Google extension construct. Other
+ * differences between the versions, such as required bindings and datatype
+ * casing, are checked where they are read.
+ */
+export declare const FORMAT_VERSION_PLACEMENT: Readonly<Record<FormatVersion, ConstructPlacements>>;
+declare const expressionSchema: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+    dialects: z.ZodArray<z.ZodObject<{
+        dialect: z.ZodString;
+        expression: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>]>;
+export declare function noSqlReason(text: string, dialect: string, entity?: string): string | undefined;
+export declare function listed(problems: string[], conjunction?: string): string | undefined;
+export declare function plural(n: number, one: string, many: string): string;
+export declare function expressionDocOf(f: Pick<Field, 'expression' | 'dialects' | 'stringForm' | 'importedExpression' | 'importedDialect'>): string | {
+    dialects: DialectExpression[];
+} | undefined;
+export declare function noSqlProblemOf(x: Pick<Field, 'expression' | 'dialects' | 'stringForm' | 'importedExpression' | 'importedDialect'>, entity?: string): string | undefined;
+export declare function inheritedNoSqlProblems(entities: Entity[], concepts: Map<string, DeclaredConcept>, problemOf?: (f: Field, entity?: string) => string | undefined): string[];
+type ExpressionDoc = z.infer<typeof expressionSchema>;
+export declare const GOOGLE_VENDOR = "GOOGLE";
+export declare function isGoogleVendor(vendorName: unknown): boolean;
+export declare function hasGoogleBlock(exts: ReadonlyArray<{
+    vendor_name?: unknown;
+}> | undefined): boolean;
+export declare function setsAKeyTwice(data: string): boolean;
+/**
+ * The profiles the model in a vanilla document carries in its GOOGLE blocks,
+ * read as a load reads them, without loading the rest of the model. So a
+ * caller finds a profile even in a model that does not load, as it finds a
+ * profile file. Only the profiles in the model's GOOGLE blocks are read, and
+ * the load reports a problem with any other key. Empty for a document that is
+ * not a vanilla model.
+ *
+ * A profile's field binding that is not blank needs the SQL parser, so call
+ * `loadSqlEngine()` first. Without it, this throws the parser's plain Error.
+ *
+ * A GOOGLE block whose shape the load rejects is read too, and the load
+ * reports its shape. Its profiles may be in data written as a JSON string or
+ * as a YAML mapping, or listed beside `vendor_name` with no data. Throws
+ * SemanticModelError on profiles a load rejects, on data that sets `profiles`
+ * twice or a key twice inside them, and on data that is not a JSON object in
+ * a block whose shape the load accepts.
+ *
+ * Text that is not valid YAML is read as far as it parses. A document whose
+ * root keys are all strings, and that sets `version` once, to a string other
+ * than the vanilla one, gives none when each YAML error is a key set twice, an
+ * alias whose anchor is not set, or more aliases than a load expands. Otherwise
+ * its profiles are read as in text that parses, and only when that reading is
+ * unambiguous. Each YAML error is a key set twice or an alias whose anchor is
+ * not set, since any other error, such as a bad indent, can move the blocks,
+ * cut them short or change the version. The document sets `version` once, to
+ * the vanilla one, and `semantic_model` at most once. Its model sets
+ * `custom_extensions` at most once, and each block that is a mapping sets
+ * `vendor_name` once, to a string. A GOOGLE block sets `data` and `profiles` at
+ * most once each, and holds no alias. Every key of a mapping on that path is a
+ * string, so not an alias or a merge key, and no value on it is an alias. No
+ * key is set twice inside `custom_extensions`. When any of these fails, when a
+ * GOOGLE block cannot be read, or when a load rejects its profiles, it throws
+ * the error a load reports for the text. So does a vanilla model whose text has
+ * more aliases than a load expands, or a merge key whose value is not a
+ * mapping.
+ */
+export declare function googleBlockProfiles(text: string): ProfileSpec[];
+/**
+ * The `version` the model document `text` sets, as googleBlockProfiles reads
+ * it. Valid YAML gives its version. Past a YAML error, the version is read
+ * only when every root key is a string and the root sets `version` once, to a
+ * string. Each error must be a key set twice, an alias whose anchor is not
+ * set, or more aliases than a load expands. Undefined otherwise, and when the
+ * text sets no string version.
+ */
+export declare function modelDocumentVersion(text: string): string | undefined;
+export declare function isRecord(v: unknown): v is Record<string, any>;
+export declare function modelAiContexts(doc: unknown): Generator<{
+    ai: Record<string, unknown>;
+    label: string;
+}>;
+/**
+ * Loads YAML or JSON text (a document in the AI-first semantics format) into
+ * the Semantic Model IR. `yaml.parse` accepts JSON too, so both are supported.
+ *
+ * A document with a field or metric expression that is not blank needs the SQL
+ * parser, so call `loadSqlEngine()` first. Without it, this throws a plain
+ * Error instead of a SemanticModelError.
+ */
+export declare function loadModels(text: string, opts?: LoadOptions): LoadResult;
+/**
+ * Converts an already-parsed document object into the Semantic Model IR. Throws
+ * on a structurally invalid document; softer, lossy conversions are reported in
+ * `warnings` rather than thrown.
+ */
+export declare function fromDocument(doc: unknown, opts?: LoadOptions): LoadResult;
+export declare function inferMetricEntities(metric: Pick<Metric, 'name' | 'authoredEntity' | 'expression' | 'importedExpression' | 'importedDialect' | 'dialects'>, entityNames: string[], preferred?: string, impliedDialect?: string | null, version?: FormatVersion): {
+    referenced: string[];
+    warning?: string;
+};
+export declare function entityAndMetricWarnings(model: SemanticModel, preferred?: string, profiled?: boolean): string[];
+type FieldExpression = Pick<Field, 'expression' | 'dialects' | 'stringForm' | 'importedExpression' | 'importedDialect'>;
+export declare function parseFieldExpression(raw: unknown, where: string, dialect: string, entity: string): FieldExpression;
+export declare function readFieldExpression(raw: unknown, where: string, dialect: string, problemOf: (doc: ExpressionDoc) => string | undefined): FieldExpression;
+export declare function parseFieldBinding(binding: Pick<Field, 'expression' | 'dialects' | 'stringForm' | 'importedExpression' | 'importedDialect'>, where: string, dialect: string, entity: string): FieldExpression;
+export declare function parseExecutor(raw: unknown, where: string): Executor;
+interface ParsedSource {
+    dataSource: string;
+    authoredSource: string;
+    sourceDialect?: string;
+}
+export interface CloudSqlTable {
+    project: string;
+    location: string;
+    instance: string;
+    resourceName: string;
+    inSchema: boolean;
+}
+export declare function cloudSqlTableOf(source: string): CloudSqlTable | undefined;
+export type SourceTable = {
+    resourceName: string;
+    project: string;
+} & ({
+    system: 'bigquery';
+    dataset: string;
+    table: string;
+} | {
+    system: 'biglake';
+    catalog: string;
+    hive: boolean;
+} | {
+    system: 'spanner';
+    instance: string;
+} | {
+    system: 'alloydb';
+    location: string;
+});
+export declare function sourceTableOf(source: string): SourceTable | undefined;
+export declare function asResourceUri(value: string): string;
+export declare function asResourceName(value: string): string;
+export declare function resourceUriFix(uri: string): string;
+export declare function oldSourceForm(source: string): string | undefined;
+export declare const NO_SPACE = "kcmd cannot name a table whose name holds a space";
+export declare const TABLE_FORMS: {
+    bigquery: string;
+    spanner: string;
+    alloydb: string;
+    cloudsql: string;
+    cloudsqlSchema: string;
+    biglake: string;
+    biglakeHive: string;
+};
+export declare function fillForm(form: string, parts: string[]): string | undefined;
+export declare function dottedPartProblem(parts: string[], form: string, service?: boolean): string | undefined;
+export declare function catalogNameSegments(path: string, colons?: boolean): string[];
+export declare function hasUnquotedWhitespace(source: string): boolean;
+export declare function databaseOf(written: string): string | undefined;
+export declare function isAcceptedSource(source: string | undefined): boolean;
+export declare function writtenSource(entity: {
+    authoredSource?: string;
+    dataSource?: string;
+}): string;
+export declare function sourceToDataSource(source: string): string;
+export declare const DIALECT_OF_ENTRY_TYPE: Record<string, string>;
+export declare const DIALECT_OF_FQN_PREFIX: Map<string, string>;
+export declare const ENTRY_NAME_FORM = "projects/<p>/locations/<l>/entryGroups/<g>/entries/<id>";
+export declare const THIRD_PARTY_SOURCE: string;
+export interface ThirdPartyEntry {
+    project: string;
+    location: string;
+    name: string;
+}
+export declare function thirdPartyEntryOf(source: string): ThirdPartyEntry | undefined;
+export declare function bindsThirdPartyTable(entity: {
+    authoredSource?: string;
+}): boolean;
+export declare function dialectLookupKey(source: string): string | undefined;
+export declare function spannerDatabaseOf(source: string): string | undefined;
+export declare function isGoogleCloudForm(source: string): boolean;
+export declare function parseSource(source: string, opts: LoadOptions, ctx: string, warnings?: string[], importVersion?: FormatVersion): ParsedSource;
+export declare function bareNameSegments(name: string, bigQuery: boolean): string[];
+export declare function bareNameParts(name: string, bigQuery: boolean): Array<{
+    text: string;
+    quoted: boolean;
+}>;
+export interface LoadedModel {
+    document: string;
+    model: SemanticModel;
+}
+export interface LoadedModels {
+    models: LoadedModel[];
+    warnings: string[];
+    error?: string;
+}
+/**
+ * Loads every authored document into the IR once, so a multi-destination push
+ * parses and validates each model a single time and fans the result out to each
+ * deploy leg (BigQuery, Knowledge Catalog) rather than re-parsing per leg.
+ *
+ * A parse/schema error is returned as `error` (naming the document) rather than
+ * thrown, mirroring how the deploy legs previously reported it; loader warnings
+ * are prefixed with their document name.
+ *
+ * Each document needs the SQL parser as loadModels does, so call
+ * `loadSqlEngine()` first. Without it, this throws the parser's plain Error.
+ */
+export declare function loadSemanticModels(docs: {
+    name: string;
+    text: string;
+}[], opts?: LoadOptions): LoadedModels;
+export {};