Search - Graphiti

Overview

The search module provides powerful hybrid search capabilities for querying knowledge graphs. It supports multiple search methods (vector similarity, BM25 full-text search, breadth-first search) and various reranking strategies.

SearchConfig

The SearchConfig class defines search behavior across different graph layers (edges, nodes, episodes, communities).

class SearchConfig(BaseModel):
    edge_config: EdgeSearchConfig | None = None
    node_config: NodeSearchConfig | None = None
    episode_config: EpisodeSearchConfig | None = None
    community_config: CommunitySearchConfig | None = None
    limit: int = 10
    reranker_min_score: float = 0

edge_config

EdgeSearchConfig | None

Configuration for searching edges.

node_config

NodeSearchConfig | None

Configuration for searching nodes.

episode_config

EpisodeSearchConfig | None

Configuration for searching episodes.

community_config

CommunitySearchConfig | None

Configuration for searching communities.

limit

int

default:"10"

Maximum number of results to return.

reranker_min_score

float

default:"0"

Minimum score threshold for reranked results.

EdgeSearchConfig

Configuration for edge search operations.

class EdgeSearchConfig(BaseModel):
    search_methods: list[EdgeSearchMethod]
    reranker: EdgeReranker = EdgeReranker.rrf
    sim_min_score: float = DEFAULT_MIN_SCORE
    mmr_lambda: float = DEFAULT_MMR_LAMBDA
    bfs_max_depth: int = MAX_SEARCH_DEPTH

search_methods

list[EdgeSearchMethod]

required

List of search methods to use. Options: EdgeSearchMethod.cosine_similarity, EdgeSearchMethod.bm25, EdgeSearchMethod.bfs.

reranker

EdgeReranker

default:"EdgeReranker.rrf"

Reranking strategy. Options: rrf (reciprocal rank fusion), node_distance, episode_mentions, mmr (maximal marginal relevance), cross_encoder.

sim_min_score

float

Minimum similarity score for vector search results.

mmr_lambda

float

Lambda parameter for MMR reranking (diversity vs relevance tradeoff).

bfs_max_depth

int

Maximum depth for breadth-first search.

NodeSearchConfig

Configuration for node search operations.

class NodeSearchConfig(BaseModel):
    search_methods: list[NodeSearchMethod]
    reranker: NodeReranker = NodeReranker.rrf
    sim_min_score: float = DEFAULT_MIN_SCORE
    mmr_lambda: float = DEFAULT_MMR_LAMBDA
    bfs_max_depth: int = MAX_SEARCH_DEPTH

search_methods

list[NodeSearchMethod]

required

List of search methods to use. Options: NodeSearchMethod.cosine_similarity, NodeSearchMethod.bm25, NodeSearchMethod.bfs.

reranker

NodeReranker

default:"NodeReranker.rrf"

Reranking strategy. Options: rrf, node_distance, episode_mentions, mmr, cross_encoder.

sim_min_score

float

Minimum similarity score for vector search results.

mmr_lambda

float

Lambda parameter for MMR reranking.

bfs_max_depth

int

Maximum depth for breadth-first search.

EpisodeSearchConfig

Configuration for episode search operations.

class EpisodeSearchConfig(BaseModel):
    search_methods: list[EpisodeSearchMethod]
    reranker: EpisodeReranker = EpisodeReranker.rrf
    sim_min_score: float = DEFAULT_MIN_SCORE
    mmr_lambda: float = DEFAULT_MMR_LAMBDA
    bfs_max_depth: int = MAX_SEARCH_DEPTH

search_methods

list[EpisodeSearchMethod]

required

List of search methods to use. Options: EpisodeSearchMethod.bm25.

reranker

EpisodeReranker

default:"EpisodeReranker.rrf"

Reranking strategy. Options: rrf, cross_encoder.

CommunitySearchConfig

Configuration for community search operations.

class CommunitySearchConfig(BaseModel):
    search_methods: list[CommunitySearchMethod]
    reranker: CommunityReranker = CommunityReranker.rrf
    sim_min_score: float = DEFAULT_MIN_SCORE
    mmr_lambda: float = DEFAULT_MMR_LAMBDA
    bfs_max_depth: int = MAX_SEARCH_DEPTH

search_methods

list[CommunitySearchMethod]

required

List of search methods to use. Options: CommunitySearchMethod.cosine_similarity, CommunitySearchMethod.bm25.

reranker

CommunityReranker

default:"CommunityReranker.rrf"

Reranking strategy. Options: rrf, mmr, cross_encoder.

SearchResults

Container for search results across different graph layers.

class SearchResults(BaseModel):
    edges: list[EntityEdge] = []
    edge_reranker_scores: list[float] = []
    nodes: list[EntityNode] = []
    node_reranker_scores: list[float] = []
    episodes: list[EpisodicNode] = []
    episode_reranker_scores: list[float] = []
    communities: list[CommunityNode] = []
    community_reranker_scores: list[float] = []

edges

list[EntityEdge]

List of relevant entity edges.

edge_reranker_scores

list[float]

Reranker scores for edges (parallel to edges list).

nodes

list[EntityNode]

List of relevant entity nodes.

node_reranker_scores

list[float]

Reranker scores for nodes (parallel to nodes list).

episodes

list[EpisodicNode]

List of relevant episodes.

episode_reranker_scores

list[float]

Reranker scores for episodes (parallel to episodes list).

communities

list[CommunityNode]

List of relevant communities.

community_reranker_scores

list[float]

Reranker scores for communities (parallel to communities list).

merge

@classmethod
def merge(cls, results_list: list[SearchResults]) -> SearchResults

Merge multiple SearchResults objects into a single SearchResults object.

results_list

list[SearchResults]

required

List of SearchResults objects to merge.

Filters to apply when searching the graph.

class SearchFilters(BaseModel):
    node_labels: list[str] | None = None
    edge_types: list[str] | None = None
    valid_at: list[list[DateFilter]] | None = None
    invalid_at: list[list[DateFilter]] | None = None
    created_at: list[list[DateFilter]] | None = None
    expired_at: list[list[DateFilter]] | None = None
    edge_uuids: list[str] | None = None
    property_filters: list[PropertyFilter] | None = None

node_labels

list[str] | None

Filter nodes by labels.

edge_types

list[str] | None

Filter edges by type names.

valid_at

list[list[DateFilter]] | None

Filter by valid_at timestamp (list of OR conditions, each containing AND conditions).

invalid_at

list[list[DateFilter]] | None

Filter by invalid_at timestamp.

created_at

list[list[DateFilter]] | None

Filter by created_at timestamp.

expired_at

list[list[DateFilter]] | None

Filter by expired_at timestamp.

edge_uuids

list[str] | None

Filter to specific edge UUIDs.

property_filters

list[PropertyFilter] | None

Filter by custom properties.

Example

from graphiti_core.search.search_filters import SearchFilters, DateFilter, ComparisonOperator
from datetime import datetime

filters = SearchFilters(
    node_labels=["Person", "Organization"],
    created_at=[
        [
            DateFilter(
                date=datetime(2024, 1, 1),
                comparison_operator=ComparisonOperator.greater_than
            )
        ]
    ]
)

results = await graphiti.search_(query="AI research", search_filter=filters)

DateFilter

Filter for date-based queries.

class DateFilter(BaseModel):
    date: datetime | None = None
    comparison_operator: ComparisonOperator

date

datetime | None

The datetime to filter on.

comparison_operator

ComparisonOperator

required

Comparison operator: equals, not_equals, greater_than, less_than, greater_than_equal, less_than_equal, is_null, is_not_null.

PropertyFilter

Filter for custom property queries.

class PropertyFilter(BaseModel):
    property_name: str
    property_value: str | int | float | None = None
    comparison_operator: ComparisonOperator

property_name

str

required

Name of the property to filter on.

property_value

str | int | float | None

Value to match on for the property.

comparison_operator

ComparisonOperator

required

Comparison operator for the property.

Search Config Recipes

Pre-configured search configurations for common use cases.

COMBINED_HYBRID_SEARCH_CROSS_ENCODER

from graphiti_core.search.search_config_recipes import COMBINED_HYBRID_SEARCH_CROSS_ENCODER

Performs a full-text search, similarity search, and BFS with cross_encoder reranking over edges, nodes, episodes, and communities. Best for high-accuracy results.

COMBINED_HYBRID_SEARCH_RRF

from graphiti_core.search.search_config_recipes import COMBINED_HYBRID_SEARCH_RRF

Performs a hybrid search with RRF (reciprocal rank fusion) reranking over all graph layers. Good balance of speed and accuracy.

COMBINED_HYBRID_SEARCH_MMR

from graphiti_core.search.search_config_recipes import COMBINED_HYBRID_SEARCH_MMR

Performs a hybrid search with MMR (maximal marginal relevance) reranking for diverse results.

EDGE_HYBRID_SEARCH_RRF

from graphiti_core.search.search_config_recipes import EDGE_HYBRID_SEARCH_RRF

Performs a hybrid search over edges only with RRF reranking.

EDGE_HYBRID_SEARCH_MMR

from graphiti_core.search.search_config_recipes import EDGE_HYBRID_SEARCH_MMR

Performs a hybrid search over edges with MMR reranking for diverse edge results.

EDGE_HYBRID_SEARCH_NODE_DISTANCE

from graphiti_core.search.search_config_recipes import EDGE_HYBRID_SEARCH_NODE_DISTANCE

Performs a hybrid search over edges with node distance reranking. Requires center_node_uuid parameter.

EDGE_HYBRID_SEARCH_EPISODE_MENTIONS

from graphiti_core.search.search_config_recipes import EDGE_HYBRID_SEARCH_EPISODE_MENTIONS

Performs a hybrid search over edges with reranking by episode mention count.

EDGE_HYBRID_SEARCH_CROSS_ENCODER

from graphiti_core.search.search_config_recipes import EDGE_HYBRID_SEARCH_CROSS_ENCODER

Performs a hybrid search over edges with cross encoder reranking for highest accuracy.

NODE_HYBRID_SEARCH_RRF

from graphiti_core.search.search_config_recipes import NODE_HYBRID_SEARCH_RRF

Performs a hybrid search over nodes with RRF reranking.

NODE_HYBRID_SEARCH_MMR

from graphiti_core.search.search_config_recipes import NODE_HYBRID_SEARCH_MMR

Performs a hybrid search over nodes with MMR reranking.

NODE_HYBRID_SEARCH_NODE_DISTANCE

from graphiti_core.search.search_config_recipes import NODE_HYBRID_SEARCH_NODE_DISTANCE

Performs a hybrid search over nodes with node distance reranking.

NODE_HYBRID_SEARCH_EPISODE_MENTIONS

from graphiti_core.search.search_config_recipes import NODE_HYBRID_SEARCH_EPISODE_MENTIONS

Performs a hybrid search over nodes with episode mention count reranking.

NODE_HYBRID_SEARCH_CROSS_ENCODER

from graphiti_core.search.search_config_recipes import NODE_HYBRID_SEARCH_CROSS_ENCODER

Performs a hybrid search over nodes with cross encoder reranking.

COMMUNITY_HYBRID_SEARCH_RRF

from graphiti_core.search.search_config_recipes import COMMUNITY_HYBRID_SEARCH_RRF

Performs a hybrid search over communities with RRF reranking.

COMMUNITY_HYBRID_SEARCH_MMR

from graphiti_core.search.search_config_recipes import COMMUNITY_HYBRID_SEARCH_MMR

Performs a hybrid search over communities with MMR reranking.

COMMUNITY_HYBRID_SEARCH_CROSS_ENCODER

from graphiti_core.search.search_config_recipes import COMMUNITY_HYBRID_SEARCH_CROSS_ENCODER

Performs a hybrid search over communities with cross encoder reranking.

Examples

Basic Search

from graphiti_core import Graphiti

graphiti = Graphiti(uri="bolt://localhost:7687", user="neo4j", password="password")

# Simple search
edges = await graphiti.search(
    query="What are the user's interests?",
    group_ids=["user_123"],
    num_results=10
)

for edge in edges:
    print(f"Fact: {edge.fact}")

Advanced Search with Custom Config

from graphiti_core.search.search_config import (
    SearchConfig,
    EdgeSearchConfig,
    EdgeSearchMethod,
    EdgeReranker,
    NodeSearchConfig,
    NodeSearchMethod,
    NodeReranker
)

# Create custom search config
config = SearchConfig(
    edge_config=EdgeSearchConfig(
        search_methods=[EdgeSearchMethod.bm25, EdgeSearchMethod.cosine_similarity],
        reranker=EdgeReranker.cross_encoder
    ),
    node_config=NodeSearchConfig(
        search_methods=[NodeSearchMethod.cosine_similarity],
        reranker=NodeReranker.rrf
    ),
    limit=20
)

results = await graphiti.search_(
    query="AI research projects",
    config=config,
    group_ids=["user_123"]
)

print(f"Found {len(results.edges)} edges and {len(results.nodes)} nodes")

Search with Filters

from graphiti_core.search.search_filters import (
    SearchFilters,
    DateFilter,
    ComparisonOperator,
    PropertyFilter
)
from datetime import datetime, timedelta

# Filter for recent data
recent_date = datetime.now() - timedelta(days=30)

filters = SearchFilters(
    node_labels=["Person", "Organization"],
    edge_types=["WORKS_AT", "COLLABORATES_WITH"],
    created_at=[
        [
            DateFilter(
                date=recent_date,
                comparison_operator=ComparisonOperator.greater_than
            )
        ]
    ],
    property_filters=[
        PropertyFilter(
            property_name="status",
            property_value="active",
            comparison_operator=ComparisonOperator.equals
        )
    ]
)

results = await graphiti.search_(
    query="active collaborations",
    search_filter=filters,
    group_ids=["user_123"]
)

Node Distance Reranking

from graphiti_core.search.search_config_recipes import EDGE_HYBRID_SEARCH_NODE_DISTANCE

# Search with results reranked by proximity to a center node
edges = await graphiti.search(
    query="related information",
    center_node_uuid="node-uuid-123",
    group_ids=["user_123"],
    num_results=10
)

# Or with advanced search
results = await graphiti.search_(
    query="related information",
    config=EDGE_HYBRID_SEARCH_NODE_DISTANCE,
    center_node_uuid="node-uuid-123",
    group_ids=["user_123"]
)

Breadth-First Search

from graphiti_core.search.search_config import (
    SearchConfig,
    EdgeSearchConfig,
    EdgeSearchMethod,
    EdgeReranker
)

config = SearchConfig(
    edge_config=EdgeSearchConfig(
        search_methods=[EdgeSearchMethod.bfs],
        reranker=EdgeReranker.rrf,
        bfs_max_depth=3
    )
)

results = await graphiti.search_(
    query="expand from these nodes",
    config=config,
    bfs_origin_node_uuids=["node-1", "node-2"],
    group_ids=["user_123"]
)

Core

Data Models

Drivers

LLM Clients

Embedders

​Overview

​SearchConfig

​EdgeSearchConfig

​NodeSearchConfig

​EpisodeSearchConfig

​CommunitySearchConfig

​SearchResults

​merge

​SearchFilters

​Example

​DateFilter

​PropertyFilter

​Search Config Recipes

​COMBINED_HYBRID_SEARCH_CROSS_ENCODER

​COMBINED_HYBRID_SEARCH_RRF

​COMBINED_HYBRID_SEARCH_MMR

​EDGE_HYBRID_SEARCH_RRF

​EDGE_HYBRID_SEARCH_MMR

​EDGE_HYBRID_SEARCH_NODE_DISTANCE

​EDGE_HYBRID_SEARCH_EPISODE_MENTIONS

​EDGE_HYBRID_SEARCH_CROSS_ENCODER

​NODE_HYBRID_SEARCH_RRF

​NODE_HYBRID_SEARCH_MMR

​NODE_HYBRID_SEARCH_NODE_DISTANCE

​NODE_HYBRID_SEARCH_EPISODE_MENTIONS

​NODE_HYBRID_SEARCH_CROSS_ENCODER

​COMMUNITY_HYBRID_SEARCH_RRF

​COMMUNITY_HYBRID_SEARCH_MMR

​COMMUNITY_HYBRID_SEARCH_CROSS_ENCODER

​Examples

​Basic Search

​Advanced Search with Custom Config

​Search with Filters

​Node Distance Reranking

​Breadth-First Search

Build docs developers (and LLMs) love

Overview

SearchConfig

EdgeSearchConfig

NodeSearchConfig

EpisodeSearchConfig

CommunitySearchConfig

SearchResults

merge

SearchFilters

Example

DateFilter

PropertyFilter

Search Config Recipes

COMBINED_HYBRID_SEARCH_CROSS_ENCODER

COMBINED_HYBRID_SEARCH_RRF

COMBINED_HYBRID_SEARCH_MMR

EDGE_HYBRID_SEARCH_RRF

EDGE_HYBRID_SEARCH_MMR

EDGE_HYBRID_SEARCH_NODE_DISTANCE

EDGE_HYBRID_SEARCH_EPISODE_MENTIONS

EDGE_HYBRID_SEARCH_CROSS_ENCODER

NODE_HYBRID_SEARCH_RRF

NODE_HYBRID_SEARCH_MMR

NODE_HYBRID_SEARCH_NODE_DISTANCE

NODE_HYBRID_SEARCH_EPISODE_MENTIONS

NODE_HYBRID_SEARCH_CROSS_ENCODER

COMMUNITY_HYBRID_SEARCH_RRF

COMMUNITY_HYBRID_SEARCH_MMR

COMMUNITY_HYBRID_SEARCH_CROSS_ENCODER

Examples

Basic Search

Advanced Search with Custom Config

Search with Filters

Node Distance Reranking

Breadth-First Search