# How search works

Source: https://docs.littlebigbrain.com/start/platform/

A question rarely uses the words stored in your data. Similarity finds a
starting point. Links show whether that starting point leads to an answer. This
page shows how the two work together. It uses the
[quickstart](https://docs.littlebigbrain.com/start/quickstart/) example: **which release fixed the login bug?**

## Find the nearest facts

The question says "users cannot sign in after the upgrade". The ticket says
"login fails after 3.1". Vector search matches the two by meaning, so the
ticket is the top hit.

You choose which types are searchable and which fields to embed. The platform
builds one text per record and embeds it. It keeps the vectors current as
records change.

Each hit is checked against the graph at one commit. A deleted record does not
come back. Filters narrow a search by type and by link.
[Search by meaning](https://docs.littlebigbrain.com/guides/search-by-meaning/) covers the options.

A search result is a candidate. A similarity score cannot show that the bug was
fixed in a particular release. The next step checks the stored links.

## Follow the facts

The ticket names the bug, and the bug names the release:

```text
ticket 4821: login fails after 3.1
    └─ REPORTED_AS → bug AUTH-112: session token expiry
                       └─ FIXED_IN → Release 3.2
```

A graph query follows both links. It starts at the ticket the search found:

```sparql
PREFIX dr: <https://littlebigbrain.com/r/>
PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>

SELECT ?bug ?release WHERE {
  <ticket-iri-from-the-search> dr:reported_as ?b .
  ?b rdfs:label ?bug ; dr:fixed_in ?r .
  ?r rdfs:label ?release .
}
```

It returns `session token expiry` and `Release 3.2`. The agent can answer
"Release 3.2 fixed it" and name the records and links behind it. Each link can
also carry evidence, such as "Release notes 3.2", for the agent to cite.

The graph can only confirm what you loaded. A query does not turn a missing
fact into a verified one. When a link is absent, the query returns no row. The
agent then knows it has no proof.

## Replay the answer

A search response names the commit it read, as `served_at_seq`. A SPARQL
response from `/v1/query/sparql-text` names it in `snapshot.served_at_seq`.
Store it with the answer, together with the query and its rows.

Say the answer read commit `412`. A later query with `as_of_commit_seq: 412`
reads the same data, even after newer writes.

This reproduces the evidence behind the answer. To reproduce the generated
text too, keep the prompt, the model version and its settings.

A commit stays readable while it is retained. [Replay an answer](https://docs.littlebigbrain.com/guides/time-travel-audit/)
explains what to save. It also covers commits that are no longer retained.

## Keep meaning with the data

A schema says what your records mean. It declares the types, the links between
them and the fields each type has. An agent can read the schema before it
queries or writes.

Rules make writes safe. Declare rules as SHACL shapes, such as "each bug has at
most one fix release".

In reject mode, the platform refuses a write that breaks a rule. The error
reports what to repair. The agent fixes its write and retries.
[Validate writes](https://docs.littlebigbrain.com/guides/sparql-and-shacl/#published-shacl-conformance).

The schema can also say how types relate. For example, an active study site is
a study site. A query can then use that hierarchy.
[Reasoning & inference](https://docs.littlebigbrain.com/guides/reasoning/) shows how.

Schema suggestions come from the data you already have. They propose
properties and rules that your records already follow. Review the evidence for
a suggestion before you accept it. The schema stays an explicit part of the
graph.

## Improve the next answer

Feedback shows which results and paths helped an agent. Evaluation checks
whether a change makes answers better or worse. Ranking can then pick a more
useful starting point. The graph still supplies the links behind each answer.

The [retrieval comparison](https://docs.littlebigbrain.com/start/database-comparison/) shows where vector,
full-text, SQL and graph retrieval fit an application's questions.

## Truth in object storage

Facts, indexes, vectors and history live in object storage. Serving nodes cache
hot data on NVMe. You can add or replace a node without moving your data. This
is the storage model behind the landing page's
[architecture diagram](https://littlebigbrain.com/#storage).

The [overview](https://docs.littlebigbrain.com/start/overview/) describes the whole system.
[Usage and billing](https://docs.littlebigbrain.com/start/billing/) explains what counts as stored data.