@lancedb/lancedb 0.38.0-beta.0 → 0.38.0-beta.13

package/dist/schema.js

@@ -0,0 +1,387 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright The LanceDB Authors
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.inferSchema = inferSchema;
+const apache_arrow_1 = require("apache-arrow");
+const arrow_type_1 = require("./arrow_type");
+const sanitize_1 = require("./sanitize");
+/**
+ * Infer the Arrow schema represented by a set of records.
+ *
+ * This is the intentionally small interface to schema inference. The stateful
+ * details of combining partial type evidence are encapsulated below so callers
+ * only need to provide records, an optional schema, and inference options.
+ */
+function inferSchema(data, schema, options) {
+    return new SchemaInferrer(schema, options).infer(data);
+}
+class SchemaInferrer {
+    providedSchema;
+    options;
+    fields = new FieldTree();
+    constructor(providedSchema, options) {
+        this.providedSchema = providedSchema;
+        this.options = options;
+    }
+    infer(data) {
+        for (const [row, record] of data.entries()) {
+            for (const [path, value] of recordPathsAndValues(record)) {
+                this.observe(path, value, row);
+            }
+        }
+        return this.providedSchema === undefined
+            ? new apache_arrow_1.Schema(fieldsFromTree(this.fields))
+            : new apache_arrow_1.Schema(matchingFields(this.providedSchema.fields, this.fields));
+    }
+    observe(path, value, row) {
+        const current = this.fields.get(path);
+        if (current === undefined) {
+            this.addField(path, value, row);
+        }
+        else if (this.providedSchema === undefined) {
+            this.updateInferredField(path, value, row, current);
+        }
+    }
+    addField(path, value, row) {
+        if (this.providedSchema !== undefined) {
+            this.addSchemaField(this.providedSchema, path, row);
+            return;
+        }
+        const evidence = this.inferType(value, path) ?? DeferredTypeEvidence.from(value, row);
+        if (evidence === undefined) {
+            throw typeInferenceError(path, row);
+        }
+        const conflict = this.fields.set(path, evidence, (existing) => existing instanceof DeferredTypeEvidence && existing.isOnlyNulls());
+        if (conflict !== undefined) {
+            throw branchConflictError(conflict, row, "Struct");
+        }
+    }
+    addSchemaField(schema, path, row) {
+        const field = fieldAtPath(schema, path);
+        if (field === undefined) {
+            throw new Error(`Found field not in schema: ${path.join(".")} at row ${row}`);
+        }
+        const conflict = this.fields.set(path, field.type);
+        if (conflict !== undefined) {
+            throw branchConflictError(conflict, row, "Struct");
+        }
+    }
+    updateInferredField(path, value, row, current) {
+        const newType = this.inferType(value, path);
+        const deferred = DeferredTypeEvidence.from(value, row);
+        if (current instanceof FieldTree) {
+            if (deferred?.isOnlyNulls()) {
+                return;
+            }
+            throw schemaInferenceError(path, row, "Struct", describeEvidence(newType ?? deferred));
+        }
+        if (current instanceof DeferredTypeEvidence) {
+            this.resolveDeferredField(path, row, current, newType, deferred);
+            return;
+        }
+        if (newType !== undefined) {
+            if (!inferredTypesEqual(current, newType)) {
+                throw schemaInferenceError(path, row, describeEvidence(current), describeEvidence(newType));
+            }
+            return;
+        }
+        if (deferred === undefined || !deferred.matches(current)) {
+            throw schemaInferenceError(path, row, describeEvidence(current), describeEvidence(deferred));
+        }
+    }
+    resolveDeferredField(path, row, current, newType, deferred) {
+        if (newType !== undefined) {
+            if (!current.matches(newType)) {
+                throw schemaInferenceError(path, row, current.describe(), describeEvidence(newType));
+            }
+            this.fields.set(path, newType);
+            return;
+        }
+        if (deferred !== undefined) {
+            this.fields.set(path, current.merge(deferred));
+            return;
+        }
+        throw schemaInferenceError(path, row, current.describe(), describeEvidence(newType));
+    }
+    inferType(value, path) {
+        if (typeof value === "bigint") {
+            return new apache_arrow_1.Int64();
+        }
+        if (typeof value === "number") {
+            return new apache_arrow_1.Float64();
+        }
+        if (typeof value === "string") {
+            return this.options.dictionaryEncodeStrings
+                ? new apache_arrow_1.Dictionary(new apache_arrow_1.Utf8(), new apache_arrow_1.Int32())
+                : new apache_arrow_1.Utf8();
+        }
+        if (typeof value === "boolean") {
+            return new apache_arrow_1.Bool();
+        }
+        if (value instanceof Buffer) {
+            return new apache_arrow_1.Binary();
+        }
+        if (ArrayBuffer.isView(value) && !(value instanceof DataView)) {
+            const typedArray = (0, arrow_type_1.typedArrayToArrowType)(value);
+            return typedArray === undefined
+                ? undefined
+                : new apache_arrow_1.FixedSizeList(typedArray.length, new apache_arrow_1.Field("item", typedArray.elementType, true));
+        }
+        if (!Array.isArray(value) || value.length === 0) {
+            return undefined;
+        }
+        const configuredVector = path.length === 1 ? this.options.vectorColumns[path[0]] : undefined;
+        if (configuredVector !== undefined) {
+            return new apache_arrow_1.FixedSizeList(value.length, new apache_arrow_1.Field("item", (0, sanitize_1.sanitizeType)(configuredVector.type), true));
+        }
+        const itemType = this.inferArrayItemType(value, path);
+        if (itemType === undefined) {
+            return undefined;
+        }
+        return nameSuggestsVectorColumn(path[path.length - 1])
+            ? new apache_arrow_1.FixedSizeList(value.length, new apache_arrow_1.Field("item", new apache_arrow_1.Float32(), true))
+            : new apache_arrow_1.List(new apache_arrow_1.Field("item", itemType, true));
+    }
+    inferArrayItemType(values, path) {
+        let itemType;
+        const deferredItems = [];
+        for (const value of values) {
+            const candidate = this.inferType(value, path);
+            if (candidate === undefined) {
+                if (!isDeferredValue(value)) {
+                    return undefined;
+                }
+                deferredItems.push(value);
+            }
+            else if (itemType === undefined) {
+                itemType = candidate;
+            }
+            else if (!inferredTypesEqual(itemType, candidate)) {
+                return undefined;
+            }
+        }
+        if (itemType === undefined) {
+            return undefined;
+        }
+        return deferredItems.every((value) => deferredValueMatchesType(value, itemType))
+            ? itemType
+            : undefined;
+    }
+}
+/** Nulls and empty/all-null lists that do not determine a type by themselves. */
+class DeferredTypeEvidence {
+    values;
+    constructor(values) {
+        this.values = values;
+    }
+    static from(value, row) {
+        return isDeferredValue(value)
+            ? new DeferredTypeEvidence([{ value, row }])
+            : undefined;
+    }
+    isOnlyNulls() {
+        return this.values.every(({ value }) => value == null);
+    }
+    matches(type) {
+        return this.values.every(({ value }) => deferredValueMatchesType(value, type));
+    }
+    merge(other) {
+        return new DeferredTypeEvidence([...this.values, ...other.values]);
+    }
+    describe() {
+        const list = this.values.find(({ value }) => Array.isArray(value));
+        return list === undefined
+            ? "null"
+            : `List[${list.value.length}]`;
+    }
+    firstRow() {
+        return this.values[0].row;
+    }
+}
+/** Nested field state, kept separate from Arrow's eventual Struct types. */
+class FieldTree {
+    children = new Map();
+    get(path) {
+        let current = this;
+        for (const part of path) {
+            if (!(current instanceof FieldTree)) {
+                return undefined;
+            }
+            const child = current.children.get(part);
+            if (child === undefined) {
+                return undefined;
+            }
+            current = child;
+        }
+        return current;
+    }
+    set(path, value, canReplaceLeaf = () => false) {
+        let branch = this;
+        for (const [index, part] of path.slice(0, -1).entries()) {
+            const child = branch.children.get(part);
+            if (child === undefined || (isLeaf(child) && canReplaceLeaf(child))) {
+                const nextBranch = new FieldTree();
+                branch.children.set(part, nextBranch);
+                branch = nextBranch;
+            }
+            else if (child instanceof FieldTree) {
+                branch = child;
+            }
+            else {
+                return { path: path.slice(0, index + 1), value: child };
+            }
+        }
+        const name = path[path.length - 1];
+        const current = branch.children.get(name);
+        if (current instanceof FieldTree) {
+            return { path, value: current };
+        }
+        branch.children.set(name, value);
+        return undefined;
+    }
+    entries() {
+        return this.children.entries();
+    }
+    has(name) {
+        return this.children.has(name);
+    }
+}
+function isLeaf(value) {
+    return !(value instanceof FieldTree);
+}
+function fieldsFromTree(tree, path = []) {
+    const fields = [];
+    for (const [name, value] of tree.entries()) {
+        if (value instanceof FieldTree) {
+            fields.push(new apache_arrow_1.Field(name, new apache_arrow_1.Struct(fieldsFromTree(value, [...path, name])), true));
+        }
+        else if (value instanceof DeferredTypeEvidence) {
+            throw typeInferenceError([...path, name], value.firstRow());
+        }
+        else {
+            fields.push(new apache_arrow_1.Field(name, value, true));
+        }
+    }
+    return fields;
+}
+function matchingFields(fields, tree) {
+    const matches = [];
+    for (const field of fields) {
+        if (!tree.has(field.name)) {
+            continue;
+        }
+        const value = tree.get([field.name]);
+        if (value instanceof FieldTree) {
+            const struct = field.type;
+            matches.push(new apache_arrow_1.Field(field.name, new apache_arrow_1.Struct(matchingFields(struct.children, value)), field.nullable, field.metadata));
+        }
+        else {
+            matches.push(field);
+        }
+    }
+    return matches;
+}
+function* recordPathsAndValues(record, path = []) {
+    for (const [name, value] of Object.entries(record)) {
+        if (isRecord(value)) {
+            yield* recordPathsAndValues(value, [...path, name]);
+        }
+        else if (value !== undefined) {
+            yield [[...path, name], value];
+        }
+    }
+}
+function isRecord(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        !(value instanceof RegExp) &&
+        !(value instanceof Date) &&
+        !(value instanceof Set) &&
+        !(value instanceof Map) &&
+        !(value instanceof Buffer) &&
+        !ArrayBuffer.isView(value));
+}
+function fieldAtPath(schema, path) {
+    let fields = schema.fields;
+    let field;
+    for (const [index, name] of path.entries()) {
+        field = fields.find((candidate) => candidate.name === name);
+        if (field === undefined || index === path.length - 1) {
+            return field;
+        }
+        if (!apache_arrow_1.DataType.isStruct(field.type)) {
+            return undefined;
+        }
+        fields = field.type.children;
+    }
+    return field;
+}
+function isDeferredValue(value) {
+    return (value == null || (Array.isArray(value) && value.every(isDeferredValue)));
+}
+function deferredValueMatchesType(value, type) {
+    if (value == null) {
+        return true;
+    }
+    if (!Array.isArray(value)) {
+        return false;
+    }
+    if (apache_arrow_1.DataType.isList(type)) {
+        return value.every((item) => deferredValueMatchesType(item, type.valueType));
+    }
+    if (apache_arrow_1.DataType.isFixedSizeList(type)) {
+        return (value.length === type.listSize &&
+            value.every((item) => deferredValueMatchesType(item, type.valueType)));
+    }
+    return false;
+}
+function inferredTypesEqual(current, candidate) {
+    if (apache_arrow_1.DataType.isDictionary(current)) {
+        return (apache_arrow_1.DataType.isDictionary(candidate) &&
+            current.isOrdered === candidate.isOrdered &&
+            inferredTypesEqual(current.indices, candidate.indices) &&
+            inferredTypesEqual(current.dictionary, candidate.dictionary));
+    }
+    if (apache_arrow_1.DataType.isList(current)) {
+        return (apache_arrow_1.DataType.isList(candidate) &&
+            current.valueField.name === candidate.valueField.name &&
+            current.valueField.nullable === candidate.valueField.nullable &&
+            inferredTypesEqual(current.valueType, candidate.valueType));
+    }
+    if (apache_arrow_1.DataType.isFixedSizeList(current)) {
+        return (apache_arrow_1.DataType.isFixedSizeList(candidate) &&
+            current.listSize === candidate.listSize &&
+            current.valueField.name === candidate.valueField.name &&
+            current.valueField.nullable === candidate.valueField.nullable &&
+            inferredTypesEqual(current.valueType, candidate.valueType));
+    }
+    return apache_arrow_1.util.compareTypes(current, candidate);
+}
+function describeEvidence(evidence) {
+    if (evidence === undefined) {
+        return "an unsupported value";
+    }
+    return evidence instanceof DeferredTypeEvidence
+        ? evidence.describe()
+        : evidence.toString();
+}
+function branchConflictError(conflict, row, candidate) {
+    return schemaInferenceError(conflict.path, row, conflict.value instanceof FieldTree
+        ? "Struct"
+        : describeEvidence(conflict.value), candidate);
+}
+function schemaInferenceError(path, row, currentType, newType) {
+    return new Error(`Failed to infer schema for data. Previously inferred type ${currentType} ` +
+        `but found ${newType} for field ${path.join(".")} at row ${row}. ` +
+        "Consider providing an explicit schema.");
+}
+function typeInferenceError(path, row) {
+    return new Error(`Failed to infer data type for field ${path.join(".")} at row ${row}. ` +
+        "Consider providing an explicit schema.");
+}
+function nameSuggestsVectorColumn(name) {
+    const normalized = name.toLowerCase();
+    return normalized.includes("vector") || normalized.includes("embedding");
+}

package/dist/table.d.ts

@@ -1,10 +1,11 @@
 import { Table as ArrowTable, Data, DataType, Field, IntoVector, MultiVector, Schema } from "./arrow";
 import { IndexOptions } from "./indices";
 import { MergeInsertBuilder } from "./merge";
-import { AddColumnsResult, AddColumnsSql, AddResult, AlterColumnsResult, BranchContents, DeleteResult, DropColumnsResult, IndexConfig, IndexStatistics, Job, Branches as NativeBranches, OptimizeStats, TableStatistics, Tags, UpdateFieldMetadataResult, UpdateResult, Table as _NativeTable } from "./native";
-import { FullTextQuery, Query, TakeQuery, VectorQuery } from "./query";
+import { AddColumnsResult, AddColumnsSql, AddResult, AlterColumnsResult, BranchContents, DeleteResult, DropColumnsResult, IndexConfig, IndexStatistics, Job, LsmStats, Branches as NativeBranches, OptimizeStats, RefreshColumnResult, RefreshMaterializedViewResult, TableStatistics, Tags, UpdateFieldMetadataResult, UpdateResult, Table as _NativeTable } from "./native";
+import { AutoQuery, FullTextQuery, Query, TakeQuery, VectorQuery } from "./query";
 import { IntoSql } from "./util";
 export { IndexConfig } from "./native";
+export { BucketStats, GenerationStats, LsmStats, MemtableStats, } from "./native";
 /**
  * Progress snapshot for a write operation, delivered to the `progress`
  * callback passed to {@link Table.add}.
@@ -421,7 +422,7 @@ export declare abstract class Table {
      * when "auto" is used, if the query is a string and an embedding function is defined, it will be treated as a vector query
      * if the query is a string and no embedding function is defined, it will be treated as a full text search query
      */
-    abstract search(query: string | IntoVector | MultiVector | FullTextQuery, queryType?: string, ftsColumns?: string | string[]): VectorQuery | Query;
+    abstract search(query: string | IntoVector | MultiVector | FullTextQuery, queryType?: string, ftsColumns?: string | string[]): VectorQuery | Query | AutoQuery;
     /**
      * Search the table with a given query vector.
      *
@@ -432,15 +433,75 @@ export declare abstract class Table {
     abstract vectorSearch(vector: IntoVector | MultiVector): VectorQuery;
     /**
      * Add new columns with defined values.
+     *
+     * The `{ computed }` form stores the expression rather than evaluating it
+     * now: the column is committed with no values, and rows get them from
+     * {@link Table#refreshColumn}. Declaring one therefore costs the same on a
+     * large table as on an empty one.
+     *
+     * A refresh does not revisit rows it has already filled, so mutating an
+     * input leaves the value computed at fill time; recomputing means dropping
+     * the column and declaring it again. While a declaration reads a column,
+     * that column cannot be renamed, retyped or dropped.
+     *
+     * On LanceDB Cloud and Enterprise the expression is planned by the
+     * server, and the refresh runs as a server job -- see
+     * {@link Table#refreshColumnAsync}.
      * @param {AddColumnsSql[] | Field | Field[] | Schema} newColumnTransforms Either:
      *   - An array of objects with column names and SQL expressions to calculate values
      *   - A single Arrow Field defining one column with its data type (column will be initialized with null values)
      *   - An array of Arrow Fields defining columns with their data types (columns will be initialized with null values)
      *   - An Arrow Schema defining columns with their data types (columns will be initialized with null values)
+     *   - `{ computed }`, declaring columns defined by a SQL expression whose type and inputs are derived from it
      * @returns {Promise<AddColumnsResult>} A promise that resolves to an object
      * containing the new version number of the table after adding the columns.
+     * @example
+     * ```ts
+     * await table.addColumns({ computed: [{ name: "doubled", valueSql: "x * 2" }] });
+     * const { rowsFilled } = await table.refreshColumn("doubled");
+     * ```
+     */
+    abstract addColumns(newColumnTransforms: AddColumnsSql[] | Field | Field[] | Schema | {
+        computed: AddColumnsSql[];
+    }): Promise<AddColumnsResult>;
+    /**
+     * Fill the rows of a computed column that hold no value yet.
+     *
+     * Rows appended since the last refresh are filled by the next one; rows
+     * already filled are left as they are, so the call is idempotent and does
+     * not observe a mutated input. Local tables only: a remote refresh runs
+     * as a server job, through {@link Table#refreshColumnAsync}.
+     * @param {string} column The name of the computed column to fill.
+     * @returns {Promise<RefreshColumnResult>} A promise that resolves to the
+     * number of rows filled and the new version number of the table.
      */
-    abstract addColumns(newColumnTransforms: AddColumnsSql[] | Field | Field[] | Schema): Promise<AddColumnsResult>;
+    abstract refreshColumn(column: string): Promise<RefreshColumnResult>;
+    /**
+     * Like {@link Table#refreshColumn}, but returns a handle to the refresh
+     * job instead of blocking until it completes.
+     *
+     * The job may already be complete when returned; callers must not assume
+     * the column is filled until {@link Job.wait} resolves. Invalid input --
+     * an unknown column, or one that is not computed -- rejects here rather
+     * than failing the job. On local tables the job runs in-process; on
+     * LanceDB Cloud and Enterprise it is the server's backfill job.
+     * @param {string} column The name of the computed column to fill.
+     * @example
+     * ```ts
+     * const job = await table.refreshColumnAsync("doubled");
+     * await job.wait();
+     * console.log(await job.status()); // "finished"
+     * ```
+     */
+    abstract refreshColumnAsync(column: string): Promise<Job>;
+    /**
+     * Recompute this table's contents from its materialized-view definition.
+     *
+     * Plumbing for {@link MaterializedView.refresh}, which is the way to call
+     * it: rejects tables that carry no view definition. Local tables only.
+     * @ignore
+     */
+    abstract refreshMaterializedView(full?: boolean, sourceVersion?: number): Promise<RefreshMaterializedViewResult>;
     /**
      * Alter the name or nullability of columns.
      * @param {ColumnAlteration[]} columnAlterations One or more alterations to
@@ -451,6 +512,18 @@ export declare abstract class Table {
     abstract alterColumns(columnAlterations: ColumnAlteration[]): Promise<AlterColumnsResult>;
     /**
      * Update per-field (column) metadata.
+     *
+     * The following keys are treated specially, by convention, and should be
+     * used when appropriate:
+     *
+     * - `lancedb:description`: for a human-readable description of a field.
+     * - `lancedb:tag:<name>`: for a user-defined key-value tag, where the suffix
+     *   names the tag category; e.g. `lancedb:tag:model: "clip"`.
+     * - `lancedb:logical-column`: for a column grouping; e.g. `feature_v1` and
+     *   `feature_v2` might be in the same logical column.
+     * - `lancedb:status`: for status options (`production`, `candidate`,
+     *   `deprecated`, `archived`) to designate the current life cycle state of
+     *   this column.
      * @param {FieldMetadataUpdate[]} updates One or more per-field updates. Each
      * update's metadata is merged into the field's existing metadata by default;
      * a value of `null` deletes that key, and `replace: true` swaps the whole map.
@@ -546,6 +619,57 @@ export declare abstract class Table {
      * @returns {Promise<void>}
      */
     abstract closeLsmWriters(): Promise<void>;
+    /**
+     * Seal every bucket's active memtable into a new L0 generation.
+     *
+     * Returns once the seal is committed. Sealing an empty memtable is a no-op,
+     * so this is safe to call repeatedly.
+     * @returns {Promise<void>}
+     */
+    abstract flushLsm(): Promise<void>;
+    /**
+     * Trigger a background L0 → base compaction pass per bucket.
+     *
+     * Returns once the passes are *dispatched*, not once they finish — watch
+     * {@link Table#getLsmStats} for progress, or use
+     * {@link Table#checkpointLsm} to wait for convergence.
+     * @returns {Promise<void>}
+     */
+    abstract compactLsm(): Promise<void>;
+    /**
+     * Converge this table's LSM write path into its base table.
+     *
+     * Seals once, then triggers compaction and polls until the L0 that existed
+     * at the start is gone. The target set is fixed at the start, so
+     * generations created *during* the checkpoint are ignored — that is what
+     * lets it terminate under write load, and what makes it best-effort: it
+     * converges the fresh tier as of some instant. Idempotent, abandonable at
+     * any point, and safe to run on a cadence.
+     *
+     * There is no liveness bound — the compactor pool is shared across tables,
+     * so a checkpoint queued behind unrelated work looks exactly like one that
+     * is merging. The caller owns the deadline.
+     * @returns {Promise<void>}
+     * @example
+     * ```ts
+     * const before = await table.getLsmStats();
+     * await table.checkpointLsm();
+     * const after = await table.getLsmStats();
+     * ```
+     */
+    abstract checkpointLsm(): Promise<void>;
+    /**
+     * Read live per-bucket LSM state.
+     *
+     * Answers "how far behind is my fresh tier", "which bucket is hot", and
+     * "why is my fresh-tier vector search brute-force". Mutates no table state.
+     *
+     * Resolves to `undefined` only when the LSM write path is not enabled.
+     * @param {boolean} includeGenerationRows Also count rows per L0 generation.
+     *   Off by default because each count opens an uncached Lance dataset.
+     * @returns {Promise<LsmStats | undefined>}
+     */
+    abstract getLsmStats(includeGenerationRows?: boolean): Promise<LsmStats | undefined>;
     /** Retrieve the version of the table */
     abstract version(): Promise<number>;
     /**
@@ -727,9 +851,14 @@ export declare class LocalTable extends Table {
     takeOffsets(offsets: number[]): TakeQuery;
     takeRowIds(rowIds: readonly (bigint | number)[]): TakeQuery;
     query(): Query;
-    search(query: string | IntoVector | MultiVector | FullTextQuery, queryType?: string, ftsColumns?: string | string[]): VectorQuery | Query;
+    search(query: string | IntoVector | MultiVector | FullTextQuery, queryType?: string, ftsColumns?: string | string[]): VectorQuery | Query | AutoQuery;
     vectorSearch(vector: IntoVector | MultiVector): VectorQuery;
-    addColumns(newColumnTransforms: AddColumnsSql[] | Field | Field[] | Schema): Promise<AddColumnsResult>;
+    addColumns(newColumnTransforms: AddColumnsSql[] | Field | Field[] | Schema | {
+        computed: AddColumnsSql[];
+    }): Promise<AddColumnsResult>;
+    refreshColumn(column: string): Promise<RefreshColumnResult>;
+    refreshColumnAsync(column: string): Promise<Job>;
+    refreshMaterializedView(full?: boolean, sourceVersion?: number): Promise<RefreshMaterializedViewResult>;
     alterColumns(columnAlterations: ColumnAlteration[]): Promise<AlterColumnsResult>;
     updateFieldMetadata(updates: FieldMetadataUpdate[]): Promise<UpdateFieldMetadataResult>;
     dropColumns(columnNames: string[]): Promise<DropColumnsResult>;
@@ -738,6 +867,10 @@ export declare class LocalTable extends Table {
     unsetLsmWriteSpec(): Promise<void>;
     getLsmWriteSpec(): Promise<LsmWriteSpec | undefined>;
     closeLsmWriters(): Promise<void>;
+    flushLsm(): Promise<void>;
+    compactLsm(): Promise<void>;
+    checkpointLsm(): Promise<void>;
+    getLsmStats(includeGenerationRows?: boolean): Promise<LsmStats | undefined>;
     version(): Promise<number>;
     checkout(version: number | string): Promise<void>;
     checkoutLatest(): Promise<void>;
@@ -820,7 +953,8 @@ export interface FieldMetadataUpdate {
     path: string;
     /**
      * Metadata key/value pairs. Merged into the field's existing metadata by
-     * default; a value of `null` deletes that key.
+     * default; a value of `null` deletes that key. See
+     * {@link Table.updateFieldMetadata} for the conventional `lancedb:*` keys.
      */
     metadata: Record<string, string | null>;
     /** If true, replace the field's entire metadata map instead of merging. */
@@ -854,8 +988,8 @@ export interface BranchRowCountSummary {
     inputsChanged: number;
     deltaAvailable: boolean;
 }
-/** A reason why a branch cannot currently be merged. */
-export interface MergeBlocker {
+/** A reason why a cherry-pick cannot currently land. */
+export interface CherryPickError {
     code: string;
     message: string;
 }
@@ -874,18 +1008,17 @@ export interface BranchDiff {
     changedColumns: BranchColumnChange[];
     addedIndexes: BranchIndexSummary[];
     removedIndexes: BranchIndexSummary[];
-    mergeable: boolean;
-    mergeBlockers: MergeBlocker[];
+    errors: CherryPickError[];
 }
-/** Changes that would be, or were, promoted by a branch merge. */
-export interface MergePreview {
+/** Changes that would be, or were, promoted by a cherry-pick. */
+export interface CherryPickPreview {
     promotedColumns: string[];
 }
-/** Result of previewing or attempting a branch merge. */
-export interface MergeBranchResult {
-    status: "ready" | "rejected" | "notImplemented" | "merged" | "unknown";
+/** Result of previewing or attempting a cherry-pick. */
+export interface CherryPickResult {
+    status: "ready" | "failed" | "notImplemented" | "cherryPicked" | "unknown";
     diff: BranchDiff;
-    preview: MergePreview;
+    preview: CherryPickPreview;
     mainVersionAfter?: number;
 }
 /**
@@ -924,13 +1057,13 @@ export declare class Branches {
     /** Compare a branch against main without modifying either branch. */
     diff(fromBranch: string): Promise<BranchDiff>;
     /**
-     * Merge a branch into main.
+     * Cherry-pick a branch onto main.
      *
-     * Set `dryRun` to `true` to preview the merge. A rejected merge resolves
-     * with `status: "rejected"` instead of throwing.
+     * Set `dryRun` to `true` to preview. A failed cherry-pick resolves
+     * with `status: "failed"` instead of throwing.
      *
-     * @param fromBranch Branch to merge from.
-     * @param dryRun When true, only preview the merge. Defaults to false.
+     * @param fromBranch Branch to cherry-pick from.
+     * @param dryRun When true, only preview. Defaults to false.
      */
-    merge(fromBranch: string, dryRun?: boolean): Promise<MergeBranchResult>;
+    cherryPick(fromBranch: string, dryRun?: boolean): Promise<CherryPickResult>;
 }