Using datasets

Search a dataset from Compass Chat, a workflow, an agent, or your own code — and answer from your own documents.

A dataset is only useful when something searches it. Searches are by meaning, not keywords: ask "what's our refund window?" and you'll find the passage about returns within 30 days, even if it never says "refund window". Each result is a passage of text with the document it came from, the heading it sits under, and a relevance score.

In Compass Chat

Compass Chat can use datasets two ways:

On its own — on the Compass harness (the default), chat can list your datasets, see what's in them, and search them. When a question might be answered by your documents, it searches and answers from the passages, naming each document it used.
As a tool you pick — open Tools in the composer and tick a dataset under Datasets. It starts with its read actions — search and list_documents — switched on; click the dataset to change which actions chat may use.

In a workflow

Add the Dataset component to the canvas, pick the dataset, and choose an action. search takes a query and returns the top matching passages, ready to bind into a Prompt or an agent's input:

Input (question) → Dataset (search) → Agent (answer from the passages) → Output

The component can also add documents to a dataset (index), remove them, list them, or run a source's sync — so a workflow can keep a dataset up to date as part of a larger process.

As an agent tool

To let an agent decide when to search, give it the dataset as a tool: in the agent builder, Add tool lists the project's datasets under Datasets; on the canvas, attach a Dataset component to the agent's Tools handle. The agent gets one tool per enabled action; search and list_documents are enabled when you add it, while actions that change the dataset — index, delete_document, sync — stay off until you turn them on. Any of them can require approval.

From your code

The API, SDK, and CLI can search a dataset directly — no workflow required — which makes a dataset a ready-made retrieval backend for your own applications:

curl -X POST https://your-compass-url/v1/datasets/<dataset-id>/search \
  -H "Authorization: Bearer $COMPASS_ACCESS_TOKEN" \
  -H "X-Compass-Project-Id: <project-id>" \
  -H "Content-Type: application/json" \
  -d '{ "query": "What is our refund window?", "top_k": 5 }'

The CLI's search is also the quickest way to check whether a dataset's chunking finds what it should. See API, CLI & SDK for uploading, sources, and the rest.

Searching well

top_k — how many passages come back (1–50, default 5). More gives the model more to work with, at the cost of a longer prompt.
filter — narrow results to chunks whose metadata matches exactly. Metadata is whatever was attached when a document was indexed through the index action.
Score — higher is closer. Scores compare results within one search; they aren't a fixed threshold across datasets.

Dataset component

Every action, with its inputs and outputs.

Compass Chat

Ask questions of your documents conversationally.