Seekable handles for blob values stored in a table.
Obtain handles with
LanceDB.Blob.open/3, using _rowid values from a query with
with_row_id: true. Offsets and lengths are bytes, relative to the blob.
Reads return Elixir binaries. read/2 and seek/2 share a synchronized cursor
when a handle is passed between processes; range reads and stream/2 leave
that cursor unchanged. Separate fetches return independent handles.
close/1 closes the handle for every process sharing it and is idempotent.
Native references are also released when the handle is garbage collected.
Keep the table version's files available while reading; version cleanup can
invalidate handles. External references require the source object to remain available.
Summary
Functions
Closes the shared handle, returning {:ok, :ok}. Repeated closes succeed.
Whether the shared handle is closed.
Returns blob column paths in schema order, including dotted paths for nested blobs.
Materializes blobs as binaries in row ID order, preserving duplicates and nulls.
Obtain IDs from a query with with_row_id: true; these are not row offsets or
application primary keys. Supports top-level and struct-nested blob columns;
the pinned SDK cannot address individual list elements by row ID.
Invalid/missing IDs fail. Use range reads or file
handles to limit memory for large payloads.
Reads {row_id, offset, length} blob ranges in request order, preserving nulls. Ranges must fit each blob.
Returns storage metadata with string keys: size, position, data_path, kind, and uri.
Opens seekable LanceDB.Blob handles in row ID order; null values return nil.
Reads from the current cursor to EOF, advancing the cursor.
Reads up to length bytes and advances the cursor. EOF returns an empty binary.
Reads exactly length bytes at offset without moving the cursor. Out-of-bounds ranges fail.
Reads {offset, length} ranges in input order without moving the cursor.
A blob write value naming an external object URI. Writes retain the reference by default; external_blob_mode: :ingest copies its bytes.
Sets the cursor's absolute byte offset. Seeking beyond EOF is allowed.
Returns the byte length; remains available after close.
Lazily reads the entire blob in binary chunks (default chunk_size: 65_536).
Enumeration starts at byte zero, leaves the cursor unchanged, and raises
LanceDB.Error on failure. It borrows the handle: halting does not close it.
Each chunk performs a bounded range read; repeated enumeration is supported.
Returns the current cursor offset.
Types
@type byte_range() :: {non_neg_integer(), non_neg_integer()}
@type request() :: {non_neg_integer(), non_neg_integer(), non_neg_integer()}
@opaque t()
Functions
@spec close(t()) :: LanceDB.result(:ok)
Closes the shared handle, returning {:ok, :ok}. Repeated closes succeed.
Whether the shared handle is closed.
@spec columns(LanceDB.Table.t()) :: LanceDB.result([String.t()])
Returns blob column paths in schema order, including dotted paths for nested blobs.
@spec fetch(LanceDB.Table.t(), atom() | String.t(), [non_neg_integer()]) :: LanceDB.result([binary() | nil])
Materializes blobs as binaries in row ID order, preserving duplicates and nulls.
Obtain IDs from a query with with_row_id: true; these are not row offsets or
application primary keys. Supports top-level and struct-nested blob columns;
the pinned SDK cannot address individual list elements by row ID.
Invalid/missing IDs fail. Use range reads or file
handles to limit memory for large payloads.
@spec fetch_ranges(LanceDB.Table.t(), atom() | String.t(), [request()]) :: LanceDB.result([binary() | nil])
Reads {row_id, offset, length} blob ranges in request order, preserving nulls. Ranges must fit each blob.
@spec info(t()) :: LanceDB.result(map())
Returns storage metadata with string keys: size, position, data_path, kind, and uri.
@spec open(LanceDB.Table.t(), atom() | String.t(), [non_neg_integer()]) :: LanceDB.result([t() | nil])
Opens seekable LanceDB.Blob handles in row ID order; null values return nil.
@spec read(t()) :: LanceDB.result(binary())
Reads from the current cursor to EOF, advancing the cursor.
@spec read(t(), non_neg_integer()) :: LanceDB.result(binary())
Reads up to length bytes and advances the cursor. EOF returns an empty binary.
@spec read_range(t(), non_neg_integer(), non_neg_integer()) :: LanceDB.result(binary())
Reads exactly length bytes at offset without moving the cursor. Out-of-bounds ranges fail.
@spec read_ranges(t(), [byte_range()]) :: LanceDB.result([binary()])
Reads {offset, length} ranges in input order without moving the cursor.
@spec reference(String.t()) :: LanceDB.Blob.Reference.t()
A blob write value naming an external object URI. Writes retain the reference by default; external_blob_mode: :ingest copies its bytes.
@spec seek(t(), non_neg_integer()) :: LanceDB.result(:ok)
Sets the cursor's absolute byte offset. Seeking beyond EOF is allowed.
@spec size(t()) :: non_neg_integer()
Returns the byte length; remains available after close.
@spec stream(t(), keyword()) :: Enumerable.t()
Lazily reads the entire blob in binary chunks (default chunk_size: 65_536).
Enumeration starts at byte zero, leaves the cursor unchanged, and raises
LanceDB.Error on failure. It borrows the handle: halting does not close it.
Each chunk performs a bounded range read; repeated enumeration is supported.
@spec tell(t()) :: LanceDB.result(non_neg_integer())
Returns the current cursor offset.