rag.indexing.hierarchical

Hierarchical index for parent-child chunk retrieval.

Hierarchical index for parent-child chunk retrieval.

class HierarchicalIndex(include_parent_context=True)

Bases: object

Index for hierarchical chunk storage and retrieval.

Stores both parent and child chunks, enabling: - Fine-grained search on child chunks - Parent context retrieval for matched children

Parameters:

include_parent_context (bool) – Whether to include parent content in results.

add_chunk(chunk_id, content, embedding=None, parent_id=None, hierarchy_level=0, metadata=None)

Add a chunk to the hierarchical index.

Parameters:

• chunk_id (str) – Unique chunk identifier.

• content (str) – Chunk text content.

• embedding (list[float] | None) – Chunk embedding vector (optional).

• parent_id (str | None) – Parent chunk ID (None for root/parent chunks).

• hierarchy_level (int) – Level in hierarchy (0=parent, 1+=children).

• metadata (dict[str, Any] | None) – Optional metadata dictionary.

Return type:

None

get_chunk(chunk_id)

Get a chunk by ID.

Parameters:

chunk_id (str) – Chunk identifier.

Returns:

Chunk data dictionary or None if not found.

Return type:

dict[str, Any] | None

get_parent(chunk_id)

Get the parent of a chunk.

Parameters:

chunk_id (str) – Child chunk identifier.

Returns:

Parent chunk data or None if not found or no parent.

Return type:

dict[str, Any] | None

get_children(parent_id)

Get all children of a parent chunk.

Parameters:

parent_id (str) – Parent chunk identifier.

Returns:

List of child chunk data dictionaries.

Return type:

list[dict[str, Any]]

get_parent_chunks()

Get all parent chunks (level 0).

Returns:

List of parent chunk data dictionaries.

Return type:

list[dict[str, Any]]

get_child_chunks()

Get all child chunks (level > 0).

Returns:

List of child chunk data dictionaries.

Return type:

list[dict[str, Any]]

get_child_embeddings()

Get IDs and embeddings for all child chunks.

Returns:

Tuple of (chunk_ids, embeddings).

Return type:

tuple[list[str], list[list[float]]]

enhance_results_with_context(results, include_parent=None)

Enhance search results with parent context.

Parameters:

• results (list[dict[str, Any]]) – Search results with chunk IDs.

• include_parent (bool | None) – Override default include_parent_context.

Returns:

Enhanced results with parent content added.

Return type:

list[dict[str, Any]]

delete_chunk(chunk_id)

Delete a chunk and update relationships.

Parameters:

chunk_id (str) – Chunk identifier to delete.

Returns:

True if deleted, False if not found.

Return type:

bool

delete_by_reference(reference_name)

Delete all chunks for a document reference.

Parameters:

reference_name (str) – Document reference name in metadata.

Returns:

Number of chunks deleted.

Return type:

int

clear()

Clear all chunks from the index.

Return type:

None

count()

Get total number of chunks.

Return type:

int

count_parents()

Get number of parent chunks.

Return type:

int

count_children()

Get number of child chunks.

Return type:

int

get_stats()

Get index statistics.

Return type:

dict[str, Any]

Classes

class HierarchicalIndex(include_parent_context=True)

Bases: object

Index for hierarchical chunk storage and retrieval.

Stores both parent and child chunks, enabling: - Fine-grained search on child chunks - Parent context retrieval for matched children

Parameters:

include_parent_context (bool) – Whether to include parent content in results.

add_chunk(chunk_id, content, embedding=None, parent_id=None, hierarchy_level=0, metadata=None)

Add a chunk to the hierarchical index.

Parameters:

• chunk_id (str) – Unique chunk identifier.

• content (str) – Chunk text content.

• embedding (list[float] | None) – Chunk embedding vector (optional).

• parent_id (str | None) – Parent chunk ID (None for root/parent chunks).

• hierarchy_level (int) – Level in hierarchy (0=parent, 1+=children).

• metadata (dict[str, Any] | None) – Optional metadata dictionary.

Return type:

None

get_chunk(chunk_id)

Get a chunk by ID.

Parameters:

chunk_id (str) – Chunk identifier.

Returns:

Chunk data dictionary or None if not found.

Return type:

dict[str, Any] | None

get_parent(chunk_id)

Get the parent of a chunk.

Parameters:

chunk_id (str) – Child chunk identifier.

Returns:

Parent chunk data or None if not found or no parent.

Return type:

dict[str, Any] | None

get_children(parent_id)

Get all children of a parent chunk.

Parameters:

parent_id (str) – Parent chunk identifier.

Returns:

List of child chunk data dictionaries.

Return type:

list[dict[str, Any]]

get_parent_chunks()

Get all parent chunks (level 0).

Returns:

List of parent chunk data dictionaries.

Return type:

list[dict[str, Any]]

get_child_chunks()

Get all child chunks (level > 0).

Returns:

List of child chunk data dictionaries.

Return type:

list[dict[str, Any]]

get_child_embeddings()

Get IDs and embeddings for all child chunks.

Returns:

Tuple of (chunk_ids, embeddings).

Return type:

tuple[list[str], list[list[float]]]

enhance_results_with_context(results, include_parent=None)

Enhance search results with parent context.

Parameters:

• results (list[dict[str, Any]]) – Search results with chunk IDs.

• include_parent (bool | None) – Override default include_parent_context.

Returns:

Enhanced results with parent content added.

Return type:

list[dict[str, Any]]

delete_chunk(chunk_id)

Delete a chunk and update relationships.

Parameters:

chunk_id (str) – Chunk identifier to delete.

Returns:

True if deleted, False if not found.

Return type:

bool

delete_by_reference(reference_name)

Delete all chunks for a document reference.

Parameters:

reference_name (str) – Document reference name in metadata.

Returns:

Number of chunks deleted.

Return type:

int

clear()

Clear all chunks from the index.

Return type:

None

count()

Get total number of chunks.

Return type:

int

count_parents()

Get number of parent chunks.

Return type:

int

count_children()

Get number of child chunks.

Return type:

int

get_stats()

Get index statistics.

Return type:

dict[str, Any]