How to Run Atlas Search Queries Against Objects in Arrays

On this page

Required Access

Create a Sample Collection and Load the Data
Create an Atlas Search Index
Run Atlas Search Queries Against Embedded Document Fields

This tutorial describes how to index and run queries against fields in documents that are inside an array. This tutorial takes you through the following steps:

Create a sample collection named schools with embedded documents in your Atlas cluster.
Set up an Atlas Search index with embeddedDocuments fields configured at the following paths:
- teachers field
- teachers.classes field
- clubs.sports field
Run Atlas Search queries that search the embedded documents in the the schools collection using the compound operator with the embeddedDocument and text operators.

Before you begin, ensure that your Atlas cluster meets the requirements described in the Prerequisites. For this tutorial, you don't need to upload the sample data because you will create a new collection and load the documents that you need to run the queries in this tutorial.

Required Access

To create an Atlas Search index, you must have Project Data Access Admin or higher access to the project.

Create a Sample Collection and Load the Data

Each document in the sample collection named schools contains the name and mascot of the school, school teacher's first and last name, the classes that each teacher teaches including the subject name and grade level, and the various clubs for the school students.

You must begin by creating a collection named schools in an existing or new database on your Atlas cluster. After creating the collection, you must upload the sample data into your collection. The steps in this section walk you through creating a new database and collection, and loading the sample data into your collection.

Log in to Atlas and navigate to the Collections tab.

Log in to your cluster.
Click your cluster name.
Click Collections.

Create a new collection.

Click Create Database to create a new database.
Enter the database name and collection name.
- In the Database Name field, specify local_school_district.
- For the Collection Name field, specify schools.

Load the following documents into the collection.

Select the schools collection if it's not selected.
Click Insert Document for each of the sample documents to add to the collection.
Click the JSON view ({}) to replace the default document.

Copy and paste the following sample documents, one at a time, and click Insert to add the documents, one at a time, to the collection.

{
  "_id": 0,
  "name": "Springfield High",
  "mascot": "Pumas",
  "teachers": [{
    "first": "Jane",
    "last": "Smith",
    "classes": [{
      "subject": "art of science",
      "grade": "12th"
    },
    {
      "subject": "applied science and practical science",
      "grade": "9th"
    },
    {
      "subject": "remedial math",
      "grade": "12th"
    },
    {
      "subject": "science",
      "grade": "10th"
    }]
  },
  {
    "first": "Bob",
    "last": "Green",
    "classes": [{
      "subject": "science of art",
      "grade": "11th"
    },
    {
      "subject": "art art art",
      "grade": "10th"
    }]
  }],
  "clubs": {
    "stem": [
      {
        "club_name": "chess",
        "description": "provides students opportunity to play the board game of chess informally and competitively in tournaments."
      },
      {
        "club_name": "kaboom chemistry",
        "description": "provides students opportunity to experiment with chemistry that fizzes and explodes."
      }
    ],
    "arts": [
      {
        "club_name": "anime",
        "description": "provides students an opportunity to discuss, show, and collaborate on anime and broaden their Japanese cultural understanding."
      },
      {
        "club_name": "visual arts",
        "description": "provides students an opportunity to train, experiment, and prepare for internships and jobs as photographers, illustrators, graphic designers, and more."
      }
    ]
  }
}

{
  "_id": 1,
  "name": "Evergreen High",
  "mascot": "Jaguars",
  "teachers": [{
    "first": "Jane",
    "last": "Earwhacker",
    "classes": [{
      "subject": "art",
      "grade": "9th"
    },
    {
      "subject": "science",
      "grade": "12th"
    }]
  },
  {
    "first": "John",
    "last": "Smith",
    "classes": [{
      "subject": "math",
      "grade": "12th"
    },
    {
      "subject": "art",
      "grade": "10th"
    }]
  }],
  "clubs": {
    "sports": [
      {
        "club_name": "archery",
        "description": "provides students an opportunity to practice and hone the skill of using a bow to shoot arrows in a fun and safe environment."
      },
      {
        "club_name": "ultimate frisbee",
        "description": "provides students an opportunity to play frisbee and learn the basics of holding the disc and complete passes."
      }
    ],
    "stem": [
      {
        "club_name": "zapped",
        "description": "provides students an opportunity to make exciting gadgets and explore electricity."
      },
      {
        "club_name": "loose in the chem lab",
        "description": "provides students an opportunity to put the scientific method to the test and get elbow deep in chemistry."
      }
    ]
  }
}

{
  "_id": 2,
  "name": "Lincoln High",
  "mascot": "Sharks",
  "teachers": [{
    "first": "Jane",
    "last": "Smith",
    "classes": [{
      "subject": "science",
      "grade": "9th"
    },
    {
      "subject": "math",
      "grade": "12th"
    }]
  },
  {
    "first": "John",
    "last": "Redman",
    "classes": [{
      "subject": "art",
      "grade": "12th"
    }]
  }],
  "clubs": {
    "arts": [
      {
        "club_name": "ceramics",
        "description": "provides students an opportunity to acquire knowledge of form, volume, and space relationships by constructing hand-built and wheel-thrown forms of clay."
      },
      {
        "club_name": "digital art",
        "description": "provides students an opportunity to learn about design for entertainment, 3D animation, technical art, or 3D modeling."
      }
    ],
    "sports": [
      {
        "club_name": "dodgeball",
        "description": "provides students an opportunity to play dodgeball by throwing balls to eliminate the members of the opposing team while avoiding being hit themselves."
      },
      {
        "club_name": "martial arts",
        "description": "provides students an opportunity to learn self-defense or combat that utilize physical skill and coordination without weapons."
      }
    ]
  }
}

Create an Atlas Search Index

In this section, you will create an Atlas Search index for the fields in the embedded documents in the local_school_district.schools collection.

Navigate to the Atlas Search page for your project.

If it isn't already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.
If it isn't already displayed, select your desired project from the Projects menu in the navigation bar.
Click your cluster's name.
Click the Search tab.

Click Create Index.

Select a Configuration Method and click Next.

For a guided experience, select Visual Editor.
To edit the raw index definition, select JSON Editor.

Enter the Index Name, and set the Database and Collection.

In the Index Name field, enter embedded-documents-tutorial.
Note
If you name your index default, you don't need to specify an index parameter when using the $search pipeline stage. Otherwise, you must specify the index name using the index parameter.
In the Database and Collection section, find the local_school_district database, and select the schools collection.

Specify an index configuration that indexes embedded documents.

The following index definition specifies that documents in the arrays at the teachers and teachers.classes paths must be indexed as How to Index Fields in Arrays of Objects and Documents, and the fields inside the documents must be dynamically indexed.

Click Create Search Index.

Atlas displays a modal window to let you know your index is building.

Click the Close button and wait for the index to finish building.

The index should take about one minute to build. While it is building, the Status column reads Build in Progress. When it is finished building, the Status column reads Active.

Run Atlas Search Queries Against Embedded Document Fields

You can run queries against the embedded document fields. This tutorial uses embeddedDocument and text operators inside the compound operator in the queries.

In this section, you will connect to your Atlas cluster and run the sample queries using the operators against the fields in the schools collection.

➤ Use the Select your language drop-down menu on this page to set the language of the examples in this section.

← How to Run $unionWith with an Atlas Search $search Query How to Run Atlas Search Queries with a Date Range Filter →