Skip to content
This repository was archived by the owner on Nov 21, 2026. It is now read-only.
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion bindings/python/docs/development/testing.md
Original file line number Diff line number Diff line change
Expand Up @@ -147,7 +147,7 @@ asserts, so the list below stops at the file.
| `test_docs_examples.py` | Python blocks from the documentation run as code; see [Documentation example tests](#documentation-example-tests) |
| `test_equivalence.py` | ArcadeDB answers like DuckDB (SQL), NetworkX (graph algorithms) and NumPy (vector recall), and like itself with indexes, a view and parameters; see [Equivalence checks](#equivalence-checks) |
| `test_equivalence_ladybug.py` | ArcadeDB's Cypher answers like LadybugDB's over the same graph and queries (not collected on Windows; see [Equivalence checks](#equivalence-checks)) |
| `test_collection_equality_known_issues.py` | The workarounds for SQL `=` on a list or map written from Python (ArcadeData/arcadedb#10448, open): openCypher `=` and a named SQL parameter, with strict `xfail` tripwires on the SQL list and map literals and on the parameter through a `BY ITEM` index |
| `test_collection_equality_known_issues.py` | SQL `=` on a list or map written from Python (ArcadeData/arcadedb#10448, fixed on upstream's main and in 26.11.1, not in the 26.10.2 wheel): plain tests of the fixed answer for the SQL list and map literals, `<>`, and the parameter through a `BY ITEM` index, plus the openCypher `=` and named-parameter workarounds, which pass on every engine. CI's snapshot image can still hold the engine from before the fix under the same version string, so the file probes the behavior and asserts the old answer there |
| `test_count_pushdown_known_issues.py` | Regression tests for the openCypher count push-down fixes and the `BYTE` aggregate fix that shipped in 26.10.2, with the workarounds that were documented for them (they fail on the 26.10.1 wheel) |
| `test_light_edge_and_view_known_issues.py` | Regression tests for the two openCypher count fixes that shipped in 26.10.2 (a one-hop `count(*)` over `light_edges=True` edges in an edge type that is not `LIGHTWEIGHT`, and a pattern predicate over an edge type that a Graph Analytical View does not list): the refusal and the right counts, with the workarounds that were documented for them (they fail on the 26.10.1 wheel) |
| `test_null_index_known_issues.py`, `test_declared_type_known_issues.py`, `test_dml_plan_cache_known_issues.py` | Plain regression tests for engine bugs that 26.10.1 fixed (null keys and index lookups, declared properties, positional parameters in a cached DML plan), with the workarounds that were documented for them |
Expand Down
2 changes: 1 addition & 1 deletion bindings/python/docs/guide/core/queries.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Query Languages Guide

!!! warning "Known engine issues"
Open ArcadeDB bugs can return a wrong answer or refuse a lookup; see
Known bugs that can return a wrong answer or refuse a lookup, and the releases that fixed earlier ones, are listed on
[Known Engine Issues](../known-issues.md).

The bindings run SQL and OpenCypher through `db.query()` and `db.command()`. Use them
Expand Down
2 changes: 1 addition & 1 deletion bindings/python/docs/guide/graph-analytics.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Graph Analytics Guide

!!! warning "Known engine issues"
Open ArcadeDB bugs can return a wrong answer or refuse a lookup; see
Known bugs that can return a wrong answer or refuse a lookup, and the releases that fixed earlier ones, are listed on
[Known Engine Issues](known-issues.md).

ArcadeDB ships two things for whole-graph questions such as "who matters most" or
Expand Down
53 changes: 31 additions & 22 deletions bindings/python/docs/guide/known-issues.md
Original file line number Diff line number Diff line change
@@ -1,37 +1,46 @@
# Known Engine Issues

This page lists the known bugs that can return a wrong answer, store a wrong value, change the
wrong rows, or refuse a read or a write. The first entry is an engine bug. The other two, about
Ctrl-C and about memory held by results, are not: they are in JPype, the library that connects
wrong rows, or refuse a read or a write. The first entry is an engine bug that is fixed on
upstream's main and not yet in a release. The other two, about
Ctrl-C and about memory held by results, are not engine bugs: they are in JPype, the library that connects
Python to the engine. Each entry names the versions it was measured on, what you see, a workaround that was
checked on the same reproduction, and the release that fixes it once there is one. Entries leave
this page when the fix ships in a release these bindings package.
An entry with a `Tests:` line has a test of its workaround.
An entry with a `Tests:` line has a test of its workaround. An entry for a bug that is fixed on upstream's main but not yet in a release says so, with the release that will carry the fix.

## SQL `=` on a list or map misses a list written from Python
## SQL `=` on a list or map misses a list written from Python (fixed in 26.11.1)

ArcadeDB 26.10.2 (the wheel) and the 26.11.1 snapshot at 58e00054b1. Open, reported as
[ArcadeData/arcadedb#10448](https://github.com/ArcadeData/arcadedb/issues/10448).
ArcadeDB 26.10.2 (the wheel) and earlier. Reported as
[ArcadeData/arcadedb#10448](https://github.com/ArcadeData/arcadedb/issues/10448), fixed by
[#10457](https://github.com/ArcadeData/arcadedb/pull/10457) on upstream's main on 2026-10-20 and
in 26.11.1, which is not released yet. On 26.11.1 (and on a snapshot built after that change) the
query below is right and you need none of the workarounds; on 26.10.2 and earlier it is not.

`Document.set`, `Vertex.set` and `GraphBatch.create_vertices` store a Python `int` as a Java
`Long`. A SQL literal such as `[1, 2]` parses to `Integer` elements, and SQL `=` compares the
`Long`. A SQL literal such as `[1, 2]` parses to `Integer` elements, and SQL `=` compared the
elements of two lists, or the values of two maps, with Java `equals()`, which keeps a `Long` 1
and an `Integer` 1 apart. So `SELECT FROM V WHERE li = [1, 2]` misses a vertex whose `li` was
written from Python as `[1, 2]`, `li <> [1, 2]` returns it, and `mp = {"a": 1}` misses a map
and an `Integer` 1 apart. So `SELECT FROM V WHERE li = [1, 2]` missed a vertex whose `li` was
written from Python as `[1, 2]`, `li <> [1, 2]` returned it, and `mp = {"a": 1}` missed a map
the same way. `insert_many` stores `Integer` elements (the engine reads its rows as JSON), so
the literal matches a list written there and misses the same list written with `Document.set`.
`CONTAINS`, `CONTAINSALL`, `GROUP BY` and openCypher's `=` treat the two lists as equal.

Use openCypher's `=` (`MATCH (n:V) WHERE n.li = [1, 2]`), or bind the list as a named SQL
parameter, `db.query("sql", "SELECT FROM V WHERE li = :p", {"p": [1, 2]})`: it crosses with
`Long` elements, so it matches lists written with `Document.set`, `Vertex.set` and `GraphBatch`
(and misses lists written with `insert_many`). The parameter does not help when the list has a
`BY ITEM` index: SQL `=` is then answered from the index and matches nothing, literal or
parameter. openCypher's `=` matches with or without the index.

Tests: `tests/test_collection_equality_known_issues.py` covers both workarounds, with tripwires
on the SQL literals and on the parameter through a `BY ITEM` index that fail the suite once the
fix reaches the wheel.
the literal matched a list written there and missed the same list written with `Document.set`.
`CONTAINS`, `CONTAINSALL`, `GROUP BY` and openCypher's `=` treated the two lists as equal.
From 26.11.1, `=` and `<>` on a list or a map compare the elements numerically, as those do, and
so do `IN` and `CONTAINS` with a list or map value. A `BY ITEM` index is no longer used to answer
a whole-list `=`: the query scans, so the answer is right and no longer depends on the index.

On 26.10.2 and earlier, use openCypher's `=` (`MATCH (n:V) WHERE n.li = [1, 2]`), or bind the
list as a named SQL parameter, `db.query("sql", "SELECT FROM V WHERE li = :p", {"p": [1, 2]})`:
it crosses with `Long` elements, so it matches lists written with `Document.set`,
`Vertex.set` and `GraphBatch` (and misses lists written with `insert_many`). The parameter does
not help when the list has a `BY ITEM` index: SQL `=` is then answered from the index and
matches nothing, literal or parameter. openCypher's `=` matches with or without the index.

Tests: `tests/test_collection_equality_known_issues.py` asserts the fixed answer for the SQL
literals, `<>` and the parameter through a `BY ITEM` index, and keeps the two workarounds
passing on every engine. Upstream's snapshot image that CI builds the wheel from may still hold
the engine from before the fix, with the same version string, so the test file probes the
behavior and asserts the old answer on such an engine.

## Ctrl-C during an interruptible Java wait can raise `InterruptedException`, not `KeyboardInterrupt`

Expand Down
2 changes: 1 addition & 1 deletion bindings/python/docs/guide/timeseries.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Time Series Guide

!!! warning "Known engine issues"
Open ArcadeDB bugs can return a wrong answer or refuse a lookup; see
Known bugs that can return a wrong answer or refuse a lookup, and the releases that fixed earlier ones, are listed on
[Known Engine Issues](known-issues.md).

A `TIMESERIES` type is a native ArcadeDB type for samples that arrive in time order:
Expand Down
82 changes: 53 additions & 29 deletions bindings/python/tests/test_collection_equality_known_issues.py
Original file line number Diff line number Diff line change
@@ -1,16 +1,24 @@
"""SQL `=` on a list or map misses a list written from Python (known-issues.md).
"""SQL `=` on a list or map and a list written from Python (known-issues.md), fixed in 26.11.1.

`Document.set`, `Vertex.set` and `GraphBatch.create_vertices` store a Python `int` as a `Long`,
and a SQL literal such as `[1, 2]` parses to `Integer` elements. SQL `=` compares list and map
elements with Java `equals()`, so the list written from Python is not equal to the literal.
The workarounds (openCypher `=`, and a named SQL parameter, which crosses as `Long` elements)
must keep passing (the parameter only without a `BY ITEM` index on the list: with one, SQL `=`
is answered from the index and matches nothing). The engine behavior itself is a strict `xfail`, a tripwire as in
`test_null_index_known_issues.py`: when the fix reaches the wheel it starts passing and the
suite fails, and the test then becomes a plain one.

Upstream: ArcadeData/arcadedb #10448 (open; measured on the 26.10.2 wheel and on main
58e00054b1).
and a SQL literal such as `[1, 2]` parses to `Integer` elements. SQL `=` used to compare list and
map elements with Java `equals()`, so the list written from Python was not equal to the literal.
ArcadeData/arcadedb#10448 (fixed by #10457, in 26.11.1) makes `=` and `<>` compare the elements
numerically, as openCypher, `CONTAINSALL` and `GROUP BY` already did, and a `BY ITEM` index is no
longer used to answer a whole-list `=` (the query scans, so the answer is right).

The workarounds that were documented (openCypher `=`, and a named SQL parameter, which crosses as
`Long` elements) must keep passing on every engine. The three SQL tests that were strict `xfail`
tripwires are plain tests now: they assert the fixed answer.

CI builds its wheel from upstream's 26.11.1-SNAPSHOT image, which carries no build number and is
republished only when upstream's deploy job succeeds; at the time of this change it still held the
engine from before #10457, with the same version string as the fixed engine. So the version cannot
tell the two apart, and `fixed` probes the one behavior that changed: two lists that differ only in
the element class are equal. On an engine without the fix the same tests assert the old answer (no
row), as `test_vector_sql.py` does for `where` (the repository accepts no skips,
scripts/check_test_skips.py). When 26.11.1 is released and the wheel the suite runs on is built
from it, delete `fixed` and the old-answer branches.
"""

import arcadedb_embedded as arcadedb
Expand Down Expand Up @@ -46,6 +54,14 @@ def indexed_db(temp_db_path):
yield db


@pytest.fixture
def fixed(tmp_path):
"""True when the engine has the #10448 fix (see the module docstring)."""
with arcadedb.create_database(str(tmp_path / "probe")) as probe:
row = probe.query("sql", "SELECT ([1, 2] = :p) AS eq", {"p": [1, 2]}).to_list()
return row[0]["eq"] is True


def _keys(db, language, query, *args):
return sorted(row["k"] for row in db.query(language, query, *args).to_list())

Expand All @@ -66,18 +82,22 @@ def test_a_named_sql_parameter_matches_lists_written_from_python(db):
]


@pytest.mark.xfail(
strict=True, raises=AssertionError, reason="ArcadeData/arcadedb#10448"
)
def test_a_sql_list_literal_matches_lists_written_from_python(db):
assert _keys(db, "sql", "SELECT k FROM V WHERE li = [1, 2]") == ["batch", "set"]
def test_a_sql_list_literal_matches_lists_written_from_python(db, fixed):
assert _keys(db, "sql", "SELECT k FROM V WHERE li = [1, 2]") == (
["batch", "set"] if fixed else []
)


def test_a_sql_map_literal_matches_maps_written_from_python(db, fixed):
assert _keys(db, "sql", 'SELECT k FROM V WHERE mp = {"a": 1}') == (
["batch", "set"] if fixed else []
)

@pytest.mark.xfail(
strict=True, raises=AssertionError, reason="ArcadeData/arcadedb#10448"
)
def test_a_sql_map_literal_matches_maps_written_from_python(db):
assert _keys(db, "sql", 'SELECT k FROM V WHERE mp = {"a": 1}') == ["batch", "set"]

def test_sql_inequality_on_a_list_excludes_lists_written_from_python(db, fixed):
assert _keys(db, "sql", "SELECT k FROM V WHERE li <> [1, 2]") == (
[] if fixed else ["batch", "set"]
)


def test_opencypher_equality_matches_through_a_by_item_index(indexed_db):
Expand All @@ -86,11 +106,15 @@ def test_opencypher_equality_matches_through_a_by_item_index(indexed_db):
) == ["set"]


@pytest.mark.xfail(
strict=True, raises=AssertionError, reason="ArcadeData/arcadedb#10448"
)
def test_a_named_sql_parameter_matches_through_a_by_item_index(indexed_db):
# With a BY ITEM index on the list, SQL = is answered from the index and matches nothing
assert _keys(indexed_db, "sql", "SELECT k FROM X WHERE li = :p", {"p": [1, 2]}) == [
"set"
]
def test_a_named_sql_parameter_matches_through_a_by_item_index(indexed_db, fixed):
# Before the fix, SQL = on a list with a BY ITEM index was answered from the index and
# matched nothing; now the query scans
assert _keys(indexed_db, "sql", "SELECT k FROM X WHERE li = :p", {"p": [1, 2]}) == (
["set"] if fixed else []
)


def test_a_sql_list_literal_matches_through_a_by_item_index(indexed_db, fixed):
assert _keys(indexed_db, "sql", "SELECT k FROM X WHERE li = [1, 2]") == (
["set"] if fixed else []
)
Loading