Search Configuration

The Search Configuration page provides administrators with granular control over the Freedam search engine. It allows you to define which asset properties and metadata fields are searchable, how heavily they influence search results, and how the system handles complex queries across different languages.

By adjusting these settings, you can ensure that the most relevant assets appear at the top of search results, fine-tune the balance between keyword and semantic (AI-driven) search, and manage the performance of the search index.

Page Overview

• Purpose: To optimize search relevance and performance by controlling indexing behavior and scoring weights.
• When to use it: Use this page when adding new metadata fields, adjusting search ranking for specific properties, enabling multi-language search, or troubleshooting why certain assets aren't appearing as expected.
• What you can do here:
  • Enable or disable indexing for specific asset fields (e.g., Filename, AI Tags).
  • Assign "Boost" values to prioritize matches in specific fields.
  • Configure default search behavior for custom metadata.
  • Tune hybrid search parameters (BM25 vs. Vector fusion).
  • Manage the order of Quick Gallery Filters.
  • Trigger a full rebuild of the search index.

Page Layout

• Top bar: Displays the page title and description. Contains the Discard Changes and Save Settings buttons, which remain disabled until a change is detected.
• Main area: A tabbed interface organized by configuration category:
  • Indexed Properties: Core asset fields.
  • Metadata Defaults/Overrides: Custom field settings.
  • Vocabulary: Hierarchy-based weighting.
  • Language: Stemming and multi-language indexing.
  • Hybrid Tuning: Advanced algorithm adjustments.
  • Suggestions: Search-as-you-type behavior.
  • Quick Filters: Gallery filter management.
  • Rebuild index: System maintenance tools.

Main Features

Indexed Properties

• What it's for: Controlling the searchability of standard asset fields like Title, Description, and AI Caption.
• Typical use: If users find that "Original Filename" matches are cluttering results, you can lower its boost or exclude it entirely.
• Result: Changes how the search engine ranks assets based on where the search term was found.

Hybrid Tuning

• What it's for: Balancing traditional keyword matching (BM25) with AI-powered semantic similarity (Vector).
• Typical use: Increasing the BM25 weight if users prefer exact keyword matches, or increasing Vector weight to prioritize conceptual similarity.
• Result: Adjusts the mathematical fusion of search results to change the final ranking order.

Quick Gallery Filters

• What it's for: Managing the one-click filters that appear next to the search bar in the main gallery.
• Typical use: Reordering filters so that "Department" appears before "Project Status."
• Result: Updates the visual order of filter buttons for all users in the gallery.

Detailed Feature Documentation

Metadata Overrides

• Purpose: To give specific metadata fields (like "Product Name") higher priority than the default metadata settings.
• Where to find it: In the main area, click the Metadata Overrides tab.
• What you'll see: A searchable table of all text-based metadata fields with individual "Include" checkboxes and "Boost" sliders.

How to use it:

1. Use the Search metadata definitions… field to find a specific metadata key.
2. Toggle the Include checkbox to enable or disable search for that specific field.
3. Adjust the Boost slider (0–5). A value of 5 makes matches in this field extremely important for ranking.
4. Click Save Settings in the top bar.

Language & Indexing

• Purpose: To configure how the system handles different languages and spelling errors.
• Where to find it: In the main area, click the Language tab.
• What you'll see: Options for typo tolerance, multi-language indexing, and a mapping table for PostgreSQL configurations.

How to use it:

1. Toggle Enable typo tolerance to allow fuzzy matching for misspelled search terms.
2. Toggle Index all active languages if your DAM contains assets with metadata in multiple languages.
3. In the Language Map table, use the Type filter (dropdown) to select a specific stemming configuration (e.g., "English", "French") for each active language.
4. Click Save Settings.

Rebuild Search Index

• Purpose: To completely refresh the search index based on current settings and asset data.
• Where to find it: In the main area, click the Rebuild index tab.
• What you'll see: A Rebuild Search Index button and a warning about the operation's duration.

How to use it:

1. Click the Rebuild index tab.
2. Click Rebuild Search Index.
3. A confirmation dialog will appear. Review the warning regarding system performance.
4. Click Rebuild to queue the background job.

Complete Workflows

Workflow: Prioritize Product Names in Search

• Goal: Ensure that assets matching a specific "Product Name" metadata field appear at the top of results.
• Prerequisites: The "Product Name" metadata field must be a searchable type (string, text, or select).

Steps:

1. Navigate to the Metadata Overrides tab.
2. Type "Product Name" into the Search metadata definitions… field.
3. Ensure the Include checkbox is checked for that field.
4. Move the Boost slider to 5.
5. Click Save Settings in the top bar.

• Expected result: Assets where the search term appears in the "Product Name" field will now rank higher than assets where the term only appears in the "Description."

Workflow: Reorder Gallery Quick Filters

• Goal: Change the sequence of one-click filters shown in the asset gallery.
• Prerequisites: Quick filters must be enabled on individual metadata field settings.

Steps:

1. Navigate to the Quick Filters tab.
2. Locate the filter you wish to move.
3. Click the Move up (Up Arrow) or Move down (Down Arrow) buttons to change its position.
4. Click Save order.

• Expected result: The gallery search bar will immediately reflect the new filter sequence.

What each setting really does

Boost weights (0 to 5)

Every searchable field carries a small number between 0 and 5 that decides how much its matches count towards ranking. Freedam ships with sensible defaults:

• Title: 3 (matches in the title matter most).
• Description, keywords, extracted document text, OCR text: 2 (important, but a title match still wins).
• Original filename, creator, copyright, location, AI tags, AI caption, collection names: 1.
• All custom metadata fields: 1 by default, unless you raise the boost for a specific field in the Metadata Overrides tab.
• Vocabulary hierarchy: 3 for broad ancestor terms, 2 for parent terms, 1 for the exact leaf term — so tagging an asset with "Rugby" lets it also surface under "Team sports".

Setting a boost to 0 keeps the field in the index but removes its influence from ranking. Unchecking "Include" removes the field from the index entirely.

Hybrid tuning defaults

Freedam blends two search approaches and these defaults are what you will find on a fresh install:

• Keyword weight (BM25): 1.0.
• Semantic weight (Vector): 1.0 — the two are balanced equally out of the box.
• Keyword candidates per search: 200.
• Semantic candidates per search: 200.
• Rank-fusion smoothing: 60 — lower numbers make top-ranked results dominate more aggressively.
• Semantic sharpness thresholds: Freedam applies a stricter semantic cut-off when the query is very short (a single word, or two words) than when the query is long. Very long queries open up to a wider net, because people describing what they want in several words usually expect fuzzier matches.

Did-you-mean and typo tolerance

• When typo tolerance is off, Freedam only returns exact matches.
• When it is on, Freedam automatically suggests close spellings: if you type "sumer holdiay", Freedam will quietly look up similar-looking words in its dictionary of indexed terms and offer "summer holiday" as a "Did you mean?" hint.
• The similarity bar is adjustable: short words (3–5 letters) need a higher similarity to trigger a suggestion than long words, which can tolerate more typos. Defaults are 70% for short words, 60% for medium, and 50% for long.
• Freedam only shows the "Did you mean?" banner when the original query returned 3 or fewer results — this stops the hint from appearing on successful searches. That cut-off can be raised or lowered.
• If the original search returned zero results, Freedam can also automatically fall back to the corrected spelling and show those results directly.

Suggestions (search-as-you-type)

• Suggestions start appearing after the user types 2 characters by default.
• Freedam gathers up to 40 raw candidates from a mix of exact matches, prefix matches, fuzzy matches, and semantic matches, and then re-ranks them using two sets of weights:
  • Match type: an exact match is worth 100%, a prefix match 90%, a contains-match 70%, a fuzzy match 60%, a semantic match 60%, a trigram match 45%.
  • Suggestion type: field names get a 1.2x boost, tags and collections 1.1x, metadata and values 1.0x, the asset itself 0.9x, concepts 0.8x, and semantic-only asset hits 0.75x.
• The Semantic Match Threshold (default 0.35) is the bar a semantic suggestion must clear to show up at all — raise it for stricter results, lower it for more adventurous matches.

Who can use it

The Search Configuration page is limited to users with the "system settings" administrator permission. That covers workspace owners and senior administrators; regular content managers and marketers will not see the page in the Administration menu.

What happens behind the scenes

• Setting changes are applied live, but they only affect new searches. Historical search logs are not touched.
• Changes to what is indexed (the "Include" toggles), or changes to how content is broken into words (the Language Map) only take full effect after the search index has been refreshed. Freedam will re-index gradually on its own as assets are updated, but for a big change you should trigger a manual rebuild to bring everything in line immediately.
• Rebuilding the index runs in the background, one active language at a time. While it runs, searches continue to work — they use the current index until the fresh copy is ready. A rebuild can take from a few minutes on a small library to a couple of hours on very large libraries; it is safe to navigate away and come back.
• If you have no active languages configured, rebuilding will be blocked with a friendly error — activate at least one language first.
• Quick filter changes (reordering or removing) take effect immediately for every user in the gallery the next time they load the page. No re-indexing required.

Good to know

• Boolean, date and numeric metadata fields are intentionally not shown in the Metadata Overrides table — it is not meaningful to "boost" a number or a date, so these fields use separate filter mechanisms rather than text relevance.
• Vector dimensions and embedding language strategy are advanced settings that affect how AI understands your content. They are safe to leave on the defaults (768-dimensional multilingual embeddings) unless you are working with a specialist dataset.
• Accent handling is off by default — searching for "cafe" will not automatically match "café". Turn on "Remove accents from text before embedding" if your workspace is multilingual and users switch between accented and unaccented spellings.

Tips and Best Practices

• Start with Defaults: Most boost values are set to 2 or 3 by default. Only increase a boost to 5 for highly unique identifiers like "SKU" or "Asset ID."
• Typo Tolerance: Enable this if your users frequently search on mobile devices or if your metadata contains complex technical terms.
• Stemming: In the Language Map, use the specific language configuration (e.g., "German") rather than "Simple" to ensure that searches for "Running" also find "Run."
• Rebuild Sparingly: You do not need to rebuild the index for every setting change. Only rebuild if search results seem inconsistent or after a large bulk import of legacy data.

Troubleshooting

Issue: Metadata field not appearing in Overrides

• Symptoms: A specific metadata field is missing from the Metadata Overrides table.
• Cause: Only text-based fields (string, text, textarea, select, vocabulary) are indexed for full-text search.
• Fix: Check the field type in the Metadata settings. Boolean, Date, and Integer fields cannot be configured for text-based boosting.

Issue: Search results are slow or irrelevant

• Symptoms: Search takes several seconds to load or returns unrelated assets.
• Cause: BM25 top-k or Vector top-k values may be set too high, or Semantic Match Threshold is too low.
• Fix:
  1. Go to Hybrid Tuning.
  2. Ensure BM25 top-k and Vector top-k are near the default of 100.
  3. Increase the Semantic Match Threshold in the Suggestions tab to filter out weak matches.

Issue: Changes not taking effect

• Symptoms: Settings were changed but search behavior remains the same.
• Cause: The changes were not saved, or the index needs a refresh.
• Fix:
  1. Ensure you clicked Save Settings (the button should be disabled after a successful save).
  2. If behavior persists, perform a Rebuild Search Index from the operations tab.