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/api/database.md
Original file line number Diff line number Diff line change
Expand Up @@ -848,7 +848,7 @@ load many vertices and edges efficiently.
- `batch_size`: buffered edge batch size
- `expected_edge_count`: tuning hint for large graph loads
- `light_edges`: create property-less edges as light edges
Warning: `light_edges=True` into an edge type that is not declared `LIGHTWEIGHT` makes an openCypher one-hop `count(*)` answer 0 on the 26.10.1 engine, an open upstream bug; see [Known Engine Issues](../guide/known-issues.md#an-opencypher-one-hop-count-answers-0-for-edges-loaded-with-light_edgestrue-into-a-type-that-is-not-lightweight) for the workaround.
Warning: from ArcadeDB 26.11.1, `light_edges=True` raises `ArcadeDBError` from `new_edge` for an edge type that is not declared `LIGHTWEIGHT`; declare it with `CREATE EDGE TYPE ... LIGHTWEIGHT` or leave the option out. On 26.10.1 and earlier the load succeeds but an openCypher one-hop `count(*)` over those edges answers 0, and a graph loaded that way stays wrong; see [Known Engine Issues](../guide/known-issues.md#an-opencypher-one-hop-count-answers-0-for-edges-loaded-with-light_edgestrue-into-a-type-that-is-not-lightweight) for the workaround.
- `commit_every`: commit cadence during flush
- `use_wal`: enable WAL for higher durability
- `parallel_flush`: parallelize flush/close work
Expand Down
2 changes: 1 addition & 1 deletion bindings/python/docs/api/graph_batch.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ Create a configured batch helper tied to the current database.
a single flush is the optimal shape
- `edge_list_initial_size`: initial size in bytes of each vertex's edge segment
- `light_edges`: create property-less light edges when appropriate
Warning: `light_edges=True` into an edge type that is not declared `LIGHTWEIGHT` makes an openCypher one-hop `count(*)` answer 0 on the 26.10.1 engine, an open upstream bug; see [Known Engine Issues](../guide/known-issues.md#an-opencypher-one-hop-count-answers-0-for-edges-loaded-with-light_edgestrue-into-a-type-that-is-not-lightweight) for the workaround.
Warning: from ArcadeDB 26.11.1, `light_edges=True` raises `ArcadeDBError` from `new_edge` for an edge type that is not declared `LIGHTWEIGHT`; declare it with `CREATE EDGE TYPE ... LIGHTWEIGHT` or leave the option out. On 26.10.1 and earlier the load succeeds but an openCypher one-hop `count(*)` over those edges answers 0, and a graph loaded that way stays wrong; see [Known Engine Issues](../guide/known-issues.md#an-opencypher-one-hop-count-answers-0-for-edges-loaded-with-light_edgestrue-into-a-type-that-is-not-lightweight) for the workaround.
- `bidirectional`: store each edge on both vertices (the default) or on its source only.
Pass `False` only for an edge type declared one-way (`CREATE EDGE TYPE ...
UNIDIRECTIONAL`). A one-way edge in a two-way type (the default `CREATE EDGE TYPE`)
Expand Down
2 changes: 1 addition & 1 deletion bindings/python/docs/development/testing.md
Original file line number Diff line number Diff line change
Expand Up @@ -134,7 +134,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_count_pushdown_known_issues.py` | The openCypher count push-down and `BYTE` aggregate entries on [Known Engine Issues](../guide/known-issues.md): their workarounds pass, and plain regression tests assert the right answer (fixed in 26.11.1; they fail on the 26.10.1 wheel) |
| `test_light_edge_and_view_known_issues.py` | The two open entries on [Known Engine Issues](../guide/known-issues.md) about openCypher counts: 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. Plain tests of the workarounds and of the cases that are not affected, and strict `xfail` tripwires of the right counts (upstream #9378 and #9377) |
| `test_light_edge_and_view_known_issues.py` | The two openCypher count entries on [Known Engine Issues](../guide/known-issues.md) (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): their workarounds pass, and plain regression tests assert the refusal and the right counts (fixed in 26.11.1; they fail on the 26.10.1 wheel). One strict `xfail` keeps the caveat that the engine does not repair light edges an older version wrote |
| `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 |

## Markers
Expand Down
70 changes: 49 additions & 21 deletions bindings/python/docs/guide/known-issues.md
Original file line number Diff line number Diff line change
Expand Up @@ -106,14 +106,16 @@ affected.

ArcadeDB [#9378](https://github.com/ArcadeData/arcadedb/issues/9378); measured through the
bindings on the 26.10.1 wheel (the official jars are upstream build d36b4ca3ae), and in Java on that
build and on upstream main 246821a605 (26.11.1-SNAPSHOT), on Temurin 21 and 25, with the same
answers. Open: reported upstream and not fixed on main, so no release carries a fix yet.
build and on upstream main 246821a605, on Temurin 21 and 25, with the same answers. Fixed upstream
for new loads by [ArcadeData/arcadedb#9383](https://github.com/ArcadeData/arcadedb/pull/9383), merged
on 2026-10-07 for ArcadeDB 26.11.1, which is not released yet. The 26.10.1 wheel still has the bug.
The fix does not repair a database that an older version already wrote.

`db.graph_batch(light_edges=True)` writes each edge that has no properties as a light edge, one
with no record of its own. When the edge type is an ordinary one (`CREATE EDGE TYPE E`, not
`CREATE EDGE TYPE E LIGHTWEIGHT`), a `MATCH` of one hop that ends in `RETURN count(*)` is answered
by the count push-down from the number of records in the type, and the type holds none. On three
vertices a, b, and c with the edges a to b and b to c, loaded that way:
vertices a, b, and c with the edges a to b and b to c, loaded that way on 26.10.1:

```python
db.command("sql", "CREATE VERTEX TYPE V")
Expand All @@ -133,29 +135,53 @@ database is closed and opened again. It also holds for `<-[:E]-`, for an undirec
for unlabelled nodes. A type declared `LIGHTWEIGHT`, a batch with `light_edges=False`, and a
batch that does not pass `light_edges` all counted 2 in the same run.

Do not pass `light_edges=True` for an edge type that is not declared `LIGHTWEIGHT`: declare the
type `LIGHTWEIGHT` before the load, or leave the option out. A `LIGHTWEIGHT` type refuses an edge with
properties (`IllegalArgumentException`). For a graph that is already loaded, count in a way that does not take the push-down:
put the variables through a `WITH`, count a node, or name the relationship and count that. All
three counted 2 on the graph above:
**In 26.11.1** the batch refuses the load. `new_edge` raises `ArcadeDBError`, and nothing is
written for that edge:

```
Failed to buffer batch edge 'E': java.lang.IllegalArgumentException: Edge type 'E' does not declare
LIGHTWEIGHT, so a batch built with withLightEdges(true) cannot store its property-less edges as
light edges. Declare the type with CREATE EDGE TYPE E LIGHTWEIGHT, or build the batch without
withLightEdges(true)
```

Edges with properties are not light edges and still load into an undeclared type. On the 26.11.1
snapshot, the load above with `CREATE EDGE TYPE E LIGHTWEIGHT`, with `light_edges=False`, and
without the option all counted 2.

On 26.10.1, do not pass `light_edges=True` for an edge type that is not declared `LIGHTWEIGHT`:
declare the type `LIGHTWEIGHT` before the load, or leave the option out. A `LIGHTWEIGHT` type
refuses an edge with properties (`IllegalArgumentException`).

**A database that was already loaded that way stays wrong** on every engine, 26.11.1 included: the
snapshot does not detect the light edges and still answers 0 for the same query, which I checked by
writing two light edges into an undeclared type with the engine's `newLightEdge`. Count in a way
that does not take the push-down: put the variables through a `WITH`, count a node, or name the
relationship and count that. All three counted 2 on the 26.10.1 wheel and on the snapshot:

```python
db.query("opencypher", "MATCH (a:V)-[:E]->(b:V) WITH a, b RETURN count(*) AS n")
db.query("opencypher", "MATCH (a:V)-[:E]->(b:V) RETURN count(b) AS n")
db.query("opencypher", "MATCH (a:V)-[r:E]->(b:V) RETURN count(r) AS n")
```

Tests: `tests/test_light_edge_and_view_known_issues.py` checks the workarounds and the cases that are
not affected, and has a strict `xfail` test of the right count; it starts failing the suite when
the engine fixes it, which is the cue to remove this entry.
Tests: `tests/test_light_edge_and_view_known_issues.py` checks the workarounds, the refusal, and the
cases that are not affected. The refusal test is plain and passes on the engine the suite builds
against (upstream's 26.11.1 snapshot, which has the fix) and fails on the 26.10.1 wheel. A strict
`xfail` test of the count over light edges that an older version wrote keeps the caveat above
honest: it starts failing the suite if an engine repairs them. Remove the 26.10.1 part of this entry
when the release that carries the fix ships.


## An openCypher count with a pattern predicate over an edge type that a Graph Analytical View does not list is wrong

ArcadeDB [#9377](https://github.com/ArcadeData/arcadedb/issues/9377); measured through the
bindings on the 26.10.1 wheel (the official jars are upstream build d36b4ca3ae), and in Java on that
build and on upstream main 246821a605 (26.11.1-SNAPSHOT), on Temurin 21 and 25, with the same
answers. Open: reported upstream and not fixed on main, so no release carries a fix yet.
build and on upstream main 246821a605, on Temurin 21 and 25, with the same answers. Fixed upstream by
[ArcadeData/arcadedb#9383](https://github.com/ArcadeData/arcadedb/pull/9383), merged on 2026-10-07
for ArcadeDB 26.11.1, which is not released yet: a predicate over an edge type the view does not
list now reads the record. The 26.10.1 wheel still has the bug, and the workarounds below are
still needed on it.

A Graph Analytical View copies the structure of the vertex and edge types it lists
(`CREATE GRAPH ANALYTICAL VIEW ... VERTEX TYPES (...) EDGE TYPES (...)`), and a query that the
Expand All @@ -164,7 +190,7 @@ view can serve is answered from the copy. A view that lists the edge types of th
aggregate, and the predicate is then checked against the copy, where the unlisted type has no
edges. On the vertices x, y, and z of type `V` with the edges x `-E->` y, x `-F->` y, and
y `-E->` z, and a view over `V` and `E`, the pair (x, y) has an `F` edge, so the right count of each
query below is 1. The view answered:
query below is 1. The 26.10.1 view answered:

| Query over the view that lists `E` only | Counted | Right |
| --- | --- | --- |
Expand All @@ -175,12 +201,13 @@ query below is 1. The view answered:
`EXPLAIN` of the first shows `GAV ONE-HOP SCAN` with the predicate as its filter. The same
predicates counted right with no view, with a view that lists `F` as well as `E`, behind a `WITH`,
and in a query that returns rows instead of an aggregate. The query returns no error and no
warning, only the wrong number.
warning, only the wrong number. On the 26.11.1 snapshot all three counted 1, with the view still in
the plan.

Put the variables through a `WITH` before the `WHERE`, as for the count push-down entries below.
That keeps the query off the view, and counted 1 for both forms above. It gives up the view's
speed for that query. Or list every edge type that your pattern predicates name when you create the
view (`EDGE TYPES (E, F)`), which counted 1 as well:
On 26.10.1, put the variables through a `WITH` before the `WHERE`, as for the count push-down
entries below. That keeps the query off the view, and counted 1 for both forms above. It gives up
the view's speed for that query. Or list every edge type that your pattern predicates name when you
create the view (`EDGE TYPES (E, F)`), which counted 1 as well:

```python
db.query(
Expand All @@ -190,8 +217,9 @@ db.query(
```

Tests: `tests/test_light_edge_and_view_known_issues.py` checks both workarounds and the cases that
are not affected, and has strict `xfail` tests of the right counts; they start failing the suite
when the engine fixes them, which is the cue to remove this entry.
are not affected, and has plain regression tests of the right counts. They pass on the engine the
suite builds against (upstream's 26.11.1 snapshot, which has the fix) and fail on the 26.10.1
wheel. Remove this entry when the release that carries the fix ships.


## An openCypher count with a negated pattern in a chain is wrong when the far end has another label or the pattern has a property map
Expand Down
10 changes: 6 additions & 4 deletions bindings/python/src/arcadedb_embedded/core.py
Original file line number Diff line number Diff line change
Expand Up @@ -1200,10 +1200,12 @@ def graph_batch(
batch_size: Maximum buffered edges before auto-flush.
expected_edge_count: Hint for auto-tuning batch size when not set.
edge_list_initial_size: Initial edge-segment size in bytes.
light_edges: Create property-less edges as light edges when True.
Into an edge type not declared LIGHTWEIGHT, an openCypher one-hop
``count(*)`` then answers 0 (ArcadeData/arcadedb#9378, open); declare the
type LIGHTWEIGHT before the load or leave this unset.
light_edges: Create property-less edges as light edges when True. From engine
26.11.1 ``new_edge`` raises ArcadeDBError for an edge type that is not declared
LIGHTWEIGHT; declare the type or leave this unset. On 26.10.1 and earlier the load
succeeds, but an openCypher one-hop ``count(*)`` over those edges answers 0
(ArcadeData/arcadedb#9378, fixed in 26.11.1), and a graph loaded that way stays
wrong.
bidirectional: Connect incoming edges as well as outgoing edges (the
default). Pass False only for an edge type declared UNIDIRECTIONAL. From
26.10.1 a one-way edge in a two-way type is refused: ``new_edge`` raises
Expand Down
Loading
Loading