Overview
Quail is an extensible query engine. This section explains how to implement extensions and use them in a session.
Extension types
| Task | Guide |
|---|---|
| Read tables from another storage system. | Custom data sources |
| Add a model or GPU specification, or implement another model architecture. | Custom models and GPUs |
| Add a query operation. | Custom operators |
| Change query planning decisions. | Custom Rules |
| Run code after an operator finishes. | Observers |
Registration
An extension registry holds the implementations available to a session.
Use ExtensionRegistry.with_built_ins() to create a registry containing
Quail's included implementations.
To add an extension:
- Implement the interface described in its guide.
- Register the implementation with the appropriate
register_*method, such asregister_model()orregister_observer(). - Pass the registry to
Session(config=config, registry=registry).
Each guide includes an example of implementation and registration.
Registration does not load model weights or run inference. A duplicate
name within the same extension type raises ValueError.
Data sources use session.register(name, provider) directly.
See Custom data sources.
Extension modules
A Python package can register its extensions through a
register_quail_extension(registry) function. The function receives the
registry and calls the registration methods for the package's extensions.
Call registry.load_extension(module_name) to import the module and run
its registration function. The module must be importable in the process
that creates the registry. Loading the same module into the same registry
twice raises ValueError.