[tae898]

Third slice of #267 (audit of the docs against 26.11.1). It covers rows 4 and 5: two new pages, how-to/import-export.adoc (Importing and exporting data) and how-to/dataframes-and-columns.adoc (DataFrames, Arrow and columns).

Tests first, as for the Transactions page. tests/test_import_export_behavior.py and tests/test_dataframe_columns_behavior.py pin each statement of the two pages, and tests/test_docs_data_exchange_pages.py runs every Python block of both pages in order on both backends and checks the printed output. The pages say only what those tests prove, link the main manual for importer settings, SQL syntax and data types, and stay DSL-first (statements through db.command and db.query, uv add for the extras). The nav gets two adjacent lines, and the pages are linked from Quickstart, Databases and queries and Bulk loads. No size threshold is stated for choosing a path, because nothing in this repository measures one; the page says what each path takes and links the measured commit sizes.

I could not run the tests on the laptop (CI runs them). The JVM test workflow on the current head passes (24 of 24 jobs). The first run found one wrong statement: on Windows EXPORT DATABASE does not refuse a name with a forward slash, because the engine rejects .. and the platform's own path separator. The test and the page now say that per platform. The native parity legs run now that the PR is ready. The importer and exporter rules come from reading the engine source and its own tests (CSVImporterFormat.loadDocuments, ImportDatabaseStatement, ExportDatabaseStatement), the frame and column rules from dataframe.py and core.py. The native reader semantics were checked by running _native/columns.py directly against the output the page shows, and the settings mapping, the type table, the batch sizes and the Arrow conversion by calling the helpers directly. If a test fails in CI, the page statement it backs is wrong and gets fixed here. The ones I am least sure of: probe_only giving PROBE_ONLY on the native build, an import inside the caller's transaction on the native build, the error type of a rejected EXPORT DATABASE name, and the FAIL row of the SQL statement.

Behavior worth a look, none of it filed:

• SQL EXPORT DATABASE calls rollbackAllNested() when a transaction is active, so rows you wrote and did not commit are gone after it. db.export_database(...) does not go through the statement.
• SQL IMPORT DATABASE reports an unusable setting value (commitEvery = 'many') as a row with result FAIL and a reason, where import_documents raises ArcadeDBError for the same mistake. Other import failures raise.
• A failed import of one file of documents leaves none of its rows (one owned transaction, rolled back), but on_row_error="skip" commits row by row. An import inside your own transaction joins it and commits nothing. Skip mode inside your transaction raises.
• insert_columns does not check a column against a declared property: a float column into an INTEGER property is stored without its fraction (1.5 becomes 1), while insert_dataframe and insert_arrow refuse it with TypeError before writing.
• insert_columns refuses a datetime64 array with TypeError on both packages, so the JVM-only rejection that was suspected is not there. A list of datetime objects loads, and a datetime64 column loads through insert_dataframe.
• The two builds differ in how to_columns() and to_arrow() get the rows: the JVM build reads batches of batch_size rows from the engine's column buffer, the native build reads every row into Python dicts first and ignores batch_size (a test spies on each).
• On the native build to_dataframe(convert_types=...) accepts the argument and ignores it, and a missing pandas raises the plain ImportError where the JVM build adds the uv add hint. to_columns() returns None without numpy and to_arrow() returns None without pyarrow, while to_polars() and to_dataframe() raise.
• A RecordBatchReader given to insert_arrow is read to the end before the first batch is written (read_all()), so it is no way to stream a source larger than memory. The page does not say this, because no test pins it.

Left of #267: rows 3 (types and datetimes, in progress elsewhere), 8 (Python functions and events), 9 (record objects), 10 (set_wal_flush, fileSync, txWalGroupCommit), 11 (AsyncExecutor) and 12 (the Schema API line). Rows 6, 7 and 13 and the stale statements were planned for #264 and #276 and are not re-checked here.

The datetime rule on the Arrow section of the DataFrame page links to the Datetimes section of the Values and records page (#281, merged).

A JVM test run on the first commit (run 42156099576) passed on linux/amd64 Python 3.13 with 2414 tests, which include the three new files. An editorial pass and the softened sentences are in the second commit.

Refs #267

🤖 Generated with Claude Code