@lancedb/lancedb/dist/connection.d.ts

LanceDB: A serverless, low-latency vector database for AI applications

import { Data, SchemaLike, TableLike } from "./arrow";
import { EmbeddingFunctionConfig } from "./embedding/registry";
import { Connection as LanceDbConnection } from "./native";
import type { CreateNamespaceResponse, DescribeNamespaceResponse, DropNamespaceResponse, ListNamespacesResponse } from "./native";
export type { CreateNamespaceResponse, DescribeNamespaceResponse, DropNamespaceResponse, ListNamespacesResponse, };
import { Table } from "./table";
export interface CreateTableOptions {
    /**
     * The mode to use when creating the table.
     *
     * If this is set to "create" and the table already exists then either
     * an error will be thrown or, if existOk is true, then nothing will
     * happen.  Any provided data will be ignored.
     *
     * If this is set to "overwrite" then any existing table will be replaced.
     */
    mode: "create" | "overwrite";
    /**
     * If this is true and the table already exists and the mode is "create"
     * then no error will be raised.
     */
    existOk: boolean;
    /**
     * Configuration for object storage.
     *
     * Options already set on the connection will be inherited by the table,
     * but can be overridden here.
     *
     * The available options are described at https://docs.lancedb.com/storage/
     */
    storageOptions?: Record<string, string>;
    /**
     * The version of the data storage format to use.
     *
     * The default is `stable`.
     * Set to "legacy" to use the old format.
     *
     * @deprecated Pass `new_table_data_storage_version` to storageOptions instead.
     */
    dataStorageVersion?: string;
    /**
     * Use the new V2 manifest paths. These paths provide more efficient
     * opening of datasets with many versions on object stores.  WARNING:
     * turning this on will make the dataset unreadable for older versions
     * of LanceDB (prior to 0.10.0). To migrate an existing dataset, instead
     * use the {@link LocalTable#migrateManifestPathsV2} method.
     *
     * @deprecated Pass `new_table_enable_v2_manifest_paths` to storageOptions instead.
     */
    enableV2ManifestPaths?: boolean;
    schema?: SchemaLike;
    embeddingFunction?: EmbeddingFunctionConfig;
}
export interface OpenTableOptions {
    /**
     * Open the table scoped to this branch instead of the default branch.
     *
     * Reads and writes on the returned table operate in the branch's context.
     */
    branch?: string;
    /**
     * Open the table pinned to this version, producing a read-only view.
     *
     * Composes with {@link OpenTableOptions.branch}: when both are set, opens
     * that branch at the version; otherwise opens `main` at the version. Call
     * `checkoutLatest` to return to a writable state.
     */
    version?: number;
    /**
     * Configuration for object storage.
     *
     * Options already set on the connection will be inherited by the table,
     * but can be overridden here.
     *
     * The available options are described at https://docs.lancedb.com/storage/
     */
    storageOptions?: Record<string, string>;
    /**
     * Set the size of the index cache, specified as a number of entries
     *
     * @deprecated Use session-level cache configuration instead.
     * Create a Session with custom cache sizes and pass it to the connect() function.
     *
     * The exact meaning of an "entry" will depend on the type of index:
     * - IVF: there is one entry for each IVF partition
     * - BTREE: there is one entry for the entire index
     *
     * This cache applies to the entire opened table, across all indices.
     * Setting this value higher will increase performance on larger datasets
     * at the expense of more RAM
     */
    indexCacheSize?: number;
}
export interface TableNamesOptions {
    /**
     * If present, only return names that come lexicographically after the
     * supplied value.
     *
     * This can be combined with limit to implement pagination by setting this to
     * the last table name from the previous page.
     */
    startAfter?: string;
    /** An optional limit to the number of results to return. */
    limit?: number;
}
export interface ListNamespacesOptions {
    /** Token from a previous response for pagination. */
    pageToken?: string;
    /** An optional limit to the number of results to return. */
    limit?: number;
}
export interface CreateNamespaceOptions {
    /** Creation mode. */
    mode?: "create" | "exist_ok" | "overwrite";
    /** Properties to set on the new namespace. */
    properties?: Record<string, string>;
}
export interface DropNamespaceOptions {
    /** Whether to skip if the namespace doesn't exist, or fail. */
    mode?: "skip" | "fail";
    /** Refuse to drop if non-empty (restrict) or drop recursively (cascade). */
    behavior?: "restrict" | "cascade";
}
export interface RenameTableOptions {
    /**
     * The namespace path of the table being renamed. Defaults to the root
     * namespace (`[]`) when omitted.
     */
    namespacePath?: string[];
    /**
     * The namespace path to move the table to as part of the rename. When
     * omitted the table stays in `namespacePath`.
     */
    newNamespacePath?: string[];
}
/**
 * A LanceDB Connection that allows you to open tables and create new ones.
 *
 * Connection could be local against filesystem or remote against a server.
 *
 * A Connection is intended to be a long lived object and may hold open
 * resources such as HTTP connection pools.  This is generally fine and
 * a single connection should be shared if it is going to be used many
 * times. However, if you are finished with a connection, you may call
 * close to eagerly free these resources.  Any call to a Connection
 * method after it has been closed will result in an error.
 *
 * Closing a connection is optional.  Connections will automatically
 * be closed when they are garbage collected.
 *
 * Any created tables are independent and will continue to work even if
 * the underlying connection has been closed.
 * @hideconstructor
 */
export declare abstract class Connection {
    /**
     * Return true if the connection has not been closed
     */
    abstract isOpen(): boolean;
    /**
     * Close the connection, releasing any underlying resources.
     *
     * It is safe to call this method multiple times.
     *
     * Any attempt to use the connection after it is closed will result in an error.
     */
    abstract close(): void;
    /**
     * Return a brief description of the connection
     */
    abstract display(): string;
    /**
     * List all the table names in this database.
     *
     * Tables will be returned in lexicographical order.
     * @param {Partial<TableNamesOptions>} options - options to control the
     * paging / start point (backwards compatibility)
     *
     */
    abstract tableNames(options?: Partial<TableNamesOptions>): Promise<string[]>;
    /**
     * List all the table names in this database.
     *
     * Tables will be returned in lexicographical order.
     * @param {string[]} namespacePath - The namespace path to list tables from (defaults to root namespace)
     * @param {Partial<TableNamesOptions>} options - options to control the
     * paging / start point
     *
     */
    abstract tableNames(namespacePath?: string[], options?: Partial<TableNamesOptions>): Promise<string[]>;
    /**
     * Open a table in the database.
     * @param {string} name - The name of the table
     * @param {string[]} namespacePath - The namespace path of the table (defaults to root namespace)
     * @param {Partial<OpenTableOptions>} options - Additional options
     */
    abstract openTable(name: string, namespacePath?: string[], options?: Partial<OpenTableOptions>): Promise<Table>;
    /**
     * Creates a new Table and initialize it with new data.
     * @param {object} options - The options object.
     * @param {string} options.name - The name of the table.
     * @param {Data} options.data - Non-empty Array of Records to be inserted into the table
     * @param {string[]} namespacePath - The namespace path to create the table in (defaults to root namespace)
     *
     */
    abstract createTable(options: {
        name: string;
        data: Data;
    } & Partial<CreateTableOptions>, namespacePath?: string[]): Promise<Table>;
    /**
     * Creates a new Table and initialize it with new data.
     * @param {string} name - The name of the table.
     * @param {Record<string, unknown>[] | TableLike} data - Non-empty Array of Records
     * to be inserted into the table
     * @param {Partial<CreateTableOptions>} options - Additional options (backwards compatibility)
     */
    abstract createTable(name: string, data: Record<string, unknown>[] | TableLike, options?: Partial<CreateTableOptions>): Promise<Table>;
    /**
     * Creates a new Table and initialize it with new data.
     * @param {string} name - The name of the table.
     * @param {Record<string, unknown>[] | TableLike} data - Non-empty Array of Records
     * to be inserted into the table
     * @param {string[]} namespacePath - The namespace path to create the table in (defaults to root namespace)
     * @param {Partial<CreateTableOptions>} options - Additional options
     */
    abstract createTable(name: string, data: Record<string, unknown>[] | TableLike, namespacePath?: string[], options?: Partial<CreateTableOptions>): Promise<Table>;
    /**
     * Creates a new empty Table
     * @param {string} name - The name of the table.
     * @param {Schema} schema - The schema of the table
     * @param {Partial<CreateTableOptions>} options - Additional options (backwards compatibility)
     */
    abstract createEmptyTable(name: string, schema: import("./arrow").SchemaLike, options?: Partial<CreateTableOptions>): Promise<Table>;
    /**
     * Creates a new empty Table
     * @param {string} name - The name of the table.
     * @param {Schema} schema - The schema of the table
     * @param {string[]} namespacePath - The namespace path to create the table in (defaults to root namespace)
     * @param {Partial<CreateTableOptions>} options - Additional options
     */
    abstract createEmptyTable(name: string, schema: import("./arrow").SchemaLike, namespacePath?: string[], options?: Partial<CreateTableOptions>): Promise<Table>;
    /**
     * Drop an existing table.
     * @param {string} name The name of the table to drop.
     * @param {string[]} namespacePath The namespace path of the table (defaults to root namespace).
     */
    abstract dropTable(name: string, namespacePath?: string[]): Promise<void>;
    /**
     * Drop all tables in the database.
     * @param {string[]} namespacePath The namespace path to drop tables from (defaults to root namespace).
     */
    abstract dropAllTables(namespacePath?: string[]): Promise<void>;
    /**
     * Describe a namespace, returning its properties.
     *
     * @param {string[]} namespacePath - The namespace path to describe, in
     *   parent → child order, e.g. `["analytics", "sales"]`.
     * @returns {Promise<DescribeNamespaceResponse>} The namespace's properties
     *   (may be undefined if the namespace has none).
     */
    abstract describeNamespace(namespacePath: string[]): Promise<DescribeNamespaceResponse>;
    /**
     * List the immediate child namespaces under the given parent.
     *
     * Results may be paginated. To retrieve subsequent pages, pass the
     * `pageToken` returned by a previous call.
     *
     * @param {string[]} namespacePath - The parent namespace path. Defaults
     *   to the root namespace if omitted.
     * @param {Partial<ListNamespacesOptions>} options - Pagination options
     *   (`pageToken`, `limit`).
     * @returns {Promise<ListNamespacesResponse>} Child namespace names and
     *   an optional token for fetching the next page.
     */
    abstract listNamespaces(namespacePath?: string[], options?: Partial<ListNamespacesOptions>): Promise<ListNamespacesResponse>;
    /**
     * Create a new namespace at the given path.
     *
     * @param {string[]} namespacePath - The namespace path to create.
     * @param {Partial<CreateNamespaceOptions>} options - Creation `mode`
     *   ("create" | "exist_ok" | "overwrite") and optional `properties`
     *   to attach to the namespace.
     * @returns {Promise<CreateNamespaceResponse>} The properties of the
     *   created namespace and an optional transaction id.
     */
    abstract createNamespace(namespacePath: string[], options?: Partial<CreateNamespaceOptions>): Promise<CreateNamespaceResponse>;
    /**
     * Drop a namespace.
     *
     * Use `behavior: "cascade"` to also drop everything contained in the
     * namespace (sub-namespaces and tables). The default `"restrict"`
     * behavior refuses to drop a non-empty namespace.
     *
     * @param {string[]} namespacePath - The namespace path to drop.
     * @param {Partial<DropNamespaceOptions>} options - `mode` ("skip" | "fail"
     *   for missing-namespace handling) and `behavior` ("restrict" | "cascade").
     * @returns {Promise<DropNamespaceResponse>} Any properties returned by
     *   the server and an optional transaction id.
     */
    abstract dropNamespace(namespacePath: string[], options?: Partial<DropNamespaceOptions>): Promise<DropNamespaceResponse>;
    /**
     * Clone a table from a source table.
     *
     * A shallow clone creates a new table that shares the underlying data files
     * with the source table but has its own independent manifest. This allows
     * both the source and cloned tables to evolve independently while initially
     * sharing the same data, deletion, and index files.
     *
     * @param {string} targetTableName - The name of the target table to create.
     * @param {string} sourceUri - The URI of the source table to clone from.
     * @param {object} options - Clone options.
     * @param {string[]} options.targetNamespacePath - The namespace path for the target table (defaults to root namespace).
     * @param {number} options.sourceVersion - The version of the source table to clone.
     * @param {string} options.sourceTag - The tag of the source table to clone.
     * @param {boolean} options.isShallow - Whether to perform a shallow clone (defaults to true).
     */
    abstract cloneTable(targetTableName: string, sourceUri: string, options?: {
        targetNamespacePath?: string[];
        sourceVersion?: number;
        sourceTag?: string;
        isShallow?: boolean;
    }): Promise<Table>;
    /**
     * Rename a table.
     *
     * Currently only supported by LanceDB Cloud. Local OSS connections and
     * namespace-backed connections (via {@link connectNamespace}) reject with
     * a "not supported" error.
     *
     * @param {string} currentName - The current name of the table.
     * @param {string} newName - The new name for the table.
     * @param {RenameTableOptions} options - Optional namespace paths. When
     *   `newNamespacePath` is omitted the table stays in `namespacePath`.
     */
    abstract renameTable(currentName: string, newName: string, options?: RenameTableOptions): Promise<void>;
}
/** @hideconstructor */
export declare class LocalConnection extends Connection {
    readonly inner: LanceDbConnection;
    /** @hidden */
    constructor(inner: LanceDbConnection);
    isOpen(): boolean;
    close(): void;
    display(): string;
    tableNames(namespacePathOrOptions?: string[] | Partial<TableNamesOptions>, options?: Partial<TableNamesOptions>): Promise<string[]>;
    openTable(name: string, namespacePath?: string[], options?: Partial<OpenTableOptions>): Promise<Table>;
    cloneTable(targetTableName: string, sourceUri: string, options?: {
        targetNamespacePath?: string[];
        sourceVersion?: number;
        sourceTag?: string;
        isShallow?: boolean;
    }): Promise<Table>;
    private getStorageOptions;
    createTable(nameOrOptions: string | ({
        name: string;
        data: Data;
    } & Partial<CreateTableOptions>), dataOrNamespacePath?: Record<string, unknown>[] | TableLike | string[], namespacePathOrOptions?: string[] | Partial<CreateTableOptions>, options?: Partial<CreateTableOptions>): Promise<Table>;
    private _createTableImpl;
    createEmptyTable(name: string, schema: import("./arrow").SchemaLike, namespacePathOrOptions?: string[] | Partial<CreateTableOptions>, options?: Partial<CreateTableOptions>): Promise<Table>;
    dropTable(name: string, namespacePath?: string[]): Promise<void>;
    dropAllTables(namespacePath?: string[]): Promise<void>;
    describeNamespace(namespacePath: string[]): Promise<DescribeNamespaceResponse>;
    listNamespaces(namespacePath?: string[], options?: Partial<ListNamespacesOptions>): Promise<ListNamespacesResponse>;
    createNamespace(namespacePath: string[], options?: Partial<CreateNamespaceOptions>): Promise<CreateNamespaceResponse>;
    dropNamespace(namespacePath: string[], options?: Partial<DropNamespaceOptions>): Promise<DropNamespaceResponse>;
    renameTable(currentName: string, newName: string, options?: RenameTableOptions): Promise<void>;
}
/**
 * Takes storage options and makes all the keys snake case.
 */
export declare function cleanseStorageOptions(options?: Record<string, string>): Record<string, string> | undefined;