Opteryx Core
Opteryx Core is the SQL execution engine behind opteryx.app. It is a fork of Opteryx with a smaller, more opinionated API and configuration surface, shaped around the workloads used by the hosted service.
This library is designed for fast, read-heavy analytical queries over Parquet-backed data. It handles SQL parsing, planning, predicate pushdown, projection pruning, and execution so you can query datasets from Python without standing up a separate warehouse.
This project is opinionated toward the needs of opteryx.app. It is still useful as a standalone library if you want to query local Parquet, NDJSON, and CSV datasets, embed SQL into a Python service or notebook, or experiment with engine internals directly.
Requirements
- Python 3.13
- A C/C++ toolchain for local source builds
- Rust/Cargo for the Rust extension in
src/
Install
pip install opteryx-core
Import it as:
import opteryx
Quick Start: Query Local Files
If your current working directory contains local Parquet data, the simplest way to use Opteryx Core is to register a local workspace and query it with dot-separated names.
import opteryx
from opteryx.connectors import DiskConnector
opteryx.register_workspace("data", DiskConnector)
session = opteryx.session()
result = session.execute_to_arrow(
"SELECT id, name FROM data.planets WHERE id < 5"
)
print(result)
In this model, dataset names are resolved relative to the current working directory. For example, data.planets resolves to ./data/planets, and Opteryx Core reads the Parquet files it finds there.
What It Is For
- Powering the execution layer used by
opteryx.app - Running analytical SQL against local Parquet-backed datasets
- Embedding a query engine inside Python applications, scripts, notebooks, and services
- Working on engine internals such as planning, execution, and Parquet performance
Local Development
The supported local build path is the repository Makefile:
make dev-install
make compile
make q
Useful targets:
| Target | Purpose |
|---|---|
make compile |
Clean in-place build of Cython, C++, and Rust extensions |
make c |
Incremental extension build |
make q |
Fast SQL shape smoke test |
make test |
Full pytest suite after compiling |
make dt |
Draken native unit tests |
make check |
Ruff and import-order checks without modifying files |
Do not use pip install . as the primary development build path; make compile matches the layout expected by this repository.
Repository Layout
| Path | Purpose |
|---|---|
opteryx/ |
Python package, planner, operators, connectors, expression evaluation, and Cython modules |
draken/ |
Native columnar vector substrate used by the execution engine |
rugo/ |
Internal Parquet and JSONL reader used by scans and metadata paths |
src/ |
Rust extension code, currently including the SQL dialect integration |
tests/ |
Unit, integration, fuzzing, sqllogictest, and benchmark harnesses |
testdata/ |
Local datasets and benchmark fixtures |
dev/ |
Development, release, vendoring, and analysis scripts |
scratch/ |
Experimental prototypes and one-off investigations |
third_party/ |
Vendored native dependencies |
Best With Opteryx Catalog
Opteryx Core works best when paired with the opteryx_catalog library. That is the intended model for named datasets, catalog-backed tables, and the general experience used in opteryx.app.
Typical setup:
import os
import opteryx
from opteryx import set_default_connector
from opteryx.connectors import OpteryxConnector
from opteryx_catalog import OpteryxCatalog
set_default_connector(
OpteryxConnector,
catalog=OpteryxCatalog,
firestore_project=os.environ["GCP_PROJECT_ID"],
firestore_database=os.environ["FIRESTORE_DATABASE"],
gcs_bucket=os.environ["GCS_BUCKET"],
)
Once configured, you can query catalog-backed datasets using dot-separated names such as public.space.planets or opteryx.ops.billing.
For local data, Opteryx Core is typically used through registered workspaces such as testdata, scratch, or data. Queries refer to datasets by dot-separated names relative to the workspace root, for example testdata.planets, testdata.satellites, or scratch.signals.
Where It Fits
Opteryx Core is best thought of as an embedded analytical engine rather than a full end-user platform. If you want a hosted experience, multi-tenant service features, and the broader product workflow, use opteryx.app. If you want the core engine in your own environment, this package gives you that engine directly. If you want the intended table-resolution model, pair it with opteryx_catalog.
Contributing
If you use Opteryx-Core yourself, we want to hear from you.
- Use it on your own datasets
- Raise bugs when queries, schemas, or performance do not behave as expected
- Open pull requests for fixes, tests, docs, or performance improvements
- Share repro cases, failing queries, and edge-case Parquet files
This project is being actively built, and outside usage helps make it better.
Docs: https://docs.opteryx.app/ Source: https://github.com/mabel-dev/opteryx-core License: Apache-2.0
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distributions
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file opteryx_core-0.9.48.tar.gz.
File metadata
- Download URL: opteryx_core-0.9.48.tar.gz
- Upload date:
- Size: 12.1 MB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
fe2e5409ded630022baeac18bf7b360754ce24697b4b772d5995434e281810c4
|
|
| MD5 |
0a63611e47e92d3b25d9c7948bd59193
|
|
| BLAKE2b-256 |
e7c5e2837a81756f332e19c236a1ef0f7140e45d5e3f0b91490efa7167d41498
|
File details
Details for the file opteryx_core-0.9.48-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.whl.
File metadata
- Download URL: opteryx_core-0.9.48-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
- Upload date:
- Size: 44.4 MB
- Tags: CPython 3.14, manylinux: glibc 2.17+ x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
5b5308d366d1d553b433656f0b8bd099b74f722ad56a659d34e0c98216e5ccbb
|
|
| MD5 |
e53d473d7ed022e2a40864814e51da8d
|
|
| BLAKE2b-256 |
bbfd2b38687b16073b7164de38a8986ea3aae370453daeb0563b0958ed1f633f
|
File details
Details for the file opteryx_core-0.9.48-cp314-cp314-macosx_11_0_arm64.whl.
File metadata
- Download URL: opteryx_core-0.9.48-cp314-cp314-macosx_11_0_arm64.whl
- Upload date:
- Size: 24.7 MB
- Tags: CPython 3.14, macOS 11.0+ ARM64
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
f201ff0810c2b35ce6205b9d63986c30cf805ab6f049d301a50e8c36df360708
|
|
| MD5 |
ef8994b33a2b7b4dd400f804e144de0e
|
|
| BLAKE2b-256 |
97a02bfea01e4dc850fd4714c020029fb0ad8f50f60c0e40aab9ff915f087b93
|
File details
Details for the file opteryx_core-0.9.48-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.whl.
File metadata
- Download URL: opteryx_core-0.9.48-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
- Upload date:
- Size: 44.3 MB
- Tags: CPython 3.13, manylinux: glibc 2.17+ x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
2d9dfe1f0bec2f33df4db887ca53728834b3ca49cd8af989f6af9c516e6a4e56
|
|
| MD5 |
c433824225d95f35ba14cedca55fa36e
|
|
| BLAKE2b-256 |
a6f86a85c390f59b53b29fa960d960bbad0c5e640d681a2ac2729f2907c45265
|
File details
Details for the file opteryx_core-0.9.48-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.whl.
File metadata
- Download URL: opteryx_core-0.9.48-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
- Upload date:
- Size: 44.4 MB
- Tags: CPython 3.12, manylinux: glibc 2.17+ x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
6b7383287236dedfbe7c3c32db904176e9e11ae3f0f65cbbbfe91dbbff9f83cd
|
|
| MD5 |
fe17cd094b3c769b6f88044ba1ea1d2f
|
|
| BLAKE2b-256 |
614e17d0be1b82897da9684242196868c97071f404969c2a4accd5daffefc032
|
