Blobs & I/O

Scalar Functions

Function	Summary
`spql.blob.blob`	Construct a `spql.Blob` value.
`spql.blob.bytes`	Return a blob's inline bytes.
`spql.blob.digest`	Return a blob's multihash digest.
`spql.blob.etag`	Return the entity tag a read of the blob must match.
`spql.blob.external`	Construct a URI-backed blob without reading bytes.
`spql.blob.inline`	Construct an inline blob from binary bytes.
`spql.blob.mime_type`	Return a blob's MIME type.
`spql.blob.offset`	Return a blob's byte offset inside the referenced object.
`spql.blob.size`	Return a blob's byte size.
`spql.blob.uri`	Return a blob's URI: a Spiral address or a direct provider URI.
`spql.blob.version`	Return the provider object version a read of the blob must return.
`spql.blob.with_mime_type`	Return a blob with its MIME type replaced without reading payload bytes.
`spql.io.fetch`	Fetch a blob's payload into an inline blob.
`spql.io.read_bytes`	Read a blob's payload bytes.
`spql.io.stat`	Return a blob's object metadata without reading payload bytes.

`spql.blob.blob`

Construct a spql.Blob value.

Kind: scalar function
Volatility: immutable

spql.blob.blob(bytes?, uri?, offset?, size?, mime_type?, version?, etag?, digest?) -> spql.Blob?

Parameters

Name	Required	Type	Description
`bytes`	no	`binary?`	Inline payload bytes.
`uri`	no	`utf8?`	`spiral://<resource-id>/<key>`, or a direct provider URI.
`offset`	no	`u64?`	Byte offset of the payload inside the referenced object; null is 0.
`size`	no	`u64?`	Payload length in bytes; null means to the end of the object.
`mime_type`	no	`utf8?`	Optional media type.
`version`	no	`utf8?`	Provider object version a read must return.
`etag`	no	`utf8?`	Entity tag a read must match.
`digest`	no	`binary?`	Multihash of the payload bytes.

`spql.blob.bytes`

Return a blob's inline bytes.

Kind: scalar function
Volatility: immutable

spql.blob.bytes(blob) -> binary?

Parameters

Name	Required	Type	Description
`blob`	yes	`spql.Blob`	Blob to inspect without reading its payload.

`spql.blob.digest`

Return a blob's multihash digest.

Kind: scalar function
Volatility: immutable

spql.blob.digest(blob) -> binary?

Parameters

Name	Required	Type	Description
`blob`	yes	`spql.Blob`	Blob to inspect without reading its payload.

`spql.blob.etag`

Return the entity tag a read of the blob must match.

Kind: scalar function
Volatility: immutable

spql.blob.etag(blob) -> utf8?

Parameters

Name	Required	Type	Description
`blob`	yes	`spql.Blob`	Blob to inspect without reading its payload.

`spql.blob.external`

Construct a URI-backed blob without reading bytes.

Kind: scalar function
Volatility: immutable

spql.blob.external(uri, offset?, size?, mime_type?, version?, etag?, digest?) -> spql.Blob?

The URI is a Spiral address (spiral://<resource-id>/<key>) or a direct provider URI. Written into a table, the blob stays a reference to it; to store a copy, write spql.io.fetch(blob) instead. version and etag pin the object a read must return. Null URI with no metadata returns null; metadata without a URI is an error. The digest must be a supported BLAKE3-256 or SHA2-256 multihash. URI schemes are normalized without changing provider paths.

Parameters

Name	Required	Type	Description
`uri`	yes	`utf8?`	URI of the object containing the payload.
`offset`	no	`u64?`	Byte offset of the payload within the object; omitted means zero.
`size`	no	`u64?`	Size of the payload in bytes, when known.
`mime_type`	no	`utf8?`	MIME type of the payload, when known.
`version`	no	`utf8?`	Provider object version required when reading the payload.
`etag`	no	`utf8?`	Entity tag required when reading the payload.
`digest`	no	`binary?`	Multihash digest used to verify the payload.

`spql.blob.inline`

Construct an inline blob from binary bytes.

Kind: scalar function
Volatility: immutable

spql.blob.inline(bytes, size?, mime_type?, digest?) -> spql.Blob?

Null bytes produce a null blob; empty bytes produce a valid zero-length blob. The payload buffer is reused without I/O. A supplied digest is checked for a supported multihash format without hashing the payload.

Parameters

Name	Required	Type	Description
`bytes`	yes	`binary?`	Inline payload bytes; null produces a null blob.
`size`	no	`u64?`	Payload length in bytes. Omit or pass null to infer it; a supplied length must match.
`mime_type`	no	`utf8?`	Optional payload MIME type.
`digest`	no	`binary?`	Optional BLAKE3-256 or SHA2-256 multihash digest.

Returns

A blob containing the supplied bytes and metadata.

`spql.blob.mime_type`

Return a blob's MIME type.

Kind: scalar function
Volatility: immutable

spql.blob.mime_type(blob) -> utf8?

Parameters

Name	Required	Type	Description
`blob`	yes	`spql.Blob`	Blob to inspect without reading its payload.

`spql.blob.offset`

Return a blob's byte offset inside the referenced object.

Kind: scalar function
Volatility: immutable

spql.blob.offset(blob) -> u64?

Parameters

Name	Required	Type	Description
`blob`	yes	`spql.Blob`	Blob to inspect without reading its payload.

`spql.blob.size`

Return a blob's byte size.

Kind: scalar function
Volatility: immutable

spql.blob.size(blob) -> u64?

Parameters

Name	Required	Type	Description
`blob`	yes	`spql.Blob`	Blob to inspect without reading its payload.

`spql.blob.uri`

Return a blob's URI: a Spiral address or a direct provider URI.

Kind: scalar function
Volatility: immutable

spql.blob.uri(blob) -> utf8?

Parameters

Name	Required	Type	Description
`blob`	yes	`spql.Blob`	Blob to inspect without reading its payload.

`spql.blob.version`

Return the provider object version a read of the blob must return.

Kind: scalar function
Volatility: immutable

spql.blob.version(blob) -> utf8?

Parameters

Name	Required	Type	Description
`blob`	yes	`spql.Blob`	Blob to inspect without reading its payload.

`spql.blob.with_mime_type`

Return a blob with its MIME type replaced without reading payload bytes.

Kind: scalar function
Volatility: immutable

spql.blob.with_mime_type(blob, mime_type) -> spql.Blob?

Null blobs remain null. A null MIME type clears the metadata. All other fields, including the payload source and object identity, are preserved.

Parameters

Name	Required	Type	Description
`blob`	yes	`spql.Blob?`	Blob whose MIME metadata is replaced.
`mime_type`	yes	`utf8?`	Replacement MIME type; null clears the field.

Returns

A blob with the replacement MIME type.

`spql.io.fetch`

Fetch a blob's payload into an inline blob.

Kind: scalar function
Volatility: immutable

spql.io.fetch(blob, offset?, size?, on_error?) -> spql.Blob?

This is an effectful query operation. A spiral:// address is read with the addressed resource's permission. The result holds the bytes inline, and the source's media type when the whole payload is read; spql.blob.bytes returns them as binary. Written into a table, it is stored in that table's own storage. The optional offset and size select a range within the blob's own payload. The optional on_error mode is strict by default; null or nullable returns NULL for row-level read failures. Full reads validate the blob's declared size and digest; range reads do not.

Parameters

Name	Required	Type	Description
`blob`	yes	`spql.Blob`	Blob whose payload to read through the execution host.
`offset`	no	`u64?`	Byte offset relative to the blob payload; omitted means zero.
`size`	no	`u64?`	Number of bytes to read; omitted means the remaining payload.
`on_error`	no	`utf8?`	Read error policy: strict (default), null or nullable. The latter two return null for row-level read failures.

`spql.io.read_bytes`

Read a blob's payload bytes.

Kind: scalar function
Volatility: immutable
Visibility: deprecated

spql.io.read_bytes(blob, offset?, size?, on_error?) -> binary?

This is an effectful query operation. Use it eagerly over Python values or lazily in SQL and relation expressions. A spiral:// address is read with the addressed resource's permission. The optional offset and size select a range within the blob's own payload. The optional on_error mode is strict by default; null or nullable returns NULL for row-level read failures. Full reads validate the blob's declared size and digest; range reads do not.

Parameters

Name	Required	Type	Description
`blob`	yes	`spql.Blob`	Blob whose payload to read through the execution host.
`offset`	no	`u64?`	Byte offset relative to the blob payload; omitted means zero.
`size`	no	`u64?`	Number of bytes to read; omitted means the remaining payload.
`on_error`	no	`utf8?`	Read error policy: strict (default), null or nullable. The latter two return null for row-level read failures.

`spql.io.stat`

Return a blob's object metadata without reading payload bytes.

Kind: scalar function
Volatility: immutable

spql.io.stat(blob) -> struct { size: u64?, snapshot_kind: utf8?, snapshot_value: utf8?, modified_unix_nanos: u64? }

Inline blobs answer from the value itself. URI-backed blobs are authorized as a payload read is and issue a storage metadata request only. The result carries the payload size, the provider snapshot identity (such as an etag or version) when one is available, and the last-modified time in Unix nanoseconds.

Parameters

Name	Required	Type	Description
`blob`	yes	`spql.Blob`	Blob whose payload to read through the execution host.

Found a problem? Edit this page or report an issue.

Scalar FunctionsCopy Anchor Link

spql.blob.blobCopy Anchor Link

spql.blob.bytesCopy Anchor Link

spql.blob.digestCopy Anchor Link

spql.blob.etagCopy Anchor Link

spql.blob.externalCopy Anchor Link

spql.blob.inlineCopy Anchor Link

spql.blob.mime_typeCopy Anchor Link

spql.blob.offsetCopy Anchor Link

spql.blob.sizeCopy Anchor Link

spql.blob.uriCopy Anchor Link

spql.blob.versionCopy Anchor Link

spql.blob.with_mime_typeCopy Anchor Link

spql.io.fetchCopy Anchor Link

spql.io.read_bytesCopy Anchor Link

spql.io.statCopy Anchor Link

Scalar Functions

`spql.blob.blob`

`spql.blob.bytes`

`spql.blob.digest`

`spql.blob.etag`

`spql.blob.external`

`spql.blob.inline`

`spql.blob.mime_type`

`spql.blob.offset`

`spql.blob.size`

`spql.blob.uri`

`spql.blob.version`

`spql.blob.with_mime_type`

`spql.io.fetch`

`spql.io.read_bytes`

`spql.io.stat`