> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pool.day/llms.txt
> Use this file to discover all available pages before exploring further.

# Queries

> Ask in plain words, with a typed query, or both. Every answer says how Pool knows it and how much it could see.

## Plain words

```swift theme={null}
let result = try await pool.context.query("recipes from last week", using: grant)
```

Pool reads the question on the device with fixed rules: kind words become type filters (“recipes”), source words become source filters (“screenshots”), date phrases become a capture window (“last week”), and the rest become search words. The same question always produces the same plan, and the plan comes back on the result so you can show or log how it was read.

## Typed queries

```swift theme={null}
var query = ContextQuery(text: "running shoes")
query.types = [.product]
query.sources = [.screenshots]
query.dateRange = DateInterval(start: monthAgo, end: .now)

let result = try await pool.context.query(query, using: grant, limit: 20)
```

Filters you set yourself win over the words. A query returns things, such as products and places. To get the photos themselves, or photos that look like one you already have, use [search and similar](https://docs.pool.day/search.md).

## What comes back

| On QueryResult | Meaning |
| - | - |
| `matches` | Ranked things and captures. Each has a `summary`, a `confidence`, a `provenance`, how often and when it was seen. |
| `evidence` | Which capture each match came from, where in it, and which extractor produced it. |
| `coverage` | What Pool could see when it answered. See [Evidence and coverage](https://docs.pool.day/evidence.md). |
| `asOf` | When the answer was computed. |
| `plan` | How the question was read: filters, search words and the date window. |
| `nextCursor` | Pass it back as `cursor` for the next page. `nil` on the last page. |
| `traceID` | An identifier with no personal content, safe to put in your logs and support tickets. |

## Paging

```swift theme={null}
var page = try await pool.context.query(query, using: grant, limit: 20)
while let cursor = page.nextCursor {
    page = try await pool.context.query(query, using: grant, limit: 20, cursor: cursor)
}
```

A cursor belongs to one version of the index. If the index is rebuilt or deleted, an old cursor fails with `PoolError.invalidCursor` and you start again from the first page.

## Languages

Search by exact words works in any language Apple's text recognition reads. Ranking by meaning and related-word expansion cover English in version 1.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.