@google-cloud/kcmd 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,129 @@
+import * as context from '../gcp/context';
+import { CatalogClient, Entry } from '../gcp/dataplex';
+import type { OverviewSidecar } from '../layouts/semantic-model';
+import { FileCopy } from './kc_custom_types';
+import * as kcEmit from './knowledge_catalog';
+import { LoadedModel } from './loader';
+export interface KcDeployOptions {
+    project: string;
+    location: string;
+    entryGroup: string;
+    systemTypeProject?: string;
+    systemTypeLocation?: string;
+    emitExpressions?: boolean;
+    v2Aspects?: boolean;
+    sourceFiles?: FileCopy[];
+    overviews?: ReadonlyMap<string, OverviewSidecar>;
+    fileCopyTypeChecked?: boolean;
+    onWarnings?: (warnings: readonly string[]) => void;
+    validateOnly?: boolean;
+    forceRemove?: boolean;
+    entryCreateTries?: number;
+    entryCreateRetryMs?: number;
+}
+export interface KcDeployResult {
+    success: boolean;
+    details?: string;
+    warnings: string[];
+    created: number;
+    updated: number;
+    deleted: number;
+    linked: number;
+    unlinked: number;
+    plan: string[];
+}
+/** One authored model paired with the catalog resources it emitted. */
+export interface EmittedModel {
+    model: string;
+    resources: kcEmit.KcResources;
+}
+/**
+ * The read-only preflight output handed to `applyKnowledgeCatalog`. Holds the
+ * emitted catalog resources, the pre-write entry-group snapshot, any emitter
+ * warnings, and the human-readable plan so `applyKnowledgeCatalog` can write
+ * without repeating generation or listing.
+ */
+export interface KcPreparedDeploy {
+    emitted: EmittedModel[];
+    existing: Entry[];
+    warnings: string[];
+    plan: string[];
+}
+/**
+ * Runs every read-only check for a Knowledge Catalog push without writing to
+ * the catalog.
+ *
+ * The method performs the following actions:
+ *   1. Translates the IR models into catalog resources.
+ *   2. Verifies that exactly one model is being deployed and that each file
+ *      copy fits in one aspect, builds the dry-run plan, and returns early
+ *      when `opts.validateOnly` is set.
+ *   3. Lists the destination entry group and fails if an unrecognized model's
+ *      anchor entry is present without `--force-remove`.
+ *   4. Verifies that every custom entry type and aspect type required by the
+ *      model exists in the target project. Skips the file-copy type when
+ *      `opts.fileCopyTypeChecked` is set.
+ *   5. Returns the emitted resources, entry-group listing, warnings, and plan
+ *      as `prepared` for `applyKnowledgeCatalog`.
+ * With `opts.v2Aspects` set, step 2 also checks every aspect's size.
+ */
+export declare function preflightKnowledgeCatalog(models: LoadedModel[], ctx: context.ApiContext, opts: KcDeployOptions): Promise<{
+    prepared?: KcPreparedDeploy;
+    result?: KcDeployResult;
+}>;
+/**
+ * Writes a preflight-checked Knowledge Catalog deployment.
+ *
+ * The method performs the following actions:
+ *   1. Removes foreign models when `--force-remove` is set.
+ *   2. Writes each emitted model's entries and relationship links and deletes
+ *      any orphaned links and entries.
+ */
+export declare function applyKnowledgeCatalog(prepared: KcPreparedDeploy, ctx: context.ApiContext, opts: KcDeployOptions): Promise<KcDeployResult>;
+/**
+ * Deploys every authored model's Knowledge Catalog resources.
+ *
+ * Runs `preflightKnowledgeCatalog` followed by `applyKnowledgeCatalog`, and
+ * passes the warnings to `opts.onWarnings` between the two.
+ */
+export declare function deployKnowledgeCatalog(models: LoadedModel[], ctx: context.ApiContext, opts: KcDeployOptions): Promise<KcDeployResult>;
+/**
+ * Publishes models that are already mapped to catalog resources.
+ *
+ * Origin-agnostic wrapper over `preflightEmittedModels` and
+ * `applyKnowledgeCatalog` for callers with their own emitter (such as LookML).
+ */
+export declare function deployEmittedModels(emitted: EmittedModel[], emitWarnings: string[], ctx: context.ApiContext, opts: KcDeployOptions): Promise<KcDeployResult>;
+/** The error for an entry group that would receive more than one model. */
+export declare function oneModelPerEntryGroupMessage(entryGroup: string, models: number): string;
+export declare const MAX_ASPECT_DATA_BYTES: number;
+/**
+ * Checks a push's file copies before anything is written. Returns the error
+ * to report, or undefined when every copy fits in one aspect and no two file
+ * names map to one entry id.
+ *
+ * Push calls it before any graph deploys. Every copy of a model shares the
+ * model's part of the entry id, so two file names collide when their slugs
+ * do.
+ */
+export declare function checkFileCopies(files: readonly FileCopy[]): string | undefined;
+/**
+ * The emitter's warnings for `models` with v2Aspects on, and why push's
+ * catalog leg cannot write them: an emit error or an aspect too large to
+ * store. Calls no service.
+ */
+export declare function checkCatalogAspects(models: LoadedModel[], opts: KcDeployOptions): {
+    error?: string;
+    warnings: string[];
+};
+/**
+ * Checks that each custom type in `typeIds` exists in the destination
+ * project. Returns the error to report, or undefined when every one exists.
+ *
+ * Push also calls it before any graph deploys, for the file-copy type every
+ * push with v2Aspects off needs. Push then sets `fileCopyTypeChecked`, so the
+ * catalog preflight looks up only the other custom types.
+ */
+export declare function checkCustomTypes(cat: CatalogClient, dest: {
+    project: string;
+}, typeIds: readonly string[]): Promise<string | undefined>;