@databricks/sdk-uc-externalmetadata 0.0.0-dev → 0.1.0-dev.2

package/src/v1/client.ts

@@ -0,0 +1,268 @@
+// Code generated from API definition by Databricks SDK Generator. DO NOT EDIT.
+
+import {VERSION as AUTH_VERSION} from '@databricks/sdk-auth';
+import {createDefault} from '@databricks/sdk-core/clientinfo';
+import type {Logger} from '@databricks/sdk-core/logger';
+import {NoOpLogger} from '@databricks/sdk-core/logger';
+import type {CallOptions} from '@databricks/sdk-options/call';
+import type {ClientOptions} from '@databricks/sdk-options/client';
+import type {HttpClient} from '@databricks/sdk-core/http';
+import {newHttpClient} from './transport';
+import {
+  buildHttpRequest,
+  executeCall,
+  executeHttpCall,
+  marshalRequest,
+  parseResponse,
+} from './utils';
+import pkgJson from '../../package.json' with {type: 'json'};
+import type {
+  CreateExternalMetadataRequest,
+  DeleteExternalMetadataRequest,
+  ExternalMetadata,
+  GetExternalMetadataRequest,
+  ListExternalMetadataRequest,
+  ListExternalMetadataResponseV2,
+  UpdateExternalMetadataRequest,
+} from './model';
+import {
+  marshalExternalMetadataSchema,
+  unmarshalExternalMetadataSchema,
+  unmarshalListExternalMetadataResponseV2Schema,
+} from './model';
+
+// Package identity segment for this client to be used in the User-Agent header.
+const PACKAGE_SEGMENT = {
+  key: 'sdk-js-' + pkgJson.name.replace(/^@[^/]+\/sdk-/, ''),
+  value: pkgJson.version,
+};
+
+export class ExternalMetadataClient {
+  private readonly host: string;
+  // Workspace ID used to route workspace-level calls on unified hosts (SPOG).
+  // When set, workspace-level methods send X-Databricks-Org-Id on every
+  // request.
+  private readonly workspaceId: string | undefined;
+  private readonly httpClient: HttpClient;
+  private readonly logger: Logger;
+  // User-Agent header value. Composed once at construction from
+  // createDefault() merged with this package's identity and the active
+  // credential's name.
+  private readonly userAgent: string;
+
+  constructor(options: ClientOptions) {
+    if (options.host === undefined) {
+      throw new Error('Host is required.');
+    }
+    this.host = options.host.replace(/\/$/, '');
+    this.workspaceId = options.workspaceId;
+    this.logger = options.logger ?? new NoOpLogger();
+    const info = createDefault()
+      .with(PACKAGE_SEGMENT)
+      .with({key: 'sdk-js-auth', value: AUTH_VERSION})
+      .with({key: 'auth', value: options.credentials?.name() ?? 'default'});
+    this.userAgent = info.toString();
+    this.httpClient = newHttpClient(options);
+  }
+
+  /**
+   * Creates a new external metadata object in the parent metastore if the caller is a metastore admin or has the **CREATE_EXTERNAL_METADATA** privilege.
+   * Grants **BROWSE** to all account users upon creation by default.
+   */
+  async createExternalMetadataV2(
+    req: CreateExternalMetadataRequest,
+    options?: CallOptions
+  ): Promise<ExternalMetadata> {
+    const url = `${this.host}/api/2.0/lineage-tracking/external-metadata`;
+    const body = marshalRequest(
+      req.externalMetadata,
+      marshalExternalMetadataSchema
+    );
+    let resp: ExternalMetadata | undefined;
+    const call = async (callSignal?: AbortSignal): Promise<void> => {
+      const headers = new Headers({'Content-Type': 'application/json'});
+      if (this.workspaceId !== undefined) {
+        headers.set('X-Databricks-Org-Id', this.workspaceId);
+      }
+      headers.set('User-Agent', this.userAgent);
+      const httpReq = buildHttpRequest('POST', url, headers, callSignal, body);
+      const respBody = await executeHttpCall({
+        request: httpReq,
+        httpClient: this.httpClient,
+        logger: this.logger,
+      });
+      resp = parseResponse(respBody, unmarshalExternalMetadataSchema);
+    };
+    await executeCall(call, options);
+    if (resp === undefined) {
+      throw new Error('operation completed without a result.');
+    }
+    return resp;
+  }
+
+  /**
+   * Deletes the external metadata object that matches the supplied name.
+   * The caller must be a metastore admin, the owner of the external metadata object, or a user that has the **MANAGE** privilege.
+   */
+  async deleteExternalMetadataV2(
+    req: DeleteExternalMetadataRequest,
+    options?: CallOptions
+  ): Promise<void> {
+    const url = `${this.host}/api/2.0/lineage-tracking/external-metadata/${req.name ?? ''}`;
+    const call = async (callSignal?: AbortSignal): Promise<void> => {
+      const headers = new Headers();
+      if (this.workspaceId !== undefined) {
+        headers.set('X-Databricks-Org-Id', this.workspaceId);
+      }
+      headers.set('User-Agent', this.userAgent);
+      const httpReq = buildHttpRequest('DELETE', url, headers, callSignal);
+      await executeHttpCall({
+        request: httpReq,
+        httpClient: this.httpClient,
+        logger: this.logger,
+      });
+    };
+    await executeCall(call, options);
+  }
+
+  /**
+   * Gets the specified external metadata object in a metastore.
+   * The caller must be a metastore admin, the owner of the external metadata object, or a user that has the **BROWSE** privilege.
+   */
+  async getExternalMetadataV2(
+    req: GetExternalMetadataRequest,
+    options?: CallOptions
+  ): Promise<ExternalMetadata> {
+    const url = `${this.host}/api/2.0/lineage-tracking/external-metadata/${req.name ?? ''}`;
+    let resp: ExternalMetadata | undefined;
+    const call = async (callSignal?: AbortSignal): Promise<void> => {
+      const headers = new Headers();
+      if (this.workspaceId !== undefined) {
+        headers.set('X-Databricks-Org-Id', this.workspaceId);
+      }
+      headers.set('User-Agent', this.userAgent);
+      const httpReq = buildHttpRequest('GET', url, headers, callSignal);
+      const respBody = await executeHttpCall({
+        request: httpReq,
+        httpClient: this.httpClient,
+        logger: this.logger,
+      });
+      resp = parseResponse(respBody, unmarshalExternalMetadataSchema);
+    };
+    await executeCall(call, options);
+    if (resp === undefined) {
+      throw new Error('operation completed without a result.');
+    }
+    return resp;
+  }
+
+  /**
+   * Gets an array of external metadata objects in the metastore.
+   * If the caller is the metastore admin, all external metadata objects will be retrieved.
+   * Otherwise, only external metadata objects that the caller has **BROWSE** on will be retrieved.
+   * There is no guarantee of a specific ordering of the elements in the array.
+   */
+  async listExternalMetadataV2(
+    req: ListExternalMetadataRequest,
+    options?: CallOptions
+  ): Promise<ListExternalMetadataResponseV2> {
+    const url = `${this.host}/api/2.0/lineage-tracking/external-metadata`;
+    const params = new URLSearchParams();
+    if (req.pageSize !== undefined) {
+      params.append('page_size', String(req.pageSize));
+    }
+    if (req.pageToken !== undefined) {
+      params.append('page_token', req.pageToken);
+    }
+    const query = params.toString();
+    const fullUrl = query !== '' ? `${url}?${query}` : url;
+    let resp: ListExternalMetadataResponseV2 | undefined;
+    const call = async (callSignal?: AbortSignal): Promise<void> => {
+      const headers = new Headers();
+      if (this.workspaceId !== undefined) {
+        headers.set('X-Databricks-Org-Id', this.workspaceId);
+      }
+      headers.set('User-Agent', this.userAgent);
+      const httpReq = buildHttpRequest('GET', fullUrl, headers, callSignal);
+      const respBody = await executeHttpCall({
+        request: httpReq,
+        httpClient: this.httpClient,
+        logger: this.logger,
+      });
+      resp = parseResponse(
+        respBody,
+        unmarshalListExternalMetadataResponseV2Schema
+      );
+    };
+    await executeCall(call, options);
+    if (resp === undefined) {
+      throw new Error('operation completed without a result.');
+    }
+    return resp;
+  }
+
+  async *listExternalMetadataV2Iter(
+    req: ListExternalMetadataRequest,
+    options?: CallOptions
+  ): AsyncGenerator<ExternalMetadata> {
+    const pageReq: ListExternalMetadataRequest = {...req};
+    for (;;) {
+      const resp = await this.listExternalMetadataV2(pageReq, options);
+      for (const item of resp.externalMetadata ?? []) {
+        yield item;
+      }
+      if (resp.nextPageToken === undefined || resp.nextPageToken === '') {
+        return;
+      }
+      pageReq.pageToken = resp.nextPageToken;
+    }
+  }
+
+  /**
+   * Updates the external metadata object that matches the supplied name. The caller can only update either the owner or other metadata fields in one request.
+   * The caller must be a metastore admin, the owner of the external metadata object, or a user that has the **MODIFY** privilege.
+   * If the caller is updating the owner, they must also have the **MANAGE** privilege.
+   */
+  async updateExternalMetadataV2(
+    req: UpdateExternalMetadataRequest,
+    options?: CallOptions
+  ): Promise<ExternalMetadata> {
+    const url = `${this.host}/api/2.0/lineage-tracking/external-metadata/${req.externalMetadata?.name ?? ''}`;
+    const params = new URLSearchParams();
+    if (req.updateMask !== undefined) {
+      params.append('update_mask', req.updateMask.toString());
+    }
+    const query = params.toString();
+    const fullUrl = query !== '' ? `${url}?${query}` : url;
+    const body = marshalRequest(
+      req.externalMetadata,
+      marshalExternalMetadataSchema
+    );
+    let resp: ExternalMetadata | undefined;
+    const call = async (callSignal?: AbortSignal): Promise<void> => {
+      const headers = new Headers({'Content-Type': 'application/json'});
+      if (this.workspaceId !== undefined) {
+        headers.set('X-Databricks-Org-Id', this.workspaceId);
+      }
+      headers.set('User-Agent', this.userAgent);
+      const httpReq = buildHttpRequest(
+        'PATCH',
+        fullUrl,
+        headers,
+        callSignal,
+        body
+      );
+      const respBody = await executeHttpCall({
+        request: httpReq,
+        httpClient: this.httpClient,
+        logger: this.logger,
+      });
+      resp = parseResponse(respBody, unmarshalExternalMetadataSchema);
+    };
+    await executeCall(call, options);
+    if (resp === undefined) {
+      throw new Error('operation completed without a result.');
+    }
+    return resp;
+  }
+}

package/src/v1/index.ts

@@ -0,0 +1,18 @@
+// Code generated from API definition by Databricks SDK Generator. DO NOT EDIT.
+
+export {ExternalMetadataClient} from './client';
+
+export {SystemType} from './model';
+
+export type {
+  CreateExternalMetadataRequest,
+  DeleteExternalMetadataRequest,
+  ExternalMetadata,
+  ExternalMetadata_PropertiesEntry,
+  GetExternalMetadataRequest,
+  ListExternalMetadataRequest,
+  ListExternalMetadataResponseV2,
+  UpdateExternalMetadataRequest,
+} from './model';
+
+export {externalMetadataFieldMask} from './model';

package/src/v1/model.ts

@@ -0,0 +1,221 @@
+// Code generated from API definition by Databricks SDK Generator. DO NOT EDIT.
+
+import {Temporal} from '@js-temporal/polyfill';
+import {FieldMask} from '@databricks/sdk-core/wkt';
+import type {FieldMaskSchema} from '@databricks/sdk-core/wkt';
+import {z} from 'zod';
+
+export enum SystemType {
+  SYSTEM_TYPE_UNSPECIFIED = 'SYSTEM_TYPE_UNSPECIFIED',
+  OTHER = 'OTHER',
+  TABLEAU = 'TABLEAU',
+  POWER_BI = 'POWER_BI',
+  LOOKER = 'LOOKER',
+  KAFKA = 'KAFKA',
+  SAP = 'SAP',
+  ORACLE = 'ORACLE',
+  SALESFORCE = 'SALESFORCE',
+  WORKDAY = 'WORKDAY',
+  MYSQL = 'MYSQL',
+  POSTGRESQL = 'POSTGRESQL',
+  MICROSOFT_SQL_SERVER = 'MICROSOFT_SQL_SERVER',
+  SERVICENOW = 'SERVICENOW',
+  AMAZON_REDSHIFT = 'AMAZON_REDSHIFT',
+  AZURE_SYNAPSE = 'AZURE_SYNAPSE',
+  SNOWFLAKE = 'SNOWFLAKE',
+  GOOGLE_BIGQUERY = 'GOOGLE_BIGQUERY',
+  MICROSOFT_FABRIC = 'MICROSOFT_FABRIC',
+  MONGODB = 'MONGODB',
+  TERADATA = 'TERADATA',
+  CONFLUENT = 'CONFLUENT',
+  DATABRICKS = 'DATABRICKS',
+  STREAM_NATIVE = 'STREAM_NATIVE',
+}
+
+export interface CreateExternalMetadataRequest {
+  externalMetadata?: ExternalMetadata | undefined;
+}
+
+export interface DeleteExternalMetadataRequest {
+  name?: string | undefined;
+}
+
+export interface ExternalMetadata {
+  /** Name of the external metadata object. */
+  name?: string | undefined;
+  /** Type of external system. */
+  systemType?: SystemType | undefined;
+  /** Type of entity within the external system. */
+  entityType?: string | undefined;
+  /** URL associated with the external metadata object. */
+  url?: string | undefined;
+  /** User-provided free-form text description. */
+  description?: string | undefined;
+  /** List of columns associated with the external metadata object. */
+  columns?: string[] | undefined;
+  /** A map of key-value properties attached to the external metadata object. */
+  properties?: Record<string, string> | undefined;
+  /** Owner of the external metadata object. */
+  owner?: string | undefined;
+  /** Unique identifier of parent metastore. */
+  metastoreId?: string | undefined;
+  /** Time at which this external metadata object was created. */
+  createTime?: Temporal.Instant | undefined;
+  /** Username of external metadata object creator. */
+  createdBy?: string | undefined;
+  /** Time at which this external metadata object was last modified. */
+  updateTime?: Temporal.Instant | undefined;
+  /** Username of user who last modified external metadata object. */
+  updatedBy?: string | undefined;
+  /** Unique identifier of the external metadata object. */
+  id?: string | undefined;
+}
+
+// eslint-disable-next-line @typescript-eslint/naming-convention -- Proto-style nested message name.
+export interface ExternalMetadata_PropertiesEntry {
+  key?: string | undefined;
+  value?: string | undefined;
+}
+
+export interface GetExternalMetadataRequest {
+  name?: string | undefined;
+}
+
+export interface ListExternalMetadataRequest {
+  /**
+   * Specifies the maximum number of external metadata objects to return in a single response.
+   * The value must be less than or equal to 1000.
+   */
+  pageSize?: number | undefined;
+  /** Opaque pagination token to go to next page based on previous query. */
+  pageToken?: string | undefined;
+}
+
+export interface ListExternalMetadataResponseV2 {
+  externalMetadata?: ExternalMetadata[] | undefined;
+  nextPageToken?: string | undefined;
+}
+
+export interface UpdateExternalMetadataRequest {
+  externalMetadata?: ExternalMetadata | undefined;
+  updateMask?: FieldMask<ExternalMetadata> | undefined;
+}
+
+export const unmarshalExternalMetadataSchema: z.ZodType<ExternalMetadata> = z
+  .object({
+    name: z.string().optional(),
+    system_type: z.enum(SystemType).optional(),
+    entity_type: z.string().optional(),
+    url: z.string().optional(),
+    description: z.string().optional(),
+    columns: z.array(z.string()).optional(),
+    properties: z.record(z.string(), z.string()).optional(),
+    owner: z.string().optional(),
+    metastore_id: z.string().optional(),
+    create_time: z
+      .string()
+      .transform(s => Temporal.Instant.from(s))
+      .optional(),
+    created_by: z.string().optional(),
+    update_time: z
+      .string()
+      .transform(s => Temporal.Instant.from(s))
+      .optional(),
+    updated_by: z.string().optional(),
+    id: z.string().optional(),
+  })
+  .transform(d => ({
+    name: d.name,
+    systemType: d.system_type,
+    entityType: d.entity_type,
+    url: d.url,
+    description: d.description,
+    columns: d.columns,
+    properties: d.properties,
+    owner: d.owner,
+    metastoreId: d.metastore_id,
+    createTime: d.create_time,
+    createdBy: d.created_by,
+    updateTime: d.update_time,
+    updatedBy: d.updated_by,
+    id: d.id,
+  }));
+
+export const unmarshalListExternalMetadataResponseV2Schema: z.ZodType<ListExternalMetadataResponseV2> =
+  z
+    .object({
+      external_metadata: z
+        .array(z.lazy(() => unmarshalExternalMetadataSchema))
+        .optional(),
+      next_page_token: z.string().optional(),
+    })
+    .transform(d => ({
+      externalMetadata: d.external_metadata,
+      nextPageToken: d.next_page_token,
+    }));
+
+export const marshalExternalMetadataSchema: z.ZodType = z
+  .object({
+    name: z.string().optional(),
+    systemType: z.enum(SystemType).optional(),
+    entityType: z.string().optional(),
+    url: z.string().optional(),
+    description: z.string().optional(),
+    columns: z.array(z.string()).optional(),
+    properties: z.record(z.string(), z.string()).optional(),
+    owner: z.string().optional(),
+    metastoreId: z.string().optional(),
+    createTime: z
+      .any()
+      .transform((d: Temporal.Instant) => d.toString())
+      .optional(),
+    createdBy: z.string().optional(),
+    updateTime: z
+      .any()
+      .transform((d: Temporal.Instant) => d.toString())
+      .optional(),
+    updatedBy: z.string().optional(),
+    id: z.string().optional(),
+  })
+  .transform(d => ({
+    name: d.name,
+    system_type: d.systemType,
+    entity_type: d.entityType,
+    url: d.url,
+    description: d.description,
+    columns: d.columns,
+    properties: d.properties,
+    owner: d.owner,
+    metastore_id: d.metastoreId,
+    create_time: d.createTime,
+    created_by: d.createdBy,
+    update_time: d.updateTime,
+    updated_by: d.updatedBy,
+    id: d.id,
+  }));
+
+const externalMetadataFieldMaskSchema: FieldMaskSchema = {
+  columns: {wire: 'columns'},
+  createTime: {wire: 'create_time'},
+  createdBy: {wire: 'created_by'},
+  description: {wire: 'description'},
+  entityType: {wire: 'entity_type'},
+  id: {wire: 'id'},
+  metastoreId: {wire: 'metastore_id'},
+  name: {wire: 'name'},
+  owner: {wire: 'owner'},
+  properties: {wire: 'properties'},
+  systemType: {wire: 'system_type'},
+  updateTime: {wire: 'update_time'},
+  updatedBy: {wire: 'updated_by'},
+  url: {wire: 'url'},
+};
+
+export function externalMetadataFieldMask(
+  ...paths: string[]
+): FieldMask<ExternalMetadata> {
+  return FieldMask.build<ExternalMetadata>(
+    paths,
+    externalMetadataFieldMaskSchema
+  );
+}

package/src/v1/transport.ts

@@ -0,0 +1,73 @@
+// Code generated from API definition by Databricks SDK Generator. DO NOT EDIT.
+
+import type {Credentials} from '@databricks/sdk-auth';
+import {defaultCredentials} from '@databricks/sdk-auth/credentials';
+import type {
+  HttpClient,
+  HttpRequest,
+  HttpResponse,
+} from '@databricks/sdk-core/http';
+import {newFetchHttpClient} from '@databricks/sdk-core/http';
+import type {ClientOptions} from '@databricks/sdk-options/client';
+
+/** Creates a new HTTP client with the given options. */
+export function newHttpClient(options?: ClientOptions): HttpClient {
+  const opts = options ?? {};
+
+  // If an HTTP client is provided, use it as-is. Throw if other options are
+  // also set, since they would be silently ignored.
+  if (opts.httpClient !== undefined) {
+    if (opts.credentials !== undefined || opts.timeout !== undefined) {
+      throw new Error(
+        'httpClient cannot be combined with credentials or timeout'
+      );
+    }
+    return opts.httpClient;
+  }
+
+  const credentials = opts.credentials ?? defaultCredentials();
+
+  const base = newFetchHttpClient();
+  let client: HttpClient = new AuthHttpClient(base, credentials);
+
+  if (opts.timeout !== undefined) {
+    client = new TimeoutHttpClient(client, opts.timeout);
+  }
+
+  return client;
+}
+
+/** Wraps an HttpClient and adds authentication headers to requests. */
+class AuthHttpClient implements HttpClient {
+  constructor(
+    private readonly base: HttpClient,
+    private readonly credentials: Credentials
+  ) {}
+
+  async send(request: HttpRequest): Promise<HttpResponse> {
+    const authHeaders = await this.credentials.authHeaders();
+    // Do not modify the original request.
+    const headers = new Headers(request.headers);
+    for (const h of authHeaders) {
+      headers.set(h.key, h.value);
+    }
+    return this.base.send({...request, headers});
+  }
+}
+
+/** Wraps an HttpClient and applies a default timeout to requests. */
+class TimeoutHttpClient implements HttpClient {
+  constructor(
+    private readonly base: HttpClient,
+    private readonly timeout: number
+  ) {}
+
+  async send(request: HttpRequest): Promise<HttpResponse> {
+    const timeoutSignal = AbortSignal.timeout(this.timeout);
+    const signal =
+      request.signal !== undefined
+        ? AbortSignal.any([request.signal, timeoutSignal])
+        : timeoutSignal;
+    return this.base.send({...request, signal});
+  }
+}