Implementation:Lance format Lance BlobBuilder

Knowledge Sources	Lance
Domains	Core, Data_Modeling
Last Updated	2026-02-08 19:33 GMT

Overview

Description

The BlobBuilder module provides convenience builders for Lance blob v2 input columns. Blob v2 is a Lance extension type that stores binary large objects either inline (as raw bytes) or by reference (as a URI). The column is shaped as Struct<data: LargeBinary?, uri: Utf8?> and tagged with the Arrow extension metadata ARROW:extension:name = "lance.blob.v2".

The module provides two public items:

• blob_field -- A function that constructs the correctly typed and annotated Arrow Field for a blob v2 column
• BlobArrayBuilder -- A type-safe builder that enforces the constraint that each row contains exactly one of data or uri (or is null), and validates capacity bounds

The builder supports four row types:

• push_bytes -- Inline blob backed by raw bytes
• push_uri -- Blob referenced by URI (validates non-empty)
• push_empty -- Inline blob with zero-length payload
• push_null -- Null row

Usage

The BlobBuilder is used when constructing Lance datasets that contain binary large objects. It is re-exported from the main lance crate as lance::blob_field and lance::BlobArrayBuilder.

Code Reference

Source Location

rust/lance/src/blob.rs

Signature

pub fn blob_field(name: &str, nullable: bool) -> Field;

pub struct BlobArrayBuilder {
    // internal fields
}

impl BlobArrayBuilder {
    pub fn new(capacity: usize) -> Self;
    pub fn push_bytes(&mut self, bytes: impl AsRef<[u8]>) -> Result<()>;
    pub fn push_uri(&mut self, uri: impl Into<String>) -> Result<()>;
    pub fn push_empty(&mut self) -> Result<()>;
    pub fn push_null(&mut self) -> Result<()>;
    pub fn finish(mut self) -> Result<ArrayRef>;
}

Import

use lance::{blob_field, BlobArrayBuilder};
// or directly:
use lance::blob::{blob_field, BlobArrayBuilder};

I/O Contract

Inputs

Parameter	Type	Description
name	&str	Column name for the blob field
nullable	bool	Whether the blob column allows null values
capacity	usize	Expected number of rows; builder enforces exact match on finish()
bytes	impl AsRef<[u8]>	Raw byte content for inline blobs
uri	impl Into<String>	URI reference for external blobs (must be non-empty)

Outputs

Type	Description
Field	Arrow field with Struct<data: LargeBinary?, uri: Utf8?> type and blob v2 extension metadata
Result<ArrayRef>	Arrow StructArray containing the built blob column, or an error if capacity mismatch

Usage Examples

use lance::{blob_field, BlobArrayBuilder};
use arrow_array::RecordBatch;
use arrow_schema::Schema;
use std::sync::Arc;

let field = blob_field("my_blob", true);
let schema = Schema::new(vec![field]);

let mut builder = BlobArrayBuilder::new(3);
builder.push_bytes(b"inline data").unwrap();
builder.push_uri("s3://bucket/key").unwrap();
builder.push_null().unwrap();
let array = builder.finish().unwrap();

let batch = RecordBatch::try_new(Arc::new(schema), vec![array]).unwrap();

Related Pages

• Lance_format_Lance_CrateRoot -- Re-exports blob_field and BlobArrayBuilder