Semantic Search User Guide¶
Overview¶
Semantic Search enhances your AtoM search experience by automatically expanding your search queries with related terms, synonyms, and alternative spellings. This means you can find more relevant records even when you don't use the exact words stored in the archive.
Example: When you search for "photograph", Semantic Search can also find records containing "photo", "picture", "image", or "snapshot".
Getting Started¶
Enabling Semantic Search¶
When searching, you can enable semantic search from the search box:
- Click the gear icon next to the search box
- Toggle "Semantic search" on
- Enter your search terms
- Click Search
┌─────────────────────────────────────────────────────────┐
│ [⚙️ ▼] [ Search archives... ] [🔍] │
│ │ │
│ └──► ┌─────────────────────────────┐ │
│ │ ○ Global search │ │
│ │ ○ Search Repository X │ │
│ │ ─────────────────────────── │ │
│ │ › Advanced search │ │
│ │ ─────────────────────────── │ │
│ │ [✓] Semantic search │ ◄── Enable here │
│ │ Expand with synonyms │ │
│ └─────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
Understanding Search Results¶
When Semantic Search expands your query, you'll see an information box showing which synonyms were used:
┌─────────────────────────────────────────────────────────────────────┐
│ 🧠 Semantic Search Active │
│ │
│ Your search has been expanded with related terms: │
│ │
│ "archive" → [repository] [depot] [record office] [holdings] │
│ "letter" → [correspondence] [epistle] [missive] │
│ │
│ ℹ️ Disable semantic search in options to search exact terms only. │
└─────────────────────────────────────────────────────────────────────┘
How It Works¶
Search Flow¶
┌──────────────────┐
│ User enters │
│ search query │
└────────┬─────────┘
│
▼
┌──────────────────┐
│ Semantic Search │
│ enabled? │
└────────┬─────────┘
│
┌──────────────┴──────────────┐
│ │
▼ Yes ▼ No
┌──────────────────┐ ┌──────────────────┐
│ Expand query │ │ Search exact │
│ with synonyms │ │ terms only │
└────────┬─────────┘ └────────┬─────────┘
│ │
▼ │
┌──────────────────┐ │
│ "photo" becomes: │ │
│ photo OR picture │ │
│ OR photograph │ │
│ OR image │ │
└────────┬─────────┘ │
│ │
└──────────────┬───────────────┘
│
▼
┌──────────────────┐
│ Search results │
│ displayed │
└──────────────────┘
Types of Term Relationships¶
Semantic Search understands different types of word relationships:
| Type | Description | Example |
|---|---|---|
| Exact Synonyms | Words with the same meaning | photo = photograph = picture |
| Related Terms | Conceptually connected words | archive ↔ repository |
| Broader Terms | More general concepts | letter → correspondence |
| Narrower Terms | More specific concepts | document → manuscript |
Administration¶
Accessing Semantic Search Settings¶
Administrators can configure Semantic Search from the AHG Settings:
- Navigate to Admin → AHG Settings
- Click on the "Semantic Search" card
- You'll see the Semantic Search dashboard
┌─────────────────────────────────────────────────────────────────────┐
│ AHG SETTINGS │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ 🎨 Theme │ │ 📧 Email │ │ 🔌 Plugins │ │ 🧠 Semantic │ │
│ │ Config │ │ Settings │ │ Management │ │ Search │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ 🛡️ Privacy │ │ 📚 Library │ │ 🏛️ Heritage│ │
│ │ Compliance │ │ Settings │ │ Accounting │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
Dashboard Overview¶
The Semantic Search dashboard shows:
┌─────────────────────────────────────────────────────────────────────┐
│ 🧠 Semantic Search [⚙️ Settings] │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ 📚 Total Terms │ │ 🔄 Synonyms │ │ 📊 Data Sources │ │
│ │ 1,247 │ │ 3,892 │ │ 3 / 4 │ │
│ │ │ │ │ │ active │ │
│ │ [local] [wnet] │ │ [exact][related]│ │ │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
│ │
│ ┌─ Quick Actions ──────────────────────────────────────────────┐ │
│ │ │ │
│ │ [Import Local] [Sync WordNet] [Export to ES] [Add Term] │ │
│ │ │ │
│ └───────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─ Test Query Expansion ────────────────────────────────────────┐ │
│ │ │ │
│ │ [ Enter a search term... ] [🔍 Expand] │ │
│ │ │ │
│ └───────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
Quick Actions Explained¶
| Action | What It Does |
|---|---|
| Import Local | Loads predefined archival, museum, library, and South African terms |
| Sync WordNet | Downloads synonyms from the WordNet linguistic database |
| Export to ES | Generates synonym file for Elasticsearch |
| Add Term | Manually add a custom term with synonyms |
Testing Query Expansion¶
Before enabling semantic search for all users, test how queries are expanded:
- Enter a term in the "Test Query Expansion" box
- Click Expand
- Review the synonyms that would be added
┌─────────────────────────────────────────────────────────────────────┐
│ Test Query Expansion │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ [ manuscript ] [🔍 Expand] │
│ │
│ Expansions: │
│ │
│ manuscript → [document] [text] [codex] [script] [holograph] │
│ │
└─────────────────────────────────────────────────────────────────────┘
Settings Configuration¶
General Settings¶
Access settings via the Settings button on the dashboard:
| Setting | Description | Recommended |
|---|---|---|
| Enable Semantic Search | Master on/off switch | On |
| Expansion Limit | Max synonyms per term (1-20) | 5 |
| Minimum Weight | Relevance threshold (0.0-1.0) | 0.6 |
| Show Expansion Info | Display synonyms used on results page | On |
| Log Searches | Keep history of expanded searches | On |
Data Sources¶
Configure where synonyms come from:
| Source | Description | When to Enable |
|---|---|---|
| Local Synonyms | Curated archival/museum terminology | Always |
| WordNet | Large English language database | For general vocabulary |
| Wikidata | Heritage and archival concepts | For specialized heritage terms |
| Ollama Embeddings | AI-powered similarity | Advanced: requires Ollama server |
┌─────────────────────────────────────────────────────────────────────┐
│ Data Sources Configuration │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ [✓] Local Synonyms │
│ Uses curated archival, museum, and library terminology │
│ │
│ [✓] WordNet (Datamuse API) │
│ Fetches synonyms from the WordNet linguistic database │
│ │
│ [ ] Wikidata │
│ Fetches heritage terms from Wikidata knowledge base │
│ │
│ [ ] Ollama Embeddings │
│ Uses AI models for semantic similarity (requires Ollama) │
│ │
└─────────────────────────────────────────────────────────────────────┘
Managing Terms¶
Browsing the Thesaurus¶
View all terms in your semantic search database:
- From the dashboard, click "Browse terms"
- Filter by source (Local, WordNet, Wikidata)
- Search for specific terms
┌─────────────────────────────────────────────────────────────────────┐
│ Terms [+ Add Term] │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ Search: [ manuscript ] Source: [All Sources ▼] [Filter] │
│ │
├─────────────────────────────────────────────────────────────────────┤
│ Term │ Source │ Domain │ Synonyms │ Created │
├───────────────┼──────────┼──────────┼──────────┼────────────────────┤
│ archive │ local │ archival │ 8 │ Jan 15, 2026 │
│ catalogue │ local │ library │ 5 │ Jan 15, 2026 │
│ manuscript │ wordnet │ general │ 6 │ Jan 18, 2026 │
│ photograph │ local │ archival │ 7 │ Jan 15, 2026 │
│ township │ local │ sa │ 4 │ Jan 15, 2026 │
└─────────────────────────────────────────────────────────────────────┘
Adding Custom Terms¶
Add organization-specific terminology:
- Click "Add Term"
- Enter the main term
- Select the domain (Archival, Museum, Library, South African, General)
- Enter synonyms (one per line)
- Set the relationship type and weight
- Click Save
┌─────────────────────────────────────────────────────────────────────┐
│ Add Term │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ Term: * │
│ [ dompas ] │
│ │
│ Domain: Relationship: Weight: │
│ [South African ▼] [Exact ▼] [0.8 ] │
│ │
│ Synonyms (one per line): │
│ ┌─────────────────────────────────────────────────┐ │
│ │ pass book │ │
│ │ reference book │ │
│ │ passbook │ │
│ │ pass laws document │ │
│ └─────────────────────────────────────────────────┘ │
│ │
│ [Cancel] [💾 Save Term] │
└─────────────────────────────────────────────────────────────────────┘
Viewing Term Details¶
Click on any term to see its full details and all associated synonyms:
┌─────────────────────────────────────────────────────────────────────┐
│ Term: archive │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ Source: local Domain: archival │
│ Created: Jan 15, 2026 │
│ │
│ ┌─ Synonyms (8) ──────────────────────────────────────────────────┐│
│ │ ││
│ │ Synonym │ Type │ Weight │ Source ││
│ │ ──────────────────┼─────────┼────────┼───────────────────────── ││
│ │ repository │ exact │ 0.95 │ local ││
│ │ record office │ exact │ 0.90 │ local ││
│ │ depot │ exact │ 0.85 │ local ││
│ │ holdings │ related │ 0.75 │ wordnet ││
│ │ collection │ related │ 0.70 │ wordnet ││
│ │ registry │ related │ 0.65 │ local ││
│ │ muniment room │ narrower│ 0.60 │ local ││
│ │ records center │ exact │ 0.80 │ local ││
│ │ ││
│ └──────────────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────────┘
Domain-Specific Terminology¶
Pre-loaded Term Collections¶
Semantic Search includes curated terminology for:
Archival Terms¶
- fonds, series, file, item, accession
- provenance, custody, arrangement, description
- finding aid, inventory, register, calendar
Library Terms¶
- catalogue, classification, call number
- monograph, serial, periodical
- ISBN, ISSN, bibliography
Museum Terms¶
- artefact, specimen, exhibit, collection
- acquisition, deaccession, loan
- conservation, restoration, provenance
South African Terms¶
- apartheid, township, homeland, bantustans
- dompas, influx control, Group Areas Act
- TRC, amnesty, reconciliation
Workflow Examples¶
Workflow 1: Initial Setup¶
┌─────────────────────────────────────────────────────────────────────┐
│ INITIAL SETUP WORKFLOW │
└─────────────────────────────────────────────────────────────────────┘
Step 1 Step 2 Step 3
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Go to AHG │ │ Click on │ │ Click │
│ Settings │ ───► │ "Semantic │ ───► │ "Import │
│ │ │ Search" card │ │ Local" │
└──────────────┘ └──────────────┘ └──────────────┘
│
▼
Step 6 Step 5 Step 4
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Test a │ │ Enable │ │ Go to │
│ search with │ ◄─── │ Semantic │ ◄─── │ Settings, │
│ synonyms │ │ Search │ │ configure │
└──────────────┘ └──────────────┘ └──────────────┘
Workflow 2: Adding Organization-Specific Terms¶
┌─────────────────────────────────────────────────────────────────────┐
│ ADDING CUSTOM TERMINOLOGY WORKFLOW │
└─────────────────────────────────────────────────────────────────────┘
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Identify │ │ Navigate to │ │ Click │
│ terms users │ ──► │ Semantic │ ──► │ "Add Term" │
│ search for │ │ Search │ │ │
└─────────────┘ └─────────────┘ └─────────────┘
│
▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Test │ │ Save │ │ Enter term │
│ expansion │ ◄── │ the term │ ◄── │ & synonyms │
│ │ │ │ │ │
└─────────────┘ └─────────────┘ └─────────────┘
│
▼
┌─────────────────────────────────┐
│ Export to Elasticsearch if │
│ using ES synonym filters │
└─────────────────────────────────┘
Workflow 3: Syncing External Sources¶
┌─────────────────────────────────────────────────────────────────────┐
│ SYNC EXTERNAL SOURCES WORKFLOW │
└─────────────────────────────────────────────────────────────────────┘
┌─────────────────┐
│ Review current │
│ term count on │
│ dashboard │
└────────┬────────┘
│
▼
┌──────────────────┴──────────────────┐
│ │
▼ ▼
┌─────────────────┐ ┌─────────────────┐
│ Click "Sync │ │ Click "Sync │
│ WordNet" for │ │ Wikidata" for │
│ general English │ │ heritage terms │
└────────┬────────┘ └────────┬────────┘
│ │
└──────────────────┬──────────────────┘
│
▼
┌─────────────────┐
│ Wait for sync │
│ to complete │
│ (check logs) │
└────────┬────────┘
│
▼
┌─────────────────┐
│ Review new │
│ terms added │
└────────┬────────┘
│
▼
┌─────────────────┐
│ Export to │
│ Elasticsearch │
└─────────────────┘
Troubleshooting¶
Common Issues¶
| Issue | Possible Cause | Solution |
|---|---|---|
| No synonyms appearing | Semantic search disabled | Enable in search options |
| Wrong synonyms | Weight too low | Increase minimum weight in settings |
| Too many results | Expansion limit too high | Reduce expansion limit |
| Missing terms | Source not enabled | Enable WordNet or Wikidata |
| Slow searches | Too many synonyms | Reduce expansion limit |
Checking Sync Status¶
View sync history to diagnose issues:
- From dashboard, click "View All" under Recent Syncs
- Check for failed syncs (red status)
- Review error messages
Best Practices¶
For Administrators¶
- Start with local synonyms - Import the curated terminology first
- Test before enabling - Use the test expansion feature
- Set appropriate limits - Start with 5 synonyms per term
- Review search logs - See what users are searching for
- Add organization-specific terms - Include your unique terminology
- Export to Elasticsearch - Keep the synonym file updated
For Users¶
- Use semantic search for discovery - Find related records
- Disable for exact matches - When you need precise results
- Check expansion info - Understand why results were returned
- Report missing synonyms - Help improve the system
Glossary¶
| Term | Definition |
|---|---|
| Synonym | A word with the same or similar meaning |
| Thesaurus | A collection of words and their relationships |
| Query expansion | Adding related terms to a search |
| Weight | A score indicating how relevant a synonym is |
| WordNet | A large English linguistic database |
| Elasticsearch | The search engine powering AtoM |
Semantic Search and Fuzzy Search¶
Semantic Search works alongside Fuzzy Search (typo-tolerant search) to maximize search coverage. They are complementary:
| Feature | Semantic Search | Fuzzy Search |
|---|---|---|
| Purpose | Expand vocabulary with synonyms | Correct misspellings and typos |
| How | Synonym dictionary relationships | Character/sound similarity |
| Example | "photo" finds "photograph", "picture" | "photograps" corrects to "photographs" |
| Activation | User toggles on/off | Always active on GLAM Browse |
| Admin setup | Import terms, configure sources | No configuration needed |
Best together: Fuzzy Search corrects your typos first, then Semantic Search expands the corrected query with related terms. For example, "archieves" is corrected to "archives", which is then expanded to include "repository", "record office", and "holdings".
For full details on fuzzy search, see the Fuzzy Search User Guide.
Support¶
For assistance with Semantic Search:
- Documentation: This guide and technical manual
- Issues: Report bugs via your system administrator
- Training: Contact The Archive and Heritage Group
Document Version: 1.1 Last Updated: February 2026 Author: The Archive and Heritage Group (Pty) Ltd