Skip to content

Commit b9b5d6e

Browse files
lmeyerovclaude
andcommitted
docs(gfql): memory note for call_mode auto bridge (G5 decision)
Document why there is no per-call size cap on the off-engine bridge: the transient copy is the same allocation as running the analytic on engine='cudf' directly, a row count is a poor memory proxy, and the real cap belongs at the RMM/container/deployment layer. Point memory-conscious users at call_mode='strict' or RMM/container limits. (G5 decision: reject a row-cap knob as the wrong mechanism — see plan PHASE 13.) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
1 parent 5368486 commit b9b5d6e

1 file changed

Lines changed: 11 additions & 0 deletions

File tree

docs/source/gfql/engines.rst

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -375,6 +375,17 @@ always will). Under ``engine='polars'`` / ``'polars-gpu'`` GFQL runs them as a
375375
bridging — for benchmark integrity (no hidden modality switch attributed to the
376376
Polars engine) or a hard memory ceiling.
377377

378+
.. note::
379+
**Memory on a very large graph.** The bridge materializes a copy of the graph in
380+
the off-engine format — pandas (host) for ``polars``, cuDF (device / unified
381+
memory) for ``polars-gpu``. That transient copy is the *same* allocation you'd
382+
incur running the analytic on ``engine='cudf'`` directly, so GFQL does **not** add
383+
a per-call size cap (a row count is a poor memory proxy, and the real cap belongs
384+
at the RMM / container / deployment layer). For a graph large enough that the copy
385+
is a concern, either set ``call_mode='strict'`` (decline the bridge) or run the
386+
analytic under an RMM device-memory limit / container memory limit, exactly as you
387+
would for any cuDF workload.
388+
378389
This is **deliberately narrower** than traversal / filter / row ops (``hop``,
379390
``WHERE``, ``RETURN`` …), which stay **parity-or-``NotImplementedError``** and are
380391
never bridged — a bridge there would hide a missing native impl and misreport

0 commit comments

Comments
 (0)