> ## Documentation Index
> Fetch the complete documentation index at: https://docs.topk.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Ask
> Get grounded, evidence-backed answers from your documents.
TopK answers natural-language queries over your documents.
It retrieves the most relevant parts of your documents and synthesizes a grounded answer with source citations.
## How it works
When you run an **Ask**, TopK:
Interprets your question and organizes it into a clear sequence of answerable steps
Your documents are searched to find the most relevant passages based on your query.
Produce a grounded answer based on the retrieved evidence.
Returns a grounded answer with facts, citations, and a confidence score. See [Understanding the answer](#understanding-the-answer).
## Usage
Once a dataset is created and your documents are processed, you can start running agentic queries against your documents:
```bash theme={null}
topk ask "What was the total net income of Bank of America in 2024?" -d my-docs
```
```python theme={null}
for message in client.ask("What was the total net income of Bank of America in 2024?", ["my-docs"]):
print(message)
```
```json title="Example output" expandable theme={null}
{
"facts": [
{
"fact": "Bank of America's total net income for the fiscal year 2024 was $27,132 million.",
"ref_ids": ["1", "2", "3", "4", "5", "6"]
},
{
"fact": "The 2024 net income of $27.1 billion represented an increase from the $26.5 billion reported in 2023.",
"ref_ids": ["3", "4", "6"]
},
{
"fact": "The increase in 2024 net income was driven by higher noninterest income, although this was partially offset by a higher provision for credit losses and lower net interest income.",
"ref_ids": ["3", "6"]
}
],
"refs": {
"1": {
"doc_id": "bank-of-america-annual-report-2024",
"doc_type": "application/pdf",
"dataset": "my-docs",
"content_id": "doc#bank-of-america-annual-report-2024#chunk#130",
"doc_name": "bank_of_america_2024.pdf",
"content": {
"data": {
"Chunk": {
"text": "## Condensed Statement of Cash Flows\n[row_1]; []=Net income; [2024]=27,132; [2023]=26,515; [2022]=27,528\n...",
"doc_pages": [170]
}
}
},
"metadata": {}
},
"2": {
"doc_id": "bank-of-america-annual-report-2024",
"doc_type": "application/pdf",
"dataset": "my-docs",
"content_id": "doc#bank-of-america-annual-report-2024#chunk#428",
"doc_name": "bank_of_america_2024.pdf",
"content": {
"data": {
"Chunk": {
"text": "## Consolidated Statement of Comprehensive Income\n[row_0]; [Dollars in millions]=Net income; [2024]=27,132; [2023]=26,515; [2022]=27,528\n...",
"doc_pages": [92]
}
}
},
"metadata": {}
},
"3": {
"doc_id": "bank-of-america-annual-report-2024",
"doc_type": "application/pdf",
"dataset": "my-docs",
"content_id": "doc#bank-of-america-annual-report-2024#image#92",
"doc_name": "bank_of_america_2024.pdf",
"content": {
"data": {
"Image": {
"mime_type": "image/jpeg",
"data": ""
}
}
},
"metadata": {}
}
},
"confidence": 100.0
}
```
```typescript theme={null}
for await (const message of client.ask("What was the total net income of Bank of America in 2024?", ["my-docs"])) {
console.log(message);
}
```
```json title="Example output" expandable theme={null}
{
"facts": [
{
"fact": "Bank of America's total net income for the fiscal year 2024 was $27,132 million.",
"refIds": ["1", "2", "3", "4", "5", "6"]
},
{
"fact": "The 2024 net income of $27.1 billion represented an increase from the $26.5 billion reported in 2023.",
"refIds": ["3", "4", "6"]
},
{
"fact": "The increase in 2024 net income was driven by higher noninterest income, although this was partially offset by a higher provision for credit losses and lower net interest income.",
"refIds": ["3", "6"]
}
],
"refs": {
"1": {
"docId": "bank-of-america-annual-report-2024",
"docType": "application/pdf",
"dataset": "my-docs",
"contentId": "doc#bank-of-america-annual-report-2024#chunk#130",
"docName": "bank_of_america_2024.pdf",
"content": {
"type": "chunk",
"data": {
"text": "## Condensed Statement of Cash Flows\n[row_1]; []=Net income; [2024]=27,132; [2023]=26,515; [2022]=27,528\n...",
"docPages": [170]
}
},
"metadata": {}
},
"2": {
"docId": "bank-of-america-annual-report-2024",
"docType": "application/pdf",
"dataset": "my-docs",
"contentId": "doc#bank-of-america-annual-report-2024#chunk#428",
"docName": "bank_of_america_2024.pdf",
"content": {
"type": "chunk",
"data": {
"text": "## Consolidated Statement of Comprehensive Income\n[row_0]; [Dollars in millions]=Net income; [2024]=27,132; [2023]=26,515; [2022]=27,528\n...",
"docPages": [92]
}
},
"metadata": {}
},
"3": {
"docId": "bank-of-america-annual-report-2024",
"docType": "application/pdf",
"dataset": "my-docs",
"contentId": "doc#bank-of-america-annual-report-2024#image#92",
"docName": "bank_of_america_2024.pdf",
"content": {
"type": "image",
"data": {
"mimeType": "image/jpeg",
"data": ""
}
},
"metadata": {}
}
},
"confidence": 100
}
```
Here's an example **Ask** query against a corporate filing (financial knowledge base):
**Query:**
What was the total net income of Bank of America in 2024?
**Answer:**
* Bank of America's total net income for the fiscal year 2024 was \$27,132 million. 1 2 3 4 5 6
* The 2024 net income of \$27.1 billion represented an increase from the \$26.5 billion reported in 2023. 3 4 6
* The increase in 2024 net income was driven by higher noninterest income, although this was partially offset by a higher provision for credit losses and lower net interest income. 3 6
**Citations:**
## Understanding the answer
The answer consists of three fields:
* **`facts`** — individual statements answering the query, each backed by one or more citations
* **`refs`** — a map from citation number to a [Search Result](/core/search#search-result)
* **`confidence`** — a score between 0 and 100 indicating confidence in the answer
```json theme={null}
{
"facts": [
{
"fact": "Bank of America's total net income for the fiscal year 2024 was $27,132 million.",
"ref_ids": ["1", "2", "3", "4", "5", "6"]
},
{
"fact": "The 2024 net income represented an increase from the $26.5 billion reported in 2023.",
"ref_ids": ["3", "4", "6"]
},
{
"fact": "The increase was driven by higher noninterest income, partially offset by a higher provision for credit losses and lower net interest income.",
"ref_ids": ["3", "6"]
}
],
"refs": {
"1": { ... }, // Search Result 1
"2": { ... }, // Search Result 2
"3": { ... }, // Search Result 3
"4": { ... }, // Search Result 4
"5": { ... }, // Search Result 5
"6": { ... } // Search Result 6
},
"confidence": 100.0
}
```
### Citations
Citations are **numbered**. Each fact's `ref_ids` list points to entries in `refs`, where each key is a citation number and each value is a [Search Result](/core/search#search-result) — the matched passage or image along with its document ID, file name, dataset, and any requested metadata.
## Scoping the search
Query across specific datasets or apply document filters to narrow the scope of the query.
### Scoping to specific datasets
When running ask, you must specify at least one dataset to query against.
To specify the datasets to query against, pass `--dataset` or `-d` (repeatable):
```bash theme={null}
topk ask "What was the total net income of Bank of America in 2024?" -d finance -d compliance
```
To specify the datasets to query against, pass a list of dataset names as the second argument:
```python Sync theme={null}
import os
from topk_sdk import Client
client = Client(
api_key=os.environ.get("TOPK_API_KEY"),
region="aws-us-east-1-elastica",
)
for message in client.ask(
"What was the total net income of Bank of America in 2024?",
["finance", "compliance"], # list of dataset names to query against
):
print(message)
```
```python Async theme={null}
import os
from topk_sdk import AsyncClient
client = AsyncClient(
api_key=os.environ.get("TOPK_API_KEY"),
region="aws-us-east-1-elastica",
)
async for message in client.ask(
"What was the total net income of Bank of America in 2024?",
["finance", "compliance"], # list of dataset names to query against
):
print(message)
```
To specify the datasets to query against, pass a list of dataset names as the second argument:
```typescript theme={null}
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.ask(
"What was the total net income of Bank of America in 2024?",
["finance", "compliance"],
)) {
console.log(message);
}
```
### Document filtering
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](/documents/query#filtering).
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 Sync theme={null}
from topk_sdk.query import field
for message in client.ask(
"What is the travel reimbursement limit?",
[
{
"dataset": "policies",
"filter": field("department").eq("finance").and_(
field("year").eq(2024)
),
}
],
):
print(message)
```
```python Async theme={null}
from topk_sdk.query import field
async for message in client.ask(
"What is the travel reimbursement limit?",
[
{
"dataset": "policies",
"filter": field("department").eq("finance").and_(
field("year").eq(2024)
),
}
],
):
print(message)
```
```typescript theme={null}
import { field } from "topk-js/query";
for await (const message of client.ask(
"What is the travel reimbursement limit?",
[
{
dataset: "policies",
filter: field("department").eq("finance").and(field("year").eq(2024)),
},
],
)) {
console.log(message);
}
```
## Retrieving metadata
By default, metadata fields are not included in citations. Pass the field names you want returned and they will appear on each cited Search Result.
Use `--field` (repeatable) and `--output json` to include metadata field(s) in the output:
```bash theme={null}
topk ask "What was the total net income of Bank of America in 2024?" -d finance --field title --field year --output json
```
```json title="Example output" expandable theme={null}
{
"facts": [
{
"fact": "Bank of America's total net income for the fiscal year 2024 was $27,132 million.",
"ref_ids": ["1", "2"]
}
],
"refs": {
"1": {
"metadata": {
"title": "Bank of America 2024 Annual Report",
"year": 2024
},
"doc_id": "bank-of-america-annual-report-2024",
"doc_type": "application/pdf",
"dataset": "finance",
"content_id": "doc#bank-of-america-annual-report-2024#chunk#130",
"doc_name": "bank_of_america_2024.pdf",
"content": {
"text": "## Condensed Statement of Cash Flows\n[row_1]; []=Net income; [2024]=27,132; [2023]=26,515; [2022]=27,528\n...",
"doc_pages": [170]
}
},
"2": {
"metadata": {
"title": "Bank of America 2024 Annual Report",
"year": 2024
},
"doc_id": "bank-of-america-annual-report-2024",
"doc_type": "application/pdf",
"dataset": "finance",
"content_id": "doc#bank-of-america-annual-report-2024#chunk#428",
"doc_name": "bank_of_america_2024.pdf",
"content": {
"text": "## Consolidated Statement of Comprehensive Income\n[row_0]; [Dollars in millions]=Net income; [2024]=27,132; [2023]=26,515; [2022]=27,528\n...",
"doc_pages": [92]
}
}
},
"confidence": 100.0
}
```
Use `select_fields` parameter to include metadata field(s):
```python theme={null}
for message in client.ask(
"What was the total net income of Bank of America in 2024?",
["finance"],
select_fields=["title", "year"],
):
print(message)
```
```json title="Example output" expandable theme={null}
{
"facts": [
{
"fact": "Bank of America's total net income for the fiscal year 2024 was $27,132 million.",
"ref_ids": ["1", "2"]
}
],
"refs": {
"1": {
"metadata": {
"title": "Bank of America 2024 Annual Report",
"year": 2024
},
"doc_id": "bank-of-america-annual-report-2024",
"doc_type": "application/pdf",
"dataset": "finance",
"content_id": "doc#bank-of-america-annual-report-2024#chunk#130",
"doc_name": "bank_of_america_2024.pdf",
"content": {
"data": {
"Chunk": {
"text": "## Condensed Statement of Cash Flows\n[row_1]; []=Net income; [2024]=27,132; [2023]=26,515; [2022]=27,528\n...",
"doc_pages": [170]
}
}
}
}
},
"confidence": 100.0
}
```
Use `selectFields` parameter to include metadata field(s):
```typescript theme={null}
for await (const message of client.ask(
"What was the total net income of Bank of America in 2024?",
["finance"],
undefined,
undefined,
["title", "year"],
)) {
console.log(message);
}
```
```json title="Example output" expandable theme={null}
{
"facts": [
{
"fact": "Bank of America's total net income for the fiscal year 2024 was $27,132 million.",
"refIds": ["1", "2"]
}
],
"refs": {
"1": {
"metadata": {
"title": "Bank of America 2024 Annual Report",
"year": 2024
},
"docId": "bank-of-america-annual-report-2024",
"docType": "application/pdf",
"dataset": "finance",
"contentId": "doc#bank-of-america-annual-report-2024#chunk#130",
"docName": "bank_of_america_2024.pdf",
"content": {
"type": "chunk",
"data": {
"text": "## Condensed Statement of Cash Flows\n[row_1]; []=Net income; [2024]=27,132; [2023]=26,515; [2022]=27,528\n...",
"docPages": [170]
}
}
}
},
"confidence": 100
}
```