Chunk retrieval

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

BaseChunkReader

Bases: ABC

Reads a chunk's retrievable payload back from one graph backend.

Implementations encapsulate the backend-specific queries that read the Element-shaped payload (text/structure/metadata) a writer previously stamped onto a chunk's Chunk node, restoring the GraphIndexer.get_chunk / get_file_chunks contract on top of a graph backend.

get_chunk(chunk_id, index_name) abstractmethod

Get a single chunk's retrievable payload by chunk id.

Parameters:

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

Returns:

Type	Description
dict[str, Any] | None	dict[str, Any] | None: The chunk's Element-shaped payload (text, structure, metadata), or None if not found.

Raises:

Type	Description
NotImplementedError	Always raised by the base implementation.

get_file_chunks(file_id, index_name, page, size) abstractmethod

Get a page of a file's chunks, ordered by their position within the file.

Parameters:

Name	Type	Description	Default
file_id	str	The file identifier chunks were indexed under.	required
index_name	str	Namespace scoping the lookup.	required
page	int	The page number (0-indexed).	required
size	int	The number of chunks per page.	required

Returns:

Type	Description
dict[str, Any]	dict[str, Any]: Response with chunks (list of Element-shaped payloads) and pagination metadata.

Raises:

Type	Description
NotImplementedError	Always raised by the base implementation.

Neo4jChunkReader(capability, use_namespaced_id=True)

Bases: BaseChunkReader

Neo4j implementation of BaseChunkReader.

Holds (rather than subclasses) a Neo4jGraphCapability and issues Cypher through its read-only retrieve path.

Attributes:

Name	Type	Description
capability	Neo4jGraphCapability	Capability used to execute Cypher.
use_namespaced_id	bool	Whether get_chunk also matches the namespaced ({index_name}:{chunk_id}) form of c.id.

Initialize the reader.

Parameters:

Name	Type	Description	Default
capability	Neo4jGraphCapability	Neo4j capability used to run Cypher.	required
use_namespaced_id	bool	Whether get_chunk should also match the namespaced ({index_name}:{chunk_id}) form of c.id, for backwards compatibility with legacy un-namespaced chunks. Set to False for an index known to hold only un-namespaced chunks, so the lookup matches on the raw chunk_id alone. Defaults to True.	True

get_chunk(chunk_id, index_name)

Get a single chunk's retrievable payload by chunk id.

Matches the namespaced ({index_name}:{chunk_id}) form of c.id alongside the raw form when use_namespaced_id is True (the default), for backwards compatibility with legacy un-namespaced chunks. Excludes nodes with no element_json (indexed before this feature shipped).

Parameters:

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

Returns:

Type	Description
dict[str, Any] | None	dict[str, Any] | None: The chunk's Element-shaped payload (text, structure, metadata), or None if not found.

get_file_chunks(file_id, index_name, page, size)

Get a page of a file's chunks, ordered by their position within the file.

Excludes Chunk nodes with no element_json (indexed before this feature shipped) from both the count and the page.

Parameters:

Name	Type	Description	Default
file_id	str	The file identifier chunks were indexed under.	required
index_name	str	Namespace scoping the lookup.	required
page	int	The page number (0-indexed).	required
size	int	The number of chunks per page.	required

Returns:

Type	Description
dict[str, Any]	dict[str, Any]: Response with chunks (list of Element-shaped payloads) and pagination metadata (page, size, total_chunks, total_pages, has_next, has_previous).

get_chunk_reader(capability, use_namespaced_id=True)

Get a chunk retrieval strategy for a given graph capability.

Parameters:

Name	Type	Description	Default
capability	BaseGraphCapability	The indexer's graph capability.	required
use_namespaced_id	bool	Forwarded to the resolved strategy; see Neo4jChunkReader.__init__ for its effect. Defaults to True.	True

Returns:

Name	Type	Description
BaseChunkReader	BaseChunkReader	A retrieval strategy bound to capability.

Raises:

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