@lancedb/lancedb 0.39.0-beta.8 → 0.40.0-beta.0

package/dist/arrow.d.ts

@@ -14,6 +14,22 @@ export type FieldLike = Field | {
     nullable: boolean;
     metadata?: Map<string, string>;
 };
+/**
+ * Create an Arrow field backed by LanceDB's JSON extension type.
+ *
+ * @param name - The field name.
+ * @param nullable - Whether the field accepts null values.
+ * @example
+ * ```ts
+ * import { connect, makeJsonField } from "@lancedb/lancedb";
+ * import { Schema } from "apache-arrow";
+ *
+ * const schema = new Schema([makeJsonField("metadata")]);
+ * const db = await connect("/path/to/database");
+ * await db.createTable("items", [{ metadata: '{"source":"api"}' }], { schema });
+ * ```
+ */
+export declare function makeJsonField(name: string, nullable?: boolean): Field;
 export type DataLike = import("apache-arrow").Data | {
     type: any;
     length: number;

package/dist/arrow.js

@@ -17,6 +17,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MakeArrowTableOptions = exports.VectorColumnOptions = void 0;
+exports.makeJsonField = makeJsonField;
 exports.isMultiVector = isMultiVector;
 exports.isIntoVector = isIntoVector;
 exports.extractVectorBuffer = extractVectorBuffer;
@@ -62,6 +63,24 @@ const registry_1 = require("./embedding/registry");
 const sanitize_1 = require("./sanitize");
 const schema_1 = require("./schema");
 __exportStar(require("apache-arrow"), exports);
+/**
+ * Create an Arrow field backed by LanceDB's JSON extension type.
+ *
+ * @param name - The field name.
+ * @param nullable - Whether the field accepts null values.
+ * @example
+ * ```ts
+ * import { connect, makeJsonField } from "@lancedb/lancedb";
+ * import { Schema } from "apache-arrow";
+ *
+ * const schema = new Schema([makeJsonField("metadata")]);
+ * const db = await connect("/path/to/database");
+ * await db.createTable("items", [{ metadata: '{"source":"api"}' }], { schema });
+ * ```
+ */
+function makeJsonField(name, nullable = true) {
+    return new apache_arrow_1.Field(name, new apache_arrow_1.Utf8(), nullable, new Map([["ARROW:extension:name", "arrow.json"]]));
+}
 function isMultiVector(value) {
     return Array.isArray(value) && isIntoVector(value[0]);
 }

package/dist/catalog.d.ts

@@ -0,0 +1,46 @@
+import { Connection } from "./connection";
+import { HeaderProvider } from "./header";
+import { ListDatabasesResponse, Catalog as NativeCatalog, CatalogOptions as NativeCatalogOptions } from "./native.js";
+import { OAuthConfig } from "./oauth";
+/** Options shared by a catalog and the database connections it returns. */
+export interface CatalogOptions extends Omit<NativeCatalogOptions, "oauthConfig"> {
+    oauthConfig?: OAuthConfig;
+    /** Called for each request to supply authentication headers. */
+    headerProvider?: HeaderProvider | (() => Record<string, string> | Promise<Record<string, string>>);
+}
+export type { ListDatabasesResponse } from "./native.js";
+/** A remote catalog manages databases through the server's root namespace. */
+export declare class Catalog {
+    private readonly inner;
+    /** @hidden */
+    constructor(inner: NativeCatalog);
+    /** The root namespace endpoint. */
+    get uri(): string;
+    /** Create a database, or open an existing database when existOk is true. */
+    createDatabase(name: string, options?: {
+        existOk?: boolean;
+    }): Promise<Connection>;
+    /** Connect to an existing database by its logical name. */
+    connectDatabase(name: string): Promise<Connection>;
+    /** Drop an empty database. The server rejects nonempty databases. */
+    dropDatabase(name: string, options?: {
+        ignoreMissing?: boolean;
+    }): Promise<void>;
+    /** List one page of databases; pass pageToken from a response for the next page. */
+    listDatabases(options?: {
+        limit?: number;
+        pageToken?: string;
+    }): Promise<ListDatabasesResponse>;
+}
+/**
+ * Connect to an HTTP(S) catalog endpoint. Catalog requests omit database-selection
+ * headers; opened database connections inherit authentication and client options.
+ *
+ * @example
+ * ```ts
+ * const catalog = await connectCatalog("https://my-server.example", { apiKey: "secret" });
+ * const db = await catalog.createDatabase("analytics", { existOk: true });
+ * const page = await catalog.listDatabases({ limit: 20 });
+ * ```
+ */
+export declare function connectCatalog(endpoint: string, options?: CatalogOptions): Promise<Catalog>;

package/dist/catalog.js

@@ -0,0 +1,63 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright The LanceDB Authors
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Catalog = void 0;
+exports.connectCatalog = connectCatalog;
+const connection_1 = require("./connection");
+const native_js_1 = require("./native.js");
+/** A remote catalog manages databases through the server's root namespace. */
+class Catalog {
+    inner;
+    /** @hidden */
+    constructor(inner) {
+        this.inner = inner;
+    }
+    /** The root namespace endpoint. */
+    get uri() {
+        return this.inner.uri;
+    }
+    /** Create a database, or open an existing database when existOk is true. */
+    async createDatabase(name, options = {}) {
+        return new connection_1.LocalConnection(await this.inner.createDatabase(name, options.existOk));
+    }
+    /** Connect to an existing database by its logical name. */
+    async connectDatabase(name) {
+        return new connection_1.LocalConnection(await this.inner.connectDatabase(name));
+    }
+    /** Drop an empty database. The server rejects nonempty databases. */
+    async dropDatabase(name, options = {}) {
+        await this.inner.dropDatabase(name, options.ignoreMissing);
+    }
+    /** List one page of databases; pass pageToken from a response for the next page. */
+    async listDatabases(options = {}) {
+        if (options.limit !== undefined &&
+            (!Number.isInteger(options.limit) ||
+                options.limit <= 0 ||
+                options.limit > 2147483647)) {
+            throw new Error("Database list limit must be an integer between 1 and 2147483647");
+        }
+        return this.inner.listDatabases(options.limit, options.pageToken);
+    }
+}
+exports.Catalog = Catalog;
+/**
+ * Connect to an HTTP(S) catalog endpoint. Catalog requests omit database-selection
+ * headers; opened database connections inherit authentication and client options.
+ *
+ * @example
+ * ```ts
+ * const catalog = await connectCatalog("https://my-server.example", { apiKey: "secret" });
+ * const db = await catalog.createDatabase("analytics", { existOk: true });
+ * const page = await catalog.listDatabases({ limit: 20 });
+ * ```
+ */
+async function connectCatalog(endpoint, options = {}) {
+    const { headerProvider, ...nativeOptions } = options;
+    const provider = headerProvider
+        ? new native_js_1.JsHeaderProvider(async () => typeof headerProvider === "function"
+            ? headerProvider()
+            : headerProvider.getHeaders())
+        : undefined;
+    return new Catalog(await native_js_1.Catalog.new(endpoint, nativeOptions, provider));
+}

package/dist/connection.d.ts

@@ -256,18 +256,19 @@ export declare abstract class Connection {
     /**
      * Define a materialized view named `name` over the table `source`.
      *
-     * The view is created empty, with the query recorded in its schema
-     * metadata; `view.refresh()` computes the rows. The view is a normal
-     * table: it can be queried, indexed and searched, and it appears in
-     * `tableNames`. The source table must have stable row ids (create it with
+     * The view is populated before creation returns. Set `withNoData` to create
+     * only its definition and empty backing table. The view is a normal table:
+     * it can be queried, indexed and searched, and it appears in `tableNames`.
+     * The source table must have stable row ids (create it with
      * the `newTableEnableStableRowIds` storage option); they keep the view's
      * provenance valid across source compactions and cannot be enabled after
-     * a table exists. Local databases only.
+     * a table exists.
      */
     abstract createMaterializedView(name: string, source: string, options?: {
         select?: MaterializedViewSelect;
         where?: string;
         limit?: number;
+        withNoData?: boolean;
     }): Promise<MaterializedView>;
     /**
      * Open the materialized view named `name`.
@@ -281,6 +282,22 @@ export declare abstract class Connection {
      * Found by reading every table's schema, so this costs an open per table.
      */
     abstract listMaterializedViews(): Promise<string[]>;
+    /**
+     * Drop the materialized view named `name`.
+     *
+     * The view may become unavailable before physical cleanup finishes. Use
+     * {@link dropMaterializedViewAsync} to retain and wait for the cleanup job.
+     *
+     * Rejects a table that exists but is not a materialized view.
+     */
+    abstract dropMaterializedView(name: string, namespacePath?: string[]): Promise<void>;
+    /**
+     * Start dropping the materialized view named `name` and return its cleanup
+     * job without waiting for completion.
+     *
+     * Rejects a table that exists but is not a materialized view.
+     */
+    abstract dropMaterializedViewAsync(name: string, namespacePath?: string[]): Promise<Job>;
     abstract openTable(name: string, namespacePath?: string[], options?: Partial<OpenTableOptions>): Promise<Table>;
     /**
      * Creates a new Table and initialize it with new data.
@@ -460,9 +477,12 @@ export declare class LocalConnection extends Connection {
         select?: MaterializedViewSelect;
         where?: string;
         limit?: number;
+        withNoData?: boolean;
     }): Promise<MaterializedView>;
     openMaterializedView(name: string): Promise<MaterializedView>;
     listMaterializedViews(): Promise<string[]>;
+    dropMaterializedView(name: string, namespacePath?: string[]): Promise<void>;
+    dropMaterializedViewAsync(name: string, namespacePath?: string[]): Promise<Job>;
     listTables(namespacePathOrOptions?: string[] | Partial<ListTablesOptions>, options?: Partial<ListTablesOptions>): Promise<ListTablesResponse>;
     openTable(name: string, namespacePath?: string[], options?: Partial<OpenTableOptions>): Promise<Table>;
     cloneTable(targetTableName: string, sourceUri: string, options?: {

package/dist/connection.js

@@ -71,7 +71,7 @@ class LocalConnection extends Connection {
     }
     async createMaterializedView(name, source, options) {
         (0, materialized_view_1.validateNonNegativeInteger)(options?.limit, "limit");
-        const innerTable = await this.inner.createMaterializedView(name, source, (0, materialized_view_1.normalizeSelect)(options?.select), options?.where, options?.limit);
+        const innerTable = await this.inner.createMaterializedView(name, source, (0, materialized_view_1.normalizeSelect)(options?.select), options?.where, options?.limit, options?.withNoData ?? false);
         return new materialized_view_1.MaterializedView(new table_1.LocalTable(innerTable));
     }
     async openMaterializedView(name) {
@@ -81,6 +81,12 @@ class LocalConnection extends Connection {
     async listMaterializedViews() {
         return await this.inner.listMaterializedViews();
     }
+    async dropMaterializedView(name, namespacePath) {
+        return this.inner.dropMaterializedView(name, namespacePath ?? []);
+    }
+    async dropMaterializedViewAsync(name, namespacePath) {
+        return new job_1.Job(await this.inner.dropMaterializedViewAsync(name, namespacePath ?? []));
+    }
     async listTables(namespacePathOrOptions, options) {
         // Detect if first argument is namespacePath array or options object
         const namespacePath = Array.isArray(namespacePathOrOptions)

package/dist/index.d.ts

@@ -7,7 +7,7 @@ export { MaterializedView, MaterializedViewDefinition, MaterializedViewSelect, }
 export { JsHeaderProvider as NativeJsHeaderProvider } from "./native.js";
 export { instrumentLanceDbMetrics } from "./otel";
 export { AddColumnsSql, ConnectionOptions, ConnectNamespaceOptions, IndexStatistics, IndexConfig, ClientConfig, TimeoutConfig, RetryConfig, TlsConfig, OptimizeStats, CompactionStats, RemovalStats, TableStatistics, FragmentStatistics, FragmentSummaryStats, Tags, TagContents, BranchContents, MergeResult, AddResult, AddColumnsResult, RefreshColumnResult, RefreshMaterializedViewResult, AlterColumnsResult, UpdateFieldMetadataResult, DeleteResult, DropColumnsResult, UpdateResult, SplitCalculatedOptions, SplitRandomOptions, SplitHashOptions, SplitSequentialOptions, ShuffleOptions, OAuthConfig as NativeOAuthConfig, } from "./native.js";
-export { makeArrowTable, MakeArrowTableOptions, Data, VectorColumnOptions, } from "./arrow";
+export { makeArrowTable, makeJsonField, MakeArrowTableOptions, Data, VectorColumnOptions, } from "./arrow";
 export { blob, isBlobField, BlobFile } from "./blob";
 export type { BlobOptions } from "./blob";
 export { Connection, CreateTableOptions, TableNamesOptions, ListTablesOptions, OpenTableOptions, ListNamespacesOptions, CreateNamespaceOptions, DropNamespaceOptions, ListNamespacesResponse, ListTablesResponse, CreateNamespaceResponse, DropNamespaceResponse, DescribeNamespaceResponse, RenameTableOptions, } from "./connection";
@@ -17,7 +17,7 @@ export { AutoQuery, ExecutableQuery, Query, QueryBase, VectorQuery, TakeQuery, A
 export { Index, IndexOptions, IvfPqOptions, IvfRqOptions, IvfFlatOptions, HnswPqOptions, HnswSqOptions, FtsOptions, BaseTokenizer, } from "./indices";
 export { Table, Branches, BranchColumnSummary, BranchColumnChange, BranchIndexSummary, BranchRowCountSummary, CherryPickError, BranchDiff, CherryPickPreview, CherryPickResult, AddDataOptions, UpdateOptions, OptimizeOptions, Version, WriteProgress, FtsToken, TokenizeTableOptions, LsmWriteSpec, LsmStats, BucketStats, GenerationStats, MemtableStats, ColumnAlteration, FieldMetadataUpdate, } from "./table";
 export { HeaderProvider, StaticHeaderProvider, OAuthHeaderProvider, TokenResponse, } from "./header";
-export { OAuthConfig, OAuthFlowType } from "./oauth";
+export { ClientAuthMethod, OAuthConfig, OAuthFlowType, OAuthSession, SessionLogout, SessionStatus, TokenCacheOptions, } from "./oauth";
 export { MergeInsertBuilder, WriteExecutionOptions } from "./merge";
 export * as embedding from "./embedding";
 export { permutationBuilder, PermutationBuilder } from "./permutation";
@@ -247,3 +247,4 @@ export declare function connectNamespace(implName: "rest", config: RestNamespace
  * ```
  */
 export declare function connectNamespace(implName: string, properties: Record<string, string>, options?: Partial<ConnectNamespaceOptions>): Promise<Connection>;
+export { Catalog, CatalogOptions, ListDatabasesResponse, connectCatalog, } from "./catalog";

package/dist/index.js

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: Copyright The LanceDB Authors
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.packBits = exports.rerankers = exports.Scannable = exports.PermutationBuilder = exports.permutationBuilder = exports.embedding = exports.MergeInsertBuilder = exports.OAuthFlowType = exports.OAuthHeaderProvider = exports.StaticHeaderProvider = exports.HeaderProvider = exports.Branches = exports.Table = exports.Index = exports.Occur = exports.Operator = exports.FullTextQueryType = exports.BooleanQuery = exports.MultiMatchQuery = exports.BoostQuery = exports.PhraseQuery = exports.MatchQuery = exports.RecordBatchIterator = exports.TakeQuery = exports.VectorQuery = exports.QueryBase = exports.Query = exports.AutoQuery = exports.Job = exports.Session = exports.Connection = exports.BlobFile = exports.isBlobField = exports.blob = exports.VectorColumnOptions = exports.MakeArrowTableOptions = exports.makeArrowTable = exports.BranchContents = exports.TagContents = exports.Tags = exports.instrumentLanceDbMetrics = exports.NativeJsHeaderProvider = exports.MaterializedView = void 0;
+exports.connectCatalog = exports.Catalog = exports.packBits = exports.rerankers = exports.Scannable = exports.PermutationBuilder = exports.permutationBuilder = exports.embedding = exports.MergeInsertBuilder = exports.OAuthSession = exports.OAuthFlowType = exports.ClientAuthMethod = exports.OAuthHeaderProvider = exports.StaticHeaderProvider = exports.HeaderProvider = exports.Branches = exports.Table = exports.Index = exports.Occur = exports.Operator = exports.FullTextQueryType = exports.BooleanQuery = exports.MultiMatchQuery = exports.BoostQuery = exports.PhraseQuery = exports.MatchQuery = exports.RecordBatchIterator = exports.TakeQuery = exports.VectorQuery = exports.QueryBase = exports.Query = exports.AutoQuery = exports.Job = exports.Session = exports.Connection = exports.BlobFile = exports.isBlobField = exports.blob = exports.VectorColumnOptions = exports.MakeArrowTableOptions = exports.makeJsonField = exports.makeArrowTable = exports.BranchContents = exports.TagContents = exports.Tags = exports.instrumentLanceDbMetrics = exports.NativeJsHeaderProvider = exports.MaterializedView = void 0;
 exports.tokenize = tokenize;
 exports.connect = connect;
 exports.connectNamespace = connectNamespace;
@@ -24,6 +24,7 @@ Object.defineProperty(exports, "TagContents", { enumerable: true, get: function
 Object.defineProperty(exports, "BranchContents", { enumerable: true, get: function () { return native_js_3.BranchContents; } });
 var arrow_1 = require("./arrow");
 Object.defineProperty(exports, "makeArrowTable", { enumerable: true, get: function () { return arrow_1.makeArrowTable; } });
+Object.defineProperty(exports, "makeJsonField", { enumerable: true, get: function () { return arrow_1.makeJsonField; } });
 Object.defineProperty(exports, "MakeArrowTableOptions", { enumerable: true, get: function () { return arrow_1.MakeArrowTableOptions; } });
 Object.defineProperty(exports, "VectorColumnOptions", { enumerable: true, get: function () { return arrow_1.VectorColumnOptions; } });
 var blob_1 = require("./blob");
@@ -61,7 +62,9 @@ Object.defineProperty(exports, "HeaderProvider", { enumerable: true, get: functi
 Object.defineProperty(exports, "StaticHeaderProvider", { enumerable: true, get: function () { return header_1.StaticHeaderProvider; } });
 Object.defineProperty(exports, "OAuthHeaderProvider", { enumerable: true, get: function () { return header_1.OAuthHeaderProvider; } });
 var oauth_1 = require("./oauth");
+Object.defineProperty(exports, "ClientAuthMethod", { enumerable: true, get: function () { return oauth_1.ClientAuthMethod; } });
 Object.defineProperty(exports, "OAuthFlowType", { enumerable: true, get: function () { return oauth_1.OAuthFlowType; } });
+Object.defineProperty(exports, "OAuthSession", { enumerable: true, get: function () { return oauth_1.OAuthSession; } });
 var merge_1 = require("./merge");
 Object.defineProperty(exports, "MergeInsertBuilder", { enumerable: true, get: function () { return merge_1.MergeInsertBuilder; } });
 exports.embedding = require("./embedding");
@@ -179,3 +182,6 @@ async function connectNamespace(implName, configOrProperties, options) {
     const nativeConn = await native_js_1.Connection.newWithNamespace(implName, properties, finalOptions);
     return new connection_1.LocalConnection(nativeConn);
 }
+var catalog_1 = require("./catalog");
+Object.defineProperty(exports, "Catalog", { enumerable: true, get: function () { return catalog_1.Catalog; } });
+Object.defineProperty(exports, "connectCatalog", { enumerable: true, get: function () { return catalog_1.connectCatalog; } });

package/dist/materialized_view.d.ts

@@ -36,6 +36,8 @@ export declare function validateNonNegativeInteger(value: number | undefined, na
 export declare function normalizeSelect(select?: MaterializedViewSelect): [string, string][] | undefined;
 /** @internal Parse a definition off a table's stored schema metadata. */
 export declare function definitionFromMetadata(metadata: Map<string, string>, name: string): MaterializedViewDefinition;
+/** @internal Parse the backend-independent definition returned by native code. */
+export declare function definitionFromJson(raw: string, name: string): MaterializedViewDefinition;
 /**
  * A handle on a materialized view: its table plus its definition.
  *
@@ -50,7 +52,7 @@ export declare class MaterializedView {
     get name(): string;
     /** The view, as the table it is. */
     table(): Table;
-    /** The query that defines the view, read from its stored schema. */
+    /** The query that defines the view. */
     definition(): Promise<MaterializedViewDefinition>;
     /**
      * Recompute the view from its source.

package/dist/materialized_view.js

@@ -6,6 +6,7 @@ exports.MaterializedView = exports.DEFINITION_META_KEY = void 0;
 exports.validateNonNegativeInteger = validateNonNegativeInteger;
 exports.normalizeSelect = normalizeSelect;
 exports.definitionFromMetadata = definitionFromMetadata;
+exports.definitionFromJson = definitionFromJson;
 /** Schema metadata key holding a materialized view's definition. */
 exports.DEFINITION_META_KEY = "mv.definition";
 /**
@@ -42,10 +43,16 @@ function definitionFromMetadata(metadata, name) {
     if (raw === undefined) {
         throw new Error(`Table '${name}' is not a materialized view`);
     }
+    return definitionFromJson(raw, name);
+}
+/** @internal Parse the backend-independent definition returned by native code. */
+function definitionFromJson(raw, name) {
     // biome-ignore lint/suspicious/noExplicitAny: raw JSON
     const value = JSON.parse(raw);
     // "namespaced_select" keeps older readers from resolving the source at root.
-    if (value.kind !== "select" && value.kind !== "namespaced_select") {
+    if (value.kind !== undefined &&
+        value.kind !== "select" &&
+        value.kind !== "namespaced_select") {
         throw new Error(`materialized view '${name}' is defined by '${value.kind}', which this ` +
             "version of lancedb cannot refresh");
     }
@@ -89,10 +96,9 @@ class MaterializedView {
     table() {
         return this.inner;
     }
-    /** The query that defines the view, read from its stored schema. */
+    /** The query that defines the view. */
     async definition() {
-        const schema = await this.inner.schema();
-        return definitionFromMetadata(schema.metadata, this.name);
+        return definitionFromJson(await this.inner.materializedViewDefinition(), this.name);
     }
     /**
      * Recompute the view from its source.

package/dist/native.d.ts

@@ -21,6 +21,15 @@ export declare class Branches {
   cherryPick(fromBranch: string, dryRun?: boolean | undefined | null): Promise<Record<string, unknown>>
 }
 
+export declare class Catalog {
+  static new(endpoint: string, options: CatalogOptions, headerProvider?: JsHeaderProvider | undefined | null): Promise<Catalog>
+  get uri(): string
+  createDatabase(name: string, existOk?: boolean | undefined | null): Promise<Connection>
+  connectDatabase(name: string): Promise<Connection>
+  dropDatabase(name: string, ignoreMissing?: boolean | undefined | null): Promise<void>
+  listDatabases(limit?: number | undefined | null, pageToken?: string | undefined | null): Promise<ListDatabasesResponse>
+}
+
 export declare class Connection {
   /** Create a new Connection instance from the given URI. */
   static new(uri: string, options: ConnectionOptions, headerProvider?: JsHeaderProvider | undefined | null): Promise<Connection>
@@ -42,9 +51,13 @@ export declare class Connection {
    */
   createTable(name: string, buf: Buffer, mode: string, namespacePath?: Array<string> | undefined | null, storageOptions?: Record<string, string> | undefined | null): Promise<Table>
   createEmptyTable(name: string, schemaBuf: Buffer, mode: string, namespacePath?: Array<string> | undefined | null, storageOptions?: Record<string, string> | undefined | null): Promise<Table>
-  createMaterializedView(name: string, source: string, projections?: Array<Array<string>> | undefined | null, filter?: string | undefined | null, limit?: number | undefined | null): Promise<Table>
+  createMaterializedView(name: string, source: string, projections: Array<Array<string>> | undefined | null, filter: string | undefined | null, limit: number | undefined | null, withNoData: boolean): Promise<Table>
   openMaterializedView(name: string): Promise<Table>
   listMaterializedViews(): Promise<Array<string>>
+  /** Drop a materialized view. */
+  dropMaterializedView(name: string, namespacePath?: Array<string> | undefined | null): Promise<void>
+  /** Start dropping a materialized view and return its cleanup job. */
+  dropMaterializedViewAsync(name: string, namespacePath?: Array<string> | undefined | null): Promise<Job>
   openTable(name: string, namespacePath?: Array<string> | undefined | null, storageOptions?: Record<string, string> | undefined | null, indexCacheSize?: number | undefined | null): Promise<Table>
   cloneTable(targetTableName: string, sourceUri: string, targetNamespacePath: Array<string> | undefined | null, sourceVersion: number | undefined | null, sourceTag: string | undefined | null, isShallow: boolean): Promise<Table>
   /** Drop table with the name. Or raise an error if the table does not exist. */
@@ -207,6 +220,50 @@ export declare class NativeMergeInsertBuilder {
   execute(buf: Buffer): Promise<MergeResult>
 }
 
+/**
+ * Explicit OAuth session lifecycle for the persistent token cache: eager
+ * `login`, non-secret `status`, and local `logout`.
+ *
+ * A session is built from the same `OAuthConfig` used to connect (including
+ * its `tokenCache` options). A connection created with the same
+ * configuration shares the cache, so logging in here prepares tokens for
+ * later processes without any database request.
+ */
+export declare class OAuthSession {
+  /**
+   * Create a session manager for the given OAuth configuration.
+   *
+   * The configuration must enable `tokenCache` options and use a flow that
+   * supports persistent sessions (authorization code or device code).
+   */
+  constructor(config: OAuthConfig)
+  /**
+   * Eagerly run the configured authentication flow and store the session.
+   *
+   * A successful login always replaces any prior cached session for this
+   * identity; if the provider does not issue a refresh token (for example
+   * without `offline_access`), the previous record is removed and the
+   * status reports `refreshable == false`.
+   */
+  login(): Promise<SessionStatus>
+  /**
+   * Report whether a matching cached session exists, with safe metadata.
+   *
+   * This never contacts the identity provider and never exposes token
+   * values.
+   */
+  status(): Promise<SessionStatus>
+  /**
+   * Remove the matching local cached credential.
+   *
+   * This only deletes the local cache entry. It does not revoke the
+   * refresh token with the provider and does not sign out of a browser
+   * SSO session. Repeated calls succeed; `removed` reports whether a
+   * credential existed.
+   */
+  logout(): Promise<SessionLogout>
+}
+
 export declare class PermutationBuilder {
   persist(connection: Connection, tableName: string): PermutationBuilder
   /** Configure random splits */
@@ -325,6 +382,7 @@ export declare class Table {
   refreshColumn(column: string): Promise<RefreshColumnResult>
   refreshColumnAsync(column: string): Promise<Job>
   refreshMaterializedView(full?: boolean | undefined | null, sourceVersion?: number | undefined | null): Promise<RefreshMaterializedViewResult>
+  materializedViewDefinition(): Promise<string>
   addColumnsWithSchema(schemaBuf: Buffer): Promise<AddColumnsResult>
   alterColumns(alterations: Array<ColumnAlteration>): Promise<AlterColumnsResult>
   updateFieldMetadata(updates: Array<FieldMetadataUpdate>): Promise<UpdateFieldMetadataResult>
@@ -349,7 +407,7 @@ export declare class Table {
   branches(): Promise<Branches>
   /** The branch this handle is scoped to, or `null` for the main branch. */
   currentBranch(): string | null
-  optimize(olderThanMs?: number | undefined | null, deleteUnverified?: boolean | undefined | null): Promise<OptimizeStats>
+  optimize(beforeTimestampMs?: number | undefined | null, deleteUnverified?: boolean | undefined | null): Promise<OptimizeStats>
   listIndices(): Promise<Array<IndexConfig>>
   tokenize(query: string, column?: string | undefined | null, indexName?: string | undefined | null): Promise<Array<FtsToken>>
   indexStats(indexName: string): Promise<IndexStatistics | null>
@@ -474,6 +532,15 @@ export interface BucketStats {
   memtables?: Array<MemtableStats>
 }
 
+export interface CatalogOptions {
+  apiKey?: string
+  clientConfig?: ClientConfig
+  /** SQL service endpoint inherited by database connections. */
+  sqlHostOverride?: string
+  readConsistencyInterval?: number
+  oauthConfig?: OAuthConfig
+}
+
 export interface ClientConfig {
   userAgent?: string
   retryConfig?: RetryConfig
@@ -832,6 +899,11 @@ export interface JobInfo {
 /** The catalog of described LanceDB metrics. Empty until the recorder is installed. */
 export declare function lancedbMetricsCatalog(): Array<MetricDescription>
 
+export interface ListDatabasesResponse {
+  databases: Array<string>
+  pageToken?: string
+}
+
 export interface ListNamespacesResponse {
   namespaces: Array<string>
   pageToken?: string
@@ -955,10 +1027,30 @@ export interface OAuthConfig {
    * or resource is required. For example: `["api://{app_id}/.default"]`
    */
   scopes: Array<string>
-  /** Authentication flow: "client_credentials" or "azure_managed_identity" */
+  /** Optional resource indicator for authorization and token requests. */
+  resource?: string
+  /** Optional provider-specific audience for authorization and token requests. */
+  audience?: string
+  /**
+   * Authentication flow: "client_credentials", "authorization_code",
+   * "device_code", or "azure_managed_identity"
+   */
   flow?: string
   /** Client secret (required for client_credentials). */
   clientSecret?: string
+  /**
+   * How the client authenticates to the token endpoint: "none",
+   * "client_secret_basic", or "client_secret_post". Defaults to
+   * "client_secret_basic" when a client secret is set, and "none" for
+   * public clients.
+   */
+  clientAuthMethod?: string
+  /** Loopback redirect URI for authorization_code. */
+  redirectUri?: string
+  /** Port for the authorization_code loopback callback server. */
+  callbackPort?: number
+  /** Whether authorization_code uses S256 PKCE (default: true). */
+  usePkce?: boolean
   /** Client ID for user-assigned managed identity (azure_managed_identity). */
   managedIdentityClientId?: string
   /**
@@ -967,6 +1059,11 @@ export interface OAuthConfig {
    * the TTL, each request refreshes the token.
    */
   refreshBufferSecs?: number
+  /**
+   * Opt in to the persistent token cache so short-lived processes reuse
+   * one session. Only refresh tokens are persisted.
+   */
+  tokenCache?: TokenCacheOptions
 }
 
 export interface OpenTableOptions {
@@ -1069,6 +1166,41 @@ export interface RetryConfig {
   statuses?: Array<number>
 }
 
+/** Result of `OAuthSession.logout()`. */
+export interface SessionLogout {
+  /**
+   * Whether a cached credential was removed. `false` means no matching
+   * session was cached; logout is idempotent.
+   */
+  removed: boolean
+}
+
+/**
+ * Safe, non-secret view of a cached OAuth session, returned by
+ * `OAuthSession.status()` and `OAuthSession.login()`.
+ */
+export interface SessionStatus {
+  /**
+   * Whether a cached session exists that can obtain tokens without
+   * interactive authentication.
+   */
+  refreshable: boolean
+  /** Canonical issuer URL of the cached session. */
+  issuerUrl: string
+  /** Client ID of the cached session. */
+  clientId: string
+  /** Canonical (sorted, de-duplicated) scopes of the cached session. */
+  scopes: Array<string>
+  /** Optional resource indicator for authorization and token requests. */
+  resource?: string
+  /** Optional provider-specific audience for authorization and token requests. */
+  audience?: string
+  /** Flow that produced the cached session. */
+  flow: string
+  /** When the cached session was obtained, as Unix seconds. */
+  obtainedAt?: number
+}
+
 export interface ShuffleOptions {
   seed?: number
   clumpSize?: number
@@ -1167,6 +1299,29 @@ export interface TlsConfig {
   assertHostname?: boolean
 }
 
+/**
+ * Options for the persistent OAuth token cache.
+ *
+ * The cache is opt-in: it is only used when set as `tokenCache` on
+ * `OAuthConfig`. Only refresh tokens are persisted, in a private directory
+ * with owner-only permissions, so short-lived processes can reuse an
+ * authenticated session instead of re-prompting on every start.
+ */
+export interface TokenCacheOptions {
+  /**
+   * Directory that holds cached credentials. Defaults to
+   * `$XDG_CACHE_HOME/lancedb/oauth`, `$HOME/.cache/lancedb/oauth` on Unix,
+   * or `%LOCALAPPDATA%\lancedb\oauth` on Windows. The directory is created
+   * with owner-only permissions (`0700`) when missing.
+   */
+  cacheDir?: string
+  /**
+   * How long to wait for the cross-process refresh lock before failing,
+   * in seconds (default: 30).
+   */
+  lockTimeoutSecs?: number
+}
+
 export declare function tokenize(query: string, baseTokenizer?: string | undefined | null, language?: string | undefined | null, maxTokenLength?: number | undefined | null, lowerCase?: boolean | undefined | null, stem?: boolean | undefined | null, removeStopWords?: boolean | undefined | null, customStopWords?: Array<string> | undefined | null, asciiFolding?: boolean | undefined | null, ngramMinLength?: number | undefined | null, ngramMaxLength?: number | undefined | null, prefixOnly?: boolean | undefined | null): Array<FtsToken>
 
 export interface UpdateFieldMetadataResult {