@lancedb/lancedb 0.22.0 → 0.22.2-beta.1

package/dist/arrow.d.ts

@@ -85,7 +85,7 @@ export declare class MakeArrowTableOptions {
     constructor(values?: Partial<MakeArrowTableOptions>);
 }
 /**
- * An enhanced version of the {@link makeTable} function from Apache Arrow
+ * An enhanced version of the apache-arrow makeTable function from Apache Arrow
  * that supports nested fields and embeddings columns.
  *
  * (typically you do not need to call this function.  It will be called automatically

package/dist/arrow.js

@@ -212,7 +212,7 @@ class MakeArrowTableOptions {
 }
 exports.MakeArrowTableOptions = MakeArrowTableOptions;
 /**
- * An enhanced version of the {@link makeTable} function from Apache Arrow
+ * An enhanced version of the apache-arrow makeTable function from Apache Arrow
  * that supports nested fields and embeddings columns.
  *
  * (typically you do not need to call this function.  It will be called automatically
@@ -417,7 +417,11 @@ function* rowPathsAndValues(row, basePath = []) {
             yield* rowPathsAndValues(value, [...basePath, key]);
         }
         else {
-            yield [[...basePath, key], value];
+            // Skip undefined values - they should be treated the same as missing fields
+            // for embedding function purposes
+            if (value !== undefined) {
+                yield [[...basePath, key], value];
+            }
         }
     }
 }
@@ -596,7 +600,7 @@ function transposeData(data, field, path = []) {
             }
             return current;
         });
-        return makeVector(values, field.type);
+        return makeVector(values, field.type, undefined, field.nullable);
     }
 }
 /**
@@ -633,8 +637,26 @@ function makeListVector(lists) {
     return listBuilder.finish().toVector();
 }
 /** Helper function to convert an Array of JS values to an Arrow Vector */
-function makeVector(values, type, stringAsDictionary) {
+function makeVector(values, type, stringAsDictionary, nullable) {
     if (type !== undefined) {
+        // Convert undefined values to null for nullable fields
+        if (nullable) {
+            values = values.map((v) => (v === undefined ? null : v));
+        }
+        // workaround for: https://github.com/apache/arrow-js/issues/68
+        if (apache_arrow_1.DataType.isBool(type)) {
+            const hasNonNullValue = values.some((v) => v !== null && v !== undefined);
+            if (!hasNonNullValue) {
+                const nullBitmap = new Uint8Array(Math.ceil(values.length / 8));
+                const data = (0, apache_arrow_1.makeData)({
+                    type: type,
+                    length: values.length,
+                    nullCount: values.length,
+                    nullBitmap,
+                });
+                return (0, apache_arrow_1.makeVector)(data);
+            }
+        }
         // No need for inference, let Arrow create it
         if (type instanceof apache_arrow_1.Int) {
             if (apache_arrow_1.DataType.isInt(type) && type.bitWidth === 64) {
@@ -741,7 +763,7 @@ async function applyEmbeddingsFromMetadata(table, schema) {
     for (const field of schema.fields) {
         if (!(field.name in columns)) {
             const nullValues = new Array(table.numRows).fill(null);
-            columns[field.name] = makeVector(nullValues, field.type);
+            columns[field.name] = makeVector(nullValues, field.type, undefined, field.nullable);
         }
     }
     const newTable = new apache_arrow_1.Table(columns);
@@ -793,7 +815,7 @@ async function applyEmbeddings(table, embeddings, schema) {
         else if (schema != null) {
             const destField = schema.fields.find((f) => f.name === destColumn);
             if (destField != null) {
-                newColumns[destColumn] = makeVector([], destField.type);
+                newColumns[destColumn] = makeVector([], destField.type, undefined, destField.nullable);
             }
             else {
                 throw new Error(`Attempt to apply embeddings to an empty table failed because schema was missing embedding column '${destColumn}'`);

package/dist/connection.d.ts

@@ -204,6 +204,28 @@ export declare abstract class Connection {
      * @param {string[]} namespace The namespace to drop tables from (defaults to root namespace).
      */
     abstract dropAllTables(namespace?: string[]): Promise<void>;
+    /**
+     * 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.targetNamespace - The namespace 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?: {
+        targetNamespace?: string[];
+        sourceVersion?: number;
+        sourceTag?: string;
+        isShallow?: boolean;
+    }): Promise<Table>;
 }
 /** @hideconstructor */
 export declare class LocalConnection extends Connection {
@@ -215,6 +237,12 @@ export declare class LocalConnection extends Connection {
     display(): string;
     tableNames(namespaceOrOptions?: string[] | Partial<TableNamesOptions>, options?: Partial<TableNamesOptions>): Promise<string[]>;
     openTable(name: string, namespace?: string[], options?: Partial<OpenTableOptions>): Promise<Table>;
+    cloneTable(targetTableName: string, sourceUri: string, options?: {
+        targetNamespace?: string[];
+        sourceVersion?: number;
+        sourceTag?: string;
+        isShallow?: boolean;
+    }): Promise<Table>;
     private getStorageOptions;
     createTable(nameOrOptions: string | ({
         name: string;

package/dist/connection.js

@@ -71,6 +71,10 @@ class LocalConnection extends Connection {
         const innerTable = await this.inner.openTable(name, namespace ?? [], cleanseStorageOptions(options?.storageOptions), options?.indexCacheSize);
         return new table_1.LocalTable(innerTable);
     }
+    async cloneTable(targetTableName, sourceUri, options) {
+        const innerTable = await this.inner.cloneTable(targetTableName, sourceUri, options?.targetNamespace ?? [], options?.sourceVersion ?? null, options?.sourceTag ?? null, options?.isShallow ?? true);
+        return new table_1.LocalTable(innerTable);
+    }
     getStorageOptions(options) {
         if (options?.dataStorageVersion !== undefined) {
             if (options.storageOptions === undefined) {

package/dist/header.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Header providers for LanceDB remote connections.
+ *
+ * This module provides a flexible header management framework for LanceDB remote
+ * connections, allowing users to implement custom header strategies for
+ * authentication, request tracking, custom metadata, or any other header-based
+ * requirements.
+ *
+ * @module header
+ */
+/**
+ * Abstract base class for providing custom headers for each request.
+ *
+ * Users can implement this interface to provide dynamic headers for various purposes
+ * such as authentication (OAuth tokens, API keys), request tracking (correlation IDs),
+ * custom metadata, or any other header-based requirements. The provider is called
+ * before each request to ensure fresh header values are always used.
+ *
+ * @example
+ * Simple JWT token provider:
+ * ```typescript
+ * class JWTProvider extends HeaderProvider {
+ *   constructor(private token: string) {
+ *     super();
+ *   }
+ *
+ *   getHeaders(): Record<string, string> {
+ *     return { authorization: `Bearer ${this.token}` };
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * Provider with request tracking:
+ * ```typescript
+ * class RequestTrackingProvider extends HeaderProvider {
+ *   constructor(private sessionId: string) {
+ *     super();
+ *   }
+ *
+ *   getHeaders(): Record<string, string> {
+ *     return {
+ *       "X-Session-Id": this.sessionId,
+ *       "X-Request-Id": `req-${Date.now()}`
+ *     };
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class HeaderProvider {
+    /**
+     * Get the latest headers to be added to requests.
+     *
+     * This method is called before each request to the remote LanceDB server.
+     * Implementations should return headers that will be merged with existing headers.
+     *
+     * @returns Dictionary of header names to values to add to the request.
+     * @throws If unable to fetch headers, the exception will be propagated and the request will fail.
+     */
+    abstract getHeaders(): Record<string, string>;
+}
+/**
+ * Example implementation: A simple header provider that returns static headers.
+ *
+ * This is an example implementation showing how to create a HeaderProvider
+ * for cases where headers don't change during the session.
+ *
+ * @example
+ * ```typescript
+ * const provider = new StaticHeaderProvider({
+ *   authorization: "Bearer my-token",
+ *   "X-Custom-Header": "custom-value"
+ * });
+ * const headers = provider.getHeaders();
+ * // Returns: {authorization: 'Bearer my-token', 'X-Custom-Header': 'custom-value'}
+ * ```
+ */
+export declare class StaticHeaderProvider extends HeaderProvider {
+    private _headers;
+    /**
+     * Initialize with static headers.
+     * @param headers - Headers to return for every request.
+     */
+    constructor(headers: Record<string, string>);
+    /**
+     * Return the static headers.
+     * @returns Copy of the static headers.
+     */
+    getHeaders(): Record<string, string>;
+}
+/**
+ * Token response from OAuth provider.
+ * @public
+ */
+export interface TokenResponse {
+    accessToken: string;
+    expiresIn?: number;
+}
+/**
+ * Example implementation: OAuth token provider with automatic refresh.
+ *
+ * This is an example implementation showing how to manage OAuth tokens
+ * with automatic refresh when they expire.
+ *
+ * @example
+ * ```typescript
+ * async function fetchToken(): Promise<TokenResponse> {
+ *   const response = await fetch("https://oauth.example.com/token", {
+ *     method: "POST",
+ *     body: JSON.stringify({
+ *       grant_type: "client_credentials",
+ *       client_id: "your-client-id",
+ *       client_secret: "your-client-secret"
+ *     }),
+ *     headers: { "Content-Type": "application/json" }
+ *   });
+ *   const data = await response.json();
+ *   return {
+ *     accessToken: data.access_token,
+ *     expiresIn: data.expires_in
+ *   };
+ * }
+ *
+ * const provider = new OAuthHeaderProvider(fetchToken);
+ * const headers = provider.getHeaders();
+ * // Returns: {"authorization": "Bearer <your-token>"}
+ * ```
+ */
+export declare class OAuthHeaderProvider extends HeaderProvider {
+    private _tokenFetcher;
+    private _refreshBufferSeconds;
+    private _currentToken;
+    private _tokenExpiresAt;
+    private _refreshPromise;
+    /**
+     * Initialize the OAuth provider.
+     * @param tokenFetcher - Function to fetch new tokens. Should return object with 'accessToken' and optionally 'expiresIn'.
+     * @param refreshBufferSeconds - Seconds before expiry to refresh token. Default 300 (5 minutes).
+     */
+    constructor(tokenFetcher: () => Promise<TokenResponse> | TokenResponse, refreshBufferSeconds?: number);
+    /**
+     * Check if token needs refresh.
+     */
+    private _needsRefresh;
+    /**
+     * Refresh the token if it's expired or close to expiring.
+     */
+    private _refreshTokenIfNeeded;
+    /**
+     * Get OAuth headers, refreshing token if needed.
+     * Note: This is synchronous for now as the Rust implementation expects sync.
+     * In a real implementation, this would need to handle async properly.
+     * @returns Headers with Bearer token authorization.
+     * @throws If unable to fetch or refresh token.
+     */
+    getHeaders(): Record<string, string>;
+    /**
+     * Manually refresh the token.
+     * Call this before using getHeaders() to ensure token is available.
+     */
+    refreshToken(): Promise<void>;
+}

package/dist/header.js

@@ -0,0 +1,217 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright The LanceDB Authors
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OAuthHeaderProvider = exports.StaticHeaderProvider = exports.HeaderProvider = void 0;
+/**
+ * Header providers for LanceDB remote connections.
+ *
+ * This module provides a flexible header management framework for LanceDB remote
+ * connections, allowing users to implement custom header strategies for
+ * authentication, request tracking, custom metadata, or any other header-based
+ * requirements.
+ *
+ * @module header
+ */
+/**
+ * Abstract base class for providing custom headers for each request.
+ *
+ * Users can implement this interface to provide dynamic headers for various purposes
+ * such as authentication (OAuth tokens, API keys), request tracking (correlation IDs),
+ * custom metadata, or any other header-based requirements. The provider is called
+ * before each request to ensure fresh header values are always used.
+ *
+ * @example
+ * Simple JWT token provider:
+ * ```typescript
+ * class JWTProvider extends HeaderProvider {
+ *   constructor(private token: string) {
+ *     super();
+ *   }
+ *
+ *   getHeaders(): Record<string, string> {
+ *     return { authorization: `Bearer ${this.token}` };
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * Provider with request tracking:
+ * ```typescript
+ * class RequestTrackingProvider extends HeaderProvider {
+ *   constructor(private sessionId: string) {
+ *     super();
+ *   }
+ *
+ *   getHeaders(): Record<string, string> {
+ *     return {
+ *       "X-Session-Id": this.sessionId,
+ *       "X-Request-Id": `req-${Date.now()}`
+ *     };
+ *   }
+ * }
+ * ```
+ */
+class HeaderProvider {
+}
+exports.HeaderProvider = HeaderProvider;
+/**
+ * Example implementation: A simple header provider that returns static headers.
+ *
+ * This is an example implementation showing how to create a HeaderProvider
+ * for cases where headers don't change during the session.
+ *
+ * @example
+ * ```typescript
+ * const provider = new StaticHeaderProvider({
+ *   authorization: "Bearer my-token",
+ *   "X-Custom-Header": "custom-value"
+ * });
+ * const headers = provider.getHeaders();
+ * // Returns: {authorization: 'Bearer my-token', 'X-Custom-Header': 'custom-value'}
+ * ```
+ */
+class StaticHeaderProvider extends HeaderProvider {
+    _headers;
+    /**
+     * Initialize with static headers.
+     * @param headers - Headers to return for every request.
+     */
+    constructor(headers) {
+        super();
+        this._headers = { ...headers };
+    }
+    /**
+     * Return the static headers.
+     * @returns Copy of the static headers.
+     */
+    getHeaders() {
+        return { ...this._headers };
+    }
+}
+exports.StaticHeaderProvider = StaticHeaderProvider;
+/**
+ * Example implementation: OAuth token provider with automatic refresh.
+ *
+ * This is an example implementation showing how to manage OAuth tokens
+ * with automatic refresh when they expire.
+ *
+ * @example
+ * ```typescript
+ * async function fetchToken(): Promise<TokenResponse> {
+ *   const response = await fetch("https://oauth.example.com/token", {
+ *     method: "POST",
+ *     body: JSON.stringify({
+ *       grant_type: "client_credentials",
+ *       client_id: "your-client-id",
+ *       client_secret: "your-client-secret"
+ *     }),
+ *     headers: { "Content-Type": "application/json" }
+ *   });
+ *   const data = await response.json();
+ *   return {
+ *     accessToken: data.access_token,
+ *     expiresIn: data.expires_in
+ *   };
+ * }
+ *
+ * const provider = new OAuthHeaderProvider(fetchToken);
+ * const headers = provider.getHeaders();
+ * // Returns: {"authorization": "Bearer <your-token>"}
+ * ```
+ */
+class OAuthHeaderProvider extends HeaderProvider {
+    _tokenFetcher;
+    _refreshBufferSeconds;
+    _currentToken = null;
+    _tokenExpiresAt = null;
+    _refreshPromise = null;
+    /**
+     * Initialize the OAuth provider.
+     * @param tokenFetcher - Function to fetch new tokens. Should return object with 'accessToken' and optionally 'expiresIn'.
+     * @param refreshBufferSeconds - Seconds before expiry to refresh token. Default 300 (5 minutes).
+     */
+    constructor(tokenFetcher, refreshBufferSeconds = 300) {
+        super();
+        this._tokenFetcher = tokenFetcher;
+        this._refreshBufferSeconds = refreshBufferSeconds;
+    }
+    /**
+     * Check if token needs refresh.
+     */
+    _needsRefresh() {
+        if (this._currentToken === null) {
+            return true;
+        }
+        if (this._tokenExpiresAt === null) {
+            // No expiration info, assume token is valid
+            return false;
+        }
+        // Refresh if we're within the buffer time of expiration
+        const now = Date.now() / 1000;
+        return now >= this._tokenExpiresAt - this._refreshBufferSeconds;
+    }
+    /**
+     * Refresh the token if it's expired or close to expiring.
+     */
+    async _refreshTokenIfNeeded() {
+        if (!this._needsRefresh()) {
+            return;
+        }
+        // If refresh is already in progress, wait for it
+        if (this._refreshPromise) {
+            await this._refreshPromise;
+            return;
+        }
+        // Start refresh
+        this._refreshPromise = (async () => {
+            try {
+                const tokenData = await this._tokenFetcher();
+                this._currentToken = tokenData.accessToken;
+                if (!this._currentToken) {
+                    throw new Error("Token fetcher did not return 'accessToken'");
+                }
+                // Set expiration if provided
+                if (tokenData.expiresIn) {
+                    this._tokenExpiresAt = Date.now() / 1000 + tokenData.expiresIn;
+                }
+                else {
+                    // Token doesn't expire or expiration unknown
+                    this._tokenExpiresAt = null;
+                }
+            }
+            finally {
+                this._refreshPromise = null;
+            }
+        })();
+        await this._refreshPromise;
+    }
+    /**
+     * Get OAuth headers, refreshing token if needed.
+     * Note: This is synchronous for now as the Rust implementation expects sync.
+     * In a real implementation, this would need to handle async properly.
+     * @returns Headers with Bearer token authorization.
+     * @throws If unable to fetch or refresh token.
+     */
+    getHeaders() {
+        // For simplicity in this example, we assume the token is already fetched
+        // In a real implementation, this would need to handle the async nature properly
+        if (!this._currentToken && !this._refreshPromise) {
+            // Synchronously trigger refresh - this is a limitation of the current implementation
+            throw new Error("Token not initialized. Call refreshToken() first or use async initialization.");
+        }
+        if (!this._currentToken) {
+            throw new Error("Failed to obtain OAuth token");
+        }
+        return { authorization: `Bearer ${this._currentToken}` };
+    }
+    /**
+     * Manually refresh the token.
+     * Call this before using getHeaders() to ensure token is available.
+     */
+    async refreshToken() {
+        this._currentToken = null; // Force refresh
+        await this._refreshTokenIfNeeded();
+    }
+}
+exports.OAuthHeaderProvider = OAuthHeaderProvider;

package/dist/index.d.ts

@@ -1,12 +1,15 @@
 import { Connection } from "./connection";
 import { ConnectionOptions, Session } from "./native.js";
-export { AddColumnsSql, ConnectionOptions, IndexStatistics, IndexConfig, ClientConfig, TimeoutConfig, RetryConfig, OptimizeStats, CompactionStats, RemovalStats, TableStatistics, FragmentStatistics, FragmentSummaryStats, Tags, TagContents, MergeResult, AddResult, AddColumnsResult, AlterColumnsResult, DeleteResult, DropColumnsResult, UpdateResult, } from "./native.js";
+import { HeaderProvider } from "./header";
+export { JsHeaderProvider as NativeJsHeaderProvider } from "./native.js";
+export { AddColumnsSql, ConnectionOptions, IndexStatistics, IndexConfig, ClientConfig, TimeoutConfig, RetryConfig, TlsConfig, OptimizeStats, CompactionStats, RemovalStats, TableStatistics, FragmentStatistics, FragmentSummaryStats, Tags, TagContents, MergeResult, AddResult, AddColumnsResult, AlterColumnsResult, DeleteResult, DropColumnsResult, UpdateResult, } from "./native.js";
 export { makeArrowTable, MakeArrowTableOptions, Data, VectorColumnOptions, } from "./arrow";
 export { Connection, CreateTableOptions, TableNamesOptions, OpenTableOptions, } from "./connection";
 export { Session } from "./native.js";
 export { ExecutableQuery, Query, QueryBase, VectorQuery, TakeQuery, QueryExecutionOptions, FullTextSearchOptions, RecordBatchIterator, FullTextQuery, MatchQuery, PhraseQuery, BoostQuery, MultiMatchQuery, BooleanQuery, FullTextQueryType, Operator, Occur, } from "./query";
 export { Index, IndexOptions, IvfPqOptions, IvfFlatOptions, HnswPqOptions, HnswSqOptions, FtsOptions, } from "./indices";
 export { Table, AddDataOptions, UpdateOptions, OptimizeOptions, Version, ColumnAlteration, } from "./table";
+export { HeaderProvider, StaticHeaderProvider, OAuthHeaderProvider, TokenResponse, } from "./header";
 export { MergeInsertBuilder, WriteExecutionOptions } from "./merge";
 export * as embedding from "./embedding";
 export * as rerankers from "./rerankers";
@@ -35,8 +38,20 @@ export { IntoSql, packBits } from "./util";
  *   {storageOptions: {timeout: "60s"}
  * });
  * ```
+ * @example
+ * Using with a header provider for per-request authentication:
+ * ```ts
+ * const provider = new StaticHeaderProvider({
+ *   "X-API-Key": "my-key"
+ * });
+ * const conn = await connectWithHeaderProvider(
+ *   "db://host:port",
+ *   options,
+ *   provider
+ * );
+ * ```
  */
-export declare function connect(uri: string, options?: Partial<ConnectionOptions>, session?: Session): Promise<Connection>;
+export declare function connect(uri: string, options?: Partial<ConnectionOptions>, session?: Session, headerProvider?: HeaderProvider | (() => Record<string, string>) | (() => Promise<Record<string, string>>)): Promise<Connection>;
 /**
  * Connect to a LanceDB instance at the given URI.
  *

package/dist/index.js

@@ -2,21 +2,24 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: Copyright The LanceDB Authors
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.packBits = exports.rerankers = exports.embedding = exports.MergeInsertBuilder = 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.Session = exports.Connection = exports.VectorColumnOptions = exports.MakeArrowTableOptions = exports.makeArrowTable = exports.TagContents = exports.Tags = void 0;
+exports.packBits = exports.rerankers = exports.embedding = exports.MergeInsertBuilder = exports.OAuthHeaderProvider = exports.StaticHeaderProvider = exports.HeaderProvider = 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.Session = exports.Connection = exports.VectorColumnOptions = exports.MakeArrowTableOptions = exports.makeArrowTable = exports.TagContents = exports.Tags = exports.NativeJsHeaderProvider = void 0;
 exports.connect = connect;
 const connection_1 = require("./connection");
 const native_js_1 = require("./native.js");
+// Re-export native header provider for use with connectWithHeaderProvider
 var native_js_2 = require("./native.js");
-Object.defineProperty(exports, "Tags", { enumerable: true, get: function () { return native_js_2.Tags; } });
-Object.defineProperty(exports, "TagContents", { enumerable: true, get: function () { return native_js_2.TagContents; } });
+Object.defineProperty(exports, "NativeJsHeaderProvider", { enumerable: true, get: function () { return native_js_2.JsHeaderProvider; } });
+var native_js_3 = require("./native.js");
+Object.defineProperty(exports, "Tags", { enumerable: true, get: function () { return native_js_3.Tags; } });
+Object.defineProperty(exports, "TagContents", { enumerable: true, get: function () { return native_js_3.TagContents; } });
 var arrow_1 = require("./arrow");
 Object.defineProperty(exports, "makeArrowTable", { enumerable: true, get: function () { return arrow_1.makeArrowTable; } });
 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 connection_2 = require("./connection");
 Object.defineProperty(exports, "Connection", { enumerable: true, get: function () { return connection_2.Connection; } });
-var native_js_3 = require("./native.js");
-Object.defineProperty(exports, "Session", { enumerable: true, get: function () { return native_js_3.Session; } });
+var native_js_4 = require("./native.js");
+Object.defineProperty(exports, "Session", { enumerable: true, get: function () { return native_js_4.Session; } });
 var query_1 = require("./query");
 Object.defineProperty(exports, "Query", { enumerable: true, get: function () { return query_1.Query; } });
 Object.defineProperty(exports, "QueryBase", { enumerable: true, get: function () { return query_1.QueryBase; } });
@@ -35,29 +38,66 @@ var indices_1 = require("./indices");
 Object.defineProperty(exports, "Index", { enumerable: true, get: function () { return indices_1.Index; } });
 var table_1 = require("./table");
 Object.defineProperty(exports, "Table", { enumerable: true, get: function () { return table_1.Table; } });
+var header_1 = require("./header");
+Object.defineProperty(exports, "HeaderProvider", { enumerable: true, get: function () { return header_1.HeaderProvider; } });
+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 merge_1 = require("./merge");
 Object.defineProperty(exports, "MergeInsertBuilder", { enumerable: true, get: function () { return merge_1.MergeInsertBuilder; } });
 exports.embedding = require("./embedding");
 exports.rerankers = require("./rerankers");
 var util_1 = require("./util");
 Object.defineProperty(exports, "packBits", { enumerable: true, get: function () { return util_1.packBits; } });
-async function connect(uriOrOptions, options) {
+async function connect(uriOrOptions, optionsOrSession, sessionOrHeaderProvider, headerProvider) {
     let uri;
     let finalOptions = {};
+    let finalHeaderProvider;
     if (typeof uriOrOptions !== "string") {
+        // First overload: connect(options)
         const { uri: uri_, ...opts } = uriOrOptions;
         uri = uri_;
         finalOptions = opts;
     }
     else {
+        // Second overload: connect(uri, options?, session?, headerProvider?)
         uri = uriOrOptions;
-        finalOptions = options || {};
+        // Handle optionsOrSession parameter
+        if (optionsOrSession && "inner" in optionsOrSession) {
+            // Second param is session, so no options provided
+            finalOptions = {};
+        }
+        else {
+            // Second param is options
+            finalOptions = optionsOrSession || {};
+        }
+        // Handle sessionOrHeaderProvider parameter
+        if (sessionOrHeaderProvider &&
+            (typeof sessionOrHeaderProvider === "function" ||
+                "getHeaders" in sessionOrHeaderProvider)) {
+            // Third param is header provider
+            finalHeaderProvider = sessionOrHeaderProvider;
+        }
+        else {
+            // Third param is session, header provider is fourth param
+            finalHeaderProvider = headerProvider;
+        }
     }
     if (!uri) {
         throw new Error("uri is required");
     }
     finalOptions = finalOptions ?? {};
     finalOptions.storageOptions = (0, connection_1.cleanseStorageOptions)(finalOptions.storageOptions);
-    const nativeConn = await native_js_1.Connection.new(uri, finalOptions);
+    // Create native header provider if one was provided
+    let nativeProvider;
+    if (finalHeaderProvider) {
+        if (typeof finalHeaderProvider === "function") {
+            nativeProvider = new native_js_1.JsHeaderProvider(finalHeaderProvider);
+        }
+        else if (finalHeaderProvider &&
+            typeof finalHeaderProvider.getHeaders === "function") {
+            nativeProvider = new native_js_1.JsHeaderProvider(async () => finalHeaderProvider.getHeaders());
+        }
+    }
+    const nativeConn = await native_js_1.Connection.new(uri, finalOptions, nativeProvider);
     return new connection_1.LocalConnection(nativeConn);
 }

package/dist/merge.d.ts

@@ -45,6 +45,17 @@ export declare class MergeInsertBuilder {
     whenNotMatchedBySourceDelete(options?: {
         where: string;
     }): MergeInsertBuilder;
+    /**
+     * Controls whether to use indexes for the merge operation.
+     *
+     * When set to `true` (the default), the operation will use an index if available
+     * on the join key for improved performance. When set to `false`, it forces a full
+     * table scan even if an index exists. This can be useful for benchmarking or when
+     * the query optimizer chooses a suboptimal path.
+     *
+     * @param useIndex - Whether to use indices for the merge operation. Defaults to `true`.
+     */
+    useIndex(useIndex: boolean): MergeInsertBuilder;
     /**
      * Executes the merge insert operation
      *

package/dist/merge.js

@@ -55,6 +55,19 @@ class MergeInsertBuilder {
     whenNotMatchedBySourceDelete(options) {
         return new MergeInsertBuilder(this.#native.whenNotMatchedBySourceDelete(options?.where), this.#schema);
     }
+    /**
+     * Controls whether to use indexes for the merge operation.
+     *
+     * When set to `true` (the default), the operation will use an index if available
+     * on the join key for improved performance. When set to `false`, it forces a full
+     * table scan even if an index exists. This can be useful for benchmarking or when
+     * the query optimizer chooses a suboptimal path.
+     *
+     * @param useIndex - Whether to use indices for the merge operation. Defaults to `true`.
+     */
+    useIndex(useIndex) {
+        return new MergeInsertBuilder(this.#native.useIndex(useIndex), this.#schema);
+    }
     /**
      * Executes the merge insert operation
      *

package/dist/native.d.ts

@@ -81,12 +81,24 @@ export interface RetryConfig {
    */
   statuses?: Array<number>
 }
+/** TLS/mTLS configuration for the remote HTTP client. */
+export interface TlsConfig {
+  /** Path to the client certificate file (PEM format) for mTLS authentication. */
+  certFile?: string
+  /** Path to the client private key file (PEM format) for mTLS authentication. */
+  keyFile?: string
+  /** Path to the CA certificate file (PEM format) for server verification. */
+  sslCaCert?: string
+  /** Whether to verify the hostname in the server's certificate. */
+  assertHostname?: boolean
+}
 export interface ClientConfig {
   userAgent?: string
   retryConfig?: RetryConfig
   timeoutConfig?: TimeoutConfig
   extraHeaders?: Record<string, string>
   idDelimiter?: string
+  tlsConfig?: TlsConfig
 }
 export interface RerankerCallbacks {
   rerankHybrid: (...args: any[]) => any
@@ -312,7 +324,7 @@ export interface OpenTableOptions {
 }
 export class Connection {
   /** Create a new Connection instance from the given URI. */
-  static new(uri: string, options: ConnectionOptions): Promise<Connection>
+  static new(uri: string, options: ConnectionOptions, headerProvider?: JsHeaderProvider | undefined | null): Promise<Connection>
   display(): string
   isOpen(): boolean
   close(): void
@@ -329,10 +341,20 @@ export class Connection {
   createTable(name: string, buf: Buffer, mode: string, namespace: Array<string>, storageOptions?: Record<string, string> | undefined | null): Promise<Table>
   createEmptyTable(name: string, schemaBuf: Buffer, mode: string, namespace: Array<string>, storageOptions?: Record<string, string> | undefined | null): Promise<Table>
   openTable(name: string, namespace: Array<string>, storageOptions?: Record<string, string> | undefined | null, indexCacheSize?: number | undefined | null): Promise<Table>
+  cloneTable(targetTableName: string, sourceUri: string, targetNamespace: Array<string>, 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. */
   dropTable(name: string, namespace: Array<string>): Promise<void>
   dropAllTables(namespace: Array<string>): Promise<void>
 }
+/**
+ * JavaScript HeaderProvider implementation that wraps a JavaScript callback.
+ * This is the only native header provider - all header provider implementations
+ * should provide a JavaScript function that returns headers.
+ */
+export class JsHeaderProvider {
+  /** Create a new JsHeaderProvider from a JavaScript callback */
+  constructor(getHeadersCallback: (...args: any[]) => any)
+}
 export class Index {
   static ivfPq(distanceType?: string | undefined | null, numPartitions?: number | undefined | null, numSubVectors?: number | undefined | null, numBits?: number | undefined | null, maxIterations?: number | undefined | null, sampleRate?: number | undefined | null): Index
   static ivfFlat(distanceType?: string | undefined | null, numPartitions?: number | undefined | null, maxIterations?: number | undefined | null, sampleRate?: number | undefined | null): Index
@@ -353,6 +375,7 @@ export class NativeMergeInsertBuilder {
   whenNotMatchedInsertAll(): NativeMergeInsertBuilder
   whenNotMatchedBySourceDelete(filter?: string | undefined | null): NativeMergeInsertBuilder
   setTimeout(timeout: number): void
+  useIndex(useIndex: boolean): NativeMergeInsertBuilder
   execute(buf: Buffer): Promise<MergeResult>
 }
 export class Query {

package/dist/native.js

@@ -319,8 +319,9 @@ if (!nativeBinding) {
     }
     throw new Error(`Failed to load native binding`);
 }
-const { Connection, Index, RecordBatchIterator, NativeMergeInsertBuilder, Query, VectorQuery, TakeQuery, JsFullTextQuery, Reranker, RrfReranker, Session, Table, TagContents, Tags } = nativeBinding;
+const { Connection, JsHeaderProvider, Index, RecordBatchIterator, NativeMergeInsertBuilder, Query, VectorQuery, TakeQuery, JsFullTextQuery, Reranker, RrfReranker, Session, Table, TagContents, Tags } = nativeBinding;
 module.exports.Connection = Connection;
+module.exports.JsHeaderProvider = JsHeaderProvider;
 module.exports.Index = Index;
 module.exports.RecordBatchIterator = RecordBatchIterator;
 module.exports.NativeMergeInsertBuilder = NativeMergeInsertBuilder;

package/package.json

@@ -11,7 +11,7 @@
     "ann"
   ],
   "private": false,
-  "version": "0.22.0",
+  "version": "0.22.2-beta.1",
   "main": "dist/index.js",
   "exports": {
     ".": "./dist/index.js",
@@ -100,14 +100,14 @@
     "reflect-metadata": "^0.2.2"
   },
   "optionalDependencies": {
-    "@lancedb/lancedb-darwin-x64": "0.22.0",
-    "@lancedb/lancedb-darwin-arm64": "0.22.0",
-    "@lancedb/lancedb-linux-x64-gnu": "0.22.0",
-    "@lancedb/lancedb-linux-arm64-gnu": "0.22.0",
-    "@lancedb/lancedb-linux-x64-musl": "0.22.0",
-    "@lancedb/lancedb-linux-arm64-musl": "0.22.0",
-    "@lancedb/lancedb-win32-x64-msvc": "0.22.0",
-    "@lancedb/lancedb-win32-arm64-msvc": "0.22.0"
+    "@lancedb/lancedb-darwin-x64": "0.22.2-beta.1",
+    "@lancedb/lancedb-darwin-arm64": "0.22.2-beta.1",
+    "@lancedb/lancedb-linux-x64-gnu": "0.22.2-beta.1",
+    "@lancedb/lancedb-linux-arm64-gnu": "0.22.2-beta.1",
+    "@lancedb/lancedb-linux-x64-musl": "0.22.2-beta.1",
+    "@lancedb/lancedb-linux-arm64-musl": "0.22.2-beta.1",
+    "@lancedb/lancedb-win32-x64-msvc": "0.22.2-beta.1",
+    "@lancedb/lancedb-win32-arm64-msvc": "0.22.2-beta.1"
   },
   "peerDependencies": {
     "apache-arrow": ">=15.0.0 <=18.1.0"