Chunk write

Backend-specific subgraph-write strategies for the regulation graph indexer.

BaseChunkSubgraphWriter

Bases: ABC

Upserts a batch of regulation nodes and edges into one backend.

Implementations encapsulate the backend-specific writes that persist the pre-generated, already-deduplicated nodes and edges of a document's chunks. A single upsert_subgraph call owns the two-pass ordering — every node is written before any edge — so cross-chunk relationship endpoints exist by the time relationships are written; an edge whose endpoints are absent is silently skipped.

upsert_subgraph(nodes, edges) abstractmethod

Upsert nodes and then edges into the backend.

All nodes are upserted before any edge so cross-chunk relationship endpoints exist when relationships are written; an edge whose endpoints do not exist is silently skipped. Each node's and edge's metadata already carries the indexer's index_name namespace property.

Parameters:

Name	Type	Description	Default
nodes	list[Node]	Nodes to upsert; id is the identity key.	required
edges	list[Edge]	Edges to upsert; both endpoints are matched by id.	required

Returns:

Type	Description
tuple[int, int]	tuple[int, int]: (nodes_written, edges_written) — the counts submitted.

Raises:

Type	Description
NotImplementedError	Always raised by the base implementation.

GenericChunkSubgraphWriter(capability)

Bases: BaseChunkSubgraphWriter

Portable writer that upserts one node/edge per capability call.

Works with any BaseGraphCapability by issuing a single upsert_node / upsert_relationship per element. It performs no batching, so it carries the per-item round-trip cost; it exists so backends without a batched strategy keep working unchanged. The batched Neo4j fast path lives in Neo4jChunkSubgraphWriter.

Attributes:

Name	Type	Description
capability	BaseGraphCapability	Capability used to upsert nodes and edges.

Initialize the writer.

Parameters:

Name	Type	Description	Default
capability	BaseGraphCapability	Graph capability used for upserts.	required

upsert_subgraph(nodes, edges)

Upsert every node, then every edge, one capability call per element.

Nodes are written before edges so cross-chunk relationship endpoints exist when edges are written.

Parameters:

Name	Type	Description	Default
nodes	list[Node]	Nodes to upsert.	required
edges	list[Edge]	Edges to upsert.	required

Returns:

Type	Description
tuple[int, int]	tuple[int, int]: (nodes_written, edges_written) — the counts submitted.

Neo4jChunkSubgraphWriter(capability)

Bases: BaseChunkSubgraphWriter

Neo4j writer that upserts nodes and edges in batched UNWIND queries.

Borrows (does not own) a Neo4jGraphCapability and issues Cypher through its read-write query path. Instead of one transaction per node/edge, nodes are grouped by label and edges by relationship type — neither of which can be parameterised in Cypher — and each group is written with a single UNWIND $rows AS row MERGE ... statement, collapsing thousands of per-item commits into a handful of batched ones. Each statement is further split into transactions of at most _BATCH_SIZE rows.

Attributes:

Name	Type	Description
capability	Neo4jGraphCapability	Capability used to execute Cypher.

Initialize the writer.

Parameters:

Name	Type	Description	Default
capability	Neo4jGraphCapability	Neo4j capability used to run Cypher.	required

upsert_subgraph(nodes, edges)

Upsert all nodes (grouped by label) before all edges (grouped by type).

Writing every node before any edge ensures cross-chunk relationship endpoints exist by the time edges are matched; an edge whose endpoints are absent matches nothing and is silently skipped.

Parameters:

Name	Type	Description	Default
nodes	list[Node]	Nodes to upsert; id is the MERGE key.	required
edges	list[Edge]	Edges to upsert; endpoints are matched by id.	required

Returns:

Type	Description
tuple[int, int]	tuple[int, int]: (nodes_written, edges_written) — the counts submitted.

get_chunk_writer(capability)

Get a subgraph-write strategy for a given graph capability.

Neo4j gets the batched UNWIND writer; every other backend falls back to the portable per-item writer so the indexer's write path stays backend-agnostic (unlike chunk deletion, which is Neo4j-only).

Parameters:

Name	Type	Description	Default
capability	BaseGraphCapability	The indexer's graph capability.	required

Returns:

Name	Type	Description
BaseChunkSubgraphWriter	BaseChunkSubgraphWriter	A write strategy bound to capability — a Neo4jChunkSubgraphWriter for Neo4j, otherwise a GenericChunkSubgraphWriter.