Custom Extensions - Spiral Docs

Experimental: Contact Us

This surface is directional and may change before public release. Contact Spiral if you want to use it in an early workflow.

A custom Extension should expose a small, documented user surface:

One or more table functions.
Output schemas with stable field names.
Optional scalar or aggregate functions.
Optional materializers for previews, tensors, artifacts, or batch streams.
Configuration keys and credentials.

At SQL level, an Extension usually appears as table functions:


SELECT *
FROM myextension.scan('s3://bucket/path/', option => 'value');

The current binder supports positional and named table-function arguments. Each extension function should document its accepted parameter names and which arguments must be literals for schema discovery.

Documentation checklist

Every custom extension should document:

Section	Required content
Installation	Package name, version constraints, and activation steps.
Table functions	Function ids, parameters, examples, and output schema.
Types	Deferred reference types and materialized value types.
Configuration	Credentials, cache paths, object-store settings, and defaults.
Performance	Pushdown behavior, decode behavior, caching, and memory notes.
Limits	Unsupported formats, size limits, and stability status.

Function ids

Use a stable namespace:


myextension.scan
myextension.metadata
myextension.decode

Avoid short global names that can collide with other packages.

Output schema

Prefer explicit metadata columns and a deferred reference column:

Column	Purpose
`<domain>_id`	Stable id for joins and reproducibility.
`path` or `uri`	Source location when useful to users.
metadata columns	Filterable attributes.
`<domain>_ref`	Deferred value reference.

Materialization

Do not hide expensive work inside discovery table functions. Discovery should return metadata and references. Separate materializers should document when bytes are read, decoded, transformed, cached, or copied to a device.

For implementation details, keep design notes in internal developer documentation or the extension repository, not in the user docs.