# Finding things

All reading skills are served by the reader door. The examples were run against a fresh
house holding one small document, one claim and one source.

## By word

`search_text` searches all texts with the full-text index. A query of several words asks
for all of them by default, and every answer carries `interpreted`, which shows what the
query became: "bridge finished" became `bridge AND finished`. Each hit names the documents
it stands in and whether that version is the current one. Pass a document id to search one
document exhaustively instead of the whole house by rank.

## By meaning

`search_semantic` finds texts by similarity of meaning, using an embedding model that ships
inside the house. "When was the river crossing completed" found "The bridge was finished in
1887." without sharing a word with it. Two things to know: the score orders hits and is no
threshold, and the index covers every text in the house, including the descriptions of the
built-in vocabulary. In a nearly empty house those rank among the hits. Use both searches
for thorough work; they find different things.

## By structure

`find_things` filters things by what they are. Its `where` is a JSON object with one key: a
condition, or a junction of conditions with `all`, `any` or `not`.

```json
{"all": [{"aspect": "Source"},
         {"slot": "Source.Reliability", "contains": "dates"}]}
```

Conditions address an aspect, a kind (`{"kind": "Binary"}`), an id, or a slot of an aspect's
surface with an operator: eq, ne, lt, le, gt, ge, in, prefix, contains, exists, missing.
The answer carries `scanned`: where the candidates came from and how much was read to
answer. That is the cost of your question, stated.

Three relatives take the same `where`:

- `count_things` returns numbers instead of things, grouped by one or two axes.
- `find_missing` is the worklist of gaps: which things lack a given slot.
- `find_alike` proposes groups of things that are alike (duplicate candidates, namesakes).
  It proposes and never judges; it writes nothing.

`find_value` looks a value up without storing it: does this exact text, this formed value,
this date exist, and what points at it.

## By time and place

`find_in_period` and `find_nearby`, with `time_coverage` as the way in. See
`time-and-place`.

## By walking

- `describe` is the central reading skill: any id, with its content, its links grouped by
  meaning, its aspects and their values, and its notes.
- `get_links` lists the active links of a thing, filtered by direction, meaning or form.
- `walk_links` follows chosen kinds of edges over several steps: from the claim along
  "Stated in" it reached the source in one step.
- `get_property` and `get_history` read slots; `walk_chain` reads ordered lists.
- `find_occurrences` tells where a thing appears: in which documents, versions and
  hierarchies.
- `list_collection` pages through a collection; `overview` names them.

## What searching will not do

The skills report hits and where they come from. Judging relevance is yours. Nothing ranks
"what matters to this user"; there is no personalisation.

## Go deeper

- [time-and-place](time-and-place.md)
- [documents-and-versions](documents-and-versions.md)
- [forms-aspects-concepts](forms-aspects-concepts.md): where aspects and slots come from
- [the-three-doors](the-three-doors.md)