Repository navigation
Columnar faceting: Python support for COLUMNAR and FACETS #289
Description
Part of ArcadeData/arcadedb#10355 (columnar faceting). Moved here from ArcadeData/arcadedb#10666, because the Python bindings live in this repository.
Context
Columnar faceting is merged in ArcadeData/arcadedb (PRs #11338 to #11346) and ships in 26.12.1. It adds the COLUMNAR index type, the SQL FACETS clause (TERMS, RANGES, HISTOGRAM, HIERARCHY, DISTINCT, STATS, AFTER), the facet.searchValues(...) function and GROUP BY acceleration. In the engine, the facets of a query are returned next to the rows: ResultSet.getFacets() returns a FacetResults object (a meta member with exact, patched and lagMs, and one member per facet alias with type, source, optional reason, buckets, otherCount for terms and missing).
Both packages here (arcadedb native and arcadedb-jvm) embed the engine, so the FACETS clause and the COLUMNAR index already run through SQL once the engine version is 26.12.1. What is missing is the Python surface and the proof that it works in both builds.
Done when
- A Python query with
FACETSreturns the rows and the same facet results the Java API returns for the same query, in both packages. - Unavailable facets (
source: "unavailable"with areason) reach the caller instead of being dropped. - The tests run in the JVM and the native CI lanes against the 26.12.1 engine.
- The user guide documents it.
Sub-issues
Tracked as GitHub sub-issues of this one.
Activity
[-]Columnar faceting: Python client support for FACETS (in arcadedb-python)[/-][+]Columnar faceting: Python support for COLUMNAR and FACETS[/+]tae898 commentedon Nov 6, 2026
I am taking this. The
26.12.1-SNAPSHOTengine jar in the Sonatype snapshot repository contains facets (I checked:ResultSet.getFacets(), the columnar index and the facet classes are there), and the Docker imagearcadedata/arcadedb:latestwas pushed minutes after the last facet PR, so the JVM lane, which takes its jars from that image, should already run an engine with facets (I will confirm that with a test). The native lane links an engine from Maven Central, and 26.11.1 has no facets.I will go in this order: a small CI change so the native lane can build against the
26.12.1-SNAPSHOTengine (a snapshot repository innative/pom.xml), then #290, then #291 and #292, then the docs in #293. New facet tests that need the newer engine checkSELECT version(), astests/test_vector_sql.pydoes, so nothing is skipped on a lane with an older engine.One question: is it fine for the native lane to take its engine from the Sonatype snapshot repository until 26.12.1 is released, or would you rather have it wait for the release? I plan to move the pins to 26.12.1 right after the release.
robfrank commentedon Nov 6, 2026
the jar is published, but the native binaries are produced, tested and not published. Let me check if I can publish them as "snapshots" in the github package registry. The Docker images with native binaries are published every night.
tae898 commentedon Nov 6, 2026
Thanks. I do not need the native binaries, so there is no need to publish anything on my account: this repository compiles the engine jar into its own GraalVM shared library (
native/pom.xml,native/scripts/build-image.sh), so the26.12.1-SNAPSHOTjar on Sonatype is enough for the native lane.The draft PR #298 adds that snapshot repository to
native/pom.xml. A dispatched native run againstengine=26.12.1-SNAPSHOT(linux x86-64, Python 3.12) built the image and the wheel, and the wheel jobs for Python 3.11, 3.13, 3.14, 3.14t and 3.15 passed. One test fails in the parity job, the new smoke test that runs aFACETSquery and creates aCOLUMNARindex; I am reading why now. The PR gate stays on 26.11.1 until you tell me the snapshot is fine to use there.CI: let the native lane build against the 26.12.1-SNAPSHOT engine (refs
tae898 commentedon Nov 7, 2026
Status after today's merges: #290 (
result_set.facets, PR #299), #291 (HIERARCHY, DISTINCT, STATS, AFTER andfacet.searchValues, PR #301), #292 (the COLUMNAR index on both builds, PR #300) and #293 (a user guide and an example, PR #303) are merged and closed. PR #298 lets the native lane build against the26.12.1-SNAPSHOTengine, and a dispatched native run against it passed the facet tests.The facet and COLUMNAR tests are gated on the engine version they run against. The JVM lane (Docker
latest) runs them against an engine with facets. The native PR gate still links 26.11.1, so there the same tests assert that the older engine refusesFACETSandCOLUMNARwith the error it gives, and nothing is skipped.What is left:
DEV_ENGINEintest-native.ymlstays26.11.1until 26.12.1 is released, and then I flip it so the native PR gate runs the facet tests for real as well. One question for @robfrank: would you rather the native PR gate use the26.12.1-SNAPSHOTengine from now on? It would run the facet tests on every PR, at the cost of following a moving snapshot. If not, I wait for the release.If anything in the guide reads wrong against the engine, tell me and I will fix it in a follow-up PR.
docs(columnar): refresh the faceting roadmap now that the feature is …