Search

Search your documents and return the most relevant passages based on your natural-language query.

How it works

When you run Search, TopK:

Searches across your documents

Searches one or more datasets for the passages most relevant to the query.

Ranks the best matches

Results are ranked by relevance so the highest-signal passages come first.

Returns passages with document context

Each result includes the matched passage, document ID, dataset, page references, and requested metadata.

Usage

Once your documents are processed, you can start retrieving relevant passages immediately.

CLI
Python SDK
JavaScript SDK

topk search "travel reimbursement policy" -d policies

import os
from topk_sdk import Client

client = Client(
    api_key=os.environ.get("TOPK_API_KEY"),
    region="aws-us-east-1-elastica",
)

for result in client.search(
    query="travel reimbursement policy",
    datasets=["policies"],
    top_k=10,
):
    print(result)

import { Client } from "topk-js";

const client = new Client({
  apiKey: process.env.TOPK_API_KEY,
  region: "aws-us-east-1-elastica",
});

for await (const message of client.search("travel reimbursement policy", ["policies"], 10)) {
  console.log(message);
}

Here’s an example of a Search query over a financial dataset:

Query:What was the total net income of Bank of America in 2024?Search results:

1 Condensed Statement of Cash Flows showing net income of $27,132m (2024) vs $26,515m (2023) bank_of_america_2024.pdf p. 170
2 Consolidated Statement of Comprehensive Income: net income line item for 2024–2022 bank_of_america_2024.pdf p. 92
3 Supporting figure from the filing (tabular financial excerpt) boa-ask-ref-3-figure.jpg
4 Key performance indicators—selected annual financial data (including net income) bank_of_america_2024.pdf pp. 33–36
5 Segment results tying to total-corporation net income bank_of_america_2024.pdf pp. 166–168
6 Executive summary—summary income statement and balance sheet excerpts bank_of_america_2024.pdf pp. 29–30

Understanding search results

Search returns a list of the most relevant Search Results based on the provided query. Search Results are objects referencing specific passages extracted from the original documents.

Search Result

Each Search Result has the following fields:

Field	Type	Description
`doc_id`	`string`	The ID of the source document assigned at upload time
`doc_name`	`string`	The file name of the source document assigned at upload time
`doc_type`	`string`	The MIME type of the source document (e.g. `application/pdf`)
`dataset`	`string`	The dataset the document belongs to
`content_id`	`string`	A unique identifier for the content of this Search Result
`content`	`object`	The matched content — see Content types
`metadata`	`object`	Metadata fields attached to the source document at upload time — must be requested, see Retrieving metadata

Content types

There are three content types a search result can contain:

Chunk — a text passage extracted from a document, with optional source page number(s)
Image — an image extracted from a document
Page — an image of a page from a document, with source page number

Scoping the search

Query across multiple datasets or apply document filters to narrow the scope of the query.

Scoping to specific datasets

This is useful when you want:

More targeted results
Less ambiguity across unrelated document sets
Tighter control over what content an agent is allowed to see

CLI
Python SDK
JavaScript SDK

Use -d / --dataset (repeatable):

topk search "What was the total net income of Bank of America in 2024?" -d finance -d compliance

To specify the datasets to search against, pass them in datasets=:

for result in client.search(
    query="What was the total net income of Bank of America in 2024?",
    datasets=["finance", "compliance"],
    top_k=10,
):
    print(result)

To specify the datasets to search against, pass them in the datasets argument:

for await (const message of client.search(
  "What was the total net income of Bank of America in 2024?",
  ["finance", "compliance"],
  10,
)) {
  console.log(message);
}

Filter documents

Sometimes a dataset might contain documents that should not be considered for the query. You can filter out documents that don’t match your criteria by providing a filter expression. These filter expressions operate on the metadata fields of documents. If your documents include metadata fields, you can use those fields to narrow down the search scope. This is useful when you want to query:

Documents within a specific time range
Documents matching a particular category or type
Documents associated with a specific group or owner
Documents the end user is permitted to access

Python SDK
JavaScript SDK

from topk_sdk.query import field

for result in client.search(
    query="travel reimbursement limit",
    datasets=[
        {
            "dataset": "policies",
            "filter": field("department").eq("finance").and_(
                field("year").eq(2024)
            ),
        }
    ],
    top_k=10,
):
    print(result)

import { field } from "topk-js/query";

for await (const message of client.search(
  "travel reimbursement limit",
  [
    {
      dataset: "policies",
      filter: field("department").eq("finance").and(field("year").eq(2024)),
    },
  ],
  10,
)) {
  console.log(message);
}

Retrieving metadata

By default, metadata fields are not included in search results. Pass the field names you want returned and they will appear on each Search Result.

CLI
Python SDK
JavaScript SDK

Use --field (repeatable) and --output json to include metadata field(s) in the output:

topk search "refund policy" -d policies --field title --field author --field year --output json

Example output

[
  {
    "metadata": {
      "title": "Refund Policy 2024",
      "author": "Finance Team",
      "year": 2024
    },
    "doc_id": "refund-policy-2024",
    "doc_type": "application/pdf",
    "dataset": "policies",
    "content_id": "doc#refund-policy-2024#chunk#12",
    "doc_name": "refund_policy_2024.pdf",
    "content": {
      "text": "Refund requests must be submitted within 30 days of purchase. Approved refunds are processed within 5–7 business days.",
      "doc_pages": [3]
    }
  }
]

Pass a list of metadata field names to include in the output:

for result in client.search(
    query="refund policy",
    datasets=["policies"],
    top_k=10,
    select_fields=["title", "author", "year"], # document metadata fields
):
    print(result)

Example output

{
  "metadata": {
    "title": "Refund Policy 2024",
    "author": "Finance Team",
    "year": 2024
  },
  "doc_id": "refund-policy-2024",
  "doc_type": "application/pdf",
  "dataset": "policies",
  "content_id": "doc#refund-policy-2024#chunk#12",
  "doc_name": "refund_policy_2024.pdf",
  "content": {
    "data": {
      "Chunk": {
        "text": "Refund requests must be submitted within 30 days of purchase. Approved refunds are processed within 5–7 business days.",
        "doc_pages": [3]
      }
    }
  }
}

Pass a list of metadata field names to include in the output:

for await (const message of client.search(
  "refund policy",
  ["policies"],
  10,
  undefined,
  ["title", "author", "year"], // document metadata fields
)) {
  console.log(message);
}

Example output

{
  "metadata": {
    "title": "Refund Policy 2024",
    "author": "Finance Team",
    "year": 2024
  },
  "docId": "refund-policy-2024",
  "docType": "application/pdf",
  "dataset": "policies",
  "contentId": "doc#refund-policy-2024#chunk#12",
  "docName": "refund_policy_2024.pdf",
  "content": {
    "type": "chunk",
    "data": {
      "text": "Refund requests must be submitted within 30 days of purchase. Approved refunds are processed within 5–7 business days.",
      "docPages": [3]
    }
  }
}

If present on the original document, the requested metadata appears on the returned Search Result.

Overview

Core Concepts

Management

How it works

Usage

Understanding search results

Search Result

Content types

Scoping the search

Scoping to specific datasets

Filter documents

Retrieving metadata

Overview

Core Concepts

Management

Documentation Index

​How it works

​Usage

​Understanding search results

​Search Result

​Content types

​Scoping the search

​Scoping to specific datasets

​Filter documents

​Retrieving metadata

How it works

Usage

Understanding search results

Search Result

Content types

Scoping the search

Scoping to specific datasets

Filter documents

Retrieving metadata