Searching Documents

Master typegraph.search(): resources, weights, context, graph retrieval, prompt building, and score interpretation.

Basic Search

typegraph.search() is the primary retrieval API. Pass a natural-language string and TypeGraph returns ranked hits across the selected resources. The default weights are semantic, BM25, graph, and recency scoring fused into a final scores.fused value.

Basic search example

const response = await typegraph.search('How do I reset my password?', {
  resources: ['documents'],
  limit: 5,
})

for (const hit of response.hits) {
  console.log(hit.rank)
  console.log(hit.scores.fused)
  console.log(hit.scores.semantic)
  console.log(hit.content)
  console.log(hit.document?.id)
  console.log(hit.document?.bucketId)
  console.log(hit.metadata)
}

Choose Resources

resources controls what result families are eligible: documents, events, threads, entities, and facts. This is separate from scoring. For example, searching events and documents does not automatically enable graph weighting; it only controls which stored records can appear. Private memories are retrieved through typegraph.memory.recall().

Resources example

const onlyDocuments = await typegraph.search('deployment pipeline', {
  resources: ['documents'],
  limit: 10,
})

const eventsAndDocuments = await typegraph.search('Acme SOC2 blocker', {
  resources: ['events', 'documents'],
  limit: 10,
})

const businessGraph = await typegraph.search('Which customers have SSO issues?', {
  resources: ['events', 'documents', 'entities', 'facts'],
  weights: { semantic: 1, bm25: 0.7, graph: 0.8, recency: 0.4 },
  limit: 10,
})

const memoryOnly = await typegraph.memory.recall('What does Dana prefer?', {
  context: { userId: UserId('dana') },
  limit: 10,
})

Tune Weights

weights controls scoring. Set a weight to a number to include it, or false to disable it. semantic is vector similarity, bm25 is keyword ranking, graph uses relationships and provenance links, and recency boosts recent records.

Weights example

const semanticOnly = await typegraph.search('kubernetes pod crash loop', {
  resources: ['documents'],
  weights: { semantic: 1, bm25: false, graph: false, recency: false },
  limit: 10,
})

const hybrid = await typegraph.search('ERR_CONNECTION_REFUSED in gateway logs', {
  resources: ['documents'],
  weights: { semantic: 0.7, bm25: 1, graph: false, recency: 0.2 },
  limit: 10,
})

const graphWeighted = await typegraph.search('Who owns the renewal blockers for Acme?', {
  resources: ['events', 'documents', 'entities', 'facts'],
  weights: { semantic: 0.6, bm25: 0.4, graph: 1, recency: 0.5 },
  fusion: { method: 'rrf', k: 60 },
  explain: true,
})

Use Context and Graph Perspective

context is the only per-call actor identity object. graph selects the retrieval perspective: public users search public; internal users can search a child graph such as internal, which includes public ancestors.

Context example

const response = await typegraph.search('billing requirements', {
  graph: 'internal',
  resources: ['documents', 'facts', 'entities'],
  context: {
    userId: UserId('dana'),
    groupId: GroupId('sales'),
  },
  limit: 12,
})

// context identifies the caller. graph selects the retrieval perspective.

Filter Documents and Buckets

Filters narrow stored resource fields. Tenant and access enforcement always comes from the initialized tenant and context; filters should not carry tenant or access-control fields.

Filtering example

const response = await typegraph.search('rate limiting rollout', {
  resources: ['documents', 'events'],
  buckets: ['api-docs', 'support-tickets'],
  documentFilter: {
    status: 'complete',
    metadata: { product: 'api-gateway' },
  },
  context: {
    groupId: GroupId('engineering'),
  },
  limit: 12,
})

Build an LLM Prompt

promptBuilder replaces the old context-builder naming. When enabled, the response includes prompt, an LLM-ready string assembled from the returned hits and evidence.

Prompt builder example

const response = await typegraph.search('What are the API rate limits?', {
  resources: ['documents', 'facts', 'entities'],
  weights: { semantic: 1, bm25: 0.8, graph: 0.5, recency: 0.2 },
  limit: 20,
  promptBuilder: {
    format: 'xml',
    includeAttributes: false,
    sections: ['chunks', 'facts', 'entities'],
    maxTotalTokens: 4000,
  },
})

console.log(response.prompt)
// <context>
//   <chunk>...</chunk>
//   <fact>...</fact>
// </context>

End-to-End RAG

A typical B2B search uses documents, events, entities, and facts together. Access controls only decide which records the caller may read; graph relationships come from extracted facts, seeded entities, event participants, and provenance links.

Full RAG example

import { generateText } from 'ai'
import { openai } from '@ai-sdk/openai'
import { GroupId, UserId } from '@typegraph-ai/sdk'

const question = 'Which customers are blocked by SSO issues?'

const response = await typegraph.search(question, {
  graph: 'internal',
  resources: ['documents', 'events', 'entities', 'facts'],
  weights: { semantic: 0.8, bm25: 0.6, graph: 1, recency: 0.4 },
  buckets: ['salesforce', 'slack', 'gong'],
  context: {
    userId: UserId('dana'),
    groupId: GroupId('sales'),
  },
  limit: 15,
  promptBuilder: {
    format: 'xml',
    sections: ['chunks', 'facts', 'entities', 'events'],
    maxTotalTokens: 6000,
  },
  explain: true,
})

const { text } = await generateText({
  model: openai('gpt-5.4-mini'),
  prompt: `Answer the question using only the context below.
If the context is insufficient, say what is missing.

Context:
${response.prompt}

Question: ${question}`,
})

console.log(text)

Back to All Guides

const response = await typegraph.search('How do I reset my password?', { resources: ['documents'], limit: 5, }) for (const hit of response.hits) { console.log(hit.rank) console.log(hit.scores.fused) console.log(hit.scores.semantic) console.log(hit.content) console.log(hit.document?.id) console.log(hit.document?.bucketId) console.log(hit.metadata) }

const onlyDocuments = await typegraph.search('deployment pipeline', { resources: ['documents'], limit: 10, }) const eventsAndDocuments = await typegraph.search('Acme SOC2 blocker', { resources: ['events', 'documents'], limit: 10, }) const businessGraph = await typegraph.search('Which customers have SSO issues?', { resources: ['events', 'documents', 'entities', 'facts'], weights: { semantic: 1, bm25: 0.7, graph: 0.8, recency: 0.4 }, limit: 10, }) const memoryOnly = await typegraph.memory.recall('What does Dana prefer?', { context: { userId: UserId('dana') }, limit: 10, })

const semanticOnly = await typegraph.search('kubernetes pod crash loop', { resources: ['documents'], weights: { semantic: 1, bm25: false, graph: false, recency: false }, limit: 10, }) const hybrid = await typegraph.search('ERR_CONNECTION_REFUSED in gateway logs', { resources: ['documents'], weights: { semantic: 0.7, bm25: 1, graph: false, recency: 0.2 }, limit: 10, }) const graphWeighted = await typegraph.search('Who owns the renewal blockers for Acme?', { resources: ['events', 'documents', 'entities', 'facts'], weights: { semantic: 0.6, bm25: 0.4, graph: 1, recency: 0.5 }, fusion: { method: 'rrf', k: 60 }, explain: true, })

const response = await typegraph.search('billing requirements', { graph: 'internal', resources: ['documents', 'facts', 'entities'], context: { userId: UserId('dana'), groupId: GroupId('sales'), }, limit: 12, }) // context identifies the caller. graph selects the retrieval perspective.

const response = await typegraph.search('rate limiting rollout', { resources: ['documents', 'events'], buckets: ['api-docs', 'support-tickets'], documentFilter: { status: 'complete', metadata: { product: 'api-gateway' }, }, context: { groupId: GroupId('engineering'), }, limit: 12, })

const response = await typegraph.search('What are the API rate limits?', { resources: ['documents', 'facts', 'entities'], weights: { semantic: 1, bm25: 0.8, graph: 0.5, recency: 0.2 }, limit: 20, promptBuilder: { format: 'xml', includeAttributes: false, sections: ['chunks', 'facts', 'entities'], maxTotalTokens: 4000, }, }) console.log(response.prompt) // <context> // <chunk>...</chunk> // <fact>...</fact> // </context>

import { generateText } from 'ai' import { openai } from '@ai-sdk/openai' import { GroupId, UserId } from '@typegraph-ai/sdk' const question = 'Which customers are blocked by SSO issues?' const response = await typegraph.search(question, { graph: 'internal', resources: ['documents', 'events', 'entities', 'facts'], weights: { semantic: 0.8, bm25: 0.6, graph: 1, recency: 0.4 }, buckets: ['salesforce', 'slack', 'gong'], context: { userId: UserId('dana'), groupId: GroupId('sales'), }, limit: 15, promptBuilder: { format: 'xml', sections: ['chunks', 'facts', 'entities', 'events'], maxTotalTokens: 6000, }, explain: true, }) const { text } = await generateText({ model: openai('gpt-5.4-mini'), prompt: `Answer the question using only the context below. If the context is insufficient, say what is missing. Context: ${response.prompt} Question: ${question}`, }) console.log(text)