From d455557f2d4f5cf3850dfa2d16cb23bc9bfb2f81 Mon Sep 17 00:00:00 2001 From: Elior Nataf Lackritz Date: Tue, 29 Sep 2026 09:22:21 -0400 Subject: [PATCH] docs(checkpoint-postgres): point stale delta query comments at the builders The module comment still described one column pair per channel, no subqueries and a stage 2 on channel = ANY(%s), and the row-shape comment named hs_i keys that no longer exist. Point both at the builder docstrings instead of keeping a second description of each query. --- .../langgraph/checkpoint/postgres/base.py | 32 +++---------------- 1 file changed, 4 insertions(+), 28 deletions(-) diff --git a/libs/checkpoint-postgres/langgraph/checkpoint/postgres/base.py b/libs/checkpoint-postgres/langgraph/checkpoint/postgres/base.py index 00019c5a9..6cf8aa63a 100644 --- a/libs/checkpoint-postgres/langgraph/checkpoint/postgres/base.py +++ b/libs/checkpoint-postgres/langgraph/checkpoint/postgres/base.py @@ -172,30 +172,8 @@ class _DeltaStage2Row(TypedDict, total=False): version: str | None # "b" rows only -# Multi-channel two-stage DeltaChannel reconstruction. -# -# Stage 1 scans checkpoint metadata (no blob bytes) and emits one row per -# checkpoint with K parallel JSONB key lookups (one column pair per -# requested delta channel: ver_i / hs_i). No subqueries, no aggregation. -# Python walks the parent chain once across all channels. -# -# Stage 2 fetches all writes and the seed blobs for ALL channels in a -# single roundtrip via `channel = ANY(%s)` and chain/seed-version -# filtering. -# -# Empirical comparison vs an alternative "ship full channel_versions / -# channel_values JSONB and let Python pick" form (1000 checkpoints, -# 8 total channels in graph, 3 delta channels requested): -# -# Postgres execution: A=0.24ms vs B=0.38ms (both negligible) -# End-to-end latency: A=6.83ms vs B=2.28ms (B is 3.0x faster) -# Wire payload: A=836KB vs B=330KB (61% smaller) -# Buffer hits: identical (167 blocks) -# -# B (this dynamic-columns design) wins because it avoids JSONB -# serialization on the wire and JSONB-to-dict deserialization in -# psycopg. Even at K=8 (8 delta channels = 16 dynamic columns), B -# still beats A end-to-end (4.2ms vs 6.8ms). +# Delta history is rebuilt in two queries; `_build_delta_stage1_sql` and +# `_build_delta_stage2_sql` document their shapes. def _build_delta_stage1_sql(channels: Sequence[str], *, paged: bool) -> str: @@ -335,10 +313,8 @@ def _build_delta_stage2_sql( return " UNION ALL ".join(branches) -# Stage 1 rows are dynamic-shape dicts: {checkpoint_id, parent_checkpoint_id, -# ver_0, hs_0, ver_1, hs_1, ...}. Walking is parameterized by the channel -# list to map indices back to channel names — no static TypedDict here. -# `dict[str, Any]` is the practical signature. +# Stage 1 rows are dicts keyed by the per-channel aliases +# `_build_delta_stage1_sql` emits, so there is no static TypedDict. class BasePostgresSaver(BaseCheckpointSaver[str]):