@lancedb/lancedb 0.37.1 → 0.38.0-beta.12

package/dist/embedding/index.d.ts

@@ -1,7 +1,17 @@
 import { Schema } from "../arrow";
 import { EmbeddingFunction } from "./embedding_function";
+import { EmbeddingFunctionRegistry } from "./registry";
 export { FieldOptions, EmbeddingFunction, TextEmbeddingFunction, FunctionOptions, EmbeddingFunctionConstructor, } from "./embedding_function";
-export * from "./registry";
+export { EmbeddingFunctionRegistry, parseEmbeddingMetadata, register, } from "./registry";
+export type { CreateReturnType, EmbeddingFunctionConfig, EmbeddingFunctionCreate, EmbeddingMetadataEntry, ResolvedEmbeddingFunctionConfig, } from "./registry";
+/**
+ * Get the global embedding function registry.
+ *
+ * LanceDB built-in providers are initialized when this public API is first
+ * used, so importing the root package does not change automatic search
+ * selection for tables without embedding metadata.
+ */
+export declare function getRegistry(): EmbeddingFunctionRegistry;
 /**
  * Create a schema with embedding functions.
  *

package/dist/embedding/index.js

@@ -1,22 +1,9 @@
 "use strict";
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: Copyright The LanceDB Authors
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TextEmbeddingFunction = exports.EmbeddingFunction = void 0;
+exports.register = exports.parseEmbeddingMetadata = exports.EmbeddingFunctionRegistry = exports.TextEmbeddingFunction = exports.EmbeddingFunction = void 0;
+exports.getRegistry = getRegistry;
 exports.LanceSchema = LanceSchema;
 const arrow_1 = require("../arrow");
 const sanitize_1 = require("../sanitize");
@@ -24,7 +11,27 @@ const registry_1 = require("./registry");
 var embedding_function_1 = require("./embedding_function");
 Object.defineProperty(exports, "EmbeddingFunction", { enumerable: true, get: function () { return embedding_function_1.EmbeddingFunction; } });
 Object.defineProperty(exports, "TextEmbeddingFunction", { enumerable: true, get: function () { return embedding_function_1.TextEmbeddingFunction; } });
-__exportStar(require("./registry"), exports);
+var registry_2 = require("./registry");
+Object.defineProperty(exports, "EmbeddingFunctionRegistry", { enumerable: true, get: function () { return registry_2.EmbeddingFunctionRegistry; } });
+Object.defineProperty(exports, "parseEmbeddingMetadata", { enumerable: true, get: function () { return registry_2.parseEmbeddingMetadata; } });
+Object.defineProperty(exports, "register", { enumerable: true, get: function () { return registry_2.register; } });
+function initializeBuiltInProviders() {
+    const { OpenAIEmbeddingFunction } = require("./openai");
+    const { TransformersEmbeddingFunction } = require("./transformers");
+    (0, registry_1.registerBuiltIn)("openai", OpenAIEmbeddingFunction);
+    (0, registry_1.registerBuiltIn)("huggingface", TransformersEmbeddingFunction);
+}
+/**
+ * Get the global embedding function registry.
+ *
+ * LanceDB built-in providers are initialized when this public API is first
+ * used, so importing the root package does not change automatic search
+ * selection for tables without embedding metadata.
+ */
+function getRegistry() {
+    initializeBuiltInProviders();
+    return (0, registry_1.getRegistry)();
+}
 /**
  * Create a schema with embedding functions.
  *
@@ -60,7 +67,7 @@ function LanceSchema(fields) {
             arrowFields.push(new arrow_1.Field(key, (0, sanitize_1.sanitizeType)(value), true));
         }
     });
-    const registry = (0, registry_1.getRegistry)();
+    const registry = getRegistry();
     const metadata = registry.getTableMetadata(Array.from(embeddingFunctions.values()));
     const schema = new arrow_1.Schema(arrowFields, metadata);
     return schema;

package/dist/embedding/openai.js

@@ -1,21 +1,12 @@
 "use strict";
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: Copyright The LanceDB Authors
-var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
-    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
-    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
-    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
-    return c > 3 && r && Object.defineProperty(target, key, r), r;
-};
-var __metadata = (this && this.__metadata) || function (k, v) {
-    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OpenAIEmbeddingFunction = void 0;
 const arrow_1 = require("../arrow");
 const embedding_function_1 = require("./embedding_function");
 const registry_1 = require("./registry");
-let OpenAIEmbeddingFunction = class OpenAIEmbeddingFunction extends embedding_function_1.EmbeddingFunction {
+class OpenAIEmbeddingFunction extends embedding_function_1.EmbeddingFunction {
     #openai;
     #modelName;
     constructor(optionsRaw = {
@@ -85,9 +76,6 @@ let OpenAIEmbeddingFunction = class OpenAIEmbeddingFunction extends embedding_fu
         });
         return response.data[0].embedding;
     }
-};
+}
 exports.OpenAIEmbeddingFunction = OpenAIEmbeddingFunction;
-exports.OpenAIEmbeddingFunction = OpenAIEmbeddingFunction = __decorate([
-    (0, registry_1.register)("openai"),
-    __metadata("design:paramtypes", [Object])
-], OpenAIEmbeddingFunction);
+(0, registry_1.registerBuiltIn)("openai", OpenAIEmbeddingFunction);

package/dist/embedding/registry.d.ts

@@ -23,6 +23,8 @@ export declare class EmbeddingFunctionRegistry {
      * @throws Error if the function is already registered
      */
     register<T extends EmbeddingFunctionConstructor = EmbeddingFunctionConstructor>(this: EmbeddingFunctionRegistry, alias?: string): (ctor: T) => any;
+    /** @ignore */
+    setBuiltIn<T extends EmbeddingFunctionConstructor = EmbeddingFunctionConstructor>(name: string, ctor: T): T;
     get<T extends EmbeddingFunction<unknown>>(name: string): EmbeddingFunctionCreate<T> | undefined;
     /**
      * reset the registry to the initial state
@@ -31,7 +33,7 @@ export declare class EmbeddingFunctionRegistry {
     /**
      * @ignore
      */
-    parseFunctions(this: EmbeddingFunctionRegistry, metadata: Map<string, string>): Promise<Map<string, EmbeddingFunctionConfig>>;
+    parseFunctions(this: EmbeddingFunctionRegistry, metadata: Map<string, string>): Promise<Map<string, ResolvedEmbeddingFunctionConfig>>;
     functionToMetadata(conf: EmbeddingFunctionConfig): Record<string, any>;
     getTableMetadata(functions: EmbeddingFunctionConfig[]): Map<string, string>;
     /**
@@ -58,6 +60,8 @@ export declare class EmbeddingFunctionRegistry {
     getVar(name: string): string | undefined;
 }
 export declare function register(name?: string): (ctor: EmbeddingFunctionConstructor<EmbeddingFunction<any, import("./embedding_function").FunctionOptions>>) => any;
+/** @ignore */
+export declare function registerBuiltIn<T extends EmbeddingFunctionConstructor = EmbeddingFunctionConstructor>(name: string, ctor: T): T;
 /**
  * Utility function to get the global instance of the registry
  * @returns `EmbeddingFunctionRegistry` The global instance of the registry
@@ -72,3 +76,19 @@ export interface EmbeddingFunctionConfig {
     vectorColumn?: string;
     function: EmbeddingFunction;
 }
+/** An [EmbeddingFunctionConfig] read back from table metadata, where the
+ * vector column is always recorded. */
+export type ResolvedEmbeddingFunctionConfig = EmbeddingFunctionConfig & {
+    vectorColumn: string;
+};
+/** One entry of the `embedding_functions` schema metadata, with the column
+ * keys normalized across the bindings' spellings. */
+export type EmbeddingMetadataEntry = {
+    name: string;
+    sourceColumn: string;
+    vectorColumn: string;
+    model: EmbeddingFunction["TOptions"];
+};
+/** The single parser for `embedding_functions` schema metadata: every reader
+ * goes through here, so the wire contract cannot fork between them. */
+export declare function parseEmbeddingMetadata(json: string): EmbeddingMetadataEntry[];

package/dist/embedding/registry.js

@@ -4,8 +4,11 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EmbeddingFunctionRegistry = void 0;
 exports.register = register;
+exports.registerBuiltIn = registerBuiltIn;
 exports.getRegistry = getRegistry;
+exports.parseEmbeddingMetadata = parseEmbeddingMetadata;
 require("reflect-metadata");
+const builtInFunctionsKey = Symbol.for("@lancedb/lancedb::embedding-built-in-functions::v1");
 /**
  * This is a singleton class used to register embedding functions
  * and fetch them by name. It also handles serializing and deserializing.
@@ -39,6 +42,12 @@ class EmbeddingFunctionRegistry {
             return ctor;
         };
     }
+    /** @ignore */
+    setBuiltIn(name, ctor) {
+        this.#functions.set(name, ctor);
+        Reflect.defineMetadata("lancedb::embedding::name", name, ctor);
+        return ctor;
+    }
     /**
      * Fetch an embedding function by name
      * @param name The name of the function
@@ -72,6 +81,7 @@ class EmbeddingFunctionRegistry {
      */
     reset() {
         this.#functions.clear();
+        getBuiltInFunctions(this).clear();
     }
     /**
      * @ignore
@@ -80,25 +90,21 @@ class EmbeddingFunctionRegistry {
         if (!metadata.has("embedding_functions")) {
             return new Map();
         }
-        else {
-            const functions = (JSON.parse(metadata.get("embedding_functions")));
-            const items = await Promise.all(functions.map(async (f) => {
-                const fn = this.get(f.name);
-                if (!fn) {
-                    throw new Error(`Function "${f.name}" not found in registry`);
-                }
-                const func = await this.get(f.name).create(f.model);
-                return [
-                    f.name,
-                    {
-                        sourceColumn: f.sourceColumn,
-                        vectorColumn: f.vectorColumn,
-                        function: func,
-                    },
-                ];
-            }));
-            return new Map(items);
-        }
+        const entries = parseEmbeddingMetadata(metadata.get("embedding_functions"));
+        const items = await Promise.all(entries.map(async (f) => {
+            const fn = this.get(f.name);
+            if (!fn) {
+                throw new Error(`Function "${f.name}" not found in registry`);
+            }
+            const func = await fn.create(f.model);
+            return {
+                sourceColumn: f.sourceColumn,
+                vectorColumn: f.vectorColumn,
+                function: func,
+            };
+        }));
+        // Keyed by output column: one function may serve several columns.
+        return new Map(items.map((config) => [config.vectorColumn, config]));
     }
     // biome-ignore lint/suspicious/noExplicitAny: <explanation>
     functionToMetadata(conf) {
@@ -148,10 +154,42 @@ class EmbeddingFunctionRegistry {
     }
 }
 exports.EmbeddingFunctionRegistry = EmbeddingFunctionRegistry;
-const _REGISTRY = new EmbeddingFunctionRegistry();
+function getBuiltInFunctions(registry) {
+    const registryWithBuiltIns = registry;
+    let builtInFunctions = registryWithBuiltIns[builtInFunctionsKey];
+    if (builtInFunctions === undefined) {
+        builtInFunctions = new Set();
+        registryWithBuiltIns[builtInFunctionsKey] = builtInFunctions;
+    }
+    return builtInFunctions;
+}
+// Server bundlers can load the side-effect embedding entry points and the public
+// embedding API from separate module graphs. Keep their registry shared.
+const registryKey = Symbol.for("@lancedb/lancedb::embedding-function-registry::v1");
+const registryGlobal = globalThis;
+function getGlobalRegistry() {
+    const existingRegistry = registryGlobal[registryKey];
+    if (existingRegistry !== undefined) {
+        return existingRegistry;
+    }
+    const registry = new EmbeddingFunctionRegistry();
+    registryGlobal[registryKey] = registry;
+    return registry;
+}
+const _REGISTRY = getGlobalRegistry();
 function register(name) {
     return _REGISTRY.register(name);
 }
+/** @ignore */
+function registerBuiltIn(name, ctor) {
+    const builtInFunctions = getBuiltInFunctions(_REGISTRY);
+    if (builtInFunctions.has(name)) {
+        return _REGISTRY.setBuiltIn(name, ctor);
+    }
+    _REGISTRY.register(name)(ctor);
+    builtInFunctions.add(name);
+    return ctor;
+}
 /**
  * Utility function to get the global instance of the registry
  * @returns `EmbeddingFunctionRegistry` The global instance of the registry
@@ -163,3 +201,21 @@ function register(name) {
 function getRegistry() {
     return _REGISTRY;
 }
+/** The single parser for `embedding_functions` schema metadata: every reader
+ * goes through here, so the wire contract cannot fork between them. */
+function parseEmbeddingMetadata(json) {
+    const entries = JSON.parse(json);
+    const seen = new Set();
+    return entries.map((f) => {
+        const sourceColumn = f.sourceColumn ?? f.source_column;
+        const vectorColumn = f.vectorColumn ?? f.vector_column;
+        if (sourceColumn === undefined || vectorColumn === undefined) {
+            throw new Error(`Embedding function "${f.name}" metadata names no source or vector column`);
+        }
+        if (seen.has(vectorColumn)) {
+            throw new Error(`Multiple embedding configs claim vector column "${vectorColumn}"`);
+        }
+        seen.add(vectorColumn);
+        return { name: f.name, sourceColumn, vectorColumn, model: f.model };
+    });
+}

package/dist/embedding/transformers.js

@@ -1,21 +1,12 @@
 "use strict";
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: Copyright The LanceDB Authors
-var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
-    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
-    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
-    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
-    return c > 3 && r && Object.defineProperty(target, key, r), r;
-};
-var __metadata = (this && this.__metadata) || function (k, v) {
-    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TransformersEmbeddingFunction = void 0;
 const arrow_1 = require("../arrow");
 const embedding_function_1 = require("./embedding_function");
 const registry_1 = require("./registry");
-let TransformersEmbeddingFunction = class TransformersEmbeddingFunction extends embedding_function_1.EmbeddingFunction {
+class TransformersEmbeddingFunction extends embedding_function_1.EmbeddingFunction {
     #model;
     #tokenizer;
     #modelName;
@@ -108,12 +99,9 @@ let TransformersEmbeddingFunction = class TransformersEmbeddingFunction extends
     async computeQueryEmbeddings(data) {
         return (await this.computeSourceEmbeddings([data]))[0];
     }
-};
+}
 exports.TransformersEmbeddingFunction = TransformersEmbeddingFunction;
-exports.TransformersEmbeddingFunction = TransformersEmbeddingFunction = __decorate([
-    (0, registry_1.register)("huggingface"),
-    __metadata("design:paramtypes", [Object])
-], TransformersEmbeddingFunction);
+(0, registry_1.registerBuiltIn)("huggingface", TransformersEmbeddingFunction);
 const tensorDiv = (src, divBy) => {
     for (let i = 0; i < src.data.length; ++i) {
         src.data[i] /= divBy;

package/dist/index.d.ts

@@ -3,15 +3,16 @@ import { ConnectNamespaceOptions, ConnectionOptions, Session } from "./native.js
 import { HeaderProvider } from "./header";
 import type { BaseTokenizer } from "./indices";
 import type { FtsToken } from "./table";
+export { MaterializedView, MaterializedViewDefinition, MaterializedViewSelect, } from "./materialized_view";
 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, AlterColumnsResult, UpdateFieldMetadataResult, DeleteResult, DropColumnsResult, UpdateResult, SplitCalculatedOptions, SplitRandomOptions, SplitHashOptions, SplitSequentialOptions, ShuffleOptions, OAuthConfig as NativeOAuthConfig, } from "./native.js";
+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 { Connection, CreateTableOptions, TableNamesOptions, OpenTableOptions, ListNamespacesOptions, CreateNamespaceOptions, DropNamespaceOptions, ListNamespacesResponse, CreateNamespaceResponse, DropNamespaceResponse, DescribeNamespaceResponse, RenameTableOptions, } from "./connection";
+export { Connection, CreateTableOptions, TableNamesOptions, ListTablesOptions, OpenTableOptions, ListNamespacesOptions, CreateNamespaceOptions, DropNamespaceOptions, ListNamespacesResponse, ListTablesResponse, CreateNamespaceResponse, DropNamespaceResponse, DescribeNamespaceResponse, RenameTableOptions, } from "./connection";
 export { Job, JobDescription, JobFailureInfo, JobInfo, Session, } from "./native.js";
-export { ExecutableQuery, Query, QueryBase, VectorQuery, TakeQuery, AnalyzePlanDistributedMetrics, QueryExecutionOptions, ColumnOrdering, FullTextSearchOptions, RecordBatchIterator, FullTextQuery, MatchQuery, PhraseQuery, BoostQuery, MultiMatchQuery, BooleanQuery, FullTextQueryType, Operator, Occur, } from "./query";
+export { AutoQuery, ExecutableQuery, Query, QueryBase, VectorQuery, TakeQuery, AnalyzePlanDistributedMetrics, QueryExecutionOptions, ColumnOrdering, FullTextSearchOptions, RecordBatchIterator, FullTextQuery, MatchQuery, PhraseQuery, BoostQuery, MultiMatchQuery, BooleanQuery, FullTextQueryType, Operator, Occur, } from "./query";
 export { Index, IndexOptions, IvfPqOptions, IvfRqOptions, IvfFlatOptions, HnswPqOptions, HnswSqOptions, FtsOptions, BaseTokenizer, } from "./indices";
-export { Table, Branches, BranchColumnSummary, BranchColumnChange, BranchIndexSummary, BranchRowCountSummary, MergeBlocker, BranchDiff, MergePreview, MergeBranchResult, AddDataOptions, UpdateOptions, OptimizeOptions, Version, WriteProgress, FtsToken, TokenizeTableOptions, LsmWriteSpec, ColumnAlteration, FieldMetadataUpdate, } from "./table";
+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 { MergeInsertBuilder, WriteExecutionOptions } from "./merge";

package/dist/index.js

@@ -2,13 +2,15 @@
 // 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.Session = exports.Job = exports.Connection = exports.VectorColumnOptions = exports.MakeArrowTableOptions = exports.makeArrowTable = exports.BranchContents = exports.TagContents = exports.Tags = exports.instrumentLanceDbMetrics = exports.NativeJsHeaderProvider = void 0;
+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.Session = exports.Job = exports.Connection = exports.VectorColumnOptions = exports.MakeArrowTableOptions = 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;
 const connection_1 = require("./connection");
 const native_js_1 = require("./native.js");
 // Re-export native header provider for use with connectWithHeaderProvider
+var materialized_view_1 = require("./materialized_view");
+Object.defineProperty(exports, "MaterializedView", { enumerable: true, get: function () { return materialized_view_1.MaterializedView; } });
 var native_js_2 = require("./native.js");
 Object.defineProperty(exports, "NativeJsHeaderProvider", { enumerable: true, get: function () { return native_js_2.JsHeaderProvider; } });
 // OpenTelemetry metrics bridge. Only the high-level entry point is public; the
@@ -30,6 +32,7 @@ var native_js_4 = require("./native.js");
 Object.defineProperty(exports, "Job", { enumerable: true, get: function () { return native_js_4.Job; } });
 Object.defineProperty(exports, "Session", { enumerable: true, get: function () { return native_js_4.Session; } });
 var query_1 = require("./query");
+Object.defineProperty(exports, "AutoQuery", { enumerable: true, get: function () { return query_1.AutoQuery; } });
 Object.defineProperty(exports, "Query", { enumerable: true, get: function () { return query_1.Query; } });
 Object.defineProperty(exports, "QueryBase", { enumerable: true, get: function () { return query_1.QueryBase; } });
 Object.defineProperty(exports, "VectorQuery", { enumerable: true, get: function () { return query_1.VectorQuery; } });

package/dist/materialized_view.d.ts

@@ -0,0 +1,69 @@
+import { RefreshMaterializedViewResult } from "./native";
+import { Table } from "./table";
+/** Schema metadata key holding a materialized view's definition. */
+export declare const DEFINITION_META_KEY = "mv.definition";
+/** The query that defines a materialized view. */
+export interface MaterializedViewDefinition {
+    /** Name of the source table, in the same database as the view. */
+    sourceTable: string;
+    /** `[output column, SQL expression]` pairs, in view schema order. */
+    projections: [string, string][];
+    /** SQL predicate selecting the source rows the view holds. */
+    filter?: string;
+    /** Cap on the number of rows the view holds. */
+    limit?: number;
+    /** Source columns the projections and filter read. */
+    inputs: string[];
+}
+/**
+ * The view's columns: column names, `[alias, SQL expression]` pairs, or a
+ * record of the same. A bare name projects itself.
+ */
+export type MaterializedViewSelect = (string | [string, string])[] | Record<string, string>;
+/**
+ * @internal Reject a numeric option N-API would otherwise silently coerce:
+ * `Infinity` reaches Rust as 0, `1.5` as 1.
+ */
+export declare function validateNonNegativeInteger(value: number | undefined, name: string): void;
+/**
+ * @internal Normalize a select argument into `[alias, expression]` pairs.
+ * A bare name projects itself and is quoted, so any valid column name works;
+ * pair and record entries are kept verbatim because their right side is an
+ * expression.
+ */
+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;
+/**
+ * A handle on a materialized view: its table plus its definition.
+ *
+ * Obtained from {@link Connection#createMaterializedView} or
+ * {@link Connection#openMaterializedView}. The view is a normal table --
+ * queries, indexes and search all apply through {@link MaterializedView#table}
+ * -- whose contents are maintained by {@link MaterializedView#refresh}.
+ */
+export declare class MaterializedView {
+    private readonly inner;
+    constructor(table: Table);
+    get name(): string;
+    /** The view, as the table it is. */
+    table(): Table;
+    /** The query that defines the view, read from its stored schema. */
+    definition(): Promise<MaterializedViewDefinition>;
+    /**
+     * Recompute the view from its source.
+     *
+     * The refresh is incremental when the source's changes can be reconciled
+     * into the view -- rows added, changed or removed since the last one --
+     * and otherwise rebuilds. `full` forces a rebuild; `sourceVersion`
+     * refreshes to that source version instead of the latest.
+     *
+     * Concurrent refreshes of one view do not duplicate its rows. Two that
+     * plan the same source rows conflict on commit, and the loser throws
+     * rather than writing them a second time.
+     */
+    refresh(options?: {
+        full?: boolean;
+        sourceVersion?: number;
+    }): Promise<RefreshMaterializedViewResult>;
+}

package/dist/materialized_view.js

@@ -0,0 +1,112 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright The LanceDB Authors
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MaterializedView = exports.DEFINITION_META_KEY = void 0;
+exports.validateNonNegativeInteger = validateNonNegativeInteger;
+exports.normalizeSelect = normalizeSelect;
+exports.definitionFromMetadata = definitionFromMetadata;
+/** Schema metadata key holding a materialized view's definition. */
+exports.DEFINITION_META_KEY = "mv.definition";
+/**
+ * @internal Reject a numeric option N-API would otherwise silently coerce:
+ * `Infinity` reaches Rust as 0, `1.5` as 1.
+ */
+function validateNonNegativeInteger(value, name) {
+    if (value !== undefined && !(Number.isSafeInteger(value) && value >= 0)) {
+        throw new Error(`${name} must be a non-negative integer`);
+    }
+}
+/** @internal Quote a column name as a Lance SQL identifier (backticks). */
+function quoteIdentifier(name) {
+    return "`" + name.replace(/`/g, "``") + "`";
+}
+/**
+ * @internal Normalize a select argument into `[alias, expression]` pairs.
+ * A bare name projects itself and is quoted, so any valid column name works;
+ * pair and record entries are kept verbatim because their right side is an
+ * expression.
+ */
+function normalizeSelect(select) {
+    if (select === undefined) {
+        return undefined;
+    }
+    if (Array.isArray(select)) {
+        return select.map((item) => typeof item === "string" ? [item, quoteIdentifier(item)] : item);
+    }
+    return Object.entries(select);
+}
+/** @internal Parse a definition off a table's stored schema metadata. */
+function definitionFromMetadata(metadata, name) {
+    const raw = metadata.get(exports.DEFINITION_META_KEY);
+    if (raw === undefined) {
+        throw new Error(`Table '${name}' is not a materialized view`);
+    }
+    // biome-ignore lint/suspicious/noExplicitAny: raw JSON
+    const value = JSON.parse(raw);
+    if (value.kind !== "select") {
+        throw new Error(`materialized view '${name}' is defined by '${value.kind}', which this ` +
+            "version of lancedb cannot refresh");
+    }
+    const limit = value.limit ?? undefined;
+    // JSON.parse rounds integers past 2^53; every exact u64 parses to a safe
+    // integer and every rounded one does not, so this rejects precisely the
+    // values a number cannot carry.
+    if (limit !== undefined && !Number.isSafeInteger(limit)) {
+        throw new Error(`materialized view '${name}' has a stored limit too large to represent exactly`);
+    }
+    return {
+        sourceTable: value.source_table,
+        // biome-ignore lint/suspicious/noExplicitAny: raw JSON
+        projections: (value.projections ?? []).map((p) => [
+            p.output,
+            p.expression,
+        ]),
+        filter: value.filter ?? undefined,
+        limit,
+        inputs: value.inputs ?? [],
+    };
+}
+/**
+ * A handle on a materialized view: its table plus its definition.
+ *
+ * Obtained from {@link Connection#createMaterializedView} or
+ * {@link Connection#openMaterializedView}. The view is a normal table --
+ * queries, indexes and search all apply through {@link MaterializedView#table}
+ * -- whose contents are maintained by {@link MaterializedView#refresh}.
+ */
+class MaterializedView {
+    inner;
+    constructor(table) {
+        this.inner = table;
+    }
+    get name() {
+        return this.inner.name;
+    }
+    /** The view, as the table it is. */
+    table() {
+        return this.inner;
+    }
+    /** The query that defines the view, read from its stored schema. */
+    async definition() {
+        const schema = await this.inner.schema();
+        return definitionFromMetadata(schema.metadata, this.name);
+    }
+    /**
+     * Recompute the view from its source.
+     *
+     * The refresh is incremental when the source's changes can be reconciled
+     * into the view -- rows added, changed or removed since the last one --
+     * and otherwise rebuilds. `full` forces a rebuild; `sourceVersion`
+     * refreshes to that source version instead of the latest.
+     *
+     * Concurrent refreshes of one view do not duplicate its rows. Two that
+     * plan the same source rows conflict on commit, and the loser throws
+     * rather than writing them a second time.
+     */
+    async refresh(options) {
+        validateNonNegativeInteger(options?.sourceVersion, "sourceVersion");
+        return await this.inner.refreshMaterializedView(options?.full, options?.sourceVersion);
+    }
+}
+exports.MaterializedView = MaterializedView;