Heratio Help Center article. Category: AI & Automation.
Semantic Search User Guide
Overview
Semantic Search enhances your Heratio 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
Understanding Search Results
When Semantic Search expands your query, you'll see an information box showing which synonyms were used:
How It Works
Search Flow
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
Dashboard Overview
The Semantic Search dashboard shows:
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
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 |
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
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
Viewing Term Details
Click on any term to see its full details and all associated synonyms:
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
Workflow 2: Adding Organization-Specific Terms
Workflow 3: Syncing External Sources
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 Heratio |
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 Digital Commons Group
Document Version: 1.1 Last Updated: February 2026 Author: The Archive and Heritage Digital Commons Group (Pty) Ltd