Docs Menu
Docs Home
/
Atlas
/
MongoDB Search
/
Design Search for Your Data Model

Use Views with MongoDB Search

You can create a MongoDB Search index on a View to transform documents and collections so that you can partially index a collection, support incompatible data types or data models, and more.

The following examples use the sample_mflix and sample_airbnb sample databases.

➤ Use the Select your language drop-down menu to set the interface for the examples on this page.

Note

Disambiguation

This page discusses standard views. To learn about on-demand materialized views, see On-Demand Materialized Views.

To learn about the differences between the view types, see Comparison with On-Demand Materialized Views.

Requirements

You must use MongoDB 8.0 or higher.

To edit a View, you must have a User Admin role and use the collMod database command.

Limitations

  • MongoDB Search supports Views with the following stages:

  • Index names must be unique across a source collection and all of its Views.

  • MongoDB Search doesn't support view definitions with operators that produce dynamic results, such as the $$USER_ROLES system variable and the $rand aggregation operator.

  • MongoDB Search queries return the original documents as they appear in the source collection.

  • To retrieve the transformed document, use the storedSource option.

Example: Filter Documents

To create a View, you must have the createCollection privilege.

You can partially index a collection to filter documents. The following example creates a View on the sample_mflix.movies collection so that you can search for only movies released after January 1, 2000.

1

Connect to your cluster using mongosh.

To learn more, see Connect to a Cluster via mongosh.

2

Switch to the sample_mflix database.

use sample_mflix
3

Create a movies_ReleasedAfter2000 View.

db.createView(
  "movies_ReleasedAfter2000",
  "movies",
  [
    {
      $match: {
        $expr: {
          $gt: [
            "$released",
            ISODate("2000-01-01")
          ]
        }
      }
    }
  ]
)
4

In Atlas, go to the Clusters page for your project.

WARNING: Navigation Improvements In Progress We're currently rolling out a new and improved navigation experience. If the following steps don't match your view in the Atlas UI, see the preview documentation.

  1. If it's not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.

  2. If it's not already displayed, select your desired project from the Projects menu in the navigation bar.

  3. If it's not already displayed, click Clusters in the sidebar.

    The Clusters page displays.

5

Go to the MongoDB Search page for your cluster.

You can go the MongoDB Search page from the sidebar, the Data Explorer, or your cluster details page.

  1. In the sidebar, click Atlas Search under the Services heading.

    If you have no clusters, click Create cluster to create one. To learn more, see Create a Cluster.

  2. If your project has multiple clusters, select the cluster you want to use from the Select cluster dropdown, then click Go to Atlas Search.

    The Atlas Search page displays.

  1. Click the Browse Collections button for your cluster.

  2. Expand the database and select the collection.

  3. Click the Search Indexes tab for the collection.

    The Atlas Search page displays.

  1. Click the cluster's name.

  2. Click the Atlas Search tab.

    The Atlas Search page displays.

6

Click Create Search Index.

7

Start your index configuration.

Make the following selections on the page and then click Next.

Search Type

Select the MongoDB Search index type.

Index Name and Data Source

Specify the following information:

  • Index Name: releasedAfter2000Index

  • Database and Collection:

    • sample_mflix

    • movies_ReleasedAfter2000

Configuration Method

For a guided experience, select Visual Editor.

To edit the raw index definition, select JSON Editor.

IMPORTANT:

Your MongoDB Search index is named default by default. If you keep this name, then your index will be the default Search index for any MongoDB Search query that does not specify a different index option in its operators. If you are creating multiple indexes, we recommend that you maintain a consistent, descriptive naming convention across your indexes.

8

Click Create Search Index.

Atlas displays a Toast (brief, non-interactive notification) to let you know your index is building.

9

Check the status.

The newly created index appears on the Atlas Search tab. While the index is building, the Status field reads Build in Progress. When the index is finished building, the Status field reads Active.

IMPORTANT: Larger collections take longer to index. You will receive an email notification when your index is finished building.

10

Run a query on the releasedAfter2000Index partial index.

Note

The following example queries the releasedAfter2000Index index by running the .aggregate command against the View named movies_ReleasedAfter2000. If your cluster is running MongoDB v8.0, you must query the source collection (for example, movies) using the index on the View. Upgrade to MongoDB v8.1+ to query the View directly.

use sample_mflix
db.movies_ReleasedAfter2000.aggregate([
  {
    $search: {
      index: "releasedAfter2000Index",
      text: {
        path: "title",
        query: "foo"
      },
      sort: {
        released: 1
      }
    }
  }
])
[
  {
    _id: ObjectId('573a13d2f29313caabd929f8'),
    plot: "Rising from the ashes of Nirvana, the Foo Fighters became a Grammy-winning sensation on their own. Sixteen years of the band's history comes to life in this documentary, from their demo ...",
    genres: [ 'Documentary', 'Music' ],
    runtime: 150,
    cast: [
      'Shawn Cloninger',
      'William Goldsmith',
      'Jessy Greene',
      'Dave Grohl'
    ],
    num_mflix_comments: 0,
    poster: 'https://m.media-amazon.com/images/M/MV5BMzE4OTczMTgxM15BMl5BanBnXkFtZTcwNTU1NjQxOA@@._V1_SY1000_SX677_AL_.jpg',
    title: 'Foo Fighters: Back and Forth',
    fullplot: `Rising from the ashes of Nirvana, the Foo Fighters became a Grammy-winning sensation on their own. Sixteen years of the band's history comes to life in this documentary, from their demo tapes through the creation of their 2011 album, "Wasting Light."`,
    languages: [ 'English' ],
    released: ISODate('2011-04-05T00:00:00.000Z'),
    directors: [ 'James Moll' ],
    awards: { wins: 1, nominations: 1, text: '1 win & 1 nomination.' },
    lastupdated: '2015-08-19 00:00:25.937000000',
    year: 2011,
    imdb: { rating: 8.4, votes: 3745, id: 1853563 },
    countries: [ 'USA' ],
    type: 'movie',
    tomatoes: {
      viewer: { rating: 4.4, numReviews: 857, meter: 96 },
      dvd: ISODate('2011-08-08T00:00:00.000Z'),
      website: 'http://us.foofightersfilm.com/',
      production: 'Cinedigm Digital Cinema',
      lastUpdated: ISODate('2015-09-12T18:42:01.000Z')
    }
  }
]
1

Connect to your MongoDB Deployment using mongosh.

To learn more, see Connect to a Cluster via mongosh.

2

Switch to the sample_mflix database.

use sample_mflix
3

Create a movies_ReleasedAfter2000 View.

db.createView(
  "movies_ReleasedAfter2000",
  "movies",
  [
    {
      $match: {
        $expr: {
          $gt: [
            "$released",
            ISODate("2000-01-01")
          ]
        }
      }
    }
  ]
)
4

Create a MongoDB Search index on the View.

db.movies_ReleasedAfter2000.createSearchIndex(
  "releasedAfter2000Index",
  {
    "mappings": {
      "dynamic": true
    }
  }
)
5

Run a query on the releasedAfter2000Index partial index.

Note

The following example queries the releasedAfter2000Index index by running the .aggregate command against the View named movies_ReleasedAfter2000. If your cluster is running MongoDB v8.0, you must query the source collection (for example, movies) using the index on the View. Upgrade to MongoDB v8.1+ to query the View directly.

use sample_mflix
db.movies_ReleasedAfter2000.aggregate([
  {
    $search: {
      index: "releasedAfter2000Index",
      text: {
        path: "title",
        query: "foo"
      },
      sort: {
        released: 1
      }
    }
  }
])
[
  {
    _id: ObjectId('573a13d2f29313caabd929f8'),
    plot: "Rising from the ashes of Nirvana, the Foo Fighters became a Grammy-winning sensation on their own. Sixteen years of the band's history comes to life in this documentary, from their demo ...",
    genres: [ 'Documentary', 'Music' ],
    runtime: 150,
    cast: [
      'Shawn Cloninger',
      'William Goldsmith',
      'Jessy Greene',
      'Dave Grohl'
    ],
    num_mflix_comments: 0,
    poster: 'https://m.media-amazon.com/images/M/MV5BMzE4OTczMTgxM15BMl5BanBnXkFtZTcwNTU1NjQxOA@@._V1_SY1000_SX677_AL_.jpg',
    title: 'Foo Fighters: Back and Forth',
    fullplot: `Rising from the ashes of Nirvana, the Foo Fighters became a Grammy-winning sensation on their own. Sixteen years of the band's history comes to life in this documentary, from their demo tapes through the creation of their 2011 album, "Wasting Light."`,
    languages: [ 'English' ],
    released: ISODate('2011-04-05T00:00:00.000Z'),
    directors: [ 'James Moll' ],
    awards: { wins: 1, nominations: 1, text: '1 win & 1 nomination.' },
    lastupdated: '2015-08-19 00:00:25.937000000',
    year: 2011,
    imdb: { rating: 8.4, votes: 3745, id: 1853563 },
    countries: [ 'USA' ],
    type: 'movie',
    tomatoes: {
      viewer: { rating: 4.4, numReviews: 857, meter: 96 },
      dvd: ISODate('2011-08-08T00:00:00.000Z'),
      website: 'http://us.foofightersfilm.com/',
      production: 'Cinedigm Digital Cinema',
      lastUpdated: ISODate('2015-09-12T18:42:01.000Z')
    }
  }
]

Example: Add or Modify Fields

The following example lets you search the sample_airbnb.listingsAndReviews collection for accomodatations based on a new totalPrice field, which is the sum of the price and cleaningFee fields. Also, since MongoDB Search doesn't support Decimal128 types, we transform the values to Double.

1

Connect to the cluster using mongosh.

To learn more, see Connect to a Cluster via mongosh.

2

Switch to the sample_airbnb database.

use sample_airbnb
3

Create a listingsAndReviews_totalPrice View.

db.createView(
  "listingsAndReviews_totalPrice",
  "listingsAndReviews",
  [
    {
      $addFields: {
        totalPrice: {
          $add: [
            {
              $ifNull: [{ $toDouble: "$price" }, 0]
            },
            {
              $ifNull: [{ $toDouble: "$cleaning_fee" }, 0]
            }
          ]
        }
      }
    }
  ]
)
4

In Atlas, go to the Clusters page for your project.

WARNING: Navigation Improvements In Progress We're currently rolling out a new and improved navigation experience. If the following steps don't match your view in the Atlas UI, see the preview documentation.

  1. If it's not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.

  2. If it's not already displayed, select your desired project from the Projects menu in the navigation bar.

  3. If it's not already displayed, click Clusters in the sidebar.

    The Clusters page displays.

5

Go to the MongoDB Search page for your cluster.

You can go the MongoDB Search page from the sidebar, the Data Explorer, or your cluster details page.

  1. In the sidebar, click Atlas Search under the Services heading.

    If you have no clusters, click Create cluster to create one. To learn more, see Create a Cluster.

  2. If your project has multiple clusters, select the cluster you want to use from the Select cluster dropdown, then click Go to Atlas Search.

    The Atlas Search page displays.

  1. Click the Browse Collections button for your cluster.

  2. Expand the database and select the collection.

  3. Click the Search Indexes tab for the collection.

    The Atlas Search page displays.

  1. Click the cluster's name.

  2. Click the Atlas Search tab.

    The Atlas Search page displays.

6

Click Create Search Index.

7

Start your index configuration.

Make the following selections on the page and then click Next.

Search Type

Select the MongoDB Search index type.

Index Name and Data Source

Specify the following information:

  • Index Name: totalPriceIndex

  • Database and Collection:

    • sample_airbnb

    • listingsAndReviews_totalPrice

Configuration Method

For a guided experience, select Visual Editor.

To edit the raw index definition, select JSON Editor.

IMPORTANT:

Your MongoDB Search index is named default by default. If you keep this name, then your index will be the default Search index for any MongoDB Search query that does not specify a different index option in its operators. If you are creating multiple indexes, we recommend that you maintain a consistent, descriptive naming convention across your indexes.

8

Click Create Search Index.

Atlas displays a Toast (brief, non-interactive notification) to let you know your index is building.

9

Check the status.

The newly created index appears on the Atlas Search tab. While the index is building, the Status field reads Build in Progress. When the index is finished building, the Status field reads Active.

IMPORTANT: Larger collections take longer to index. You will receive an email notification when your index is finished building.

10

Run a query on the totalPriceIndex index.

Note

The following example queries the totalPriceIndex index by running the .aggregate command against the View named listingsAndReviews_totalPrice. If your cluster is running MongoDB v8.0, you must query the source collection (for example, listingsAndReviews) using the index on the View. Upgrade to MongoDB v8.1+ to query the View directly.

use sample_airbnb
db.listingsAndReviews_totalPrice.aggregate([
  {
    $search: {
      index: "totalPriceIndex",
      range: {
        path: "totalPrice",
        lte: 300
      },
      returnStoredSource: true
    }
  }
])
[
  { _id: '10006546', totalPrice: 115 },
  { _id: '1001265', totalPrice: 215 },
  { _id: '10021707', totalPrice: 40 },
  { _id: '1003530', totalPrice: 270 },
  { _id: '10038496', totalPrice: 269 },
  { _id: '10051164', totalPrice: 250 },
  { _id: '10057447', totalPrice: 50 },
  { _id: '10057826', totalPrice: 205 },
  { _id: '10059244', totalPrice: 43 },
  { _id: '10066928', totalPrice: 140 },
  { _id: '10082422', totalPrice: 60 },
  { _id: '10083468', totalPrice: 40 },
  { _id: '10084023', totalPrice: 231 },
  { _id: '10091713', totalPrice: 231 },
  { _id: '10092679', totalPrice: 58 },
  { _id: '10096773', totalPrice: 205 },
  { _id: '10112159', totalPrice: 90 },
  { _id: '10117617', totalPrice: 55 },
  { _id: '10120414', totalPrice: 150 },
  { _id: '10133554', totalPrice: 121 }
]
1

Connect to your MongoDB deployment using mongosh.

To learn more, see Connect to a Cluster via mongosh.

2

Switch to the sample_airbnb database.

use sample_airbnb
3

Create a listingsAndReviews_totalPrice View.

db.createView(
  "listingsAndReviews_totalPrice",
  "listingsAndReviews",
  [
    {
      $addFields: {
        totalPrice: {
          $add: [
            {
              $ifNull: [{ $toDouble: "$price" }, 0]
            },
            {
              $ifNull: [{ $toDouble: "$cleaning_fee" }, 0]
            }
          ]
        }
      }
    }
  ]
)
4

Create a MongoDB Search index on the View.

db.listingsAndReviews_totalPrice.createSearchIndex(
  "totalPriceIndex",
  {
    "mappings": {
      "dynamic": true
    },
    "storedSource": {
      "include": [
        "totalPrice"
      ]
    }
  }
)
5

Run a query on the totalPriceIndex index.

Note

The following example queries the totalPriceIndex index by running the .aggregate command against the View named listingsAndReviews_totalPrice. If your cluster is running MongoDB v8.0, you must query the source collection (for example, listingsAndReviews) using the index on the View. Upgrade to MongoDB v8.1+ to query the View directly.

use sample_airbnb
db.listingsAndReviews_totalPrice.aggregate([
  {
    $search: {
      index: "totalPriceIndex",
      range: {
        path: "totalPrice",
        lte: 300
      },
      returnStoredSource: true
    }
  }
])
[
  { _id: '10006546', totalPrice: 115 },
  { _id: '1001265', totalPrice: 215 },
  { _id: '10021707', totalPrice: 40 },
  { _id: '1003530', totalPrice: 270 },
  { _id: '10038496', totalPrice: 269 },
  { _id: '10051164', totalPrice: 250 },
  { _id: '10057447', totalPrice: 50 },
  { _id: '10057826', totalPrice: 205 },
  { _id: '10059244', totalPrice: 43 },
  { _id: '10066928', totalPrice: 140 },
  { _id: '10082422', totalPrice: 60 },
  { _id: '10083468', totalPrice: 40 },
  { _id: '10084023', totalPrice: 231 },
  { _id: '10091713', totalPrice: 231 },
  { _id: '10092679', totalPrice: 58 },
  { _id: '10096773', totalPrice: 205 },
  { _id: '10112159', totalPrice: 90 },
  { _id: '10117617', totalPrice: 55 },
  { _id: '10120414', totalPrice: 150 },
  { _id: '10133554', totalPrice: 121 }
]

Edit a View

The following example updates the movies_ReleasedAfter2000 MongoDB View for movies before 2000.

db.runCommand(
{
    collMod: "movies_ReleasedAfter2000",
    viewOn: "movies",
    "pipeline": [
      {
        $match: {
          $expr: {
            $lt: [
              "$released",
              ISODate("2000-01-01T00")
            ]
          }
        }
      }
    ]
  }
)

After you run this command, MongoDB Search automatically detects the change in the View definition and performs a reindexing with no downtime.

Return the Pipelines for a View

The following example returns the pipelines on the movies_ReleasedAfter2000 View.

db.getCollectionInfos({ name: "movies_ReleasedAfter2000" })[0].options.pipeline
[
  {
    '$match': {
      '$expr': { '$gt': [ '$released', ISODate('2000-01-01T00:00:00.000Z') ] }
    }
  }
]

Performance Considerations

Highly complex view transformations can lead to slower performance when Atlas reads the view to filter and transform the source collection. In this scenario, consider creating a materialized view to avoid additional replication load on Atlas. To avoid query latency caused by the view transformation, you can query the source collection directly to retrieve the original documents.

Troubleshoot

Indexes Change to FAILED

Indexes change to the FAILED status in the following scenarios:

  • You create an index on a View that is incompatible with MongoDB Search.

  • You edit a View in a way that does not meet the MongoDB Search compatibility requirements.

  • You remove or change a View's source collection.

    For example, if one View is created on another View, and you change the parent View source to another collection.

    Note

    This limitation also applies if a View is a descendent of other Views. For example, you can't change or remove the source collection that all descendents originate from.

Indexes Change to STALE

Indexes change to the STALE status in the following scenarios:

Warning

If the aggregation pipeline defined in your View is incompatible with the documents in the collection, search replication fails. For example, if a $toDouble expression operates on a document field that contains an array, the replication fails. Ensure your View works with all documents in the collection without errors.

  • If the View definition causes an aggregation failure while an index is READY, the index becomes STALE. The index will return to READY after you resolve the document or change the view definition so that it doesn't fail anymore. When STALE, the index remains queryable. If the index falls off the oplog, an index rebuild is triggered.

  • If the View definition causes an aggregation pipeline failure while the index is BUILDING, the index build is stuck until you fix the document. The index will return to READY after you resolve the document or change the view definition so that it doesn't fail anymore.

You can view index statuses in the Atlas UI on the index status details page.

Error: $search is only valid as the first stage in a pipeline

This error appears when you query a view using a MongoDB version before 8.1.

  • If you use a MongoDB version before 8.0, we recommend you upgrade to 8.1+ to query the view directly. You can upgrade to 8.0 to query the source collection.

  • If you use MongoDB 8.0, you must query the view index against the source collection. For example, run .aggregate() on the collection instead of the view.

Index Process

When you create an MongoDB Search index on a View, the mongot process performs the same tasks as when you create an MongoDB Search index on a regular collection. The mongot process:

  1. Creates MongoDB Search indexes based on the rules in the index definition for the collection.

  2. Monitors change streams for the current state of the documents and indexes for the collections for which you defined the MongoDB Search indexes.

  3. Processes MongoDB Search queries and returns the document IDs and other search metadata for the matching documents to mongod, which then does a full document lookup and returns the results to the client.

When you create an MongoDB Search index on a View, the View definition is applied during Step 1 and 2, and the transformed documents are stored in the MongoDB Search index on disk.

Learn More

To learn more about Views, see Views.

To create a MongoDB Vector Search index on a View, see Use Views with MongoDB Vector Search.

Back

Multiple Collections

Next

Compatibility & Limitations

On this page