Docs: the facets user guide and an example (closes #293)

.github/workflows/test-native.yml

@@ -672,7 +672,7 @@ jobs:
     env:
       KEY: ${{ matrix.key }}
       PY: ${{ matrix.python }}
-      EXAMPLES: "0[1-9]_*.py 1[0-9]_*.py 2[0-9]_*.py"
+      EXAMPLES: "0[1-9]_*.py 1[0-9]_*.py 2[0-9]_*.py 3[0-9]_*.py"
       EXAMPLES_SKIP_FILE: scripts/native_examples_skip.txt
       # The Hugging Face cache inside the workspace, as in test-python-examples.yml: one path on every platform, cacheable.
       HF_HOME: ${{ github.workspace }}/.hf-cache

.github/workflows/test-python-examples.yml

@@ -60,7 +60,7 @@ on:
         description: "Glob pattern(s) for examples to run (space-separated, relative to examples)."
         required: false
         type: string
-        default: "0[1-9]_*.py 1[0-9]_*.py 2[0-9]_*.py"
+        default: "0[1-9]_*.py 1[0-9]_*.py 2[0-9]_*.py 3[0-9]_*.py"
       build-version:
         description: "Override package version (PEP 440) for build.sh"
         required: false
@@ -76,7 +76,7 @@ on:
       examples:
         description: "Glob pattern(s) for examples to run (space-separated, relative to examples)."
         required: false
-        default: "0[1-9]_*.py 1[0-9]_*.py 2[0-9]_*.py"
+        default: "0[1-9]_*.py 1[0-9]_*.py 2[0-9]_*.py 3[0-9]_*.py"
 
 # SUPERSEDE, do not race (same rule in test-jvm.yml).
 #
@@ -113,7 +113,7 @@ env:
   # The image download-jars takes the jars from. Unset (push, pull_request, schedule)
   # means latest; a release build passes its tag.
   ARCADEDB_IMAGE_TAG: ${{ inputs.arcadedb-tag || 'latest' }}
-  EXAMPLES: ${{ inputs.examples || '0[1-9]_*.py 1[0-9]_*.py 2[0-9]_*.py' }}
+  EXAMPLES: ${{ inputs.examples || '0[1-9]_*.py 1[0-9]_*.py 2[0-9]_*.py 3[0-9]_*.py' }}
 
 # Note: Example 21 runs in CI at reduced scale; its arguments and 15-minute
 # limit are set in the per-example case in scripts/run_examples.sh, which the

README.md

@@ -61,6 +61,7 @@ This prints `Name: Alice` (the engine also logs to standard error). `create_data
 - Graph, document, key/value, vector (JVector HNSW) and time series models; ACID transactions.
 - Import from CSV, XML and ArcadeDB JSONL; export to JSONL.
 - Columnar results with `to_columns()`, `to_arrow()` and `to_dataframe()`.
+- Faceted queries: the `FACETS` clause of a `SELECT` with a `COLUMNAR` index, and the counts as a dict in `ResultSet.facets` (needs engine 26.12.1 or later).
 - An optional in-process HTTP server (`create_server()`), off until you call it, for other processes that need the same data.
 
 <!-- REMOVE WHEN: the old arcadedb-embedded* shims are retired and two releases have shipped with the two-package layout allow-old-name -->
@@ -82,13 +83,13 @@ Releases from this repository start with 26.11.1. The 26.10.x wheels were built
 
 ## Documentation
 
-- Here: [`docs/`](https://github.com/ArcadeData/arcadedb-python/tree/main/docs/modules/ROOT/pages) is an Antora component (AsciiDoc) with Installation, [Which package?](https://github.com/ArcadeData/arcadedb-python/blob/main/docs/modules/ROOT/pages/which-package.adoc), Quickstart, Databases and queries, Vectors, and Concurrency, processes and crashes. It covers only what is specific to the Python bindings.
+- Here: [`docs/`](https://github.com/ArcadeData/arcadedb-python/tree/main/docs/modules/ROOT/pages) is an Antora component (AsciiDoc) with Installation, [Which package?](https://github.com/ArcadeData/arcadedb-python/blob/main/docs/modules/ROOT/pages/which-package.adoc), Quickstart, Databases and queries, Vectors, Faceted queries, and Concurrency, processes and crashes. It covers only what is specific to the Python bindings.
 - Published at [docs.arcadedb.com/arcadedb-python](https://docs.arcadedb.com/arcadedb-python/), the same site as the main ArcadeDB manual, rebuilt daily from `main` (ArcadeData/arcadedb-docs#505). The `Docs` workflow builds it as a site of its own on every change under `docs/` and attaches it as the `docs-site` artifact. To build it locally, run `npx -p @antora/cli@3.2.1 -p @antora/site-generator@3.2.1 antora docs/antora-playbook.yml` and open `docs/build/site/index.html`.
 - ArcadeDB itself (SQL, openCypher, schema, server): [docs.arcadedb.com](https://docs.arcadedb.com). It is not repeated here.
 
 ## Examples
 
-[`examples/`](https://github.com/ArcadeData/arcadedb-python/tree/main/examples) holds 29 runnable scripts, from a first document store to vector search, time series, graph algorithms and server mode. CI runs them ([`test-python-examples.yml`](https://github.com/ArcadeData/arcadedb-python/blob/main/.github/workflows/test-python-examples.yml)).
+[`examples/`](https://github.com/ArcadeData/arcadedb-python/tree/main/examples) holds 30 runnable scripts, from a first document store to vector search, time series, graph algorithms and server mode. CI runs them ([`test-python-examples.yml`](https://github.com/ArcadeData/arcadedb-python/blob/main/.github/workflows/test-python-examples.yml)).
 
 ## Build and test from source
 

docs/modules/ROOT/nav.adoc

@@ -16,6 +16,7 @@
 ** xref:how-to/functions-and-events.adoc[Python functions and record events]
 ** xref:how-to/vectors.adoc[Vectors]
 ** xref:how-to/columnar-index.adoc[The COLUMNAR index and its settings]
+** xref:how-to/facets.adoc[Faceted queries]
 * Development
 ** xref:development/ci.adoc[Continuous integration]
 ** xref:development/release.adoc[Release]

docs/modules/ROOT/pages/how-to/columnar-index.adoc

@@ -3,7 +3,7 @@
 
 // Sources: ArcadeDB 26.12.1: GlobalConfiguration.java (COLUMNAR_*), AlterDatabaseStatement.java, ColumnarGroupByStep.java, ColumnarCrashRecoveryTest.java. The statements about Python are pinned by tests/test_columnar_index.py, which runs on arcadedb-jvm and on the native arcadedb.
 
-A `COLUMNAR` index keeps a column projection of a type next to its records. The engine applies, flushes and merges it in threads of its own, and the `FACETS` clause and `GROUP BY` read it. It needs engine 26.12.1 or later: an older engine refuses `CREATE INDEX ... COLUMNAR` with `Index type 'COLUMNAR' is not supported`. The facets themselves are read with `ResultSet.facets`.
+A `COLUMNAR` index keeps a column projection of a type next to its records. The engine applies, flushes and merges it in threads of its own, and the `FACETS` clause and `GROUP BY` read it. It needs engine 26.12.1 or later: an older engine refuses `CREATE INDEX ... COLUMNAR` with `Index type 'COLUMNAR' is not supported`. The facets themselves are read with `ResultSet.facets`, which xref:how-to/facets.adoc[Faceted queries] shows kind by kind.
 
 The index is a statement, so it is the same on both builds: