Operate search

This guide is for team admins who operate Uniform Search for a project. It tells you how to re-index the search index and keep it up to date. It also tells you how to monitor search, manage keys, and move configuration.

Who can operate search#

The Uniform Search tool is visible only to team admins. Other users do not see it in Tools. In the Uniform Search tool, all team admins can do all the tasks on this page.

Uniform Search saves the name of the user with each action. The indexing history shows the user in Triggered by. The Connect drawer shows the user who made the search API key.

Content authors do not need the Uniform Search tool. They use the search components and the data connector in Canvas. For more information, see build search experiences.

Open the Uniform Search tool#

1. In the Uniform dashboard, open your project.
2. In the project navigation, select Tools.
3. Click Uniform Search.

The Uniform Search tool has 5 tabs: Overview, Schema, Search, Relevance, and Analytics. The status strip is above the tabs. It is on every tab.

The status strip#

The status strip shows the state of the search index. It also has the controls for a re-index and for the search API key.

The status strip above the tabs of the Uniform Search tool

The Re-index button does not show before a search collection exists. On a new project, start from the Overview tab.

Check the health of search#

The health dot shows the result of a set of health checks. The Uniform Search tool does the checks again every 60 seconds.

To see the result of each check, do these steps:

1. In the status strip, click the health dot.
2. Read the chip of each check: pass, warn, or fail.
3. To do the checks again now, click Re-check.

The cluster health panel with the result of each check

These checks are the most important for you:

The panel can show more checks for internal services. A warn chip does not change the overall status.

If a check shows fail, contact Uniform support. These failures come from the server side, and you cannot correct them in the Uniform Search tool. One exception is the Semantic search check: if its detail tells you to run a re-index, re-index the search index.

The Overview tab#

The Overview tab is the first tab of the Uniform Search tool. Its title is Search overview. Below the title, you see the locales of the search index and the default locale.

The Overview tab with the stat cards, the indexing history, and the top queries

The stat cards give a summary of the search index:

If Semantic coverage is less than 100%, some documents did not get a vector. Visitors can find these documents with keyword search, but semantic search does not find them. The next re-index corrects this.

Below the stat cards, you find 2 panels:

• Indexing history shows the last runs. Click View all → to open the Indexing history drawer.
• Top queries shows the most popular queries of the last 7 days. Click Analytics → to open the Analytics tab.

When to re-index#

A re-index (a full rebuild) of the search index reads all content again. It includes all content in the indexing scope, for all locales.

Do a re-index in these conditions:

You do not need a re-index in these conditions:

How a re-index works#

A re-index has zero downtime. Visitors can search during the full run.

Uniform Search builds a new version of each search collection next to the live version. The live version continues to answer searches. When the new version of a locale is complete, it replaces the live version of that locale. If the run fails or you cancel it, Uniform Search discards the new version. The live version does not change.

A re-index includes these search sources:

• Entries, compositions, and assets in the indexing scope.
• Pull sources that are on. A pull source with the update strategy Manually is not part of a re-index. Uniform Search keeps its documents.
• Push sources. Uniform Search keeps their documents, because your system sends them.

Content changes that authors publish during a re-index are not lost. Uniform Search adds them to the new version before the new version goes live.

Only 1 indexing run can be in progress for a project at a time. This applies to a re-index and to a source refresh. If you start a re-index while a run is in progress, the Uniform Search tool shows the progress of that run.

If a re-index does not complete in 6 hours, Uniform Search stops it. The live version of the search index does not change.

The duration of a re-index depends on the quantity of content, the number of locales, computed fields, and file parsers. For example, in 1 test, a re-index of about 20,000 documents in 2 locales took about 1.4 minutes. Your results can be different.

Re-index the search index#

1. In the status strip, click Re-index.

   The Re-index button changes to a progress pill. The pill shows Re-indexing and the percentage of the run.

2. To see the progress, click the progress pill.

   The Re-indexing content panel opens.

3. Continue your work, or close the panel.

   tip

   The re-index continues in the background. It continues if you reload the page or close the Uniform Search tool. Other admins see the same progress.

4. When the pill shows Re-indexed, click the pill.

5. In the Re-indexing complete panel, click Done.

While a re-index is in progress, you cannot edit the Schema tab.

If the progress pill does not show after you click Re-index, the run did not start. Wait 1 minute, and then click Re-index again. If the run does not start again, open the Cluster health panel. If a check shows fail, contact Uniform support.

The progress panel#

The progress panel of a re-index with a bar for each locale

Cancel a re-index#

When you cancel a re-index, the live version of the search index does not change. Uniform Search discards the new version.

1. In the status strip, click the progress pill.

2. In the panel footer, click Cancel run.

   The panel shows the text Stop? Live index is unaffected.

3. Click Confirm.

The indexing history shows the run with the status cancelled.

Refresh a pull source#

You can get new data from 1 pull source without a full re-index. A source refresh updates the documents of that source in the live search index. Search stays available during the refresh.

1. Open the Schema tab.

2. Open the External sources sub-tab.

3. On the row of the pull source, click the More actions menu (⋯).

4. Click Refresh now.

   The status strip shows a progress pill with the text Refreshing source.

The Refresh now action on a pull source

Refresh now is available only for pull sources that are on. A push source does not need a refresh, because your system sends its records.

If the row of a pull source shows last refresh failed, put the pointer on the text to see the error. Correct the problem in the source, and then click Refresh now again.

Incremental updates#

Incremental updates keep the search index up to date without a re-index. When an author publishes or deletes content in Uniform, Uniform sends a webhook to Uniform Search. Uniform Search then updates only the related documents, in all locales of the indexing scope.

The Uniform team sets up the webhooks for your project. You do not need to do this. For more information about webhooks in Uniform, see webhooks.

Uniform Search handles these 9 events:

Incremental updates obey the indexing scope. If a type or a locale is not in the scope, Uniform Search skips the document. Computed fields and file parsers apply in the same way as in a re-index. For more information about project map nodes, see project maps.

Make sure that incremental updates work#

1. In Uniform, publish an entry or a composition that is in the indexing scope.

2. In the Uniform Search tool, in the status strip, click history.

3. Find the newest run with the operation Incremental (webhook).

4. Click the row to open the run detail.

5. Read the Entity, Locales, and Skipped fields.

6. Read the message at the top of the run detail.

   The message tells you how many locale collections Uniform Search updated. If Uniform Search skipped the document, the message gives the reason.

7. Open the Search tab, and search for the changed content.

The run detail of an incremental update

If no Incremental (webhook) run shows after you publish content, contact Uniform support. The webhook possibly did not get to Uniform Search.

Indexing history#

The Indexing history drawer shows each indexing run and each schema change for the project. The newest run is at the top.

To open the drawer, do one of these steps:

• In the status strip, click history.
• On the Overview tab, in the Indexing history panel, click View all →.

The indexing history drawer with filters and a list of runs

Use the filters to find a run:

• All statuses
• All locales
• All sources: Entries, Compositions, Assets, or Schema.

The table has the columns When, Scope, Locales, Counts, Duration, and Status. To see older runs, click Load more.

The history shows these operations:

The Status column shows one of these values:

Run detail#

Click a row to open the Run detail view. To go back to the list, click ← All runs.

The run detail shows these items:

• A callout with the result and a message. The result is Completed, Completed with issues, or Failed.
• The Run section: Operation, Status, Started, Triggered by, Duration, Locales, Documents, Skipped, Failed, and Entity. Some fields show only for some operations.
• The Indexed per locale section: the number of documents from each source, for each locale.
• The Log section: the log lines of the run. The history keeps a maximum of 200 log lines for each run.

The history keeps the last 1,000 indexing runs and the last 1,000 schema changes. Uniform Search deletes older entries automatically.

Find the cause of a failed run#

1. Open the Indexing history drawer.
2. In the All statuses filter, select failed or partial.
3. Click the run to open the run detail.
4. Read the message in the callout at the top.
5. Read the Log section. Look for the documents or the sources that failed.
6. If the cause is in your content or in an external source, correct it.
7. Start a new re-index.

If the same run fails again, contact Uniform support. Give them the run ID from the progress panel or from the run detail.

Search analytics#

Search analytics shows what your visitors search for and what they click. It is off by default. By default, queries from the Search tab of the Uniform Search tool are not part of analytics.

Turn on analytics#

Analytics is off for a new project. You must turn it on before Uniform Search records searches and clicks.

1. Open the Analytics tab.

   If analytics is off, the tab shows Search analytics is off.

2. Click Enable analytics.

   The tab shows the Overview sub-tab with no data. The Searches and Clicks tiles show needs snapshot history. The Popular queries panel shows No captured queries yet.

3. Set up click tracking in your front end. For more information, see set up click tracking.

The first data shows after about 5 minutes. After that, the data updates about every 5 minutes. Only queries that give results show in Popular queries.

If you cannot turn on analytics, contact your Uniform representative.

Set up click tracking#

Uniform Search records searches automatically when analytics is on. It does not record clicks automatically. Your front end must report each click on a search result. Until it does, the Clicks tile and the Top clicked documents panel stay empty.

When no clicks are recorded, the Top clicked documents panel shows the code to report clicks. The code already contains the Search URL and the project ID of your project.

The Analytics tab after you turn on analytics, with the click tracking code

To report clicks, do these steps:

1. Get the search API key. In the status strip, click Connect. For more information, see manage search API keys.

2. In the Top clicked documents panel, click Copy to copy the code.

3. Add the code to your front end. Call trackClick when a visitor clicks a search result. Use the ID of the clicked document and the locale of the search.

   If you cannot use the @uniformdev/search package, expand Or send the request directly. Then send a POST request to the /api/track endpoint from your front end. Replace <your-search-api-key> with the search API key. Browser requests must come from an allowed origin. To add the domain of your site, contact your Uniform representative.

4. Deploy your front end.

5. On your site, search and click a result.

6. After about 5 minutes, make sure that the Clicks tile and the Top clicked documents panel show the click.

For more information about trackClick and the /api/track endpoint, see report clicks on results.

If the Click tracking feature is off in the Settings sub-tab, Uniform Search does not record clicks. For more information, see change the analytics settings.

Read the analytics#

The Analytics tab has 2 sub-tabs: Overview and Settings. On the Overview sub-tab, select a time range: 7 days, 30 days, 1 year, or All time. To see the data of 1 locale, use the Locale filter.

The Overview sub-tab of the Analytics tab

The Top clicked documents panel needs click events from your front end. If the panel is empty, see set up click tracking.

Act on the analytics#

Use the analytics to improve the relevance of search. The actions open the Relevance tab with the query already filled in.

To add a synonym for a query without results, do these steps:

1. In the Zero-result queries panel, click the menu (⋯) on the row of the query.
2. Click Add synonym.
3. In the Relevance tab, complete the synonym, and save it.

To change the results of a popular query, do these steps:

1. In the Popular queries panel, click the menu (⋯) on the row of the query.
2. Click Curate results.
3. In the Relevance tab, complete the curation, and save it.

For more information about synonyms and curations, see configure search.

Export analytics data#

1. In a panel, click View all →.
2. Optional: filter the list by Query, Language, Type, or Period.
3. Click Export CSV.

The CSV file contains the rows that agree with your filters.

Change the analytics settings#

Open the Analytics tab, and then open the Settings sub-tab.

The Settings sub-tab of the Analytics tab

Manage search API keys#

The search API key lets your front end send search queries and report clicks. It cannot change the search index. It is safe to use in client code. Each project has 1 current search API key. The key starts with ufs..

You manage the key in the Connect your frontend drawer. To open it, click Connect in the status strip. The drawer also shows the Search URL of your project.

The Connect your frontend drawer with the search URL and the search API key

Generate a search API key#

1. In the status strip, click Connect.
2. Click Generate key.
3. Copy the key, or click Copy as .env.
4. Keep the key in a safe location, for example in the environment variables of your front end.
5. Click I’ve stored the key.

After this, the drawer shows only the start and the end of the key. It also shows the date and the user who made the key.

Rotate the search API key#

Rotate the key if you think that it is not safe, or as a regular security task. The old key continues to work for 24 hours. This gives you time to update your front ends without downtime.

1. In the status strip, click Connect.
2. Click Rotate API key.
3. In the Rotate the search key? dialog, click Rotate key.
4. Copy the new key, and keep it in a safe location.
5. Update all front ends that use the old key.

The drawer shows the date and time when the old key becomes invalid.

Revoke the old search API key now#

1. In the status strip, click Connect.
2. In the callout about the old key, click Revoke now.
3. In the Revoke the previous key now? dialog, click Revoke now.

The old key becomes invalid. It can take up to 60 seconds before all servers reject the old key.

Manage push API keys#

Each push source has its own push API key. Your system uses this key to send records to Uniform Search. Use the push API key only from a server. Do not put it in client code.

Uniform Search shows a push API key 1 time only. This occurs when you make the push source, and when you rotate its key. The dialog is Save this API key now or New API key for this source. Copy the key before you click I’ve saved it.

To rotate a push API key, do these steps:

1. Open the Schema tab.
2. Open the External sources sub-tab.
3. On the row of the push source, click Edit source (pen icon).
4. Click Rotate API key.
5. In the Rotate this API key? dialog, click Rotate key.
6. Copy the new key.
7. Update your system with the new key.

For more information about push sources, see configure search.

Move configuration between projects or environments#

You can export the search configuration from 1 project and import it into a different project or environment. The files do not contain a project ID.

The exports do not contain secrets. After an import, enter the credentials of each pull source again. Search API keys, push API keys, analytics settings, and the indexing history are not part of an export.

The menu of the Schema tab with the export and import actions

Export the schema#

1. Open the Schema tab.
2. Click the menu (⋯).
3. Click Export schema.

The browser downloads the file.

Import the schema#

1. Open the Schema tab of the target project.
2. Click the menu (⋯).
3. Click Import schema.
4. Select the exported file.
5. In the Overwrite existing configuration? dialog, click Overwrite & import.
6. If a dialog tells you that an external source already exists, enter a new Source type, and then click Import.
7. Enter the credentials of each pull source again.
8. In the status strip, click Re-index.

Import the relevance settings#

1. Open the Relevance tab of the target project.

2. Click the menu (⋯).

3. Click Import relevance settings.

4. Select the relevance-settings.json file.

5. Select the items to import.

   info

   An item with the text already exists — will be overridden replaces the item with the same name.

6. Click Import.

7. For each imported synonym set and curation set, turn on Use in this project.

Imported synonym sets and curation sets are not active in the project until you turn on Use in this project.

Import an external source#

1. Open the Schema tab of the target project.
2. Open the External sources sub-tab.
3. Click Add source.
4. Click Import external data.
5. Select the exported file.
6. Enter the credentials of the source again.
7. On the row of the source, click the menu (⋯), and then click Refresh now.

Monitor search from your own tools#

The Uniform team monitors the search infrastructure. You can also connect your own uptime tool to the health endpoint of your project. The endpoint does not need a key.

The health endpoint is GET /api/health on the Search URL of your project. You find the Search URL in the Connect your frontend drawer. Replace YOUR_SEARCH_URL with that URL.

If the service is available, the endpoint returns HTTP status 200 and a JSON body with "status": "ok". If it is not available, the endpoint returns HTTP status 503 and "status": "error". Use the HTTP status code in your uptime tool. Do not use other fields of the body, because they can change.

The endpoint accepts only GET requests. It checks only the search service. For the full set of checks, open the Cluster health panel in the Uniform Search tool.

Troubleshooting#

Next steps#

• Configure search: set the schema, the indexing scope, computed fields, external sources, and relevance.
• Search SDK and API: connect your front end with the search API key and send click events.
• Build search experiences: add the search components to compositions in Canvas.
• Roles and permissions: give the team admin role to the persons who operate search.
• Webhooks: learn how Uniform sends events when content changes.