@lancedb/lancedb 0.21.2-beta.1 → 0.21.2

package/CLAUDE.md

@@ -0,0 +1,13 @@
+These are the typescript bindings of LanceDB.
+The core Rust library is in the `../rust/lancedb` directory, the rust binding
+code is in the `src/` directory and the typescript bindings are in
+the `lancedb/` directory.
+
+Whenever you change the Rust code, you will need to recompile: `npm run build`.
+
+Common commands:
+* Build: `npm run build`
+* Lint: `npm run lint`
+* Fix lints: `npm run lint-fix`
+* Test: `npm test`
+* Run single test file: `npm test __test__/arrow.test.ts`

package/dist/connection.d.ts

@@ -62,6 +62,9 @@ export interface OpenTableOptions {
     /**
      * 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

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 import { Connection } from "./connection";
-import { ConnectionOptions } from "./native.js";
+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";
 export { makeArrowTable, MakeArrowTableOptions, Data, VectorColumnOptions, } from "./arrow";
 export { Connection, CreateTableOptions, TableNamesOptions, OpenTableOptions, } from "./connection";
+export { Session } from "./native.js";
 export { ExecutableQuery, Query, QueryBase, VectorQuery, 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";
@@ -35,7 +36,7 @@ export { IntoSql, packBits } from "./util";
  * });
  * ```
  */
-export declare function connect(uri: string, options?: Partial<ConnectionOptions>): Promise<Connection>;
+export declare function connect(uri: string, options?: Partial<ConnectionOptions>, session?: Session): Promise<Connection>;
 /**
  * Connect to a LanceDB instance at the given URI.
  *
@@ -53,6 +54,15 @@ export declare function connect(uri: string, options?: Partial<ConnectionOptions
  *   storageOptions: {timeout: "60s"}
  * });
  * ```
+ *
+ * @example
+ * ```ts
+ * const session = Session.default();
+ * const conn = await connect({
+ *   uri: "/path/to/database",
+ *   session: session
+ * });
+ * ```
  */
 export declare function connect(options: Partial<ConnectionOptions> & {
     uri: string;

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.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.VectorQuery = exports.QueryBase = exports.Query = exports.Connection = exports.VectorColumnOptions = exports.MakeArrowTableOptions = exports.makeArrowTable = exports.TagContents = exports.Tags = void 0;
+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.VectorQuery = exports.QueryBase = exports.Query = exports.Session = exports.Connection = exports.VectorColumnOptions = exports.MakeArrowTableOptions = exports.makeArrowTable = exports.TagContents = exports.Tags = void 0;
 exports.connect = connect;
 const connection_1 = require("./connection");
 const native_js_1 = require("./native.js");
@@ -15,6 +15,8 @@ Object.defineProperty(exports, "MakeArrowTableOptions", { enumerable: true, get:
 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 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; } });
@@ -38,21 +40,23 @@ 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, options) {
     let uri;
+    let finalOptions = {};
     if (typeof uriOrOptions !== "string") {
         const { uri: uri_, ...opts } = uriOrOptions;
         uri = uri_;
-        options = opts;
+        finalOptions = opts;
     }
     else {
         uri = uriOrOptions;
+        finalOptions = options || {};
     }
     if (!uri) {
         throw new Error("uri is required");
     }
-    options = options ?? {};
-    options.storageOptions = (0, connection_1.cleanseStorageOptions)(options.storageOptions);
-    const nativeConn = await native_js_1.Connection.new(uri, options);
+    finalOptions = finalOptions ?? {};
+    finalOptions.storageOptions = (0, connection_1.cleanseStorageOptions)(finalOptions.storageOptions);
+    const nativeConn = await native_js_1.Connection.new(uri, finalOptions);
     return new connection_1.LocalConnection(nativeConn);
 }

package/dist/native.d.ts

@@ -274,6 +274,11 @@ export interface ConnectionOptions {
    * The available options are described at https://lancedb.github.io/lancedb/guides/storage/
    */
   storageOptions?: Record<string, string>
+  /**
+   * (For LanceDB OSS only): the session to use for this connection. Holds
+   * shared caches and other session-specific state.
+   */
+  session?: Session
   /** (For LanceDB cloud only): configuration for the remote HTTP client. */
   clientConfig?: ClientConfig
   /**
@@ -403,6 +408,40 @@ export class RrfReranker {
   static tryNew(k: Float32Array): Promise<RrfReranker>
   rerankHybrid(query: string, vecResults: Buffer, ftsResults: Buffer): Promise<Buffer>
 }
+/**
+ * A session for managing caches and object stores across LanceDB operations.
+ *
+ * Sessions allow you to configure cache sizes for index and metadata caches,
+ * which can significantly impact memory use and performance. They can
+ * also be re-used across multiple connections to share the same cache state.
+ */
+export class Session {
+  /**
+   * Create a new session with custom cache sizes.
+   *
+   * # Parameters
+   *
+   * - `index_cache_size_bytes`: The size of the index cache in bytes.
+   *   Index data is stored in memory in this cache to speed up queries.
+   *   Defaults to 6GB if not specified.
+   * - `metadata_cache_size_bytes`: The size of the metadata cache in bytes.
+   *   The metadata cache stores file metadata and schema information in memory.
+   *   This cache improves scan and write performance.
+   *   Defaults to 1GB if not specified.
+   */
+  constructor(indexCacheSizeBytes?: bigint | undefined | null, metadataCacheSizeBytes?: bigint | undefined | null)
+  /**
+   * Create a session with default cache sizes.
+   *
+   * This is equivalent to creating a session with 6GB index cache
+   * and 1GB metadata cache.
+   */
+  static default(): Session
+  /** Get the current size of the session caches in bytes. */
+  sizeBytes(): bigint
+  /** Get the approximate number of items cached in the session. */
+  approxNumItems(): number
+}
 export class Table {
   name: string
   display(): string

package/dist/native.js

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

package/package.json

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