Track Search Terms

On this page

Syntax

Options
Behavior
Output
Examples

The Atlas Search tracking option allows you to track your search queries. When you track your queries, Atlas tracks the search terms and provides analytics information about the search terms in your queries. You can use the analytics information to improve the quality of your search application and to refine your query to return relevant results.

Note

You must have an M10 or higher cluster to take advantage of the analytics information returned by Atlas Search tracking option. Atlas doesn't track search terms or display analytics for queries on free and shared-tier clusters.

Syntax

{
  $search: {
    "index": "<index name>",
    "<operator>": {
      <operator-specification>
    },
    "tracking": {
      "searchTerms": "<term-to-search>"
    }
  }
}

Options

Field	Type	Description	Necessity
`searchTerms`	string	Text or term associated with the query to track. You can specify only one term per query.	Required

Behavior

For each Atlas Search index on your Atlas cluster, Atlas collects the following metrics for the tracked search terms that were run using that index:

Number of Atlas Search queries for the tracked terms.
Number of times Atlas Search didn't return any results for queries for the tracked terms.

Atlas counts the number of queries per day for tracked search terms. Atlas has a limit on the number of search terms that it captures per cluster each day from tracked $search queries. Once Atlas reaches the limit, it doesn't capture new, unique search terms. However, if you run queries for previously tracked terms for the day after Atlas reaches the limit and stops capturing, Atlas continues to increment the counter for those terms regardless of the limit for the day.

Atlas resets the terms that are tracked, the count for the terms that are tracked, and the limit on the number of tracked search terms at the beginning of each day in UTC.

Example

This example demonstrates how Atlas counts the terms that are tracked. Suppose you run queries for the term summer on:

Day 1 before Atlas reaches the limit on the number of tracked search terms for that day. Then on Day 1, Atlas counts the number of queries for summer and metrics are available for summer if summer is one of the top search terms on that day.
Day 2 before and after Atlas reaches the limit on the number of tracked search terms for that day. Then on Day 2, Atlas counts the number of queries for summer before and after it reaches the limit for the number of tracked search terms and metrics are available for summer if summer is one of the top search terms on that day.
Day 3 after Atlas reaches the limit on the number of tracked search terms for that day. Then on Day 3, Atlas doesn't count the query for term summer and metrics aren't available for summer on that day.

Atlas Search doesn't use the term that you specify with the tracking option to process the query. Also, the search term that you specify with the tracking option doesn't have any effect on the results that Atlas Search returns for the query.

Output

You can view metrics for the queries tracked using the tracking option in the Atlas UI Query Analytics page for an Atlas Search index. To learn more, see Navigate to the Query Analytics Page.

The Query Analytics page displays the following metrics for a predefined date range such as the current day, last 7 days, last 30 days, or last 90 days, or a custom range (in UTC) that you specify, with a per day granularity:

To learn more, see View Query Analytics.

Examples

The following query against the sample_mflix.movies collection searches the title field for the term summer. The query uses the tracking option (highlighted) to enable Atlas Search to capture analytics information for the query term summer. If you have the sample data on your cluster and an Atlas Search index named default on the title field in the collection, you can run the following query against the sample_mflix.movies collection on your cluster. To learn more about loading the sample data and creating an Atlas Search index, see Get Started with Atlas Search tutorial.

db.movies.aggregate([
  {
    "$search": {
      "text": {
        "query": "summer",
        "path": "title"
      },
      "tracking": {
        "searchTerms": "summer"
      }
    }
  },
  {
    "$limit": 5
  },
  {
    "$project": {
      "_id": 0,
      "title": 1
    }
  }
])

[
  { title: 'Summer' },
  { title: 'Summer Stock' },
  { title: 'Early Summer' },
  { title: 'Summer Interlude' },
  { title: 'Violent Summer' }
]

If you run this query, you can view metrics for it in the Query Analytics page for the index if Atlas collected data for the tracked search term. To learn more, see View Query Analytics.