Repository navigation
Docs gaps found in the 26.11.1 audit: single-pass results, transactions, types, import/export, server mode, and stale statements #267
Description
A read-only audit of the docs (docs/modules/ROOT/, README) against the code on main (a53f9cd6cc) and the 26.11.1 engine release notes found gaps a typical user hits, and statements the code contradicts. Paths below are on main.
Missing (ranked by how many users hit it)
| # | Gap | Code |
|---|---|---|
| 1 | A ResultSet is a lazy, single-pass cursor: closed when read to the end and by first(), one(), close(); a second pass reads nothing, a closed one raises; statement errors can surface while rows are read; an unclosed set keeps scan threads parked (arcadedb.parallelScanAbandonedTimeout); count() consumes the rows |
src/arcadedb/results.py:315-343, :1170, :1199, :1232 |
| 2 | Transactions: 26.11.1 undoes a failed statement inside a transaction and the transaction goes on (refused commit above arcadedb.txStatementSavepointMaxEntries); GraphBatch refuses to run inside a caller's transaction; set_auto_transaction(True); run_in_transaction defaults; begin/commit/rollback and nested transaction() |
src/arcadedb/graph_batch.py:27-35, src/arcadedb/core.py:470, :636-652, :1930 |
| 3 | Python types in and out, above all datetimes: naive stored as UTC wall clock, aware converted to UTC, DATE as date, DECIMAL as Decimal |
src/arcadedb/type_conversion.py:324-335, :364-380, :603-617, :855-862 |
| 4 | Import and export (import_documents, export_database, export_to_csv; GraphML/GraphSON not bundled), promised in the README but never shown |
core.py:2238, :2354, :2398; importer.py:68; exporter.py:21, :199 |
| 5 | DataFrame, Arrow and column paths (insert_dataframe, insert_arrow, insert_columns; to_arrow()/to_columns() return None without pyarrow/numpy) |
results.py:781-808, :956-981; core.py:1053, :1200, :1278; dataframe.py:116, :377 |
| 6 | Server mode: host defaults to localhost (Docker and LAN clients cannot connect), how other keys map to arcadedb.* settings, the Postgres/Redis/Bolt plugins via server_plugins, no Studio on the native server |
src/arcadedb/server.py:50-120, :237, :288; src/arcadedb/_native/server.py:1, :106 |
| 7 | Cypher 26.11.1 vector features (CREATE VECTOR INDEX, SEARCH ... IN (VECTOR INDEX ...)) are not on the vectors page |
engine 26.11.1 release notes |
| 8 | Python functions in SQL/Cypher and record events (register_function, db.on), only in example 28 |
core.py:1954, :2015, :2030; callbacks.py:281, :351, :397 |
| 9 | Record objects (new_vertex, new_document, new_edge, lookup_by_key, modify().set().save()) |
core.py:664, :674, :1429, :1492; graph.py:55, :241, :368 |
| 10 | set_wal_flush(...), and the 26.11.1 settings arcadedb.fileSync and arcadedb.txWalGroupCommit |
core.py:1855 |
| 11 | AsyncExecutor usage (one shared executor per database; close() closes it for all callers) |
async_executor.py:242, :608; core.py:2078-2100 |
| 12 | One line that the Python Schema API exists |
schema.py |
| 13 | find_nearest_by_key, and whether find_nearest's second element is a distance (lower is closer) |
vector.py:768, :582-640 |
Wrong or stale
installation.adoc:117,:266andwhich-package.adoc:95:jvm_kwargs"do not exist" on native; the nativecreate_databaseaccepts and ignores them with a warning (_native/database.py:1649-1656).installation.adoc:77lists Studio in the shared "What is included" list; the native server has none.- Docstrings point to pages that do not exist:
graph_batch.py:35(docs/api/graph_batch.md),core.py:1977("the Python functions guide"),results.py:422("the performance guide"). README.md:91"27 runnable scripts" (29 exist);README.md:32"Python 3.11 to 3.14" for both packages (native installs on 3.15, tested 3.11 to 3.14);README.md:35omits thepolarsextra ofarcadedb-jvm.- Sample outputs from old versions:
installation.adoc:107(26.11.1.dev2),quickstart.adoc:24(26.10.2.post1),quickstart.adoc:136(JVM error text),concurrency.adoc:15-20(native row labelled alpha,26.10.2.dev1). bulk-loads.adoc: theappend_samplesheading reads as native-only; the JVM executor has it too.- The pre-release notes (
README.md:27,index.adoc:27,installation.adoc:29,quickstart.adoc:21,bulk-loads.adoc:167, the README status cells) must change when the 26.11.1 finals are on PyPI.
Plan: the wrong and stale items plus rows 1, 6, 7 and 13 go into #264 before the 26.11.1 tag; the pre-release notes change on release day; rows 2 to 5 and 8 to 12 follow as their own PRs after the release, the 26.11.1 transaction behaviour checked by a test first.
Activity
Docs: fix statements the code contradicts (#267)
Docs: a result set is read once; server mode host, settings and plugi…
Docs: Cypher vector indexes in 26.11.1; find_nearest distance; find_n…
Docs: one install command per package; README CI sentence matches the…
Docs for 26.11.1: query language, find_nearest width and distance, re…
Docs: a Transactions page, with tests that pin each statement first (…
Docs: embedded documents differ per build, apply the editorial review…
Docs: editorial pass on the import-export and DataFrame pages, and so…
Docs: editorial pass on the import-export and DataFrame pages, and so…
Docs: a Values and records page, with tests that pin each statement f…
Docs: Importing and exporting data, and DataFrames, Arrow and columns…
Docs: editorial pass on the import-export and DataFrame pages, and so…
Docs: get_type_name() is a Java string on arcadedb-jvm, so the page c…
Docs: Importing and exporting data, and DataFrames, Arrow and columns…
Docs: a Python functions and record events page, with tests that pin …
Docs: get_type_name() is a Java string on arcadedb-jvm, so the page c…
Docs: Durability settings and The async executor pages, with tests th…
Docs: Python functions and record events, with tests that pin each st…