Try Studio 3T for Free
  1. Knowledge Base
  2. MongoDB Tutorials
  3. How to Query MongoDB Array String Values & Embedded Documents

How to Query MongoDB Array String Values & Embedded Documents

Get Visual Query Builder by downloading the latest Studio 3T version, available here

Arrays in MongoDB

The smallest unit of data in MongoDB is a field-value pair, like:

{
   "city" : "Berlin",
}

Field-value pairs are then stored in documents like the one below:

{ 
    "_id" : ObjectId("57d28452ed5d4d54e8686ff6"), 
    "title" : "Mr", 
    "first" : "Paul", 
    "last" : "Diaz", 
    "city" : "Berlin", 
    "country" : "Germany", 
}

MongoDB’s flexible document structure makes it possible to have a field with an array as a value.

An array is simply a list of values, and an array value can take many forms.

It can be an array of string values, as in the example below:

{
   cities: [ “London”, “New York”, “San Francisco”]
}

Or an array of embedded documents:

 "cities" : [
        {
            "city" : "London", 
            "country" : "United Kingdom"
        }, 
        {
            "city" : "New York", 
            "country" : "United States"
        }
        {
            "city" : "San Francisco", 
            "country" : "United States"
        }
    ]

Or an array of any MongoDB-support BSON data type (e.g. Decimal128, Int32, Date):

{
   cities: [ “0.128”, “20”, “1972-07-22T09:39:28.000+0000”]
}

In these examples, we would refer to array values like “London”, “0.128”, and “United States” and array embedded fields like “city”, “country” as array elements.

One would need to know MongoDB syntax to build the queries needed to find elements from the arrays (we’ve written an advanced article on the subject).

The good news for beginners is, Visual Query Builder makes it possible to query arrays through a drag-and-drop query builder.

This tutorial will show you how to query MongoDB arrays through two examples, without typing a single MongoDB command.

Download the latest Studio 3T version to access Visual Query Builder.

Two types of array fields

Let’s query a collection called expats.

To import the collection, copy all documents from the expats.json file and paste them to a new collection in Studio 3T. Alternatively, save the file and import it to your MongoDB database following these steps.

expats contains two types of array fields:

  • cities_visited whose value is an array of string values:
{
   cities_visited: [ “Tokyo”, “Sapporo”, “Kyoto”]
}
  • And previous_addresses whose value is an array of embedded documents:
 "previous_addresses" : [
        {
            "city" : "Berlin", 
            "country" : "Germany"
        }, 
        {
            "city" : "Austin", 
            "country" : "United States"
        }
    ]

Each embedded document contains two fields: city and country.

The expats collection contains ten documents (or ten expat profiles). We’d like to query the array fields cities_visited and previous_addresses to answer the questions:

  • Who has visited Berlin?
  • Who has lived in Spain?

Open the expats collection

Once you’ve downloaded and imported the expats collection, open it in Studio 3T by double-clicking on the collection in the Connection Tree.

This will open a collection tab. Table View should be chosen by default in the view dropdown menu.

expats collection in a collection tab

Query an array of string values

Who’s been to Berlin?

Let’s first query the cities_visited array field to find the element string value, “Berlin”.

1 – Open Visual Query Builder

Click on the Visual Query Builder button on the top-right corner of the collection tab.

Visual Query Button icon

This will open the query builder which contains three sections: Query, Sort, and Projection.

2 – Choose “Has array element(s) matching” in the Query Section

Choose Has array elements matching

3 – Choose the array field to query

The Array dropdown menu will appear. Here, choose cities_visited as the array to query.

Choose cities_visited as the array to query

4 – Choose <Array Element>

Double-click to expand the section that says “Drag field here or double-click”.

<Array Element> should be chosen by default. If not, choose it from the field dropdown menu.

Choose Array Element from the field dropdown menu

5 – Type the array value to look for

Type “Berlin” since we want the query to return a list of expats who have visited Berlin.

Type the array value to look for

Here we’re querying string values, but keep in mind that you can query other data types as easily by clicking and choosing from the data type dropdown menu:

Choose other data types by clicking on the dropdown

6 – Run the query

Click “Run” to execute the query.  Also, click on “Hide Query Builder”.

7 – Check results

Looks like Jonathan, Phyllis and Marilyn have visited the German capital.

Expats who have been to Berlin

We can confirm our results by “stepping into” the cities_visited column. Double-click on any value in the column.

The cities-visited column

This allows us to go a level deeper into the data so that we only see those values.

Step into cities_visited column

Query an array of embedded documents

Who’s lived in Spain?

Now that we have successfully queried an array of string values, let’s query an array of embedded documents to find the array element value, “Spain”, where the array embedded field is “country”.

Let’s start from scratch and open our expats collection in a new tab.

1 – Open Visual Query Builder

Visual Query Button icon

Click the button on the top-right corner.

2 – Choose Has array element(s) matching in the Query section

Choose Has array elements matching

2 – Choose the array field to query

Choose previous_addresses as the field to query in the Array dropdown menu.

Choose previous_addresses

3 – Click on the “Drag field here or double-click” section

4 – Type the name of the array embedded field to query

The field dropdown will choose <Array Element> by default. Let’s override it by typing the name of the embedded field we want to query, “country”.

Type the embedded field name to query

5 – Type the array value to search for

Looking for the array value, "Spain"

Here, let’s type “Spain”.

6 – Execute the query

Click on the “Run” button.

7 – Check results

The query returns two expats, Paul and Craig, who seem to have lived in Spain. But where exactly?

Right-click on any cell in the Results tab and choose Show All Embedded Fields.

Show embedded fieldsThis will show all embedded fields next to their parent fields. An embedded field is always written in dot notation (e.g. previous_addresses.0.city).

Show embedded fields for spot-checking

Now we can easily see that the two have indeed lived in Spain – in Barcelona and Madrid, respectively.


Learn more about what Visual Query Builder can do, as well as other handy tasks you can complete in Studio 3T even when you’re just getting started with MongoDB.

If you’d like to dive deeper into the topic of MongoDB arrays, check out our other article, How to Query & Filter Elements from MongoDB Arrays.

Updated on December 5, 2019

Was this article helpful?

Related Articles