> For the complete documentation index, see [llms.txt](https://docs.graphlit.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.graphlit.dev/api-guides/use-cases/knowledge-graph/knowledge-graph-guided-search.md).

# Knowledge Graph-Guided Search

## User Intent

"How can the knowledge graph improve my search results? Show me entity expansion and graph-aware retrieval."

## Operation

**SDK Methods**: `queryObservables()` + `queryContents()` combined\
**Concept**: Use entity relationships to enhance search\
**Use Case**: Graph-enhanced information retrieval

## Prerequisites

* Knowledge graph with entities
* Search queries
* Understanding of entity relationships

***

## Key Concepts

### 1. Entity Expansion

Expand search terms using entity variants:

```typescript
// User searches "Kirk"
// System expands to:
// - "Kirk Marple"
// - "K. Marple"
// - kirk@graphlit.com
```

### 2. Relationship-Aware Search

Use entity relationships to broaden results:

```typescript
// Search "Graphlit team"
// 1. Find Graphlit (Organization)
// 2. Find all People at Graphlit
// 3. Return content mentioning any team member
```

### 3. Entity Disambiguation

Use context to identify correct entity:

```typescript
// "Apple" could be company or fruit
// Knowledge graph helps disambiguate
```

***

## Complete Code Example (TypeScript)

```typescript
import { Graphlit } from 'graphlit-client';
import { ObservableTypes } from 'graphlit-client/dist/generated/graphql-types';

const graphlit = new Graphlit();

async function graphGuidedSearch(query: string) {
  console.log(`Searching: "${query}"\n`);
  
  // Step 1: Find entities matching query
  const entities = await graphlit.queryObservables({
    search: query
  });
  
  console.log(`Found ${entities.observables.results.length} matching entities\n`);
  
  // Step 2: For each entity, find related entities
  const allEntityIds = new Set<string>();
  entities.observables.results.forEach(e => allEntityIds.add(e.observable.id));
  
  for (const entity of entities.observables.results.slice(0, 3)) {
    const related = await graphlit.queryContents({
      
        observations: [{ observable: { id: entity.observable.id } }]
      });
    
    // Extract related entities
    related.contents.results.forEach(content => {
      content.observations?.forEach(obs => {
        allEntityIds.add(obs.observable.id);
      });
    });
  }
  
  console.log(`Expanded to ${allEntityIds.size} entities via relationships\n`);
  
  // Step 3: Search content mentioning any of these entities
  const expandedResults = await graphlit.queryContents({
    search: query  // Semantic search
    // Plus entity filter (if needed)
  });
  
  console.log(`Results: ${expandedResults.contents.results.length}`);
  
  return expandedResults.contents.results;
}

await graphGuidedSearch("Graphlit");
```

***

## Benefits

**Better Recall**: Find variations and related mentions\
**Entity Resolution**: "Kirk" expands to "Kirk Marple"\
**Context Awareness**: Relationships provide context\
**Disambiguation**: Choose correct entity meaning\
**Richer Results**: Include related entities

***

## Patterns

### Pattern 1: Team Search

"Show me Company X team" → Find all people at Company X

### Pattern 2: Topic Expansion

"AI research" → Find research + related papers + authors

### Pattern 3: Temporal Context

Entity mentions over time with relationship context

***

## Developer Hints

* Entity resolution improves recall
* Graph relationships add context
* Combine with semantic search
* Better than pure keyword search
* Cache entity expansions

***