Skip to main content

Retrieval

Search a collection for the chunks or sections most relevant to a query, with optional tag and metadata filters.

Hybrid search for chunks#

Run keyword + semantic search with cross-encoder reranking and get back ranked chunks.

Each result is a chunk with a `score` and full document + section provenance. Default limit is 10. Reranking is on by default for collections that have it enabled; turn it off at the collection level for lower latency on high-volume read paths.

dewey query my-docs "what are the key findings?"

# 0.91  report.pdf → Executive summary
#       Net revenue grew 18% year-over-year, driven by enterprise...
# 0.87  report.pdf → Risk factors
#       Foreign-exchange exposure continues to be the largest source...

Response

[
  {
    "score": 0.913,
    "chunk": {
      "id": "chk_8a",
      "sectionId": "sec_b4f9",
      "content": "Net revenue grew 18% year-over-year, driven by enterprise adoption..."
    },
    "section": { "id": "sec_b4f9", "title": "Executive summary", "level": 1 },
    "document": { "id": "doc_a1", "filename": "report.pdf" }
  }
]

See also

Find the most relevant sections#

Get top-k sections (not chunks) for a query — cheaper and great for citation UIs.

Scanning operates on section titles and AI-generated summaries rather than full chunk content, so it's noticeably cheaper than `query` and tends to surface broader, more recognizable results. Use it when you need a table of contents view, not the exact paragraph.

dewey scan my-docs "revenue trends" --top-k 5

# report.pdf
#   §2  Revenue          score 0.88
#   §2.1 By segment      score 0.84
# earnings.pptx
#   §3  Growth drivers   score 0.79

See also

Scope search by tags or metadata#

Restrict retrieval to a tagged or metadata-filtered subset of your collection.

Both `query` and `scan` accept `tags` (require all of these), `anyTags` (require at least one), and `metadata` (JSONB containment — return only docs whose metadata is a superset of the object you pass). The filter is applied before reranking, so it's free.

// All filters — chunks must come from documents tagged BOTH q3-2026 AND
// finance, whose metadata contains { reviewed: true }.
const results = await client.retrieval.query(
  'COLLECTION_ID',
  'revenue by segment',
  {
    tags: ['q3-2026', 'finance'],
    metadata: { reviewed: true },
    limit: 10,
  },
)

See also

Render results with citations#

Turn a retrieval response into a document → section → chunk citation trail.

Every retrieval result already carries the full provenance you need: document, section, chunk. Render the section title as the human-facing citation, the document filename as the source label, and link the chunk's `position` if you want exact-paragraph deep links.

const results = await client.retrieval.query(
  'COLLECTION_ID',
  'what does the contract say about indemnification?',
)

// Build a numbered citation block like an LLM would.
const cited = results.slice(0, 3).map((r, i) => ({
  marker: `[${i + 1}]`,
  quote: r.chunk.content.trim(),
  source: `${r.document.filename} — ${r.section.title}`,
}))

for (const c of cited) {
  console.log(`${c.marker} ${c.quote}`)
  console.log(`    ${c.source}\n`)
}

See also