OpenYXDB

Read and write Alteryx YXDB files from Python and C++.

Built on Alteryx's official open-source YXDB implementation, released under GPLv3. This fork modernizes the build system, fixes bugs, adds cross-platform support, and wraps the C++ core in a Python package with first-class PyArrow, Pandas, and Polars integration.

What changed from the Alteryx original

Cross-platform support -- builds and runs on Linux, macOS, and Windows (the original targeted Windows only)
Python bindings via nanobind, published to PyPI as openyxdb
PyArrow, Pandas, Polars, and DuckDB read/write integration with automatic type mapping
Bug fixes -- block index was never written to disk (broke files with more than 65,536 records), reference-counting crash on GCC
Modern CMake (3.20+, target-based), pixi for dependency management, Catch2 test suite, GitHub Actions CI

What is YXDB?

YXDB is the native binary format used by Alteryx Designer. Two on-disk layouts are in active use: the original format used by the classic engine and a newer columnar-friendly variant emitted by the AMP engine.

This library reads both layouts automatically -- the file's magic bytes are sniffed at open time and the appropriate decoder is selected. New files written through openyxdb.Writer use the original format.

Install

pip install openyxdb

Usage

import openyxdb

# Read to PyArrow, Pandas, or Polars
table = openyxdb.to_pyarrow("data.yxdb")
df = openyxdb.to_pandas("data.yxdb")
df = openyxdb.to_polars("data.yxdb")

# Write from any of them
openyxdb.from_polars(df, "output.yxdb")
openyxdb.from_pandas(df, "output.yxdb")
openyxdb.from_pyarrow(table, "output.yxdb")

All 17 YXDB field types are supported: Bool, Byte, Int16, Int32, Int64, FixedDecimal, Float, Double, String, WString, V_String, V_WString, Date, Time, DateTime, Blob, and SpatialObj.

Polars integration

Importing openyxdb automatically monkey-patches polars with YXDB support (no-op if polars is not installed). No extra setup is required.

Top-level aliases

import polars as pl
import openyxdb  # registers everything on import

# Eager read - returns a DataFrame
df = pl.read_yxdb("data.yxdb")

# Lazy scan - returns a LazyFrame with projection & predicate pushdown
lf = pl.scan_yxdb("data.yxdb")
df = lf.select("col_a", "col_b").filter(pl.col("col_a") > 10).collect()

Namespace plugins

# Write a DataFrame directly
df.yxdb.write("output.yxdb")

# Stream a LazyFrame through the streaming engine and write in chunks
lf.yxdb.sink("output.yxdb", chunk_size=65_536)

lf.yxdb.sink() (and the top-level openyxdb.sink_yxdb(lf, path)) execute the lazy plan on Polars' streaming engine and write the result to the YXDB file in chunks, so the writer never buffers more than chunk_size rows in Python at a time. Polars 1.x does not expose a public plugin API for custom sink_* formats, so the query result still passes through a single collect() call before being chunk-written; true per-batch push sinks require upstream Polars support.

Pushdown support

scan_yxdb implements pushdown against the underlying reader:

Optimization	Supported	Notes
Projection pushdown	Yes	Only requested columns are decoded from disk.
Row-limit pushdown	Yes	`head(n)` / `fetch(n)` stops decoding once `n` rows produced.
Batched streaming	Yes	Default 65 536 rows; honours Polars' `batch_size` hint.
Predicate pushdown	Partial	Predicates evaluate per batch after decode. YXDB has no per-block statistics, so genuine file-level skipping isn't possible; combined with `head` predicates still short-circuit once enough rows are collected.

Manual registration

If you import openyxdb after polars is already loaded, everything is registered automatically. To re-register or verify:

openyxdb.register_polars()

DuckDB integration

import duckdb, openyxdb

con = duckdb.connect()

# Register a YXDB file as a SQL view
openyxdb.register_duckdb(con, "yx", "data.yxdb")
con.execute("SELECT COUNT(*) FROM yx WHERE score > 90").fetchone()

# Or get a relation directly
rel = openyxdb.to_duckdb("data.yxdb", con)

# Write the result of a DuckDB query to YXDB
openyxdb.from_duckdb(
    "SELECT id, score FROM yx WHERE score > 90",
    "top_scores.yxdb",
    con=con,
)

DuckDB support is provided through Arrow interop: YXDB files are loaded into an Arrow table and registered on the connection. A native DuckDB table function (SELECT * FROM read_yxdb('file.yxdb')) would require a C++ extension, which is out of scope for this package.

Building from source

pixi install
pixi run build
pixi run test

Limitations

Spatial indexes are skipped on read and not created on write.
Spatial objects are accessible only as raw blobs (SHP-encoded binary).
Little-endian architectures only (x86, ARM).

Testing

The reader has been validated against 1,012 real-world E1 YXDB files sourced from the community corpus at Sigilweaver/YXDB-Sources, covering a wide range of field types, encodings, record counts (0 to 200k+), and filenames including non-ASCII characters - 100% pass rate.

The 1.3.0 streaming sink (sink_yxdb) and DuckDB round-trip paths are exercised against a sampled 25-file subset of the corpus in addition to the per-feature unit tests. Full Python suite: 1,040 passed.

License

GPLv3 -- see LICENSE.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

openyxdb-1.4.3.tar.gz (2.6 MB view details)

Uploaded Jul 18, 2026 Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

openyxdb-1.4.3-cp314-cp314-win_amd64.whl (208.9 kB view details)

Uploaded Jul 18, 2026 CPython 3.14Windows x86-64

openyxdb-1.4.3-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (271.6 kB view details)

Uploaded Jul 18, 2026 CPython 3.14manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

openyxdb-1.4.3-cp314-cp314-macosx_11_0_arm64.whl (199.9 kB view details)

Uploaded Jul 18, 2026 CPython 3.14macOS 11.0+ ARM64

openyxdb-1.4.3-cp313-cp313-win_amd64.whl (201.8 kB view details)

Uploaded Jul 18, 2026 CPython 3.13Windows x86-64

openyxdb-1.4.3-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (271.5 kB view details)

Uploaded Jul 18, 2026 CPython 3.13manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

openyxdb-1.4.3-cp313-cp313-macosx_11_0_arm64.whl (199.9 kB view details)

Uploaded Jul 18, 2026 CPython 3.13macOS 11.0+ ARM64

openyxdb-1.4.3-cp312-cp312-win_amd64.whl (201.9 kB view details)

Uploaded Jul 18, 2026 CPython 3.12Windows x86-64

openyxdb-1.4.3-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (271.6 kB view details)

Uploaded Jul 18, 2026 CPython 3.12manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

openyxdb-1.4.3-cp312-cp312-macosx_11_0_arm64.whl (200.0 kB view details)

Uploaded Jul 18, 2026 CPython 3.12macOS 11.0+ ARM64

openyxdb-1.4.3-cp311-cp311-win_amd64.whl (202.0 kB view details)

Uploaded Jul 18, 2026 CPython 3.11Windows x86-64

openyxdb-1.4.3-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (273.0 kB view details)

Uploaded Jul 18, 2026 CPython 3.11manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

openyxdb-1.4.3-cp311-cp311-macosx_11_0_arm64.whl (201.0 kB view details)

Uploaded Jul 18, 2026 CPython 3.11macOS 11.0+ ARM64

openyxdb-1.4.3-cp310-cp310-win_amd64.whl (202.3 kB view details)

Uploaded Jul 18, 2026 CPython 3.10Windows x86-64

openyxdb-1.4.3-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (273.2 kB view details)

Uploaded Jul 18, 2026 CPython 3.10manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

openyxdb-1.4.3-cp310-cp310-macosx_11_0_arm64.whl (201.2 kB view details)

Uploaded Jul 18, 2026 CPython 3.10macOS 11.0+ ARM64

File details

Details for the file openyxdb-1.4.3.tar.gz.

File metadata

Download URL: openyxdb-1.4.3.tar.gz
Upload date: Jul 18, 2026
Size: 2.6 MB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for openyxdb-1.4.3.tar.gz
Algorithm	Hash digest
SHA256	`05da3bfe15430093f8647044118412338b06550605b8c40c11dea8f2aedd59b6`
MD5	`4f8846b12ed90a5785a670992a05ee2f`
BLAKE2b-256	`b17b3f097df40ede5673a97bdb286b74c041665c729cfcde160f8e9254f0c93d`

Algorithm	Hash digest
SHA256	`50508906c27468fd679a61bc23bd9a5b54b8349a22a3b441e48df075137abc6d`
MD5	`874cde2f114a448d9655722cb35ba528`
BLAKE2b-256	`df6d3aaa7bca3cd0a0a15250bc46343ac5def3d8f298017c56416b9c8d59d671`

Algorithm	Hash digest
SHA256	`2be208f714af5803fc882fe575f28e4b5ed58cd512f3042d0abcdd115c44372c`
MD5	`1d6011df51a4b5f79ee1de0dcaffc96c`
BLAKE2b-256	`54a37dae0a38c71f5994fd4e66e657f839dbeff73ecdc3182ba438a229825fd0`

Algorithm	Hash digest
SHA256	`06efd002845e99bcde178d3b24b892cce69c4d0ce292c42ffcf6b5dc0702e7d5`
MD5	`635606ca5f72f888d056acd2d4dd8745`
BLAKE2b-256	`6cfd73acc258850fc5a92d2cb73bbb4bcf3a01dd3d2379dff7c42fb2bc6b669d`

Algorithm	Hash digest
SHA256	`57b58e395beecae74284703bc7be6f6325ed8940a1c2a2a0a38b7d5c03da45ea`
MD5	`c8e33c0607db878cb52517b8fe14af8b`
BLAKE2b-256	`ee2a4f183d8c534005a5840593efbf857e7549be9e403a29a0d8b5547bb99d21`

Algorithm	Hash digest
SHA256	`320ee0a9fbd412ccb322eee95c72fcea3f55b211f7c5fa90255657135afdf94a`
MD5	`af4440e9aa3dc3233516bb2a961b5cd8`
BLAKE2b-256	`f92a1e1a3a2f795719e9f69322ad1edb09015b977a430762363d3584cc7cc638`

Algorithm	Hash digest
SHA256	`d974fab1c2754520e4b2dc2c4c97d2b6e351b96977bb4e099df218972b062ead`
MD5	`2b9a5e551a6175863a747bb037f10f1e`
BLAKE2b-256	`c87b568bbb8b04c8cd82563f2d37a4fba46f52a748f10b7bda77b857dd4dca88`

Algorithm	Hash digest
SHA256	`ee4aca208f034938a4a31ed78c80d364197ce2a45be75dfbfbdf6d8be26c4041`
MD5	`f3f6a106d88b86a62cd8bbebc99e9513`
BLAKE2b-256	`63f8eacad6ecb9807152128133e15592d9b53bd3b945cc0f92e8b3123c63575d`

Algorithm	Hash digest
SHA256	`f7128de8ce7121f2238d38507b6378f02f568e41ee39a4a163b5982b4dd68875`
MD5	`7fa3cc46db14bc316432a580e9768c5a`
BLAKE2b-256	`804d3efb8653dd2c729fd169a0131df689a77a2cd350577389b4ed2076de1544`

Algorithm	Hash digest
SHA256	`26d4d12d79522f668b8a1b6b781381e1129658c72ba5b51af9887b3e7d37a812`
MD5	`72fdf33a11e2d2b2d5d8c860cc39114d`
BLAKE2b-256	`7d375050491d4c18e4b04b3063ad4df7197e25412c26a6825eee3c96ab3ca251`

Algorithm	Hash digest
SHA256	`56f120d8993132f78295afbc7bc10c2241664c388d6b204590644bbd4c7c9bd4`
MD5	`a8cc8e3e865ef26eede69fd3c54832f1`
BLAKE2b-256	`5340b73744ad66fa47923666f882412ac7d05267f1cbe8266e8cf7ddb6bf6d88`

Algorithm	Hash digest
SHA256	`450a5e3e884ae086010eca36690d24d83718b633ad35de79f900a36f55c7a453`
MD5	`efd0794ca30d99943f67f3c2d446547c`
BLAKE2b-256	`35fe58f539fd7b1105d95831b7ad577eb11b1ec7882eaa73605658891d2ec362`

Algorithm	Hash digest
SHA256	`ed17d2980ae479d089da9a5331adbd5dbc891d427c219826458fa28833eb03f1`
MD5	`95d4c743eb0b58e5b5aefd1e2979fe56`
BLAKE2b-256	`75f1b01c2b04a0aab3adcef5ef1465ba8096ee465d030cbb5f361b6a3ed7ba62`

Algorithm	Hash digest
SHA256	`ed0f9845f063f7eee26d02b8e64dbc1131b104d74532b11b78b323a217600eff`
MD5	`781b789d5f3410abcc38f57da5bf68ec`
BLAKE2b-256	`4c336f1d4036ece5b05bb8c4f86e3442e688d84b25b1189c16b16b41ff8befba`

Algorithm	Hash digest
SHA256	`b55453a2994121e37426ffe300cc730e7694ba5a55663472c2318dcddaa5b108`
MD5	`96d4bf6ba8596ee1c10058ae285575a3`
BLAKE2b-256	`5798d33dff6bdc08ca657cf1388d504d4a1023aa365dba52264533d2c7d102b4`

Algorithm	Hash digest
SHA256	`f38d36a6c85fd3cf1821ea7620cb88ff7f09b2779f918fc14556ca751070dc7f`
MD5	`2c1087867962e6836d6dcafd395c0854`
BLAKE2b-256	`356f3fa90f7e114c8ab7f3e81d393523a4ffd8cc9faba1a57d56c3d3f860d239`

openyxdb 1.4.3

OpenYXDB

What changed from the Alteryx original

What is YXDB?

Install

Usage

Polars integration

Top-level aliases

Namespace plugins

Pushdown support

Manual registration

DuckDB integration

Building from source

Limitations

Testing

License

Project links

Key dates

1 maintainer

GitHub Statistics

License

Requires

Provides Extra

Tags

Classifiers

Download files

Source Distribution

Built Distributions

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance