Unified Search

The SemanticSearchService provides a unified search orchestrator that combines semantic, structural, precedent, and discovery search into a single query interface. It routes queries to the appropriate backend, merges results from multiple sources, and applies combined ranking.

Overview

Unified search is the primary entry point for all Context Graph queries. Rather than requiring callers to choose between vector search, graph traversal, or decision lookup, the unified search service analyzes the query and selects the optimal strategy.

Source: data-plane/ai-service/src/context_graph/services/semantic_search_service.py

Query Interface

from context_graph.services.semantic_search_service import (
    SemanticSearchService,
    SearchQuery,
    SearchMode,
    SearchScope,
    SearchFilters,
    SortOrder,
)
 
results = await service.search(SearchQuery(
    query="customer churn prediction pipeline",
    tenant_id="acme",
    mode=SearchMode.HYBRID,
    scope=SearchScope.ALL,
    top_k=20,
    min_score=0.3,
    sort=SortOrder.RELEVANCE,
    filters=SearchFilters(
        entity_types=["dataset", "model", "feature"],
    ),
))

Query Processing Pipeline

Query Analysis -- Extracts intent, entities, and search parameters from the natural language query
Embedding Generation -- Converts the query text into a vector embedding
Multi-Backend Dispatch -- Routes the query to relevant backends based on mode and scope
Result Merging -- Combines results from different backends with deduplication
Ranking -- Applies combined scoring with configurable weights
Explanation -- Optionally generates human-readable explanations for each result

Sort Orders

Order	Description
`RELEVANCE`	Sort by combined similarity/relevance score (default)
`RECENCY`	Sort by creation or update time
`NAME`	Sort alphabetically by entity name

Result Structure

Each search result includes:

Field	Description
`entity_urn`	URN of the matching entity
`entity_type`	Type of the entity (dataset, model, etc.)
`score`	Combined relevance score (0-1)
`source`	Which backend produced the result
`entity_data`	Entity metadata and properties
`graph_context`	Optional: neighbors, relationships, lineage
`explanation`	Optional: human-readable match explanation

Search History and Analytics

The service tracks search queries for analytics purposes:

Query text and parameters
Result counts and latency
Click-through rates (when integrated with the frontend)
Popular queries per tenant

Access analytics via the search analytics API endpoint:

GET /api/v1/context-graph/search/analytics

Integration with Search Result Explainer

The SearchResultExplainer service generates human-readable explanations for search results:

from context_graph.services.search_result_explainer import (
    SearchResultExplainer,
    ExplanationLevel,
)
 
explainer = get_search_result_explainer()
explanation = await explainer.explain(
    query="customer churn models",
    result=search_result,
    level=ExplanationLevel.DETAILED,
)

Explanation levels include BRIEF (one-line summary), STANDARD (key factors), and DETAILED (full reasoning chain).

Structural Search Precedent Search