Choose an Aggregation Pipeline Stage

Definition

The $search stage performs a full-text search on the specified field or fields which must be covered by an Atlas Search index.

$search

A $search pipeline stage has the following prototype form:

{
  $search: {
    "index": "<index-name>",
    "<operator-name>"|"<collector-name>": {
      <operator-specification>|<collector-specification>
    },
    "highlight": {
      <highlight-options>
    },
    "count": {
      <count-options>
    },
    "returnStoredSource": true | false
  }
}

Fields

The $search stage takes a document with the following fields:

Behavior

$search must be the first stage of any pipeline it appears in. $search cannot be used in:

• a view definition

• a $facet pipeline stage

Aggregation Variable

$search returns only the results of your query. The metadata results of your $search query are saved in the $$SEARCH_META aggregation variable. You can use the $$SEARCH_META variable to view the metadata results for your $search query. The $$SEARCH_META aggregation variable can be used anywhere after a $search stage in any pipeline, but it can't be used after the $lookup or $unionWith stage in any pipeline. The $$SEARCH_META aggregation variable can't be used in any subsequent stage after a $searchMeta stage.

{
  "mappings": {
    "dynamic": false,
    "fields": {
      "released": {
        "type": "date"
      }
    }
  }
}

db.movies.aggregate([
  {
    "$search": {
      "near": {
        "path": "released",
        "origin": ISODate("2011-09-01T00:00:00.000+00:00"),
        "pivot": 7776000000
      }
    }
  },
  {
    $project: {
      "_id": 0,
      "title": 1,
      "released": 1
    }
  },
  {
    "$facet": {
      "docs": [
        {"$limit": 5}
      ],
      "meta": [
        {"$replaceWith": "$$SEARCH_META"},
        {"$limit": 1}
      ]
    }
  }
])

{
  "docs" : [
    {
      "title" : "Submarino",
      "released" : ISODate("2011-09-01T00:00:00Z")
    },
    {
      "title" : "Devil's Playground",
      "released" : ISODate("2011-09-01T00:00:00Z")
    },
    {
      "title" : "Bag It",
      "released" : ISODate("2011-09-01T00:00:00Z")
    },
    {
      "title" : "Dos",
      "released" : ISODate("2011-09-01T00:00:00Z")
    },
    {
      "title" : "We Were Here",
      "released" : ISODate("2011-09-01T00:00:00Z")
    }
  ],
  "meta" : [
    { "count" : { "lowerBound" : NumberLong(17373) } }
  ]
}

Definition

The $searchMeta stage returns different types of metadata result documents.

$searchMeta

A $searchMeta pipeline stage has the following prototype form:

{
  $searchMeta: {
    "index": "<index-name>",
    "<collector-name>"|"<operator-name>": {
      <collector-specification>|<operator-specification>
    },
    "count": {
      <count-options>
    }
  }
}

Fields

The $searchMeta stage takes a document with the following fields:

Behavior

The $searchMeta stage must be the first stage in any pipeline.

Metadata Result Types

The structure of the metadata results document that is returned by the $searchMeta stage varies based on the type of results. Atlas Search supports the following result types:

Initial Sync

Atlas Search can't perform $search queries against an Atlas cluster during an initial sync process. An initial sync process occurs when you create a new cluster or perform certain upgrades on a cluster. The process includes the following steps:

1. The mongod performs an initial sync.

2. The mongot performs an initial sync, which rebuilds the search indexes.

As a result, you may receive an error when running a $search query against a node that you recently created or upgraded. Try your query again after the initial syncs complete and mongot rebuilds the indexes. You can check the status of the mongot initial sync using the following steps:

1. Click the Search tab for your database deployment.

2. In the index's Status column, click View Status Details.

3. Check the state of the index for the node. During mongot initial sync, the status is INITIAL SYNC. When mongot finishes rebuilding the index, the status is ACTIVE.

mongot Process Not Installed or Running

The following error is returned if you run $search queries when the Atlas Search mongot process isn't installed or running:

MongoError: Remote error from mongot :: caused by :: Error connecting to localhost:28000.

The mongot process is installed only when the first Atlas Search index is defined. If you don't have any Atlas Search index in your Atlas cluster, create at least one Atlas Search index to resolve this error.