From 8596d59c0c6ef65a71153e153ff9fbdbc374466f Mon Sep 17 00:00:00 2001 From: Taewoon Kim Date: Mon, 26 Oct 2026 21:10:42 +0900 Subject: [PATCH] Docs: graph_batch docstrings name the churn limitation Both backends' graph_batch() docstrings now carry the same short Note: graph_batch() is recommended for bulk loads, but when it is called again and again on types that also see deletes, each flush writes its edge records onto new pages and never reuses freed space, so the edge bucket grows (ArcadeData/arcadedb#10746). For that workload write the edges with SQL CREATE EDGE or Vertex.new_edge inside db.transaction(). The Note points to the bulk-loads docs page (section "Known limitation: graph batches next to deletes", PR #97). Docstrings only, no behaviour change. Co-Authored-By: Claude Sonnet 5.5 --- src/arcadedb/_native/database.py | 10 ++++++++++ src/arcadedb/core.py | 10 ++++++++++ 2 files changed, 20 insertions(+) diff --git a/src/arcadedb/_native/database.py b/src/arcadedb/_native/database.py index 5463d08b..fe648ff9 100644 --- a/src/arcadedb/_native/database.py +++ b/src/arcadedb/_native/database.py @@ -889,6 +889,16 @@ def graph_batch(self, **options): """A GraphBatch for bulk graph loads (keywords as :meth:`Database.graph_batch`). ``commit_every`` defaults to 1000 on this build (the JVM build leaves it unset: one commit per flush); ``commit_every=0`` gives one commit per flush here too, and an explicit value wins. It is also the number of rows ``create_vertices`` sends, and commits, per call into the image. + + Note: + ``graph_batch()`` is recommended for bulk loads. When it is called again and + again on types that also see deletes (a sliding window, for example), each + flush writes its edge records onto new pages and never reuses the space + that deletes freed, so the edge bucket grows (ArcadeData/arcadedb#10746). + For that workload write the edges with SQL ``CREATE EDGE``, or + ``Vertex.new_edge`` inside ``db.transaction()``. See "Known limitation: + graph batches next to deletes" in + docs/modules/ROOT/pages/how-to/bulk-loads.adoc. """ from .extras import NativeGraphBatch diff --git a/src/arcadedb/core.py b/src/arcadedb/core.py index b828ea6d..1f44cb7f 100644 --- a/src/arcadedb/core.py +++ b/src/arcadedb/core.py @@ -2004,6 +2004,16 @@ def graph_batch( flush through the same executor and is measured exact, 20,000 vertices and 40,000 edges with and without ``parallel_flush``. + Note: + ``graph_batch()`` is recommended for bulk loads. When it is called again and + again on types that also see deletes (a sliding window, for example), each + flush writes its edge records onto new pages and never reuses the space + that deletes freed, so the edge bucket grows (ArcadeData/arcadedb#10746). + For that workload write the edges with SQL ``CREATE EDGE``, or + ``Vertex.new_edge`` inside ``db.transaction()``. See "Known limitation: + graph batches next to deletes" in + docs/modules/ROOT/pages/how-to/bulk-loads.adoc. + Args: batch_size: Maximum buffered edges before auto-flush. expected_edge_count: Hint for auto-tuning batch size when not set.