Skip to content

@lancedb/lancedb • Docs

@lancedb/lancedb / MergeInsertBuilder

Class: MergeInsertBuilder

A builder used to create and run a merge insert operation

Constructors

new MergeInsertBuilder()

new MergeInsertBuilder(native, schema): MergeInsertBuilder

Construct a MergeInsertBuilder. Internal use only.

Parameters

  • native: NativeMergeInsertBuilder

  • schema: Schema<any> | Promise<Schema<any>>

Returns

MergeInsertBuilder

Methods

execute()

execute(data, execOptions?): Promise<MergeResult>

Executes the merge insert operation

Parameters

Returns

Promise<MergeResult>

the merge result

useIndex()

useIndex(useIndex): 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.

Parameters

  • useIndex: boolean Whether to use indices for the merge operation. Defaults to true.

Returns

MergeInsertBuilder

useLsmWrite()

useLsmWrite(useLsmWrite): MergeInsertBuilder

Controls whether the merge uses the MemWAL LSM write path.

By default (unset), a mergeInsert on a table with an LSM write spec is routed through Lance's MemWAL shard writer, and a table without one uses the standard path. Pass false to force the standard path even when a spec is set. Pass true to require a spec — mergeInsert rejects if none is installed.

Parameters

  • useLsmWrite: boolean Whether to use the LSM write path.

Returns

MergeInsertBuilder

validateSingleShard()

validateSingleShard(validateSingleShard): MergeInsertBuilder

Controls how an LSM merge checks that its input targets a single shard.

When a table has an LSM write spec, every row in a mergeInsert call must route to the same shard. When true (the default), every row is inspected to verify this. When false, only the first row is inspected and the shard it routes to is used for the whole input — a faster path for callers that have already pre-sharded their input. Has no effect on tables without an LSM write spec.

Parameters

  • validateSingleShard: boolean Whether to check every row routes to one shard. Defaults to true.

Returns

MergeInsertBuilder

whenMatchedUpdateAll()

whenMatchedUpdateAll(options?): MergeInsertBuilder

Rows that exist in both the source table (new data) and the target table (old data) will be updated, replacing the old row with the corresponding matching row.

If there are multiple matches then the behavior is undefined. Currently this causes multiple copies of the row to be created but that behavior is subject to change.

An optional condition may be specified. If it is, then only matched rows that satisfy the condtion will be updated. Any rows that do not satisfy the condition will be left as they are. Failing to satisfy the condition does not cause a "matched row" to become a "not matched" row.

The condition should be an SQL string. Use the prefix target. to refer to rows in the target table (old data) and the prefix source. to refer to rows in the source table (new data).

For example, "target.last_update < source.last_update"

Parameters

  • options?

  • options.where?: string

Returns

MergeInsertBuilder

whenNotMatchedBySourceDelete()

whenNotMatchedBySourceDelete(options?): MergeInsertBuilder

Rows that exist only in the target table (old data) will be deleted. An optional condition can be provided to limit what data is deleted.

Parameters

  • options?

  • options.where?: string An optional condition to limit what data is deleted

Returns

MergeInsertBuilder

whenNotMatchedInsertAll()

whenNotMatchedInsertAll(): MergeInsertBuilder

Rows that exist only in the source table (new data) should be inserted into the target table.

Returns

MergeInsertBuilder