Chunk deletion

Backend-specific chunk-deletion strategies for the regulation graph indexer.

BaseChunkSubgraphDeleter

Bases: ABC

Deletes a chunk and its exclusively-owned subgraph from one backend.

Implementations encapsulate the backend-specific queries that enforce the regulation indexer's ownership rule: content a chunk exclusively owns is removed, while content shared with other chunks is preserved.

check_chunk_exists(chunk_id, index_name) abstractmethod

Return True if a chunk node for chunk_id exists in this index.

Performs a read-only lookup; does not modify the graph.

Parameters:

Name	Type	Description	Default
chunk_id	str	Raw (un-namespaced) chunk identifier.	required
index_name	str	Namespace to scope the lookup.	required

Returns:

Name	Type	Description
bool	bool	True when at least one chunk node matches; False otherwise.

Raises:

Type	Description
NotImplementedError	Always raised by the base implementation.

delete_chunk_subgraph(chunk_id, index_name) abstractmethod

Delete the subgraph owned exclusively by chunk_id.

Parameters:

Name	Type	Description	Default
chunk_id	str	Identifier of the chunk to delete.	required
index_name	str	Namespace scoping the deletion to one pipeline.	required

Returns:

Type	Description
tuple[int, int, int]	tuple[int, int, int]: nodes_deleted, edges_deleted, and chunks_deleted — the counts of deleted graph elements. chunks_deleted is the number of Chunk nodes removed (0 when the chunk did not exist), letting callers distinguish a real deletion from a no-op on a missing chunk.

Raises:

Type	Description
NotImplementedError	Always raised by the base implementation.

delete_chunks_subgraph(chunk_ids, index_name) abstractmethod

Delete the subgraphs owned exclusively by each chunk in chunk_ids.

Equivalent to calling delete_chunk_subgraph once per chunk id and summing the results, but implemented as a batched operation where the backend supports it, trading many round-trips for a few.

Parameters:

Name	Type	Description	Default
chunk_ids	list[str]	Identifiers of the chunks to delete. An empty list is a no-op.	required
index_name	str	Namespace scoping the deletion to one pipeline.	required

Returns:

Type	Description
tuple[int, int, int]	tuple[int, int, int]: Total nodes_deleted, edges_deleted, and chunks_deleted across every chunk in chunk_ids.

Raises:

Type	Description
NotImplementedError	Always raised by the base implementation.

Neo4jChunkSubgraphDeleter(capability)

Bases: BaseChunkSubgraphDeleter

Neo4j implementation of BaseChunkSubgraphDeleter.

Borrows (does not own) a Neo4jGraphCapability and issues Cypher through its read-write query path. Holding the capability rather than subclassing it keeps the deletion strategy decoupled from how the capability is constructed (Neo4jDataStore.with_graph()).

Attributes:

Name	Type	Description
capability	Neo4jGraphCapability	Capability used to execute Cypher.

Initialize the deleter.

Parameters:

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

check_chunk_exists(chunk_id, index_name)

Return true if a chunk node for chunk_id exists in this index.

Performs a read-only Cypher lookup. Matches both namespaced IDs (indexed after the namespacing change) and raw IDs (indexed before it) for backwards compatibility.

Parameters:

Name	Type	Description	Default
chunk_id	str	Raw (un-namespaced) chunk identifier.	required
index_name	str	Namespace to scope the lookup.	required

Returns:

Name	Type	Description
bool	bool	True when at least one chunk node matches; False otherwise.

delete_chunk_subgraph(chunk_id, index_name)

Delete all nodes and edges owned by chunk_id in a single Cypher query.

Runs three operations atomically in one round-trip:

1. Delete content nodes exclusively MENTIONS-ed by this chunk (shared nodes are preserved). Ownership is scoped to index_name to avoid cross-index interference.
2. Delete edges whose chunk_id property matches. By design only reference edges (CITES, MENTIONS_CONCEPT, CONTAINS_OBLIGATION) carry chunk_id (see OWNED_RELATION_TYPES in id_regulation_constants), so this step removes exactly the chunk's reference edges whose endpoints may outlive it. Containment edges (HAS_*, AMENDS, IMPLEMENTS, MENTIONS) carry no chunk_id and are left to DETACH DELETE of their endpoint node — this avoids over-deleting containment edges still shared by other chunks.
3. Delete the Chunk node itself (DETACH DELETE removes remaining MENTIONS edges).

Backwards-compatibility note: nodes indexed before the index_name-namespacing change store the raw chunk_id as their id (e.g. "file:reg:0"); nodes indexed after store the namespaced form ("{index_name}:file:reg:0"). Both forms are matched so that a delete call with the raw chunk_id cleans up pre-existing un-namespaced data without leaving stale nodes behind.

Parameters:

Name	Type	Description	Default
chunk_id	str	Raw (un-namespaced) identifier of the chunk to delete.	required
index_name	str	Namespace scoping the deletion to one pipeline.	required

Returns:

Type	Description
tuple[int, int, int]	tuple[int, int, int]: nodes_deleted, edges_deleted, and chunks_deleted — the counts of deleted graph elements. chunks_deleted is the number of Chunk nodes removed (0 when no chunk matched chunk_id/index_name), which callers use to tell a real deletion apart from a no-op on a missing chunk.

delete_chunks_subgraph(chunk_ids, index_name)

Delete all nodes and edges owned by every chunk in chunk_ids in batched Cypher queries.

Same three-part deletion as delete_chunk_subgraph (exclusive MENTIONS nodes, chunk_id-tagged edges, the Chunk node itself), but matched against the whole batch's chunk ids as sets instead of one query per chunk. A node is exclusive (and thus deleted) when no chunk outside the batch still mentions it, so a node mentioned only by chunks that are all being re-indexed together is correctly dropped even though multiple batch members reference it. chunk_ids is split into _BATCH_SIZE-sized slices, each issued as one query, so a very large batch does not build one oversized transaction.

Parameters:

Name	Type	Description	Default
chunk_ids	list[str]	Raw (un-namespaced) identifiers of the chunks to delete. An empty list is a no-op that issues no query.	required
index_name	str	Namespace scoping the deletion to one pipeline.	required

Returns:

Type	Description
tuple[int, int, int]	tuple[int, int, int]: Total nodes_deleted, edges_deleted, and chunks_deleted across every chunk in chunk_ids.

get_chunk_deleter(capability)

Get a chunk deleter strategy for a given graph capability.

Parameters:

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

Returns:

Name	Type	Description
BaseChunkSubgraphDeleter	BaseChunkSubgraphDeleter	A deletion strategy bound to capability.

Raises:

Type	Description
TypeError	If no deletion strategy is registered for the capability's backend.