feat(node): add blob v2 fetch and field helpers (#4155)

this PR blob v2 field helpers and reads to the Node SDK.

`blob()` marks a field as blob v2 and lets you set the storage
thresholds. Inputs can be bytes, a URI, or a data/uri struct.

Queries return descriptors. `fetchBlobs()` reads the bytes by row ID,
and `fetchBlobFiles()` gives you lazy handles for full or range reads.
`blobColumns()` lists the blob fields, including nested ones.

Fetch uses the table’s current checkout. It preserves order, duplicates,
and nulls. Holding row IDs across compaction still requires stable row
IDs.

```javascript
const db = await connect("./data");
const video = await readFile("clip.mp4");
const table = await db.createTable(
  "videos",
  [{ id: 1n, video }],
  {
    schema: new Schema([
      new Field("id", new Int64()),
      blob("video"),
    ]),
  },
);
const rows = await table.query().select(["id"]).withRowId().toArray();
const rowIds = rows.map((row) => row._rowid as bigint);
const bytes = await table.fetchBlobs("video", rowIds);
const [handle] = await table.fetchBlobFiles("video", rowIds);
const header = await handle!.readRange(0n, 65536n);

```

### Testing

- cover input validation, thresholds, nested fields, fetch ordering,
nulls, and range reads.

nodejs/lancedb/arrow.ts

@@ -40,6 +40,7 @@ import {
 } from "apache-arrow";
 import { Buffers } from "apache-arrow/data";
 import { typedArrayToArrowType } from "./arrow_type";
+import { coerceBlobValue, isBlobField } from "./blob";
 import { type EmbeddingFunction } from "./embedding/embedding_function";
 import {
   EmbeddingFunctionConfig,
@@ -430,12 +431,14 @@ export function makeArrowTable(
       throw new Error("A schema must be provided if data is empty");
     } else {
       schema = new Schema(schema.fields, schemaMetadata);
+      validateBlobSchema(schema);
       return new ArrowTable(schema);
     }
   }
 
   let inferredSchema = inferSchema(data, schema, opt);
   inferredSchema = new Schema(inferredSchema.fields, schemaMetadata);
+  validateBlobSchema(inferredSchema);
 
   const finalColumns: Record<string, Vector> = {};
   for (const field of inferredSchema.fields) {
@@ -445,6 +448,35 @@ export function makeArrowTable(
   return new ArrowTable(inferredSchema, finalColumns);
 }
 
+function validateBlobSchema(schema: Schema): void {
+  for (const field of schema.fields) {
+    validateBlobField(field);
+  }
+}
+
+function validateBlobField(field: Field): void {
+  if (
+    isFixedSizeList(field.type) &&
+    containsBlobField(field.type.children[0])
+  ) {
+    throw new Error(
+      "Blob fields inside FixedSizeList are not supported. Use List instead.",
+    );
+  }
+  for (const child of field.type.children ?? []) {
+    validateBlobField(child);
+  }
+}
+
+function containsBlobField(field: Field): boolean {
+  if (isBlobField(field)) {
+    return true;
+  }
+  return (field.type.children ?? []).some((child: Field) =>
+    containsBlobField(child),
+  );
+}
+
 function isObject(value: unknown): value is Record<string, unknown> {
   return (
     typeof value === "object" &&
@@ -480,6 +512,32 @@ function transposeData(
   path: string[] = [],
 ): Vector {
   const valuesPath = [...path, field.name];
+  if (isBlobField(field) && field.type instanceof Struct) {
+    const blobRows = data.map((datum) =>
+      coerceBlobValue(valueAtPath(datum, valuesPath)),
+    );
+    const childVectors = field.type.children.map((child) => {
+      const values = blobRows.map((row) =>
+        row == null ? null : (row[child.name as "data" | "uri"] ?? null),
+      );
+      return makeVector(values, child.type, undefined, child.nullable);
+    });
+    const nullCount = blobRows.filter((row) => row === null).length;
+    const structData = makeData({
+      type: field.type,
+      length: blobRows.length,
+      nullCount,
+      nullBitmap:
+        nullCount > 0
+          ? arrowUtil.packBools(blobRows.map((row) => row !== null))
+          : undefined,
+      children: childVectors.map((v) => v.data[0]),
+    });
+    return arrowMakeVector(structData);
+  }
+  if (isList(field.type) && containsBlobField(field.type.children[0])) {
+    return transposeListData(data, field, valuesPath);
+  }
   const values = data.map((datum) => valueAtPath(datum, valuesPath));
   if (field.type instanceof Struct) {
     const childFields = field.type.children;
@@ -495,7 +553,7 @@ function transposeData(
         nullCount > 0
           ? arrowUtil.packBools(values.map((value) => value !== null))
           : undefined,
-      children: childVectors as unknown as ArrowData<DataType>[],
+      children: childVectors.map((v) => v.data[0]),
     });
     return arrowMakeVector(structData);
   } else {
@@ -503,6 +561,48 @@ function transposeData(
   }
 }
 
+function transposeListData(
+  data: Record<string, unknown>[],
+  field: Field,
+  valuesPath: string[],
+): Vector {
+  const listType = field.type as List;
+  const childField = listType.children[0];
+  const lists = data.map((datum) => valueAtPath(datum, valuesPath));
+  const flattened: Record<string, unknown>[] = [];
+  const validity: boolean[] = [];
+  const offsets: number[] = [0];
+
+  for (const list of lists) {
+    if (list == null) {
+      validity.push(false);
+      offsets.push(flattened.length);
+      continue;
+    }
+    if (!Array.isArray(list)) {
+      throw new Error(`expected an array for list field '${field.name}'`);
+    }
+    validity.push(true);
+    for (const element of list) {
+      flattened.push({ [childField.name]: element });
+    }
+    offsets.push(flattened.length);
+  }
+
+  const childVector = transposeData(flattened, childField, []);
+  const nullCount = validity.filter((valid) => !valid).length;
+  return arrowMakeVector(
+    makeData({
+      type: listType,
+      length: lists.length,
+      nullCount,
+      nullBitmap: nullCount > 0 ? arrowUtil.packBools(validity) : undefined,
+      valueOffsets: Int32Array.from(offsets),
+      child: childVector.data[0],
+    }),
+  );
+}
+
 /**
  * Create an empty Arrow table with the provided schema
  */
@@ -952,6 +1052,7 @@ export async function fromTableToBuffer(
     schema = sanitizeSchema(schema);
   }
   const tableWithEmbeddings = await applyEmbeddings(table, embeddings, schema);
+  validateBlobSchema(tableWithEmbeddings.schema);
   const writer = RecordBatchFileWriter.writeAll(tableWithEmbeddings);
   return Buffer.from(await writer.toUint8Array());
 }