From a68c7be20254928be02186ca2fe9b62141d84755 Mon Sep 17 00:00:00 2001 From: Will Jones Date: Mon, 5 Oct 2026 12:35:00 -0700 Subject: [PATCH] feat(node): accept ArrayBuffer, Blob/File, and URL as blob column inputs (#4313) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Closes #4270. ## Summary Blob v2 columns now accept more of the containers TypeScript code commonly has, both as the column value and inside `{ data }` / `{ uri }`: | Input | Handling | |---|---| | `ArrayBuffer` | `new Uint8Array(value)`, no copy | | `URL` | stored as `value.href` | | `Blob` / `File` | `await value.arrayBuffer()` in the async write paths: `createTable`, `add`, `mergeInsert` | `makeArrowTable` is synchronous, so it can't read a `Blob`. Given one, it throws an error that names the field and row and points to the async APIs or `new Uint8Array(await value.arrayBuffer())`. It does not write a null blob. ### Types `BlobInput` is now the accepted input type. It is widened to the types above and exported from the package entry point with `BlobData` and `BlobUri`, so callers can annotate rows and `tsc` catches bad inputs. The struct forms are a union that requires exactly one of `data` / `uri`. The old normalized `{ data, uri }` shape is renamed to `BlobValue` (internal). ### Implementation - `blob.ts`: `normalizeBlobInput` (sync: `ArrayBuffer`/`URL`), `resolveBlobInput` (async: `Blob`/`File`). `coerceBlobValue` normalizes first. - `arrow.ts`: `mapBlobInputs` walks only the blob positions in the schema, including blobs nested in structs and lists. It copies records and arrays only where a value changed, so caller data is never mutated. `resolveBlobInputs` runs before `makeArrowTable` in `convertToTable` (used by `add` / `mergeInsert`) and in `createTable`. Each distinct `Blob` is read once. - `makeArrowTable` now coerces every blob value to the full `{ data, uri }` struct **before** schema inference. This also fixes two bugs that existed before this change: - Rows mixing plain bytes with `{ data }` failed inference. - A `{ uri }`-only struct produced a blob struct missing its `data` child. Blob validation errors now include the field path and row. - Also fixed along the way: - `add` / `mergeInsert` on a table with an embedding function rejected most blob values, because `ensureNestedFieldsExist` filled blob columns in like ordinary structs. It now skips them. - With a schema, a struct field that is `null` in one row and a record in a later row failed inference. Primitives and arrays given for a struct field are now rejected instead of being written as an all-null struct. - Blob structs with keys other than `data` / `uri` are rejected, which catches typos. Class instances with `data` / `uri` are handled like plain objects. ## Testing - Unit tests in `__test__/blob.test.ts`: coercion of the new types, rejection and error messages for `Blob` in the sync path, nested lists and structs, `resolveBlobInputs` (only blob columns touched, caller data untouched, shared `Blob` read once). - Table tests in `__test__/table.test.ts`: - `createTable`, `add`, and `mergeInsert` round-trip `ArrayBuffer` / `Blob` / `File` bytes through `fetchBlobs`. - `URL` and `{ uri: URL }` are added to the external-blob round-trip test from #4317 (`allowExternalBlobOutsideBases`). - Full `jest` suite passes locally after the rebase (938 passed). `pnpm lint` is clean and `pnpm run docs` has been regenerated. Streaming inputs (`ReadableStream`, Node `Readable`, async iterables) remain out of scope, as the issue says. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_012U4KdHofT5edv3LcXHXbLv --------- Co-authored-by: Claude --- docs/src/js/globals.md | 3 + docs/src/js/type-aliases/BlobData.md | 16 ++ docs/src/js/type-aliases/BlobInput.md | 36 +++ docs/src/js/type-aliases/BlobUri.md | 13 + nodejs/__test__/arrow.test.ts | 37 +++ nodejs/__test__/blob.test.ts | 329 +++++++++++++++++++++++++- nodejs/__test__/table.test.ts | 62 ++++- nodejs/lancedb/arrow.ts | 184 +++++++++++++- nodejs/lancedb/blob.ts | 173 +++++++++++++- nodejs/lancedb/connection.ts | 7 +- nodejs/lancedb/index.ts | 9 +- nodejs/lancedb/schema.ts | 48 +++- 12 files changed, 879 insertions(+), 38 deletions(-) create mode 100644 docs/src/js/type-aliases/BlobData.md create mode 100644 docs/src/js/type-aliases/BlobInput.md create mode 100644 docs/src/js/type-aliases/BlobUri.md diff --git a/docs/src/js/globals.md b/docs/src/js/globals.md index edb0bacc3..0c48ad4ec 100644 --- a/docs/src/js/globals.md +++ b/docs/src/js/globals.md @@ -157,9 +157,12 @@ - [AnalyzePlanDistributedMetrics](type-aliases/AnalyzePlanDistributedMetrics.md) - [BaseTokenizer](type-aliases/BaseTokenizer.md) +- [BlobData](type-aliases/BlobData.md) +- [BlobInput](type-aliases/BlobInput.md) - [BlobOptions](type-aliases/BlobOptions.md) - [BlobRange](type-aliases/BlobRange.md) - [BlobReadOptions](type-aliases/BlobReadOptions.md) +- [BlobUri](type-aliases/BlobUri.md) - [Data](type-aliases/Data.md) - [DataLike](type-aliases/DataLike.md) - [DataTypeLike](type-aliases/DataTypeLike.md) diff --git a/docs/src/js/type-aliases/BlobData.md b/docs/src/js/type-aliases/BlobData.md new file mode 100644 index 000000000..2af0a3659 --- /dev/null +++ b/docs/src/js/type-aliases/BlobData.md @@ -0,0 +1,16 @@ +[**@lancedb/lancedb**](../README.md) • **Docs** + +*** + +[@lancedb/lancedb](../globals.md) / BlobData + +# Type Alias: BlobData + +```ts +type BlobData: Buffer | Uint8Array | ArrayBuffer | Blob; +``` + +Bytes accepted for a blob value. `ArrayBuffer` is wrapped without copying. +`Blob` and `File` are read with `arrayBuffer()`, which only the async write +paths ([Connection.createTable](../classes/Connection.md#createtable), [Table.add](../classes/Table.md#add), +[Table.mergeInsert](../classes/Table.md#mergeinsert)) can do. diff --git a/docs/src/js/type-aliases/BlobInput.md b/docs/src/js/type-aliases/BlobInput.md new file mode 100644 index 000000000..d1738a760 --- /dev/null +++ b/docs/src/js/type-aliases/BlobInput.md @@ -0,0 +1,36 @@ +[**@lancedb/lancedb**](../README.md) • **Docs** + +*** + +[@lancedb/lancedb](../globals.md) / BlobInput + +# Type Alias: BlobInput + +```ts +type BlobInput: + | BlobData + | BlobUri + | object + | object + | null + | undefined; +``` + +A value accepted for a `lance.blob.v2` column (see [blob](../functions/blob.md)). + +Either inline bytes, a URI pointing at external bytes, or a struct that sets +exactly one of `data` or `uri`. `null` and `undefined` write a null blob. + +## Example + +```ts +import { pathToFileURL } from "node:url"; +import type { BlobInput } from "@lancedb/lancedb"; + +const rows: { id: bigint; image: BlobInput }[] = [ + { id: 1n, image: await (await fetch(url)).arrayBuffer() }, + { id: 2n, image: pathToFileURL("/data/cat.png") }, + { id: 3n, image: { data: new Blob(["hello"]) } }, +]; +await table.add(rows); +``` diff --git a/docs/src/js/type-aliases/BlobUri.md b/docs/src/js/type-aliases/BlobUri.md new file mode 100644 index 000000000..a90b395fc --- /dev/null +++ b/docs/src/js/type-aliases/BlobUri.md @@ -0,0 +1,13 @@ +[**@lancedb/lancedb**](../README.md) • **Docs** + +*** + +[@lancedb/lancedb](../globals.md) / BlobUri + +# Type Alias: BlobUri + +```ts +type BlobUri: string | URL; +``` + +A URI accepted for a blob value. A `URL` is stored as its `href`. diff --git a/nodejs/__test__/arrow.test.ts b/nodejs/__test__/arrow.test.ts index e054a5495..376533961 100644 --- a/nodejs/__test__/arrow.test.ts +++ b/nodejs/__test__/arrow.test.ts @@ -790,6 +790,43 @@ describe.each(arrowVersions)("Arrow %#", (arrow: ApacheArrow) => { } }); + it("will allow null values around struct values with a schema", function () { + const schema = new Schema([ + new Field("value", new Struct([new Field("nested", new Int32())])), + ]); + for (const { records, nullIndex } of [ + { + records: [{ value: null }, { value: { nested: 2 } }], + nullIndex: 0, + }, + { + records: [{ value: { nested: 1 } }, { value: null }], + nullIndex: 1, + }, + ]) { + const table = makeArrowTable(records, { schema }); + const values = table.getChild("value"); + + expect(values?.nullCount).toBe(1); + expect(values?.get(nullIndex)).toBeNull(); + } + }); + + it("will reject non-object values for struct fields in a schema", function () { + const schema = new Schema([ + new Field("value", new Struct([new Field("nested", new Int32())])), + ]); + for (const records of [ + [{ value: 5 }], + [{ value: 5 }, { value: { nested: 1 } }], + [{ value: { nested: 1 } }, { value: "oops" }], + ]) { + expect(() => makeArrowTable(records, { schema })).toThrow( + /Expected a struct value for field value at row \d, got/, + ); + } + }); + it("will allow a schema to be provided", async function () { await checkTableCreation( async (records, _, schema) => diff --git a/nodejs/__test__/blob.test.ts b/nodejs/__test__/blob.test.ts index 5c01897b2..b41d5716f 100644 --- a/nodejs/__test__/blob.test.ts +++ b/nodejs/__test__/blob.test.ts @@ -1,9 +1,25 @@ // SPDX-License-Identifier: Apache-2.0 // SPDX-FileCopyrightText: Copyright The LanceDB Authors -import { Field, Int64, List, Schema, Struct, Utf8 } from "apache-arrow"; -import { makeArrowTable } from "../lancedb/arrow"; +import { + Field, + Float, + Float32, + Int32, + Int64, + List, + Schema, + Struct, + Utf8, +} from "apache-arrow"; +import { + convertToTable, + makeArrowTable, + resolveBlobInputs, +} from "../lancedb/arrow"; import { BlobFile, blob, coerceBlobValue, isBlobField } from "../lancedb/blob"; +import { EmbeddingFunction, LanceSchema } from "../lancedb/embedding"; +import { getRegistry } from "../lancedb/embedding/registry"; describe("blob()", () => { it("marks the field as lance.blob.v2", () => { @@ -46,6 +62,13 @@ describe("blob()", () => { }); }); +class BlobStruct { + constructor( + public data?: unknown, + public uri?: unknown, + ) {} +} + describe("coerceBlobValue", () => { it.each([ ["Buffer", Buffer.from("x"), { data: Buffer.from("x"), uri: null }], @@ -65,6 +88,41 @@ describe("coerceBlobValue", () => { { uri: "s3://bucket/key" }, { data: null, uri: "s3://bucket/key" }, ], + [ + "ArrayBuffer", + new Uint8Array([120]).buffer, + { data: new Uint8Array([120]), uri: null }, + ], + [ + "URL", + new URL("https://example.com/blob"), + { data: null, uri: "https://example.com/blob" }, + ], + [ + "data struct with ArrayBuffer", + { data: new Uint8Array([121]).buffer }, + { data: new Uint8Array([121]), uri: null }, + ], + [ + "uri struct with URL", + { uri: new URL("file:///tmp/a.png") }, + { data: null, uri: "file:///tmp/a.png" }, + ], + [ + "class instance with Uint8Array data", + new BlobStruct(new Uint8Array([122])), + { data: new Uint8Array([122]), uri: null }, + ], + [ + "class instance with ArrayBuffer data", + new BlobStruct(new Uint8Array([122]).buffer), + { data: new Uint8Array([122]), uri: null }, + ], + [ + "class instance with URL uri", + new BlobStruct(undefined, new URL("s3://bucket/key")), + { data: null, uri: "s3://bucket/key" }, + ], ["null", null, null], ])("accepts %s", (_name, input, expected) => { expect(coerceBlobValue(input)).toEqual(expected); @@ -76,7 +134,7 @@ describe("coerceBlobValue", () => { [ "Int16Array", new Int16Array([1]), - /Blob data must be Buffer or Uint8Array/, + /Blob data must be Buffer, Uint8Array, ArrayBuffer, or Blob/, ], [ "both data and uri", @@ -88,11 +146,160 @@ describe("coerceBlobValue", () => { { data: null, uri: null }, /exactly one of 'data' or 'uri'/, ], + ["Blob", new Blob(["x"]), /must be read asynchronously/], + ["data struct with Blob", { data: new Blob(["x"]) }, /asynchronously/], + [ + "class instance with Blob data", + new BlobStruct(new Blob(["x"])), + /asynchronously/, + ], + [ + "unknown struct field", + { data: Buffer.from("y"), mime: "image/png" }, + /Blob struct values only support 'data' and 'uri', got 'mime'/, + ], + [ + "misspelled struct field", + { uri: "s3://bucket/key", dat: Buffer.from("y") }, + /got 'dat'/, + ], + [ + "SharedArrayBuffer", + new SharedArrayBuffer(2), + /Blob column values must be Buffer, Uint8Array, ArrayBuffer, Blob/, + ], + ["Date", new Date(0), /Blob column values must be/], ])("rejects %s", (_name, input, message) => { expect(() => coerceBlobValue(input)).toThrow(message); }); }); +describe("resolveBlobInputs", () => { + it("reads Blob and File values in blob columns only", async () => { + const schema = new Schema([ + new Field("name", new Utf8(), true), + blob("image"), + new Field("images", new List(blob("image")), true), + ]); + const shared = new Blob(["same"]); + const notABlobColumn = new Blob(["other"]); + const data = [ + { + name: notABlobColumn, + image: new File(["file"], "a.txt"), + images: [shared, { data: shared }, null], + }, + { name: "x", image: Buffer.from("buf"), images: null }, + ]; + const resolved = await resolveBlobInputs(data, schema); + + expect(resolved[0].name).toBe(notABlobColumn); + expect(Buffer.from(resolved[0].image as Uint8Array).toString()).toBe( + "file", + ); + const images = resolved[0].images as [Uint8Array, { data: Uint8Array }]; + expect(Buffer.from(images[0]).toString()).toBe("same"); + expect(Buffer.from(images[1].data).toString()).toBe("same"); + // Rows without Blob values and the caller's records are left alone. + expect(resolved[1]).toBe(data[1]); + expect(data[0].images?.[0]).toBe(shared); + }); + + it("reads each distinct Blob once, bare or inside data structs", async () => { + class CountingBlob extends Blob { + calls = 0; + async arrayBuffer(): Promise { + this.calls++; + return super.arrayBuffer(); + } + } + const shared = new CountingBlob(["same"]); + const schema = new Schema([blob("image")]); + const resolved = await resolveBlobInputs( + [ + { image: { data: shared } }, + { image: { data: shared } }, + { image: shared }, + ], + schema, + ); + expect(shared.calls).toBe(1); + const first = (resolved[0].image as { data: Uint8Array }).data; + expect(Buffer.from(first).toString()).toBe("same"); + expect((resolved[1].image as { data: Uint8Array }).data).toBe(first); + expect(resolved[2].image).toBe(first); + }); + + it("reads a Blob held by a class instance", async () => { + const schema = new Schema([blob("image")]); + const [row] = await resolveBlobInputs( + [{ image: new BlobStruct(new Blob(["hi"])) }], + schema, + ); + expect( + Buffer.from((row.image as { data: Uint8Array }).data).toString(), + ).toBe("hi"); + }); + + it("returns the input when there is nothing to read", async () => { + const data = [{ image: Buffer.from("x") }]; + const schema = new Schema([blob("image")]); + await expect(resolveBlobInputs(data, schema)).resolves.toBe(data); + await expect(resolveBlobInputs(data)).resolves.toBe(data); + }); +}); + +describe("convertToTable blob columns with embedding functions", () => { + // Embedding metadata routes rows through ensureNestedFieldsExist, which must + // leave blob values for the blob coercion instead of treating them as structs. + class LengthEmbedding extends EmbeddingFunction { + ndims() { + return 2; + } + embeddingDataType(): Float { + return new Float32(); + } + async computeSourceEmbeddings(data: string[]) { + return data.map((text) => [text.length, 1]); + } + } + getRegistry().register("blob-test-length")(LengthEmbedding); + const func = getRegistry().get("blob-test-length")!.create(); + const embeddingSchema = LanceSchema({ + text: func.sourceField(new Utf8()), + vector: func.vectorField(), + }); + const schema = new Schema( + [...embeddingSchema.fields, blob("image")], + embeddingSchema.metadata, + ); + + it.each([ + ["Uint8Array", new Uint8Array([104, 105]), "hi", null], + ["ArrayBuffer", new Uint8Array([104, 105]).buffer, "hi", null], + ["Blob", new Blob(["hi"]), "hi", null], + ["URI string", "s3://b/k", null, "s3://b/k"], + ["URL", new URL("s3://b/k"), null, "s3://b/k"], + ["data struct", { data: new Uint8Array([104, 105]) }, "hi", null], + ])("accepts %s input", async (_name, image, data, uri) => { + const table = await convertToTable([{ text: "a", image }], undefined, { + schema, + }); + const column = table.getChild("image")!; + expect(column.nullCount).toBe(0); + const bytes = column.getChild("data")!.get(0); + expect(bytes == null ? null : Buffer.from(bytes).toString()).toBe(data); + expect(column.getChild("uri")!.get(0)).toBe(uri); + }); + + it("writes a missing blob as null", async () => { + const table = await convertToTable([{ text: "a" }], undefined, { schema }); + const column = table.getChild("image")!; + expect(column.nullCount).toBe(1); + expect(column.get(0)).toBeNull(); + }); +}); + describe("BlobFile", () => { it("rejects constructing BlobFile without a native handle", () => { expect(() => new (BlobFile as unknown as { new (): BlobFile })()).toThrow( @@ -103,26 +310,122 @@ describe("BlobFile", () => { describe("makeArrowTable blob columns", () => { it.each([ - ["ArrayBuffer", new Uint8Array([104]).buffer], - ["Blob", new Blob(["hello"])], - ["File", new File(["hello"], "hello.txt")], - ["URL", new URL("https://example.com/blob")], ["ReadableStream", new ReadableStream()], - ["data struct with ArrayBuffer", { data: new Uint8Array([104]).buffer }], - ["uri struct with URL", { uri: new URL("https://example.com/blob") }], + ["Int16Array", new Int16Array([1])], ])("rejects %s input rather than writing a null blob", (_name, image) => { const schema = new Schema([blob("image")]); expect(() => makeArrowTable([{ image }], { schema })).toThrow(/image/); }); - it("rejects Blob instances with enumerable fields as one invalid value", () => { + it.each([ + ["Blob", new Blob(["hello"])], + ["File", new File(["hello"], "hello.txt")], + ["data struct with Blob", { data: new Blob(["hello"]) }], + [ + "Blob with enumerable fields", + Object.assign(new Blob(["hello"]), { position: 0 }), + ], + ])("points %s input at the async APIs", (_name, image) => { const schema = new Schema([blob("image")]); - const image = Object.assign(new Blob(["hello"]), { position: 0 }); - expect(() => makeArrowTable([{ image }], { schema })).toThrow( - "Unsupported object value for field image at row 0.", + expect(() => makeArrowTable([{ id: 1, image }], { schema })).toThrow( + /blob field image at row 0: Blob and File values must be read asynchronously/, ); }); + it.each([ + ["ArrayBuffer", new Uint8Array([104, 105]).buffer, "hi", null], + [ + "data struct with ArrayBuffer", + { data: new Uint8Array([104, 105]).buffer }, + "hi", + null, + ], + ["URL", new URL("https://example.com/a"), null, "https://example.com/a"], + [ + "uri struct with URL", + { uri: new URL("file:///tmp/a.png") }, + null, + "file:///tmp/a.png", + ], + ])("accepts %s input", (_name, image, data, uri) => { + const schema = new Schema([blob("image")]); + const input = { image }; + const table = makeArrowTable([input], { schema }); + const column = table.getChild("image")!; + expect(column.nullCount).toBe(0); + const bytes = column.getChild("data")!.get(0); + expect(bytes == null ? null : Buffer.from(bytes).toString()).toBe(data); + expect(column.getChild("uri")!.get(0)).toBe(uri); + // The caller's record is left untouched. + expect(input.image).toBe(image); + }); + + it.each([ + ["Uint8Array", new Uint8Array([104, 105]), "hi", null], + ["URI string", "s3://b/k", null, "s3://b/k"], + ["data struct", { data: new Uint8Array([104, 105]) }, "hi", null], + ])("accepts %s input after a null row", (_name, image, data, uri) => { + const schema = new Schema([blob("image")]); + const table = makeArrowTable([{ image: null }, { image }], { schema }); + const column = table.getChild("image")!; + expect(column.nullCount).toBe(1); + expect(column.get(0)).toBeNull(); + const bytes = column.getChild("data")!.get(1); + expect(bytes == null ? null : Buffer.from(bytes).toString()).toBe(data); + expect(column.getChild("uri")!.get(1)).toBe(uri); + }); + + it("accepts a null struct before one holding a blob", () => { + const schema = new Schema([ + new Field("info", new Struct([blob("image")]), true), + ]); + const table = makeArrowTable( + [{ info: null }, { info: { image: new Uint8Array([97]) } }], + { schema }, + ); + const info = table.getChild("info")!; + expect(info.get(0)).toBeNull(); + const image = (info.get(1) as { image: { data: Uint8Array } }).image; + expect(Buffer.from(image.data).toString()).toBe("a"); + }); + + it("skips a missing blob column named like an Object.prototype member", () => { + const schema = new Schema([ + new Field("id", new Int32(), true), + blob("constructor"), + ]); + const table = makeArrowTable([{ id: 1 }], { schema }); + expect(table.schema.fields.map((f) => f.name)).toEqual(["id"]); + }); + + it("accepts ArrayBuffer and URL inside lists and structs", () => { + const schema = new Schema([ + new Field("images", new List(blob("image")), true), + new Field("info", new Struct([blob("image")]), true), + ]); + const table = makeArrowTable( + [ + { + images: [new Uint8Array([97]).buffer, new URL("s3://b/k")], + info: { image: new Uint8Array([98]).buffer }, + }, + ], + { schema }, + ); + const images = Array.from( + table.getChild("images")!.get(0) as Iterable<{ + data: Uint8Array | null; + uri: string | null; + }>, + ); + expect(Buffer.from(images[0].data!).toString()).toBe("a"); + expect(images[1].uri).toBe("s3://b/k"); + const info = table.getChild("info")!.get(0) as { + image: { data: Uint8Array }; + }; + expect(Buffer.from(info.image.data).toString()).toBe("b"); + }); + it("coerces Buffer input onto a blob field", () => { const schema = new Schema([ new Field("id", new Int64(), true), diff --git a/nodejs/__test__/table.test.ts b/nodejs/__test__/table.test.ts index c17b0315a..24cf6e0fd 100644 --- a/nodejs/__test__/table.test.ts +++ b/nodejs/__test__/table.test.ts @@ -9,6 +9,7 @@ import * as tmp from "tmp"; import { AutoQuery, + type BlobInput, Connection, MatchQuery, PhraseQuery, @@ -2583,7 +2584,7 @@ describe("when dealing with blob columns", () => { new Field("id", new Int64(), true), blob("image"), ]); - const row = { id: 1n, image: new Uint8Array([104]).buffer }; + const row = { id: 1n, image: new ReadableStream() }; await expect(db.createTable("invalid", [row], { schema })).rejects.toThrow( /field image at row 0/, @@ -2613,6 +2614,8 @@ describe("when dealing with blob columns", () => { it.each([ ["URI string", (uri: string) => uri], ["URI struct", (uri: string) => ({ uri })], + ["URL", (uri: string) => new URL(uri)], + ["URL struct", (uri: string) => ({ uri: new URL(uri) })], ])( "round-trips an external blob from a %s after reopening", async (_label, blobValue) => { @@ -2706,6 +2709,63 @@ describe("when dealing with blob columns", () => { expect(bytes[0]).toEqual(payload); }); + it("accepts ArrayBuffer, Blob, and File in createTable and add", async () => { + const db = await connect(tmpDir.name); + const schema = new Schema([ + new Field("id", new Int64(), true), + blob("image"), + ]); + const rows: { id: bigint; image: BlobInput }[] = [ + { id: 1n, image: new TextEncoder().encode("array-buffer").buffer }, + { id: 2n, image: new Blob(["blob"]) }, + { id: 3n, image: { data: new File(["file"], "f.txt") } }, + ]; + const table = await db.createTable("widened", rows.slice(0, 2), { + schema, + }); + await table.add(rows.slice(2)); + + const results = await table.query().select(["id"]).withRowId().toArray(); + results.sort((a, b) => Number(a.id - b.id)); + const bytes = await table.fetchBlobs( + "image", + results.map((row) => row._rowid as bigint), + ); + expect(bytes.map((b) => b?.toString())).toEqual([ + "array-buffer", + "blob", + "file", + ]); + }); + + it("accepts Blob values in mergeInsert", async () => { + const db = await connect(tmpDir.name); + const schema = new Schema([ + new Field("id", new Int64(), true), + blob("image"), + ]); + const table = await db.createTable( + "merge_blobs", + [{ id: 1n, image: Buffer.from("old") }], + { schema }, + ); + await table + .mergeInsert("id") + .whenMatchedUpdateAll() + .whenNotMatchedInsertAll() + .execute([ + { id: 1n, image: new Blob(["new"]) }, + { id: 2n, image: new Uint8Array([104, 105]).buffer }, + ]); + const results = await table.query().select(["id"]).withRowId().toArray(); + results.sort((a, b) => Number(a.id - b.id)); + const bytes = await table.fetchBlobs( + "image", + results.map((row) => row._rowid as bigint), + ); + expect(bytes.map((b) => b?.toString())).toEqual(["new", "hi"]); + }); + it("discovers blob columns", async () => { const { table } = await openBlobTable(); expect(await table.blobColumns()).toEqual(["image"]); diff --git a/nodejs/lancedb/arrow.ts b/nodejs/lancedb/arrow.ts index 3daee7d65..3130da8eb 100644 --- a/nodejs/lancedb/arrow.ts +++ b/nodejs/lancedb/arrow.ts @@ -40,7 +40,12 @@ import { } from "apache-arrow"; import { Buffers } from "apache-arrow/data"; import { typedArrayToArrowType } from "./arrow_type"; -import { coerceBlobValue, isBlobField } from "./blob"; +import { + blobToRead, + coerceBlobValue, + isBlobField, + withBlobBytes, +} from "./blob"; import { type EmbeddingFunction } from "./embedding/embedding_function"; import { EmbeddingFunctionConfig, @@ -449,6 +454,24 @@ export function makeArrowTable( ); } + if (schema !== undefined) { + // Validate blob values up front and give every one the full + // `{ data, uri }` shape, so inference sees the same struct whether a row + // passed bytes, a URI, or a partial struct. + data = mapBlobInputs(data, schema, (value, field, row) => { + if (value === undefined) { + return value; + } + try { + return coerceBlobValue(value); + } catch (e) { + throw new Error( + `Invalid value for blob field ${field} at row ${row}: ${(e as Error).message}`, + ); + } + }); + } + let schemaMetadata = schema?.metadata || new Map(); if (metadata !== undefined) { schemaMetadata = new Map([...schemaMetadata, ...metadata]); @@ -510,6 +533,133 @@ function containsBlobField(field: Field): boolean { ); } +type BlobInputVisitor = (value: unknown, field: string, row: number) => unknown; + +/** + * Calls `visit` on every value that lands in a blob column of `schema`, + * including blobs nested in structs and lists, and replaces it with the + * result. Records and arrays are copied only where a value changed, so the + * caller's data is never mutated. + */ +function mapBlobInputs( + data: Array>, + schema: Schema, + visit: BlobInputVisitor, +): Array> { + if (!schema.fields.some(containsBlobField)) { + return data; + } + return data.map((record, row) => + isObject(record) + ? mapBlobFields(record, schema.fields, "", row, visit) + : record, + ); +} + +function mapBlobFields( + record: Record, + fields: Field[], + prefix: string, + row: number, + visit: BlobInputVisitor, +): Record { + let out: Record | undefined; + for (const field of fields) { + if (!containsBlobField(field) || !Object.hasOwn(record, field.name)) { + continue; + } + const value = record[field.name]; + const mapped = mapBlobField( + value, + field, + `${prefix}${field.name}`, + row, + visit, + ); + if (mapped !== value) { + out ??= { ...record }; + out[field.name] = mapped; + } + } + return out ?? record; +} + +function mapBlobField( + value: unknown, + field: Field, + label: string, + row: number, + visit: BlobInputVisitor, +): unknown { + if (isBlobField(field)) { + return visit(value, label, row); + } + if (field.type instanceof Struct && isObject(value)) { + return mapBlobFields(value, field.type.children, `${label}.`, row, visit); + } + if (isList(field.type) && Array.isArray(value)) { + const child = field.type.children[0]; + let out: unknown[] | undefined; + for (const [index, element] of value.entries()) { + const mapped = mapBlobField( + element, + child, + `${label}[${index}]`, + row, + visit, + ); + if (mapped !== element) { + out ??= [...value]; + out[index] = mapped; + } + } + return out ?? value; + } + return value; +} + +/** + * Reads `Blob` / `File` values in the blob columns of `schema` into bytes so + * the synchronous conversion in {@link makeArrowTable} can accept them. + * Returns `data` itself when there is nothing to read. + */ +export async function resolveBlobInputs( + data: Array>, + schema?: SchemaLike, +): Promise>> { + if (schema === undefined || schema === null) { + return data; + } + const sanitized = sanitizeSchema(schema); + // Keyed by the Blob itself, so rows sharing one Blob (bare or as + // `{ data }`) read it once and share the bytes. + const reads = new Map>(); + mapBlobInputs(data, sanitized, (value) => { + const source = blobToRead(value); + if (source !== undefined && !reads.has(source)) { + reads.set( + source, + source.arrayBuffer().then((buffer) => new Uint8Array(buffer)), + ); + } + return value; + }); + if (reads.size === 0) { + return data; + } + const bytes = new Map( + await Promise.all( + [...reads].map(async ([source, read]) => [source, await read] as const), + ), + ); + return mapBlobInputs(data, sanitized, (value) => { + const source = blobToRead(value); + return source === undefined + ? value + : withBlobBytes(value, bytes.get(source) as Uint8Array); + }); +} + function isObject(value: unknown): value is Record { return ( typeof value === "object" && @@ -1013,6 +1163,11 @@ export async function convertToTable( ); } + processedData = await resolveBlobInputs( + processedData, + makeTableOptions?.schema, + ); + const table = makeArrowTable(processedData, makeTableOptions); return await applyEmbeddings(table, embeddings, makeTableOptions?.schema); } @@ -1369,7 +1524,7 @@ export function ensureNestedFieldsExist( for (const field of schema.fields) { if (field.name in row) { if ( - field.type.constructor.name === "Struct" && + isPlainStructField(field) && row[field.name] !== null && row[field.name] !== undefined ) { @@ -1386,10 +1541,9 @@ export function ensureNestedFieldsExist( } else { // Keep a missing struct valid while filling each of its children with // null. This is distinct from an explicitly null struct value. - completeRow[field.name] = - field.type.constructor.name === "Struct" - ? ensureStructFieldsExist({}, field.type as Struct) - : null; + completeRow[field.name] = isPlainStructField(field) + ? ensureStructFieldsExist({}, field.type as Struct) + : null; } } @@ -1397,6 +1551,15 @@ export function ensureNestedFieldsExist( }); } +/** + * Blob fields are Arrow structs, but their values are bytes, URIs, or + * `{ data } | { uri }` inputs that the blob coercion in `makeArrowTable` + * handles, so they must not be filled in like ordinary structs. + */ +function isPlainStructField(field: Field): boolean { + return field.type.constructor.name === "Struct" && !isBlobField(field); +} + /** * Recursively ensures that all fields in a struct type exist in the data, * filling missing fields with null values. @@ -1410,7 +1573,7 @@ function ensureStructFieldsExist( for (const childField of structType.children) { if (childField.name in data) { if ( - childField.type.constructor.name === "Struct" && + isPlainStructField(childField) && data[childField.name] !== null && data[childField.name] !== undefined ) { @@ -1426,10 +1589,9 @@ function ensureStructFieldsExist( } else { // Keep a missing struct valid while filling each of its children with // null. This is distinct from an explicitly null struct value. - completeStruct[childField.name] = - childField.type.constructor.name === "Struct" - ? ensureStructFieldsExist({}, childField.type as Struct) - : null; + completeStruct[childField.name] = isPlainStructField(childField) + ? ensureStructFieldsExist({}, childField.type as Struct) + : null; } } diff --git a/nodejs/lancedb/blob.ts b/nodejs/lancedb/blob.ts index e6c780ca9..f3d648f48 100644 --- a/nodejs/lancedb/blob.ts +++ b/nodejs/lancedb/blob.ts @@ -12,7 +12,46 @@ const DEDICATED_SIZE_THRESHOLD_KEY = const PACK_FILE_SIZE_THRESHOLD_KEY = "lance-encoding:blob-pack-file-size-threshold"; -export type BlobInput = { +/** + * Bytes accepted for a blob value. `ArrayBuffer` is wrapped without copying. + * `Blob` and `File` are read with `arrayBuffer()`, which only the async write + * paths ({@link Connection.createTable}, {@link Table.add}, + * {@link Table.mergeInsert}) can do. + */ +export type BlobData = Buffer | Uint8Array | ArrayBuffer | Blob; + +/** A URI accepted for a blob value. A `URL` is stored as its `href`. */ +export type BlobUri = string | URL; + +/** + * A value accepted for a `lance.blob.v2` column (see {@link blob}). + * + * Either inline bytes, a URI pointing at external bytes, or a struct that sets + * exactly one of `data` or `uri`. `null` and `undefined` write a null blob. + * + * @example + * ```ts + * import { pathToFileURL } from "node:url"; + * import type { BlobInput } from "@lancedb/lancedb"; + * + * const rows: { id: bigint; image: BlobInput }[] = [ + * { id: 1n, image: await (await fetch(url)).arrayBuffer() }, + * { id: 2n, image: pathToFileURL("/data/cat.png") }, + * { id: 3n, image: { data: new Blob(["hello"]) } }, + * ]; + * await table.add(rows); + * ``` + */ +export type BlobInput = + | BlobData + | BlobUri + | { data: BlobData; uri?: null } + | { data?: null; uri: BlobUri } + | null + | undefined; + +/** A blob value normalized to the columns of the blob struct. */ +export type BlobValue = { data: Buffer | Uint8Array | null; uri: string | null; }; @@ -248,7 +287,77 @@ export type BlobRange = { end: bigint; }; -export function coerceBlobValue(value: unknown): BlobInput | null { +/** + * Rewrites the synchronous-only widenings of {@link BlobInput} (`ArrayBuffer`, + * `URL`) into `Uint8Array` and URI strings, keeping the value's shape. Other + * values are returned unchanged and validated later by {@link coerceBlobValue}. + * + * Throws on `Blob` / `File`, which must be read into bytes first. + */ +export function normalizeBlobInput(value: unknown): unknown { + if (blobToRead(value) !== undefined) { + throw new Error( + "Blob and File values must be read asynchronously. Pass them to " + + "createTable, add, or mergeInsert, or convert them with " + + "`new Uint8Array(await value.arrayBuffer())`", + ); + } + if (value instanceof ArrayBuffer) { + return new Uint8Array(value); + } + if (value instanceof URL) { + return value.href; + } + if (isBlobStruct(value)) { + // Read `data` and `uri` explicitly: spreading a class instance would drop + // fields defined as getters on its prototype. + const out: Record = { + ...value, + data: value.data, + uri: value.uri, + }; + let changed = false; + if (value.data instanceof ArrayBuffer) { + out.data = new Uint8Array(value.data); + changed = true; + } + if (value.uri instanceof URL) { + out.uri = value.uri.href; + changed = true; + } + return changed ? out : value; + } + return value; +} + +/** + * Returns the `Blob` / `File` a blob value needs read, either the value itself + * or its `data` field, or `undefined` when there is nothing to read. + */ +export function blobToRead(value: unknown): Blob | undefined { + if (isBlobLike(value)) { + return value; + } + if (isBlobStruct(value) && isBlobLike(value.data)) { + return value.data; + } + return undefined; +} + +/** + * Replaces the `Blob` that {@link blobToRead} found in `value` with `bytes`, + * keeping the value's shape. + */ +export function withBlobBytes(value: unknown, bytes: Uint8Array): unknown { + if (isBlobLike(value)) { + return bytes; + } + const record = value as Record; + return { ...record, uri: record.uri, data: bytes }; +} + +export function coerceBlobValue(input: unknown): BlobValue | null { + const value = normalizeBlobInput(input); if (value == null) { return null; } @@ -256,7 +365,9 @@ export function coerceBlobValue(value: unknown): BlobInput | null { return { data: value, uri: null }; } if (ArrayBuffer.isView(value)) { - throw new Error("Blob data must be Buffer or Uint8Array"); + throw new Error( + "Blob data must be Buffer, Uint8Array, ArrayBuffer, or Blob", + ); } if (typeof value === "string") { if (value === "") { @@ -264,23 +375,37 @@ export function coerceBlobValue(value: unknown): BlobInput | null { } return { data: null, uri: value }; } - if (typeof value === "object") { - const record = value as Record; + if (isBlobStruct(value)) { + const record = value; if (!("data" in record) && !("uri" in record)) { throw new Error( "Blob struct values must include a 'data' or 'uri' field", ); } + const unknownKeys = Object.keys(record).filter( + (key) => key !== "data" && key !== "uri", + ); + if (unknownKeys.length > 0) { + throw new Error( + `Blob struct values only support 'data' and 'uri', got ${unknownKeys + .map((key) => `'${key}'`) + .join(", ")}`, + ); + } const uri = record.uri; if (uri === "") { throw new Error("Blob uri cannot be empty"); } if (uri != null && typeof uri !== "string") { - throw new Error(`Blob uri must be a string or null, got ${typeof uri}`); + throw new Error( + `Blob uri must be a string, URL, or null, got ${typeof uri}`, + ); } const data = record.data; if (data != null && !isBlobBytes(data)) { - throw new Error("Blob data must be Buffer, Uint8Array, or null"); + throw new Error( + "Blob data must be Buffer, Uint8Array, ArrayBuffer, Blob, or null", + ); } const bytes = (data as Buffer | Uint8Array | null | undefined) ?? null; const uriValue = uri ?? null; @@ -292,7 +417,39 @@ export function coerceBlobValue(value: unknown): BlobInput | null { return { data: bytes, uri: uriValue }; } throw new Error( - "Blob column values must be Buffer, Uint8Array, a URI string, null, or { data?, uri? }", + "Blob column values must be Buffer, Uint8Array, ArrayBuffer, Blob, a URI string or URL, null, or { data?, uri? }", + ); +} + +function isBlobLike(value: unknown): value is Blob { + return typeof Blob !== "undefined" && value instanceof Blob; +} + +/** + * Whether `value` is a `{ data?, uri? }` struct: any plain object, or any + * other object with a `data` or `uri` field (such as a class instance), apart + * from the binary, `Blob`, and `URL` values that are blob inputs themselves. + */ +function isBlobStruct(value: unknown): value is Record { + if ( + typeof value !== "object" || + value === null || + Array.isArray(value) || + ArrayBuffer.isView(value) || + value instanceof ArrayBuffer || + (typeof SharedArrayBuffer !== "undefined" && + value instanceof SharedArrayBuffer) || + isBlobLike(value) || + value instanceof URL + ) { + return false; + } + const prototype = Object.getPrototypeOf(value); + return ( + prototype === Object.prototype || + prototype === null || + "data" in value || + "uri" in value ); } diff --git a/nodejs/lancedb/connection.ts b/nodejs/lancedb/connection.ts index 5e9641202..d2a34669e 100644 --- a/nodejs/lancedb/connection.ts +++ b/nodejs/lancedb/connection.ts @@ -8,6 +8,7 @@ import { fromTableToStreamBuffer, isArrowTable, makeArrowTable, + resolveBlobInputs, } from "./arrow"; import { Table as ArrowTable, @@ -1133,7 +1134,11 @@ async function parseTableData( if (isArrowTable(data)) { table = sanitizeTable(data); } else { - table = makeArrowTable(data as Record[], options); + const records = await resolveBlobInputs( + data as Record[], + options?.schema, + ); + table = makeArrowTable(records, options); } if (streaming) { const buf = await fromTableToStreamBuffer( diff --git a/nodejs/lancedb/index.ts b/nodejs/lancedb/index.ts index 9d4e5608b..72b8c4a56 100644 --- a/nodejs/lancedb/index.ts +++ b/nodejs/lancedb/index.ts @@ -84,7 +84,14 @@ export { } from "./arrow"; export { blob, isBlobField, BlobFile } from "./blob"; -export type { BlobOptions, BlobRange, BlobReadOptions } from "./blob"; +export type { + BlobData, + BlobInput, + BlobOptions, + BlobRange, + BlobReadOptions, + BlobUri, +} from "./blob"; export { Connection, diff --git a/nodejs/lancedb/schema.ts b/nodejs/lancedb/schema.ts index 724a81fc9..3e225464f 100644 --- a/nodejs/lancedb/schema.ts +++ b/nodejs/lancedb/schema.ts @@ -69,12 +69,18 @@ class SchemaInferrer { this.addField(path, value, row); } else if (this.providedSchema === undefined) { this.updateInferredField(path, value, row, current); + } else if (current instanceof DeferredTypeEvidence) { + if (value != null) { + this.addSchemaField(this.providedSchema, path, value, row); + } + } else if (current instanceof FieldTree || DataType.isStruct(current)) { + assertStructValue(path, value, row); } } private addField(path: string[], value: unknown, row: number): void { if (this.providedSchema !== undefined) { - this.addSchemaField(this.providedSchema, path, row); + this.addSchemaField(this.providedSchema, path, value, row); return; } @@ -95,15 +101,31 @@ class SchemaInferrer { } } - private addSchemaField(schema: Schema, path: string[], row: number): void { + private addSchemaField( + schema: Schema, + path: string[], + value: unknown, + row: number, + ): void { const field = fieldAtPath(schema, path); if (field === undefined) { throw new Error( `Found field not in schema: ${path.join(".")} at row ${row}`, ); } + if (DataType.isStruct(field.type)) { + assertStructValue(path, value, row); + } - const conflict = this.fields.set(path, field.type); + // Nulls are kept as deferred evidence so that a struct field seen first as + // null can be replaced by a record in a later row, just as a record seen + // first already ignores later nulls. + const conflict = this.fields.set( + path, + DeferredTypeEvidence.from(value, row) ?? field.type, + (existing) => + existing instanceof DeferredTypeEvidence && existing.isOnlyNulls(), + ); if (conflict !== undefined) { throw branchConflictError(conflict, row, "Struct"); } @@ -483,6 +505,26 @@ function assertSupportedValue( } } +/** + * Rejects primitives, arrays, and typed arrays given for a struct field, which + * would otherwise be written as a struct with every child null. + */ +function assertStructValue(path: string[], value: unknown, row: number): void { + if ( + value == null || + (typeof value === "object" && + !Array.isArray(value) && + !ArrayBuffer.isView(value)) + ) { + return; + } + const kind = + typeof value === "object" ? value.constructor.name : typeof value; + throw new Error( + `Expected a struct value for field ${path.join(".")} at row ${row}, got ${kind}.`, + ); +} + function fieldAtPath(schema: Schema, path: string[]): Field | undefined { let fields = schema.fields; let field: Field | undefined;