Searching Your Knowledge Graph

Search and retrieve information from your knowledge graph with hybrid search, filters, and reranking

Graphiti provides powerful search capabilities to retrieve relevant information from your knowledge graph, combining semantic similarity, full-text search, and graph-based reranking.

Basic Search

The simplest way to search is using the search() method, which returns relationship edges:

from graphiti_core import Graphiti

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

# Search for information
results = await graphiti.search("Who was the California Attorney General?")

# Display results
for result in results:
    print(f"Fact: {result.fact}")
    print(f"UUID: {result.uuid}")
    if result.valid_at:
        print(f"Valid from: {result.valid_at}")
    if result.invalid_at:
        print(f"Valid until: {result.invalid_at}")
    print("---")

Search Methods

Graphiti uses hybrid search combining multiple retrieval methods:

Semantic Similarity

Finds results based on meaning using vector embeddings

BM25 Full-Text

Finds results based on keyword matching

Graph Traversal (BFS)

Explores connected nodes in the graph

Reranking

Combines and reorders results for optimal relevance

Search Parameters

Parameter	Type	Default	Description
query	str	Required	The search query
center_node_uuid	str	None	UUID of node to rerank by graph distance
group_ids	list[str]	None	Filter results to specific graph partitions
num_results	int	10	Maximum number of results to return
search_filter	SearchFilters	None	Advanced filtering options

Center Node Reranking

Rerank results based on their graph distance from a specific node:

# Initial search
results = await graphiti.search("Who was the California Attorney General?")

if results:
    # Use the top result's source node as the center
    center_node_uuid = results[0].source_node_uuid
    
    # Rerank based on graph proximity
    reranked_results = await graphiti.search(
        "Who was the California Attorney General?",
        center_node_uuid=center_node_uuid
    )
    
    # Results are now ordered by relevance to the center node
    for result in reranked_results:
        print(f"Fact: {result.fact}")

This is useful for finding contextually related information around a specific entity.

Advanced Search with Configurations

For more control, use the search_() method with custom search configurations:

from graphiti_core.search.search_config_recipes import (
    NODE_HYBRID_SEARCH_RRF,
    EDGE_HYBRID_SEARCH_CROSS_ENCODER,
    COMBINED_HYBRID_SEARCH_RRF
)

# Search for nodes instead of edges
node_search_config = NODE_HYBRID_SEARCH_RRF.model_copy(deep=True)
node_search_config.limit = 5

results = await graphiti.search_(
    query="California Governor",
    config=node_search_config
)

# Access node results
for node in results.nodes:
    print(f"Node: {node.name}")
    print(f"Summary: {node.summary}")
    print(f"Labels: {', '.join(node.labels)}")
    if node.attributes:
        print(f"Attributes: {node.attributes}")
    print("---")

Search Configuration Recipes

Graphiti provides pre-configured search recipes optimized for different scenarios:

Edge Search Recipes

Search for relationships between entities:

from graphiti_core.search.search_config_recipes import (
    EDGE_HYBRID_SEARCH_RRF,           # Reciprocal Rank Fusion
    EDGE_HYBRID_SEARCH_MMR,            # Maximal Marginal Relevance
    EDGE_HYBRID_SEARCH_NODE_DISTANCE,  # Graph distance based
    EDGE_HYBRID_SEARCH_EPISODE_MENTIONS, # Episode frequency based
    EDGE_HYBRID_SEARCH_CROSS_ENCODER   # Neural reranking
)

results = await graphiti.search_(
    query="relationships between people",
    config=EDGE_HYBRID_SEARCH_CROSS_ENCODER
)

Node Search Recipes

Search for entities:

from graphiti_core.search.search_config_recipes import (
    NODE_HYBRID_SEARCH_RRF,           # Reciprocal Rank Fusion
    NODE_HYBRID_SEARCH_MMR,            # Maximal Marginal Relevance
    NODE_HYBRID_SEARCH_NODE_DISTANCE,  # Graph distance based
    NODE_HYBRID_SEARCH_EPISODE_MENTIONS, # Episode frequency based
    NODE_HYBRID_SEARCH_CROSS_ENCODER   # Neural reranking
)

results = await graphiti.search_(
    query="engineers in San Francisco",
    config=NODE_HYBRID_SEARCH_RRF
)

Combined Search Recipes

Search across nodes, edges, episodes, and communities:

from graphiti_core.search.search_config_recipes import (
    COMBINED_HYBRID_SEARCH_RRF,
    COMBINED_HYBRID_SEARCH_MMR,
    COMBINED_HYBRID_SEARCH_CROSS_ENCODER
)

results = await graphiti.search_(
    query="California politics",
    config=COMBINED_HYBRID_SEARCH_CROSS_ENCODER
)

print(f"Edges: {len(results.edges)}")
print(f"Nodes: {len(results.nodes)}")
print(f"Episodes: {len(results.episodes)}")
print(f"Communities: {len(results.communities)}")

Community Search Recipes

Search for clusters of related entities:

from graphiti_core.search.search_config_recipes import (
    COMMUNITY_HYBRID_SEARCH_RRF,
    COMMUNITY_HYBRID_SEARCH_MMR,
    COMMUNITY_HYBRID_SEARCH_CROSS_ENCODER
)

results = await graphiti.search_(
    query="technology companies",
    config=COMMUNITY_HYBRID_SEARCH_RRF
)

for community in results.communities:
    print(f"Community: {community.name}")
    print(f"Summary: {community.summary}")

Custom Search Configurations

Build your own search configuration:

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

# Custom configuration
custom_config = SearchConfig(
    edge_config=EdgeSearchConfig(
        search_methods=[
            EdgeSearchMethod.bm25,
            EdgeSearchMethod.cosine_similarity
        ],
        reranker=EdgeReranker.mmr,
        sim_min_score=0.5,  # Minimum similarity threshold
        mmr_lambda=0.7      # Diversity parameter (0=diverse, 1=similar)
    ),
    limit=20,
    reranker_min_score=0.3
)

results = await graphiti.search_(
    query="product recommendations",
    config=custom_config
)

Search Configuration Options

Search Methods

Edges

• EdgeSearchMethod.cosine_similarity - Semantic vector search
• EdgeSearchMethod.bm25 - Full-text keyword search
• EdgeSearchMethod.bfs - Breadth-first graph traversal

Nodes

• NodeSearchMethod.cosine_similarity - Semantic vector search
• NodeSearchMethod.bm25 - Full-text keyword search
• NodeSearchMethod.bfs - Breadth-first graph traversal

Episodes

• EpisodeSearchMethod.bm25 - Full-text keyword search

Communities

• CommunitySearchMethod.cosine_similarity - Semantic vector search
• CommunitySearchMethod.bm25 - Full-text keyword search

Reranking Methods

RRF

Reciprocal Rank Fusion - Combines multiple search methods by rank

MMR

Maximal Marginal Relevance - Balances relevance and diversity

Node Distance

Reranks by graph distance from a center node

Cross Encoder

Neural reranking for highest accuracy

Episode Mentions

Reranks by frequency across episodes

Search Filters

Filter results by group, time, or custom criteria:

from graphiti_core.search.search_filters import SearchFilters
from datetime import datetime, timezone, timedelta

# Filter by time range
start_time = datetime.now(timezone.utc) - timedelta(days=30)
end_time = datetime.now(timezone.utc)

filters = SearchFilters(
    start_date=start_time,
    end_date=end_time
)

results = await graphiti.search(
    query="recent activity",
    search_filter=filters
)

Search Results

The search_() method returns a SearchResults object with multiple result types:

results = await graphiti.search_(
    query="example query",
    config=COMBINED_HYBRID_SEARCH_RRF
)

# Access different result types
for edge in results.edges:
    print(f"Edge: {edge.fact} (score: {results.edge_reranker_scores[results.edges.index(edge)]})")

for node in results.nodes:
    print(f"Node: {node.name} (score: {results.node_reranker_scores[results.nodes.index(node)]})")

for episode in results.episodes:
    print(f"Episode: {episode.name}")

for community in results.communities:
    print(f"Community: {community.name}")

Performance Tips

Limit Results

Set appropriate limit values to reduce latency

Use Group IDs

Filter by group_ids to search specific partitions

Simple Configs

Start with RRF reranking before using cross-encoder

Min Scores

Set reranker_min_score to filter low-quality results

Example: Multi-Stage Search

Combine different search strategies:

# 1. Broad search to find relevant nodes
node_results = await graphiti.search_(
    query="product recommendations",
    config=NODE_HYBRID_SEARCH_RRF
)

if node_results.nodes:
    # 2. Use top node as center for focused edge search
    center_node = node_results.nodes[0]
    
    edge_results = await graphiti.search_(
        query="product features",
        config=EDGE_HYBRID_SEARCH_NODE_DISTANCE,
        center_node_uuid=center_node.uuid
    )
    
    # 3. Display contextual results
    print(f"Recommendations related to {center_node.name}:")
    for edge in edge_results.edges:
        print(f"  - {edge.fact}")

Next Steps

Adding Episodes

Learn how to add content to your knowledge graph

Custom Entities

Define domain-specific entity types for better search