Search and semantic search
What this page is — the two ways the repository finds documents: keyword search over structured data, and semantic search over the meaning of indexed text — and the index that decides what semantic search can see.
What it is for — so a document can be found by what it is about, not only by what somebody happened to call it.
The problem it solves — a badly named document is a lost document, however relevant its content.
Route: /org/papers/repository · Permissions: View this project's documents. for keyword
search; Use AI drafting/extraction/Q&A for documents. for the Semantic toggle.
1. What it is
The two searches read different data, which is the thing to understand first:
| Keyword | Semantic | |
|---|---|---|
| Reads | Title, document number, field values | Passages of the rendered document, from the index |
| Documents covered | Every document in scope, including drafts | Only indexed documents |
| Matching | Postgres full-text, English word stems — "payments" finds "payment" | Meaning, combined with a full-text leg |
| Runs | As you type | On Enter |
| Result | Document rows, filterable and selectable | Passage cards — the same document can appear several times |
| Filters and bulk bar | Available | Hidden while the toggle is on |
Keyword search does not read the document's wording. A phrase that appears only in a template clause — not in a field — is invisible to it. Neither search reads attachments.
What is indexed. A document is indexed automatically when it is finalized, and on demand with Reindex. Drafts are not indexed, so a young project may have only a fraction of its documents searchable by meaning.
2. Why you would use it
- The title is the author's word, not yours. Semantic search for termination for convenience also finds "either party may end this agreement on thirty days' notice".
- Keyword search is exact and immediate for numbers, party names and field values.
- Passages, not files. A semantic result shows the section and page where the idea lives, so you land on the paragraph.
- Both respect access. Two colleagues can run the same search and get different results — correctly.
3. How the index works
| Step | Detail |
|---|---|
| Trigger | Finalize, or Reindex on the row |
| Source | The rendered document |
| Chunking | Split at section headings, then into passages of about 700 characters with overlap; each passage keeps its full section as context |
| Retrieval | A dense (meaning) search and a sparse (full-text) search, fused |
| Stored per passage | Section heading, page, text |
Editing a finalized document's content without re-finalizing leaves the index on the old wording until someone presses Reindex.
4. Step by step
Keyword — type in the search box; results update after a short pause, best match first.
Semantic
- Turn on Semantic.
- Describe what you are looking for in plain language.
- Press Enter.
- Click a result card to open the document.
Turning the toggle off restores the keyword list exactly as it was.
5. Field reference
Semantic result card
| Element | Means |
|---|---|
| Document title | Where the passage comes from |
| Section heading | The section it sits in |
| Page badge | The page |
| % match | Similarity — higher is closer |
| Passage | The matched text |
States and messages
| Message | Means |
|---|---|
| Semantic search start card | Nothing searched yet — describe, then Enter |
| No matches | Nothing close enough — rephrase as a description, not keywords or operators |
| Red error | Credits, permission or a server problem. Keyword search still works |
| Failed to search documents | The keyword request failed; the list keeps its previous rows |
Keyword filters
State, Family, Tag and the selected folder combine with the search (AND). Changing any of them returns to page 1 and clears the selection.
6. Worked example
A commercial lead needs every agreement in which the company promised service credits for downtime.
Keyword service credit returns 2 documents — both have a field named Service credits. The MSA template
at Contoso phrases it "the Supplier shall reduce the monthly fee by 5% for each hour of unavailability", in a
clause, not a field. Keyword search cannot see it.
Semantic with "agreements where we owe the customer money when the service is down" → Enter. Seven cards, including MSA — Contoso Ltd · Service Levels · Page 12 · 84% match with the fee-reduction sentence quoted, and a second card from the same MSA's schedule.
One MSA the lead knows about is missing. It is still a draft — never finalized, so never indexed. They finalize it later that week; it appears on the next search.
7. The admin contract
| Must be true | Where | What breaks without it |
|---|---|---|
| The role holds Use AI drafting/extraction/Q&A for documents. | Role editor | No Semantic toggle |
| A platform embedding model is configured | Orbit AI Flow | Semantic search falls back to its full-text leg only |
| Documents are finalized, or reindexed | Lifecycle, Repository | They are invisible to semantic search |
| Important terms are captured as fields | Fields | Keyword search cannot find them |
8. Downstream
| When… | Then |
|---|---|
| A document is finalized | It becomes semantically searchable |
| You press Reindex | Its passages are rebuilt from the current content |
| A field value changes | Keyword search sees it at once; the index does not until reindexed |
9. Don't confuse this with…
| Ask the repository | Answers a question from the same index |
| Documents list search | Title and number, newest 500 only |
| Knowledge graph | Entities, not passages |
| Portfolio Insights | Reads captured fields and obligations |
10. Troubleshooting
| Symptom | Cause |
|---|---|
| A phrase you can see in the document is not found by keyword | It is template wording, not a field value — use semantic |
| A document is missing from semantic results | It is a draft, or was changed after indexing — Reindex |
| Filters disappeared | The Semantic toggle is on |
| The same document appears several times | Several passages matched |
| Semantic returns nothing useful | The wording is too far from anything indexed, or few documents are indexed |