Blob Extension - Spiral Docs

spiral-io owns spql.io.Blob, a structural extension dtype for external byte payloads resolved by spiral-io. Sessions register it with SpiralIoPlugin or spiral_io::initialize(session).

spql.io.Blob does not store inline bytes. Inline byte values use Vortex binary columns. A table writer may later externalize binary values into managed blob storage when the target table schema requires spql.io.Blob.

Storage Shape

A Blob stores these nullable fields:

Field	Meaning
`uri`	External payload URI resolved by `spiral-io`.
`offset`	Optional byte offset; null means the start of the object.
`size`	Optional byte size of this Blob range; null means through end of object.
`mime_type`	Optional MIME type.
`etag`	Optional provider ETag for validation.
`version_id`	Optional provider object version id.
`generation`	Optional provider object generation.
`md5`	Optional MD5 digest for the Blob bytes.
`sha1`	Optional SHA-1 digest for the Blob bytes.
`sha256`	Optional SHA-256 digest for the Blob bytes.

Blob construction does not read bytes. Reads happen only when a function such as spql.image.jpeg or spql.image.exif materializes the payload.

Functions


SELECT spql.io.blob('file:///tmp/photo.jpg', mime_type => 'image/jpeg') AS image_blob;

spql.io.blob(uri, offset?, size?, mime_type?, etag?, version_id?, generation?, md5?, sha1?, sha256?) constructs an external Blob over a byte range. Reads resolve through spiral-io; the default providers support bare local paths, file:// with an empty or localhost authority, and http:// or https:// URLs.

Use accessor functions to project metadata:


SELECT
  spql.io.uri(image_blob) AS uri,
  spql.io.size(image_blob) AS size,
  spql.io.sha256(image_blob) AS sha256
FROM photos;

HTTP reads require byte-range support. Servers must return 206 Partial Content with a valid Content-Range for requested ranges; servers that ignore range requests or omit range metadata fail instead of falling back to a full download. Other schemes require a registered provider and fail at read time when none is available.

Type Factories

blob() is available as an extension dtype factory in casts and schema-facing surfaces when spql.io is registered. It constructs the spql.io.Blob dtype.