> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

# Query an Array

You can query arrays in MongoDB using the following methods:

- Your programming language's driver.

- The [MongoDB Atlas UI](https://www.mongodb.com/docs/atlas/). To learn more, see [Query for Null or Missing Fields with MongoDB Atlas](https://www.mongodb.com/docs/manual/tutorial/query-for-null-fields.md#std-label-query-null-documents-atlas-ui).

- [MongoDB Compass.](https://www.mongodb.com/docs/compass/current/)

This page provides examples of query operations on array fields using the [`db.collection.find()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.find.md#mongodb-method-db.collection.find) method in [`mongosh`.](https://www.mongodb.com/docs/mongodb-shell.md#mongodb-binary-bin.mongosh)

The examples on this page use data from the [sample\_mflix dataset](https://www.mongodb.com/docs/manual/sample-data/sample-mflix.md#std-label-sample-mflix). For details on how to load this dataset into your self-managed MongoDB deployment, see [Load the Sample Dataset](https://www.mongodb.com/docs/manual/sample-data/load-sample-data-local.md#std-label-sample-dataset-local). If you made any modifications to the sample databases, you may need to drop and recreate the databases to run the examples on this page.

## Match an Array

To specify equality condition on an array, use the query document `{ <field>: <value> }` where `<value>` is the exact array to match, including the order of the elements.

The following example queries for all documents where `genres` is an array with exactly two elements, `"Action"` and `"Comedy"`, in the specified order:

```javascript
db.movies.find( { genres: ["Action", "Comedy"] } )

```

To find an array that contains both `"Action"` and `"Comedy"` regardless of order or other elements in the array, use the [`$all`](https://www.mongodb.com/docs/manual/reference/operator/query/all.md#mongodb-query-op.-all) operator:

```javascript
db.movies.find( { genres: { $all: ["Action", "Comedy"] } } )

```

## Query an Array for an Element

To query if the array field contains at least *one* element with the specified value, use the filter `{ <field>: <value> }` where `<value>` is the element value.

The following example queries for all documents where the `genres` array contains the string `"Short"` as one of its elements:

```javascript
db.movies.find( { genres: "Short" } )

```

To specify conditions on the elements in the array field, use [query operators](https://www.mongodb.com/docs/manual/reference/mql/query-predicates.md#std-label-query-selectors) in the [query filter document:](https://www.mongodb.com/docs/manual/core/documents-other-uses.md#std-label-document-query-filter)

```javascript
{ <array field>: { <operator1>: <value1>, ... } }
```

The following example queries for all documents where the `cast` array contains at least one element that matches the regular expression `^A`:

```javascript
db.movies.find( { cast: { $regex: "^A" } } )

```

## Specify Multiple Conditions for Array Elements

When you specify compound conditions on array elements, you can query for documents where either:

- A single array element meets all the specified conditions

- Different array elements collectively meet all the conditions, with each element satisfying one or more conditions

### Query an Array with Compound Filter Conditions on the Array Elements

The following example queries for documents where the `cast` array contains elements that in some combination satisfy the query conditions. One element can satisfy the `$regex: "^A"` condition and another element can satisfy the `$ne: "Adam Sandler"` condition, or a single element can satisfy both:

```javascript
db.movies.find(
   { cast: { $regex: "^A", $ne: "Adam Sandler" } }
)

```

### Query for an Array Element that Meets Multiple Criteria

Use the [`$elemMatch`](https://www.mongodb.com/docs/manual/reference/operator/query/elemmatch.md#mongodb-query-op.-elemMatch) operator to specify multiple criteria on array elements so that at least one array element satisfies all the specified criteria.

The following example queries for documents where the `cast` array contains at least one element that both matches the regular expression `^A` and is not equal to `"Adam Sandler"`:

```javascript
db.movies.find(
   { cast: { $elemMatch: { $regex: "^A", $ne: "Adam Sandler" } } }
)

```

### Query for an Element by the Array Index Position

Use [dot notation](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-dot-notation) to specify query conditions for an element at a particular index or position of the array. The array uses zero-based indexing.

**Note:**

When you query using dot notation, the field and nested field must be inside quotation marks.

The following example queries for all documents where the first element in the array `cast` equals `"Tom Hanks"`:

```javascript
db.movies.find( { "cast.0": "Tom Hanks" } )

```

### Query an Array by Array Length

Use the [`$size`](https://www.mongodb.com/docs/manual/reference/operator/query/size.md#mongodb-query-op.-size) operator to query for arrays by number of elements.

The following example selects documents where `genres` has 3 elements:

```javascript
db.movies.find( { genres: { $size: 3 } } )

```

This page provides examples of query operations on array fields using the [`pymongo.collection.Collection.find`](https://pymongo.readthedocs.io/en/stable/api/pymongo/collection.html#pymongo.collection.Collection.find) method in the [PyMongo](https://www.mongodb.com/docs/languages/python/pymongo-driver/current/) Python driver.

The examples on this page use the `inventory` collection. Connect to a test database in your MongoDB instance then create the `inventory` collection:

```python
db.inventory.insert_many(
    [
        {"item": "journal", "qty": 25, "tags": ["blank", "red"], "dim_cm": [14, 21]},
        {"item": "notebook", "qty": 50, "tags": ["red", "blank"], "dim_cm": [14, 21]},
        {
            "item": "paper",
            "qty": 100,
            "tags": ["red", "blank", "plain"],
            "dim_cm": [14, 21],
        },
        {"item": "planner", "qty": 75, "tags": ["blank", "red"], "dim_cm": [22.85, 30]},
        {"item": "postcard", "qty": 45, "tags": ["blue"], "dim_cm": [10, 15.25]},
    ]
)
```

## Match an Array

To specify equality condition on an array, use the query document `{ <field>: <value> }` where `<value>` is the exact array to match, including the order of the elements.

The following example queries for all documents where `tags` is an array with exactly two elements, `"red"` and `"blank"`, in the specified order:

```python
cursor = db.inventory.find({"tags": ["red", "blank"]})
```

To find an array that contains both `"red"` and `"blank"` regardless of order or other elements in the array, use the [`$all`](https://www.mongodb.com/docs/manual/reference/operator/query/all.md#mongodb-query-op.-all) operator:

```python
cursor = db.inventory.find({"tags": {"$all": ["red", "blank"]}})
```

## Query an Array for an Element

To query if the array field contains at least *one* element with the specified value, use the filter `{ <field>: <value> }` where `<value>` is the element value.

The following example queries for all documents where the `tags` array contains the string `"red"` as one of its elements:

```python
cursor = db.inventory.find({"tags": "red"})
```

To specify conditions on the elements in the array field, use [query operators](https://www.mongodb.com/docs/manual/reference/mql/query-predicates.md#std-label-query-selectors) in the [query filter document:](https://www.mongodb.com/docs/manual/core/documents-other-uses.md#std-label-document-query-filter)

```python
{ <array field>: { <operator1>: <value1>, ... } }
```

The following example queries for all documents where the array `dim_cm` contains at least one element whose value is greater than `25`:

```python
cursor = db.inventory.find({"dim_cm": {"$gt": 25}})
```

## Specify Multiple Conditions for Array Elements

When you specify compound conditions on array elements, you can query for documents where either:

- A single array element meets all the specified conditions

- Different array elements collectively meet all the conditions, with each element satisfying one or more conditions

### Query an Array with Compound Filter Conditions on the Array Elements

The following example queries for documents where the `dim_cm` array contains elements that in some combination satisfy the query conditions. One element can satisfy the greater than `15` condition and another element can satisfy the less than `20` condition, or a single element can satisfy both:

```python
cursor = db.inventory.find({"dim_cm": {"$gt": 15, "$lt": 20}})
```

### Query for an Array Element that Meets Multiple Criteria

Use the [`$elemMatch`](https://www.mongodb.com/docs/manual/reference/operator/query/elemmatch.md#mongodb-query-op.-elemMatch) operator to specify multiple criteria on array elements so that at least one array element satisfies all the specified criteria.

The following example queries for documents where the `dim_cm` array contains at least one element that is both greater than ([`$gt`](https://www.mongodb.com/docs/manual/reference/operator/query/gt.md#mongodb-query-op.-gt)) `22` and less than ([`$lt`](https://www.mongodb.com/docs/manual/reference/operator/query/lt.md#mongodb-query-op.-lt)) `30`:

```python
cursor = db.inventory.find({"dim_cm": {"$elemMatch": {"$gt": 22, "$lt": 30}}})
```

### Query for an Element by the Array Index Position

Use [dot notation](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-dot-notation) to specify query conditions for an element at a particular index or position of the array. The array uses zero-based indexing.

**Note:**

When you query using dot notation, the field and nested field must be inside quotation marks.

The following example queries for all documents where the second element in the array `dim_cm` is greater than `25`:

```python
cursor = db.inventory.find({"dim_cm.1": {"$gt": 25}})
```

### Query an Array by Array Length

Use the [`$size`](https://www.mongodb.com/docs/manual/reference/operator/query/size.md#mongodb-query-op.-size) operator to query for arrays by number of elements.

The following example selects documents where `tags` has 3 elements:

```python
cursor = db.inventory.find({"tags": {"$size": 3}})
```

As of May 14, 2025, Motor is deprecated in favor of the GA release of the PyMongo Async API in the PyMongo library. We will not add new features to Motor, and we will provide only bug fixes until it reaches end of life on May 14, 2026. After that, we will fix only critical bugs until final support ends on May 14, 2027. We strongly recommend migrating to the PyMongo Async API while Motor is still supported.

For more information about migrating, see the [Migrate to PyMongo Async](https://www.mongodb.com/docs/languages/python/pymongo-driver/reference/migration.md#std-label-pymongo-async-motor-migration) guide in the PyMongo documentation.

This page provides examples of query operations on array fields using the [`pymongo.asynchronous.collection.AsyncCollection.find`](https://pymongo.readthedocs.io/en/stable/api/pymongo/asynchronous/collection.html#pymongo.asynchronous.collection.AsyncCollection.find) method in the [PyMongo Async API](https://pymongo.readthedocs.io/en/stable/api/pymongo/asynchronous/index.html).

The examples on this page use the `inventory` collection. Connect to a test database in your MongoDB instance then create the `inventory` collection:

```python
await db.inventory.insert_many(
    [
        {"item": "journal", "qty": 25, "tags": ["blank", "red"], "dim_cm": [14, 21]},
        {"item": "notebook", "qty": 50, "tags": ["red", "blank"], "dim_cm": [14, 21]},
        {
            "item": "paper",
            "qty": 100,
            "tags": ["red", "blank", "plain"],
            "dim_cm": [14, 21],
        },
        {"item": "planner", "qty": 75, "tags": ["blank", "red"], "dim_cm": [22.85, 30]},
        {"item": "postcard", "qty": 45, "tags": ["blue"], "dim_cm": [10, 15.25]},
    ]
)
```

## Match an Array

To specify equality condition on an array, use the query document `{ <field>: <value> }` where `<value>` is the exact array to match, including the order of the elements.

The following example queries for all documents where `tags` is an array with exactly two elements, `"red"` and `"blank"`, in the specified order:

```python
cursor = db.inventory.find({"tags": ["red", "blank"]})
```

To find an array that contains both `"red"` and `"blank"` regardless of order or other elements in the array, use the [`$all`](https://www.mongodb.com/docs/manual/reference/operator/query/all.md#mongodb-query-op.-all) operator:

```python
cursor = db.inventory.find({"tags": {"$all": ["red", "blank"]}})
```

## Query an Array for an Element

To query if the array field contains at least *one* element with the specified value, use the filter `{ <field>: <value> }` where `<value>` is the element value.

The following example queries for all documents where the `tags` array contains the string `"red"` as one of its elements:

```python
cursor = db.inventory.find({"tags": "red"})
```

To specify conditions on the elements in the array field, use [query operators](https://www.mongodb.com/docs/manual/reference/mql/query-predicates.md#std-label-query-selectors) in the [query filter document:](https://www.mongodb.com/docs/manual/core/documents-other-uses.md#std-label-document-query-filter)

```python
{ <array field>: { <operator1>: <value1>, ... } }
```

The following example queries for all documents where the array `dim_cm` contains at least one element whose value is greater than `25`:

```python
cursor = db.inventory.find({"dim_cm": {"$gt": 25}})
```

## Specify Multiple Conditions for Array Elements

When you specify compound conditions on array elements, you can query for documents where either:

- A single array element meets all the specified conditions

- Different array elements collectively meet all the conditions, with each element satisfying one or more conditions

### Query an Array with Compound Filter Conditions on the Array Elements

The following example queries for documents where the `dim_cm` array contains elements that in some combination satisfy the query conditions. One element can satisfy the greater than `15` condition and another element can satisfy the less than `20` condition, or a single element can satisfy both:

```python
cursor = db.inventory.find({"dim_cm": {"$gt": 15, "$lt": 20}})
```

### Query for an Array Element that Meets Multiple Criteria

Use the [`$elemMatch`](https://www.mongodb.com/docs/manual/reference/operator/query/elemmatch.md#mongodb-query-op.-elemMatch) operator to specify multiple criteria on array elements so that at least one array element satisfies all the specified criteria.

The following example queries for documents where the `dim_cm` array contains at least one element that is both greater than ([`$gt`](https://www.mongodb.com/docs/manual/reference/operator/query/gt.md#mongodb-query-op.-gt)) `22` and less than ([`$lt`](https://www.mongodb.com/docs/manual/reference/operator/query/lt.md#mongodb-query-op.-lt)) `30`:

```python
cursor = db.inventory.find({"dim_cm": {"$elemMatch": {"$gt": 22, "$lt": 30}}})
```

### Query for an Element by the Array Index Position

Use [dot notation](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-dot-notation) to specify query conditions for an element at a particular index or position of the array. The array uses zero-based indexing.

**Note:**

When you query using dot notation, the field and nested field must be inside quotation marks.

The following example queries for all documents where the second element in the array `dim_cm` is greater than `25`:

```python
cursor = db.inventory.find({"dim_cm.1": {"$gt": 25}})
```

### Query an Array by Array Length

Use the [`$size`](https://www.mongodb.com/docs/manual/reference/operator/query/size.md#mongodb-query-op.-size) operator to query for arrays by number of elements.

The following example selects documents where `tags` has 3 elements:

```python
cursor = db.inventory.find({"tags": {"$size": 3}})
```

This page provides examples of query operations on array fields using the [com.mongodb.client.MongoCollection.find](https://mongodb.github.io/mongo-java-driver/3.4/javadoc/com/mongodb/client/MongoCollection.html#find--) method in the MongoDB [Java Synchronous Driver.](http://mongodb.github.io/mongo-java-driver/3.4/driver/)

**Tip:**

The driver provides [com.mongodb.client.model.Filters](https://mongodb.github.io/mongo-java-driver/3.4/javadoc/com/mongodb/client/model/Filters.html) helper methods to facilitate the creation of filter documents. The examples on this page use these methods to create the filter documents.

The examples on this page use the `inventory` collection. Connect to a test database in your MongoDB instance then create the `inventory` collection:

```java
collection.insertMany(asList(
        Document.parse("{ item: 'journal', qty: 25, tags: ['blank', 'red'], dim_cm: [ 14, 21 ] }"),
        Document.parse("{ item: 'notebook', qty: 50, tags: ['red', 'blank'], dim_cm: [ 14, 21 ] }"),
        Document.parse("{ item: 'paper', qty: 100, tags: ['red', 'blank', 'plain'], dim_cm: [ 14, 21 ] }"),
        Document.parse("{ item: 'planner', qty: 75, tags: ['blank', 'red'], dim_cm: [ 22.85, 30 ] }"),
        Document.parse("{ item: 'postcard', qty: 45, tags: ['blue'], dim_cm: [ 10, 15.25 ] }")
));
```

## Match an Array

To specify equality condition on an array, use the query document `eq( <field>, <value>)` where `<value>` is the exact array to match, including the order of the elements.

The following example queries for all documents where `tags` is an array with exactly two elements, `"red"` and `"blank"`, in the specified order:

```java
FindIterable<Document> findIterable = collection.find(eq("tags", asList("red", "blank")));
```

To find an array that contains both `"red"` and `"blank"` regardless of order or other elements in the array, use the [`$all`](https://www.mongodb.com/docs/manual/reference/operator/query/all.md#mongodb-query-op.-all) operator:

```java
findIterable = collection.find(all("tags", asList("red", "blank")));
```

## Query an Array for an Element

To query if the array field contains at least *one* element with the specified value, use the filter `eq( <field>, <value>)` where `<value>` is the element value.

The following example queries for all documents where the `tags` array contains the string `"red"` as one of its elements:

```java
findIterable = collection.find(eq("tags", "red"));
```

To specify conditions on the elements in the array field, use [query operators](https://www.mongodb.com/docs/manual/reference/mql/query-predicates.md#std-label-query-selectors) in the [query filter document](https://www.mongodb.com/docs/manual/core/documents-other-uses.md#std-label-document-query-filter). For example:

```java
and(gte(<array field>, <value1>), lt(<array field>, <value2>) ...)
```

The following example queries for all documents where the array `dim_cm` contains at least one element whose value is greater than `25`:

```java
findIterable = collection.find(gt("dim_cm", 25));
```

## Specify Multiple Conditions for Array Elements

When you specify compound conditions on array elements, you can query for documents where either:

- A single array element meets all the specified conditions

- Different array elements collectively meet all the conditions, with each element satisfying one or more conditions

### Query an Array with Compound Filter Conditions on the Array Elements

The following example queries for documents where the `dim_cm` array contains elements that in some combination satisfy the query conditions. One element can satisfy the greater than `15` condition and another element can satisfy the less than `20` condition, or a single element can satisfy both:

```java
findIterable = collection.find(and(gt("dim_cm", 15), lt("dim_cm", 20)));
```

### Query for an Array Element that Meets Multiple Criteria

Use the [`$elemMatch`](https://www.mongodb.com/docs/manual/reference/operator/query/elemmatch.md#mongodb-query-op.-elemMatch) operator to specify multiple criteria on array elements so that at least one array element satisfies all the specified criteria.

The following example queries for documents where the `dim_cm` array contains at least one element that is both greater than ([`$gt`](https://www.mongodb.com/docs/manual/reference/operator/query/gt.md#mongodb-query-op.-gt)) `22` and less than ([`$lt`](https://www.mongodb.com/docs/manual/reference/operator/query/lt.md#mongodb-query-op.-lt)) `30`:

```java
findIterable = collection.find(elemMatch("dim_cm", Document.parse("{ $gt: 22, $lt: 30 }")));
```

### Query for an Element by the Array Index Position

Use [dot notation](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-dot-notation) to specify query conditions for an element at a particular index or position of the array. The array uses zero-based indexing.

**Note:**

When you query using dot notation, the field and nested field must be inside quotation marks.

The following example queries for all documents where the second element in the array `dim_cm` is greater than `25`:

```java
findIterable = collection.find(gt("dim_cm.1", 25));
```

### Query an Array by Array Length

Use the [`$size`](https://www.mongodb.com/docs/manual/reference/operator/query/size.md#mongodb-query-op.-size) operator to query for arrays by number of elements.

The following example selects documents where `tags` has 3 elements:

```java
findIterable = collection.find(size("tags", 3));
```

This page provides examples of query operations on array fields using the [com.mongodb.reactivestreams.client.MongoCollection.find](http://mongodb.github.io/mongo-java-driver-reactivestreams/1.6/javadoc/com/mongodb/reactivestreams/client/MongoCollection.html#find\(\)) method in the MongoDB [Java Reactive Streams Driver](http://mongodb.github.io/mongo-java-driver-reactivestreams/1.6/).

The examples on this page use the `inventory` collection. Connect to a test database in your MongoDB instance then create the `inventory` collection:

```java
Publisher<Success> insertManyPublisher = collection.insertMany(asList(
        Document.parse("{ item: 'journal', qty: 25, tags: ['blank', 'red'], dim_cm: [ 14, 21 ] }"),
        Document.parse("{ item: 'notebook', qty: 50, tags: ['red', 'blank'], dim_cm: [ 14, 21 ] }"),
        Document.parse("{ item: 'paper', qty: 100, tags: ['red', 'blank', 'plain'], dim_cm: [ 14, 21 ] }"),
        Document.parse("{ item: 'planner', qty: 75, tags: ['blank', 'red'], dim_cm: [ 22.85, 30 ] }"),
        Document.parse("{ item: 'postcard', qty: 45, tags: ['blue'], dim_cm: [ 10, 15.25 ] }")
));
```

## Match an Array

To specify equality condition on an array, use the query document `eq( <field>, <value>)` where `<value>` is the exact array to match, including the order of the elements.

The following example queries for all documents where `tags` is an array with exactly two elements, `"red"` and `"blank"`, in the specified order:

```java
FindPublisher<Document> findPublisher = collection.find(eq("tags", asList("red", "blank")));
```

To find an array that contains both `"red"` and `"blank"` regardless of order or other elements in the array, use the [`$all`](https://www.mongodb.com/docs/manual/reference/operator/query/all.md#mongodb-query-op.-all) operator:

```java
findPublisher = collection.find(all("tags", asList("red", "blank")));
```

## Query an Array for an Element

To query if the array field contains at least *one* element with the specified value, use the filter `eq( <field>, <value>)` where value is the element value.

The following example queries for all documents where the `tags` array contains the string `"red"` as one of its elements:

```java
findPublisher = collection.find(eq("tags", "red"));
```

To specify conditions on the elements in the array field, use [query operators](https://www.mongodb.com/docs/manual/reference/mql/query-predicates.md#std-label-query-selectors) in the [query filter document](https://www.mongodb.com/docs/manual/core/documents-other-uses.md#std-label-document-query-filter). For example:

```java
and(gte(<array field>, <value1>), lt(<array field>, <value2>) ...)
```

The following example queries for all documents where the array `dim_cm` contains at least one element whose value is greater than `25`:

```java
findPublisher = collection.find(gt("dim_cm", 25));
```

## Specify Multiple Conditions for Array Elements

When you specify compound conditions on array elements, you can query for documents where either:

- A single array element meets all the specified conditions

- Different array elements collectively meet all the conditions, with each element satisfying one or more conditions

### Query an Array with Compound Filter Conditions on the Array Elements

The following example queries for documents where the `dim_cm` array contains elements that in some combination satisfy the query conditions. One element can satisfy the greater than `15` condition and another element can satisfy the less than `20` condition, or a single element can satisfy both:

```java
findPublisher = collection.find(and(gt("dim_cm", 15), lt("dim_cm", 20)));
```

### Query for an Array Element that Meets Multiple Criteria

Use the [`$elemMatch`](https://www.mongodb.com/docs/manual/reference/operator/query/elemmatch.md#mongodb-query-op.-elemMatch) operator to specify multiple criteria on array elements so that at least one array element satisfies all the specified criteria.

The following example queries for documents where the `dim_cm` array contains at least one element that is both greater than ([`$gt`](https://www.mongodb.com/docs/manual/reference/operator/query/gt.md#mongodb-query-op.-gt)) `22` and less than ([`$lt`](https://www.mongodb.com/docs/manual/reference/operator/query/lt.md#mongodb-query-op.-lt)) `30`:

```java
findPublisher = collection.find(elemMatch("dim_cm", Document.parse("{ $gt: 22, $lt: 30 }")));
```

### Query for an Element by the Array Index Position

Use [dot notation](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-dot-notation) to specify query conditions for an element at a particular index or position of the array. The array uses zero-based indexing.

**Note:**

When you query using dot notation, the field and nested field must be inside quotation marks.

The following example queries for all documents where the second element in the array `dim_cm` is greater than `25`:

```java
findPublisher = collection.find(elemMatch("dim_cm", Document.parse("{ $gt: 22, $lt: 30 }")));
```

### Query an Array by Array Length

Use the [`$size`](https://www.mongodb.com/docs/manual/reference/operator/query/size.md#mongodb-query-op.-size) operator to query for arrays by number of elements.

The following example selects documents where `tags` has 3 elements:

```java
findPublisher = collection.find(size("tags", 3));
```

This page provides examples of query operations on array fields by using the [MongoCollection.find()](https://mongodb.github.io/mongo-java-driver/5.11/apidocs/driver-kotlin-coroutine/mongodb-driver-kotlin-coroutine/com.mongodb.kotlin.client.coroutine/-mongo-collection/find.html) method in the MongoDB [Kotlin Coroutine Driver.](https://www.mongodb.com/docs/drivers/kotlin/coroutine/current/)

**Tip:**

The driver provides [com.mongodb.client.model.Filters](https://mongodb.github.io/mongo-java-driver/5.11/apidocs/driver-core/com/mongodb/client/model/Filters.html) helper methods to facilitate the creation of filter documents. The examples on this page use these methods to create the filter documents.

The examples on this page use the `inventory` collection. Connect to a test database in your MongoDB instance then create the `inventory` collection:

```kotlin
collection.insertMany(
    listOf(
        Document("item", "journal")
            .append("qty", 25)
            .append("tags", listOf("blank", "red"))
            .append("dim_cm", listOf(14, 21)),
        Document("item", "notebook")
            .append("qty", 50)
            .append("tags", listOf("red", "blank"))
            .append("dim_cm", listOf(14, 21)),
        Document("item", "paper")
            .append("qty", 100)
            .append("tags", listOf("red", "blank", "plain"))
            .append("dim_cm", listOf(14, 21)),
        Document("item", "planner")
            .append("qty", 75)
            .append("tags", listOf("blank", "red"))
            .append("dim_cm", listOf(22.85, 30)),
        Document("item", "postcard")
            .append("qty", 45)
            .append("tags", listOf("blue"))
            .append("dim_cm", listOf(10, 15.25)),
    )
)
```

## Match an Array

To specify equality condition on an array, use the query document `{ <field>: <value> }` where `<value>` is the exact array to match, including the order of the elements.

The following example queries for all documents where `tags` is an array with exactly two elements, `"red"` and `"blank"`, in the specified order:

```kotlin
val findFlow = collection
    .find(eq("tags", listOf("red", "blank")))
```

To find an array that contains both `"red"` and `"blank"` regardless of order or other elements in the array, use the [`$all`](https://www.mongodb.com/docs/manual/reference/operator/query/all.md#mongodb-query-op.-all) operator:

```kotlin
val findFlow = collection
    .find(all("tags", listOf("red", "blank")))
```

## Query an Array for an Element

To query if the array field contains at least *one* element with the specified value, use the filter `eq( <field>, <value>)` where `<value>` is the element value.

The following example queries for all documents where the `tags` array contains the string `"red"` as one of its elements:

```kotlin
val findFlow = collection
    .find(eq("tags", "red"))
```

To specify conditions on the elements in the array field, use [query operators](https://www.mongodb.com/docs/manual/reference/mql/query-predicates.md#std-label-query-selectors) in the [query filter document](https://www.mongodb.com/docs/manual/core/documents-other-uses.md#std-label-document-query-filter). For example:

```kotlin
and(gte(<array field>, <value1>), lt(<array field>, <value2>) ...)
```

The following example queries for all documents where the array `dim_cm` contains at least one element whose value is greater than `25`:

```kotlin
val findFlow = collection
    .find(gt("dim_cm", 25))
```

## Specify Multiple Conditions for Array Elements

When you specify compound conditions on array elements, you can query for documents where either:

- A single array element meets all the specified conditions

- Different array elements collectively meet all the conditions, with each element satisfying one or more conditions

### Query an Array with Compound Filter Conditions on the Array Elements

The following example queries for documents where the `dim_cm` array contains elements that in some combination satisfy the query conditions. One element can satisfy the greater than `15` condition and another element can satisfy the less than `20` condition, or a single element can satisfy both:

```kotlin
val findFlow = collection
    .find(and(gt("dim_cm", 15), lt("dim_cm", 20)))
```

### Query for an Array Element that Meets Multiple Criteria

Use the [`$elemMatch`](https://www.mongodb.com/docs/manual/reference/operator/query/elemmatch.md#mongodb-query-op.-elemMatch) operator to specify multiple criteria on array elements so that at least one array element satisfies all the specified criteria.

The following example queries for documents where the `dim_cm` array contains at least one element that is both greater than ([`$gt`](https://www.mongodb.com/docs/manual/reference/operator/query/gt.md#mongodb-query-op.-gt)) `22` and less than ([`$lt`](https://www.mongodb.com/docs/manual/reference/operator/query/lt.md#mongodb-query-op.-lt)) `30`:

```kotlin
val findFlow = collection
    .find(elemMatch("dim_cm", Document.parse("{ \$gt: 22, \$lt: 30 }")))
```

### Query for an Element by the Array Index Position

Use [dot notation](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-dot-notation) to specify query conditions for an element at a particular index or position of the array. The array uses zero-based indexing.

**Note:**

When you query using dot notation, the field and nested field must be inside quotation marks.

The following example queries for all documents where the second element in the array `dim_cm` is greater than `25`:

```kotlin
val findFlow = collection
    .find(gt("dim_cm.1", 25))
```

### Query an Array by Array Length

Use the [`$size`](https://www.mongodb.com/docs/manual/reference/operator/query/size.md#mongodb-query-op.-size) operator to query for arrays by number of elements.

The following example selects documents where `tags` has 3 elements:

```kotlin
val findFlow = collection
    .find(size("tags", 3))
```

This page provides examples of query operations on array fields using the [Collection.find()](http://mongodb.github.io/node-mongodb-native/3.6/api/Collection.html#find) method in the [MongoDB Node.js Driver.](http://mongodb.github.io/node-mongodb-native/3.6/)

The examples on this page use the `inventory` collection. Connect to a test database in your MongoDB instance then create the `inventory` collection:

```javascript
await db.collection('inventory').insertMany([
  {
    item: 'journal',
    qty: 25,
    tags: ['blank', 'red'],
    dim_cm: [14, 21]
  },
  {
    item: 'notebook',
    qty: 50,
    tags: ['red', 'blank'],
    dim_cm: [14, 21]
  },
  {
    item: 'paper',
    qty: 100,
    tags: ['red', 'blank', 'plain'],
    dim_cm: [14, 21]
  },
  {
    item: 'planner',
    qty: 75,
    tags: ['blank', 'red'],
    dim_cm: [22.85, 30]
  },
  {
    item: 'postcard',
    qty: 45,
    tags: ['blue'],
    dim_cm: [10, 15.25]
  }
]);
```

## Match an Array

To specify equality condition on an array, use the query document `{ <field>: <value> }` where `<value>` is the exact array to match, including the order of the elements.

The following example queries for all documents where `tags` is an array with exactly two elements, `"red"` and `"blank"`, in the specified order:

```javascript
const cursor = db.collection('inventory').find({
  tags: ['red', 'blank']
});
```

To find an array that contains both `"red"` and `"blank"` regardless of order or other elements in the array, use the [`$all`](https://www.mongodb.com/docs/manual/reference/operator/query/all.md#mongodb-query-op.-all) operator:

```javascript
const cursor = db.collection('inventory').find({
  tags: { $all: ['red', 'blank'] }
});
```

## Query an Array for an Element

To query if the array field contains at least *one* element with the specified value, use the filter `{ <field>: <value> }` where `<value>` is the element value.

The following example queries for all documents where the `tags` array contains the string `"red"` as one of its elements:

```javascript
const cursor = db.collection('inventory').find({
  tags: 'red'
});
```

To specify conditions on the elements in the array field, use [query operators](https://www.mongodb.com/docs/manual/reference/mql/query-predicates.md#std-label-query-selectors) in the [query filter document:](https://www.mongodb.com/docs/manual/core/documents-other-uses.md#std-label-document-query-filter)

```javascript
{ <array field>: { <operator1>: <value1>, ... } }
```

The following example queries for all documents where the array `dim_cm` contains at least one element whose value is greater than `25`:

```javascript
const cursor = db.collection('inventory').find({
  dim_cm: { $gt: 25 }
});
```

## Specify Multiple Conditions for Array Elements

When you specify compound conditions on array elements, you can query for documents where either:

- A single array element meets all the specified conditions

- Different array elements collectively meet all the conditions, with each element satisfying one or more conditions

### Query an Array with Compound Filter Conditions on the Array Elements

The following example queries for documents where the `dim_cm` array contains elements that in some combination satisfy the query conditions. One element can satisfy the greater than `15` condition and another element can satisfy the less than `20` condition, or a single element can satisfy both:

```javascript
const cursor = db.collection('inventory').find({
  dim_cm: { $gt: 15, $lt: 20 }
});
```

### Query for an Array Element that Meets Multiple Criteria

Use the [`$elemMatch`](https://www.mongodb.com/docs/manual/reference/operator/query/elemmatch.md#mongodb-query-op.-elemMatch) operator to specify multiple criteria on array elements so that at least one array element satisfies all the specified criteria.

The following example queries for documents where the `dim_cm` array contains at least one element that is both greater than ([`$gt`](https://www.mongodb.com/docs/manual/reference/operator/query/gt.md#mongodb-query-op.-gt)) `22` and less than ([`$lt`](https://www.mongodb.com/docs/manual/reference/operator/query/lt.md#mongodb-query-op.-lt)) `30`:

```javascript
const cursor = db.collection('inventory').find({
  dim_cm: { $elemMatch: { $gt: 22, $lt: 30 } }
});
```

### Query for an Element by the Array Index Position

Use [dot notation](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-dot-notation) to specify query conditions for an element at a particular index or position of the array. The array uses zero-based indexing.

**Note:**

When you query using dot notation, the field and nested field must be inside quotation marks.

The following example queries for all documents where the second element in the array `dim_cm` is greater than `25`:

```javascript
const cursor = db.collection('inventory').find({
  'dim_cm.1': { $gt: 25 }
});
```

### Query an Array by Array Length

Use the [`$size`](https://www.mongodb.com/docs/manual/reference/operator/query/size.md#mongodb-query-op.-size) operator to query for arrays by number of elements.

The following example selects documents where `tags` has 3 elements:

```javascript
const cursor = db.collection('inventory').find({
  tags: { $size: 3 }
});
```

This page provides examples of query operations on array fields using the [`MongoDB\\Collection::find()`](https://www.mongodb.com/docs/php-library/upcoming/reference/method/MongoDBCollection-find.md#mongodb-phpmethod-phpmethod.MongoDB-Collection--find--) method in the [MongoDB PHP Library](https://www.mongodb.com/docs/drivers/php-libraries/).

The examples on this page use the `inventory` collection. Connect to a test database in your MongoDB instance then create the `inventory` collection:

```php
$insertManyResult = $db->inventory->insertMany([
    [
        'item' => 'journal',
        'qty' => 25,
        'tags' => ['blank', 'red'],
        'dim_cm' => [14, 21],
    ],
    [
        'item' => 'notebook',
        'qty' => 50,
        'tags' => ['red', 'blank'],
        'dim_cm' => [14, 21],
    ],
    [
        'item' => 'paper',
        'qty' => 100,
        'tags' => ['red', 'blank', 'plain'],
        'dim_cm' => [14, 21],
    ],
    [
        'item' => 'planner',
        'qty' => 75,
        'tags' => ['blank', 'red'],
        'dim_cm' => [22.85, 30],
    ],
    [
        'item' => 'postcard',
        'qty' => 45,
        'tags' => ['blue'],
        'dim_cm' => [10, 15.25],
    ],
]);
```

## Match an Array

To specify equality condition on an array, use the query document `[ <field> => <value> ]` where `<value>` is the exact array to match, including the order of the elements.

The following example queries for all documents where `tags` is an array with exactly two elements, `"red"` and `"blank"`, in the specified order:

```php
$cursor = $db->inventory->find(['tags' => ['red', 'blank']]);
```

To find an array that contains both `"red"` and `"blank"` regardless of order or other elements in the array, use the [`$all`](https://www.mongodb.com/docs/manual/reference/operator/query/all.md#mongodb-query-op.-all) operator:

```php
$cursor = $db->inventory->find(['tags' => ['$all' => ['red', 'blank']]]);
```

## Query an Array for an Element

To query if the array field contains at least *one* element with the specified value, use the filter `[ <field> => <value> ]` where `<value>` is the element value.

The following example queries for all documents where the `tags` array contains the string `"red"` as one of its elements:

```php
$cursor = $db->inventory->find(['tags' => 'red']);
```

To specify conditions on the elements in the array field, use [query operators](https://www.mongodb.com/docs/manual/reference/mql/query-predicates.md#std-label-query-selectors) in the [query filter document:](https://www.mongodb.com/docs/manual/core/documents-other-uses.md#std-label-document-query-filter)

```php
[ <array field> => [ <operator1> => <value1>, ... ] ]
```

The following example queries for all documents where the array `dim_cm` contains at least one element whose value is greater than `25`:

```php
$cursor = $db->inventory->find(['dim_cm' => ['$gt' => 25]]);
```

## Specify Multiple Conditions for Array Elements

When you specify compound conditions on array elements, you can query for documents where either:

- A single array element meets all the specified conditions

- Different array elements collectively meet all the conditions, with each element satisfying one or more conditions

### Query an Array with Compound Filter Conditions on the Array Elements

The following example queries for documents where the `dim_cm` array contains elements that in some combination satisfy the query conditions. One element can satisfy the greater than `15` condition and another element can satisfy the less than `20` condition, or a single element can satisfy both:

```php
$cursor = $db->inventory->find([
    'dim_cm' => [
        '$gt' => 15,
        '$lt' => 20,
    ],
]);
```

### Query for an Array Element that Meets Multiple Criteria

Use the [`$elemMatch`](https://www.mongodb.com/docs/manual/reference/operator/query/elemmatch.md#mongodb-query-op.-elemMatch) operator to specify multiple criteria on array elements so that at least one array element satisfies all the specified criteria.

The following example queries for documents where the `dim_cm` array contains at least one element that is both greater than ([`$gt`](https://www.mongodb.com/docs/manual/reference/operator/query/gt.md#mongodb-query-op.-gt)) `22` and less than ([`$lt`](https://www.mongodb.com/docs/manual/reference/operator/query/lt.md#mongodb-query-op.-lt)) `30`:

```php
$cursor = $db->inventory->find([
    'dim_cm' => [
        '$elemMatch' => [
            '$gt' => 22,
            '$lt' => 30,
        ],
    ],
]);
```

### Query for an Element by the Array Index Position

Use [dot notation](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-dot-notation) to specify query conditions for an element at a particular index or position of the array. The array uses zero-based indexing.

**Note:**

When you query using dot notation, the field and nested field must be inside quotation marks.

The following example queries for all documents where the second element in the array `dim_cm` is greater than `25`:

```php
$cursor = $db->inventory->find(['dim_cm.1' => ['$gt' => 25]]);
```

### Query an Array by Array Length

Use the [`$size`](https://www.mongodb.com/docs/manual/reference/operator/query/size.md#mongodb-query-op.-size) operator to query for arrays by number of elements.

The following example selects documents where `tags` has 3 elements:

```php
$cursor = $db->inventory->find(['tags' => ['$size' => 3]]);
```

This page provides examples of query operations on array fields using the [Mongo::Collection#find()](https://www.mongodb.com/docs/ruby-driver/current/api/Mongo/Collection.html#find-instance_method) method in the [MongoDB Ruby Driver.](https://www.mongodb.com/docs/ruby-driver/current/)

The examples on this page use the `inventory` collection. Connect to a test database in your MongoDB instance then create the `inventory` collection:

```ruby
client[:inventory].insert_many([ { item: 'journal',
                                   qty: 25,
                                   tags: %w[blank red],
                                   dim_cm: [ 14, 21 ] },
                                 { item: 'notebook',
                                   qty: 50,
                                   tags: %w[red blank],
                                   dim_cm: [ 14, 21 ] },
                                 { item: 'paper',
                                   qty: 100,
                                   tags: %w[red blank plain],
                                   dim_cm: [ 14, 21 ] },
                                 { item: 'planner',
                                   qty: 75,
                                   tags: %w[blank red],
                                   dim_cm: [ 22.85, 30 ] },
                                 { item: 'postcard',
                                   qty: 45,
                                   tags: [ 'blue' ],
                                   dim_cm: [ 10, 15.25 ] } ])
```

## Match an Array

To specify equality condition on an array, use the query document `{ <field> => <value> }` where `<value>` is the exact array to match, including the order of the elements.

The following example queries for all documents where `tags` is an array with exactly two elements, `"red"` and `"blank"`, in the specified order:

```ruby
client[:inventory].find(tags: %w[red blank])
```

To find an array that contains both `"red"` and `"blank"` regardless of order or other elements in the array, use the [`$all`](https://www.mongodb.com/docs/manual/reference/operator/query/all.md#mongodb-query-op.-all) operator:

```ruby
client[:inventory].find(tags: { '$all' => %w[red blank] })
```

## Query an Array for an Element

To query if the array field contains at least *one* element with the specified value, use the filter `{ <field> => <value> }` where `<value>` is the element value.

The following example queries for all documents where the `tags` array contains the string `"red"` as one of its elements:

```ruby
client[:inventory].find(tags: 'red')
```

To specify conditions on the elements in the array field, use [query operators](https://www.mongodb.com/docs/manual/reference/mql/query-predicates.md#std-label-query-selectors) in the [query filter document:](https://www.mongodb.com/docs/manual/core/documents-other-uses.md#std-label-document-query-filter)

```ruby
{ <array field> => { <operator1> => <value1>, ... } }
```

The following example queries for all documents where the array `dim_cm` contains at least one element whose value is greater than `25`:

```ruby
client[:inventory].find(dim_cm: { '$gt' => 25 })
```

## Specify Multiple Conditions for Array Elements

When you specify compound conditions on array elements, you can query for documents where either:

- A single array element meets all the specified conditions

- Different array elements collectively meet all the conditions, with each element satisfying one or more conditions

### Query an Array with Compound Filter Conditions on the Array Elements

The following example queries for documents where the `dim_cm` array contains elements that in some combination satisfy the query conditions. One element can satisfy the greater than `15` condition and another element can satisfy the less than `20` condition, or a single element can satisfy both:

```ruby
client[:inventory].find(dim_cm: { '$gt' => 15,
                                  '$lt' => 20 })
```

### Query for an Array Element that Meets Multiple Criteria

Use the [`$elemMatch`](https://www.mongodb.com/docs/manual/reference/operator/query/elemmatch.md#mongodb-query-op.-elemMatch) operator to specify multiple criteria on array elements so that at least one array element satisfies all the specified criteria.

The following example queries for documents where the `dim_cm` array contains at least one element that is both greater than ([`$gt`](https://www.mongodb.com/docs/manual/reference/operator/query/gt.md#mongodb-query-op.-gt)) `22` and less than ([`$lt`](https://www.mongodb.com/docs/manual/reference/operator/query/lt.md#mongodb-query-op.-lt)) `30`:

```ruby
client[:inventory].find(dim_cm: { '$elemMatch' => { '$gt' => 22,
                                                    '$lt' => 30 } })
```

### Query for an Element by the Array Index Position

Use [dot notation](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-dot-notation) to specify query conditions for an element at a particular index or position of the array. The array uses zero-based indexing.

**Note:**

When you query using dot notation, the field and nested field must be inside quotation marks.

The following example queries for all documents where the second element in the array `dim_cm` is greater than `25`:

```ruby
client[:inventory].find('dim_cm.1' => { '$gt' => 25 })
```

### Query an Array by Array Length

Use the [`$size`](https://www.mongodb.com/docs/manual/reference/operator/query/size.md#mongodb-query-op.-size) operator to query for arrays by number of elements.

The following example selects documents where `tags` has 3 elements:

```ruby
client[:inventory].find(tags: { '$size' => 3 })
```

This page provides examples of query operations on array fields using the [collection.find()](http://mongodb.github.io/mongo-scala-driver/2.9/scaladoc/org/mongodb/scala/MongoCollection.html#find[C]\(filter:org.mongodb.scala.bson.conversions.Bson\)\(implicite:org.mongodb.scala.bson.DefaultHelper.DefaultsTo[C,TResult],implicitct:scala.reflect.ClassTag[C]\):org.mongodb.scala.FindObservable[C]) method in the [MongoDB Scala Driver](http://mongodb.github.io/mongo-scala-driver/).

The examples on this page use the `inventory` collection. Connect to a test database in your MongoDB instance then create the `inventory` collection:

```scala
collection.insertMany(Seq(
  Document("""{ item: "journal", qty: 25, tags: ["blank", "red"], dim_cm: [ 14, 21 ] }"""),
  Document("""{ item: "notebook", qty: 50, tags: ["red", "blank"], dim_cm: [ 14, 21 ] }"""),
  Document("""{ item: "paper", qty: 100, tags: ["red", "blank", "plain"], dim_cm: [ 14, 21 ] }"""),
  Document("""{ item: "planner", qty: 75, tags: ["blank", "red"], dim_cm: [ 22.85, 30 ] }"""),
  Document("""{ item: "postcard", qty: 45, tags: ["blue"], dim_cm: [ 10, 15.25 ] }""")
)).execute()
```

## Match an Array

To specify equality condition on an array, use the query document `equal( <field>, <value> )` where `<value>` is the exact array to match, including the order of the elements.

The following example queries for all documents where `tags` is an array with exactly two elements, `"red"` and `"blank"`, in the specified order:

```scala
var findObservable = collection.find(equal("tags", Seq("red", "blank")))
```

To find an array that contains both `"red"` and `"blank"` regardless of order or other elements in the array, use the [`$all`](https://www.mongodb.com/docs/manual/reference/operator/query/all.md#mongodb-query-op.-all) operator:

```scala
findObservable = collection.find(all("tags", "red", "blank"))
```

## Query an Array for an Element

To query if the array field contains at least *one* element with the specified value, use the filter `equal( <field>, <value> )` where `<value>` is the element value.

The following example queries for all documents where the `tags` array contains the string `"red"` as one of its elements:

```scala
findObservable = collection.find(equal("tags", "red"))
```

To specify conditions on the elements in the array field, use [query operators](https://www.mongodb.com/docs/manual/reference/mql/query-predicates.md#std-label-query-selectors) in the [query filter document:](https://www.mongodb.com/docs/manual/core/documents-other-uses.md#std-label-document-query-filter)

```scala
and(gte(<array field>, <value1>), lt(<array field>, <value2>) ...)
```

The following example queries for all documents where the array `dim_cm` contains at least one element whose value is greater than `25`:

```scala
findObservable = collection.find(gt("dim_cm", 25))
```

## Specify Multiple Conditions for Array Elements

When you specify compound conditions on array elements, you can query for documents where either:

- A single array element meets all the specified conditions

- Different array elements collectively meet all the conditions, with each element satisfying one or more conditions

### Query an Array with Compound Filter Conditions on the Array Elements

The following example queries for documents where the `dim_cm` array contains elements that in some combination satisfy the query conditions. One element can satisfy the greater than `15` condition and another element can satisfy the less than `20` condition, or a single element can satisfy both:

```scala
findObservable = collection.find(and(gt("dim_cm", 15), lt("dim_cm", 20)))
```

### Query for an Array Element that Meets Multiple Criteria

Use the [`$elemMatch`](https://www.mongodb.com/docs/manual/reference/operator/query/elemmatch.md#mongodb-query-op.-elemMatch) operator to specify multiple criteria on array elements so that at least one array element satisfies all the specified criteria.

The following example queries for documents where the `dim_cm` array contains at least one element that is both greater than ([`$gt`](https://www.mongodb.com/docs/manual/reference/operator/query/gt.md#mongodb-query-op.-gt)) `22` and less than ([`$lt`](https://www.mongodb.com/docs/manual/reference/operator/query/lt.md#mongodb-query-op.-lt)) `30`:

```scala
findObservable = collection.find(elemMatch("dim_cm", Document("$gt" -> 22, "$lt" -> 30)))

```

### Query for an Element by the Array Index Position

Use [dot notation](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-dot-notation) to specify query conditions for an element at a particular index or position of the array. The array uses zero-based indexing.

**Note:**

When you query using dot notation, the field and nested field must be inside quotation marks.

The following example queries for all documents where the second element in the array `dim_cm` is greater than `25`:

```scala
findObservable = collection.find(gt("dim_cm.1", 25))
```

### Query an Array by Array Length

Use the [`$size`](https://www.mongodb.com/docs/manual/reference/operator/query/size.md#mongodb-query-op.-size) operator to query for arrays by number of elements.

The following example selects documents where `tags` has 3 elements:

```scala
findObservable = collection.find(size("tags", 3))
```

This page provides examples of query operations on array fields using the [MongoCollection.Find()](https://mongodb.github.io/mongo-csharp-driver/2.10/apidocs/html/M_MongoDB_Driver_MongoCollection_1_Find.htm) method in the [MongoDB .NET/C# Driver](https://mongodb.github.io/mongo-csharp-driver/).

The examples on this page use the `inventory` collection. Connect to a test database in your MongoDB instance then create the `inventory` collection:

```csharp
var documents = new[]
{
    new BsonDocument
    {
        { "item", "journal" },
        { "qty", 25 },
        { "tags", new BsonArray { "blank", "red" } },
        { "dim_cm", new BsonArray { 14, 21 } }
    },
    new BsonDocument
    {
        { "item", "notebook" },
        { "qty", 50 },
        { "tags", new BsonArray { "red", "blank" } },
        { "dim_cm", new BsonArray { 14, 21 } }
    },
    new BsonDocument
    {
        { "item", "paper" },
        { "qty", 100 },
        { "tags", new BsonArray { "red", "blank", "plain" } },
        { "dim_cm", new BsonArray { 14, 21 } }
    },
    new BsonDocument
    {
        { "item", "planner" },
        { "qty", 75 },
        { "tags", new BsonArray { "blank", "red" } },
        { "dim_cm", new BsonArray { 22.85, 30 } }
    },
    new BsonDocument
    {
        { "item", "postcard" },
        { "qty", 45 },
        { "tags", new BsonArray { "blue" } },
        { "dim_cm", new BsonArray { 10, 15.25 } }
    }
};
collection.InsertMany(documents);
```

## Match an Array

To specify equality condition on an array, construct a filter using the [Eq](https://mongodb.github.io/mongo-csharp-driver/2.10/apidocs/html/Overload_MongoDB_Driver_FilterDefinitionBuilder_1_Eq.htm) method, where `<value>` is the exact array to match, including the order of the elements:

```csharp
Builders<BsonDocument>.Filter.Eq(<field>, <value>)
```

The following example queries for all documents where `tags` is an array with exactly two elements, `"red"` and `"blank"`, in the specified order:

```csharp
var filter = Builders<BsonDocument>.Filter.Eq("tags", new[] { "red", "blank" });
var result = collection.Find(filter).ToList();
```

To find an array that contains both `"red"` and `"blank"` regardless of order or other elements in the array, use the [`$all`](https://www.mongodb.com/docs/manual/reference/operator/query/all.md#mongodb-query-op.-all) operator:

```csharp
var filter = Builders<BsonDocument>.Filter.All("tags", new[] { "red", "blank" });
var result = collection.Find(filter).ToList();
```

## Query an Array for an Element

To query if the array field contains at least *one* element with the specified value, construct a filter using the [Eq](https://mongodb.github.io/mongo-csharp-driver/2.10/apidocs/html/Overload_MongoDB_Driver_FilterDefinitionBuilder_1_Eq.htm) method, where `<value>` is the element value to match:

```csharp
Builders<BsonDocument>.Filter.Eq(<field>, <value>)
```

The following example queries for all documents where the `tags` array contains the string `"red"` as one of its elements:

```csharp
var filter = Builders<BsonDocument>.Filter.Eq("tags", "red");
var result = collection.Find(filter).ToList();
```

To specify conditions on the elements in the array field, use [query operators](https://www.mongodb.com/docs/manual/reference/mql/query-predicates.md#std-label-query-selectors) in the [query filter document](https://www.mongodb.com/docs/manual/core/documents-other-uses.md#std-label-document-query-filter). For example:

```csharp
var builder = Builders<BsonDocument>.Filter;
builder.And(builder.Eq(<array field>, <value1>), builder.Lt(<array field>, <value2>));
```

The following example queries for all documents where the array `dim_cm` contains at least one element whose value is greater than `25`:

```csharp
var filter = Builders<BsonDocument>.Filter.Gt("dim_cm", 25);
var result = collection.Find(filter).ToList();
```

## Specify Multiple Conditions for Array Elements

When you specify compound conditions on array elements, you can query for documents where either:

- A single array element meets all the specified conditions

- Different array elements collectively meet all the conditions, with each element satisfying one or more conditions

### Query an Array with Compound Filter Conditions on the Array Elements

The following example queries for documents where the `dim_cm` array contains elements that in some combination satisfy the query conditions. One element can satisfy the greater than `15` condition and another element can satisfy the less than `20` condition, or a single element can satisfy both:

```csharp
var builder = Builders<BsonDocument>.Filter;
var filter = builder.And(builder.Gt("dim_cm", 15), builder.Lt("dim_cm", 20));
var result = collection.Find(filter).ToList();
```

### Query for an Array Element that Meets Multiple Criteria

Use the [`$elemMatch`](https://www.mongodb.com/docs/manual/reference/operator/query/elemmatch.md#mongodb-query-op.-elemMatch) operator to specify multiple criteria on array elements so that at least one array element satisfies all the specified criteria.

The following example queries for documents where the `dim_cm` array contains at least one element that is both greater than ([`$gt`](https://www.mongodb.com/docs/manual/reference/operator/query/gt.md#mongodb-query-op.-gt)) `22` and less than ([`$lt`](https://www.mongodb.com/docs/manual/reference/operator/query/lt.md#mongodb-query-op.-lt)) `30`:

```csharp
var filter = Builders<BsonDocument>.Filter.ElemMatch<BsonValue>("dim_cm", new BsonDocument { { "$gt", 22 }, { "$lt", 30 } });
var result = collection.Find(filter).ToList();
```

### Query for an Element by the Array Index Position

Use [dot notation](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-dot-notation) to specify query conditions for an element at a particular index or position of the array. The array uses zero-based indexing.

**Note:**

When you query using dot notation, the field and nested field must be inside quotation marks.

The following example queries for all documents where the second element in the array `dim_cm` is greater than `25`:

```csharp
var filter = Builders<BsonDocument>.Filter.Gt("dim_cm.1", 25);
var result = collection.Find(filter).ToList();
```

### Query an Array by Array Length

Use the [`$size`](https://www.mongodb.com/docs/manual/reference/operator/query/size.md#mongodb-query-op.-size) operator to query for arrays by number of elements.

The following example selects documents where `tags` has 3 elements:

```csharp
var filter = Builders<BsonDocument>.Filter.Size("tags", 3);
var result = collection.Find(filter).ToList();
```

This page provides examples of query operations on array fields using [mongoc\_collection\_find\_with\_opts.](https://mongoc.org/libmongoc/current/mongoc_collection_find_with_opts.html)

The examples on this page use the `inventory` collection. Connect to a test database in your MongoDB instance then create the `inventory` collection:

```c
mongoc_collection_t *collection;
mongoc_bulk_operation_t *bulk;
bson_t *doc;
bool r;
bson_error_t error;
bson_t reply;

collection = mongoc_database_get_collection (db, "inventory");
bulk = mongoc_collection_create_bulk_operation_with_opts (collection, NULL);
doc = BCON_NEW (
   "item", BCON_UTF8 ("journal"),
   "qty", BCON_INT64 (25),
   "tags", "[",
   BCON_UTF8 ("blank"), BCON_UTF8 ("red"),
   "]",
   "dim_cm", "[",
   BCON_INT64 (14), BCON_INT64 (21),
   "]");

r = mongoc_bulk_operation_insert_with_opts (bulk, doc, NULL, &error);
bson_destroy (doc);
if (!r) {
   MONGOC_ERROR ("%s\n", error.message);
   goto done;
}

doc = BCON_NEW (
   "item", BCON_UTF8 ("notebook"),
   "qty", BCON_INT64 (50),
   "tags", "[",
   BCON_UTF8 ("red"), BCON_UTF8 ("blank"),
   "]",
   "dim_cm", "[",
   BCON_INT64 (14), BCON_INT64 (21),
   "]");

r = mongoc_bulk_operation_insert_with_opts (bulk, doc, NULL, &error);
bson_destroy (doc);
if (!r) {
   MONGOC_ERROR ("%s\n", error.message);
   goto done;
}

doc = BCON_NEW (
   "item", BCON_UTF8 ("paper"),
   "qty", BCON_INT64 (100),
   "tags", "[",
   BCON_UTF8 ("red"), BCON_UTF8 ("blank"), BCON_UTF8 ("plain"),
   "]",
   "dim_cm", "[",
   BCON_INT64 (14), BCON_INT64 (21),
   "]");

r = mongoc_bulk_operation_insert_with_opts (bulk, doc, NULL, &error);
bson_destroy (doc);
if (!r) {
   MONGOC_ERROR ("%s\n", error.message);
   goto done;
}

doc = BCON_NEW (
   "item", BCON_UTF8 ("planner"),
   "qty", BCON_INT64 (75),
   "tags", "[",
   BCON_UTF8 ("blank"), BCON_UTF8 ("red"),
   "]",
   "dim_cm", "[",
   BCON_DOUBLE (22.85), BCON_INT64 (30),
   "]");

r = mongoc_bulk_operation_insert_with_opts (bulk, doc, NULL, &error);
bson_destroy (doc);
if (!r) {
   MONGOC_ERROR ("%s\n", error.message);
   goto done;
}

doc = BCON_NEW (
   "item", BCON_UTF8 ("postcard"),
   "qty", BCON_INT64 (45),
   "tags", "[",
   BCON_UTF8 ("blue"),
   "]",
   "dim_cm", "[",
   BCON_INT64 (10), BCON_DOUBLE (15.25),
   "]");

r = mongoc_bulk_operation_insert_with_opts (bulk, doc, NULL, &error);
bson_destroy (doc);
if (!r) {
   MONGOC_ERROR ("%s\n", error.message);
   goto done;
}

/* "reply" is initialized on success or error */
r = (bool) mongoc_bulk_operation_execute (bulk, &reply, &error);
if (!r) {
   MONGOC_ERROR ("%s\n", error.message);
}
```

## Match an Array

To specify equality condition on an array, use the query document `{ <field>: <value> }` where `<value>` is the exact array to match, including the order of the elements.

The following example queries for all documents where `tags` is an array with exactly two elements, `"red"` and `"blank"`, in the specified order:

```c
mongoc_collection_t *collection;
bson_t *filter;
mongoc_cursor_t *cursor;

collection = mongoc_database_get_collection (db, "inventory");
filter = BCON_NEW (
   "tags", "[",
   BCON_UTF8 ("red"), BCON_UTF8 ("blank"),
   "]");
cursor = mongoc_collection_find_with_opts (collection, filter, NULL, NULL);
```

To find an array that contains both `"red"` and `"blank"` regardless of order or other elements in the array, use the [`$all`](https://www.mongodb.com/docs/manual/reference/operator/query/all.md#mongodb-query-op.-all) operator:

```c
mongoc_collection_t *collection;
bson_t *filter;
mongoc_cursor_t *cursor;

collection = mongoc_database_get_collection (db, "inventory");
filter = BCON_NEW (
   "tags", "{",
   "$all", "[",
   BCON_UTF8 ("red"), BCON_UTF8 ("blank"),
   "]",
   "}");
cursor = mongoc_collection_find_with_opts (collection, filter, NULL, NULL);
```

## Query an Array for an Element

To query if the array field contains at least *one* element with the specified value, use the filter `{ <field>: <value> }` where `<value>` is the element value.

The following example queries for all documents where the `tags` array contains the string `"red"` as one of its elements:

```c
mongoc_collection_t *collection;
bson_t *filter;
mongoc_cursor_t *cursor;

collection = mongoc_database_get_collection (db, "inventory");
filter = BCON_NEW ("tags", BCON_UTF8 ("red"));
cursor = mongoc_collection_find_with_opts (collection, filter, NULL, NULL);
```

To specify conditions on the elements in the array field, use [query operators](https://www.mongodb.com/docs/manual/reference/mql/query-predicates.md#std-label-query-selectors) in the [query filter document:](https://www.mongodb.com/docs/manual/core/documents-other-uses.md#std-label-document-query-filter)

```c
{ <array field>: { <operator1>: <value1>, ... } }
```

The following example queries for all documents where the array `dim_cm` contains at least one element whose value is greater than `25`:

```c
mongoc_collection_t *collection;
bson_t *filter;
mongoc_cursor_t *cursor;

collection = mongoc_database_get_collection (db, "inventory");
filter = BCON_NEW (
   "dim_cm", "{",
   "$gt", BCON_INT64 (25),
   "}");
cursor = mongoc_collection_find_with_opts (collection, filter, NULL, NULL);
```

## Specify Multiple Conditions for Array Elements

When you specify compound conditions on array elements, you can query for documents where either:

- A single array element meets all the specified conditions

- Different array elements collectively meet all the conditions, with each element satisfying one or more conditions

### Query an Array with Compound Filter Conditions on the Array Elements

The following example queries for documents where the `dim_cm` array contains elements that in some combination satisfy the query conditions. One element can satisfy the greater than `15` condition and another element can satisfy the less than `20` condition, or a single element can satisfy both:

```c
mongoc_collection_t *collection;
bson_t *filter;
mongoc_cursor_t *cursor;

collection = mongoc_database_get_collection (db, "inventory");
filter = BCON_NEW (
   "dim_cm", "{",
   "$gt", BCON_INT64 (15),
   "$lt", BCON_INT64 (20),
   "}");
cursor = mongoc_collection_find_with_opts (collection, filter, NULL, NULL);
```

### Query for an Array Element that Meets Multiple Criteria

Use the [`$elemMatch`](https://www.mongodb.com/docs/manual/reference/operator/query/elemmatch.md#mongodb-query-op.-elemMatch) operator to specify multiple criteria on array elements so that at least one array element satisfies all the specified criteria.

The following example queries for documents where the `dim_cm` array contains at least one element that is both greater than ([`$gt`](https://www.mongodb.com/docs/manual/reference/operator/query/gt.md#mongodb-query-op.-gt)) `22` and less than ([`$lt`](https://www.mongodb.com/docs/manual/reference/operator/query/lt.md#mongodb-query-op.-lt)) `30`:

```c
mongoc_collection_t *collection;
bson_t *filter;
mongoc_cursor_t *cursor;

collection = mongoc_database_get_collection (db, "inventory");
filter = BCON_NEW (
   "dim_cm", "{",
   "$elemMatch", "{",
   "$gt", BCON_INT64 (22),
   "$lt", BCON_INT64 (30),
   "}",
   "}");
cursor = mongoc_collection_find_with_opts (collection, filter, NULL, NULL);
```

### Query for an Element by the Array Index Position

Use [dot notation](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-dot-notation) to specify query conditions for an element at a particular index or position of the array. The array uses zero-based indexing.

**Note:**

When you query using dot notation, the field and nested field must be inside quotation marks.

The following example queries for all documents where the second element in the array `dim_cm` is greater than `25`:

```c
mongoc_collection_t *collection;
bson_t *filter;
mongoc_cursor_t *cursor;

collection = mongoc_database_get_collection (db, "inventory");
filter = BCON_NEW (
   "dim_cm.1", "{",
   "$gt", BCON_INT64 (25),
   "}");
cursor = mongoc_collection_find_with_opts (collection, filter, NULL, NULL);
```

### Query an Array by Array Length

Use the [`$size`](https://www.mongodb.com/docs/manual/reference/operator/query/size.md#mongodb-query-op.-size) operator to query for arrays by number of elements.

The following example selects documents where `tags` has 3 elements:

```c
mongoc_collection_t *collection;
bson_t *filter;
mongoc_cursor_t *cursor;

collection = mongoc_database_get_collection (db, "inventory");
filter = BCON_NEW (
   "tags", "{",
   "$size", BCON_INT64 (3),
   "}");
cursor = mongoc_collection_find_with_opts (collection, filter, NULL, NULL);
```

Clean up any open resources by calling the following methods, as appropriate:

- [bson\_destroy](http://mongoc.org/libbson/current/bson_destroy.html)

- [mongoc\_bulk\_operation\_destroy](https://mongoc.org/libmongoc/current/mongoc_bulk_operation_destroy.html)

- [mongoc\_collection\_destroy](https://mongoc.org/libmongoc/current/mongoc_collection_destroy)

- [mongoc\_cursor\_destroy,](https://mongoc.org/libmongoc/current/mongoc_cursor_destroy.html)

This page provides examples of query operations on array fields using the [Collection.Find](https://godoc.org/github.com/mongodb/mongo-go-driver/mongo#Collection.Find) function in the [MongoDB Go Driver](https://github.com/mongodb/mongo-go-driver/).

The examples on this page use the `inventory` collection. Connect to a test database in your MongoDB instance then create the `inventory` collection:

```go

docs := []any{
	bson.D{
		{"item", "journal"},
		{"qty", 25},
		{"tags", bson.A{"blank", "red"}},
		{"dim_cm", bson.A{14, 21}},
	},
	bson.D{
		{"item", "notebook"},
		{"qty", 50},
		{"tags", bson.A{"red", "blank"}},
		{"dim_cm", bson.A{14, 21}},
	},
	bson.D{
		{"item", "paper"},
		{"qty", 100},
		{"tags", bson.A{"red", "blank", "plain"}},
		{"dim_cm", bson.A{14, 21}},
	},
	bson.D{
		{"item", "planner"},
		{"qty", 75},
		{"tags", bson.A{"blank", "red"}},
		{"dim_cm", bson.A{22.85, 30}},
	},
	bson.D{
		{"item", "postcard"},
		{"qty", 45},
		{"tags", bson.A{"blue"}},
		{"dim_cm", bson.A{10, 15.25}},
	},
}

result, err := coll.InsertMany(context.TODO(), docs)

```

## Match an Array

To specify equality condition on an array, use the query document `{ <field>: <value> }` where `<value>` is the exact array to match, including the order of the elements.

The following example queries for all documents where `tags` is an array with exactly two elements, `"red"` and `"blank"`, in the specified order:

```go

cursor, err := coll.Find(
	context.TODO(),
	bson.D{{"tags", bson.A{"red", "blank"}}},
)

```

To find an array that contains both `"red"` and `"blank"` regardless of order or other elements in the array, use the [`$all`](https://www.mongodb.com/docs/manual/reference/operator/query/all.md#mongodb-query-op.-all) operator:

```go

cursor, err := coll.Find(
	context.TODO(),
	bson.D{
		{"tags", bson.D{{"$all", bson.A{"red", "blank"}}}},
	})

```

## Query an Array for an Element

To query if the array field contains at least *one* element with the specified value, use the filter `eq( <field>, <value>)` where `<value>` is the element value.

The following example queries for all documents where the `tags` array contains the string `"red"` as one of its elements:

```go

cursor, err := coll.Find(
	context.TODO(),
	bson.D{
		{"tags", "red"},
	})

```

To specify conditions on the elements in the array field, use [query operators](https://www.mongodb.com/docs/manual/reference/mql/query-predicates.md#std-label-query-selectors) in the [query filter document](https://www.mongodb.com/docs/manual/core/documents-other-uses.md#std-label-document-query-filter). For example:

```go
filter := bson.D{
    {"$and", bson.A{
        bson.D{{<array field>, bson.D{{"$eq", <value1>}}}},
        bson.D{{<array field>, bson.D{{"$lt", <value2>}}}},
    }},
}
```

The following example queries for all documents where the array `dim_cm` contains at least one element whose value is greater than `25`:

```go

cursor, err := coll.Find(
	context.TODO(),
	bson.D{
		{"dim_cm", bson.D{
			{"$gt", 25},
		}},
	})

```

## Specify Multiple Conditions for Array Elements

When you specify compound conditions on array elements, you can query for documents where either:

- A single array element meets all the specified conditions

- Different array elements collectively meet all the conditions, with each element satisfying one or more conditions

### Query an Array with Compound Filter Conditions on the Array Elements

The following example queries for documents where the `dim_cm` array contains elements that in some combination satisfy the query conditions. One element can satisfy the greater than `15` condition and another element can satisfy the less than `20` condition, or a single element can satisfy both:

```go

cursor, err := coll.Find(
	context.TODO(),
	bson.D{
		{"dim_cm", bson.D{
			{"$gt", 15},
			{"$lt", 20},
		}},
	})

```

### Query for an Array Element that Meets Multiple Criteria

Use the [`$elemMatch`](https://www.mongodb.com/docs/manual/reference/operator/query/elemmatch.md#mongodb-query-op.-elemMatch) operator to specify multiple criteria on array elements so that at least one array element satisfies all the specified criteria.

The following example queries for documents where the `dim_cm` array contains at least one element that is both greater than ([`$gt`](https://www.mongodb.com/docs/manual/reference/operator/query/gt.md#mongodb-query-op.-gt)) `22` and less than ([`$lt`](https://www.mongodb.com/docs/manual/reference/operator/query/lt.md#mongodb-query-op.-lt)) `30`:

```go

cursor, err := coll.Find(
	context.TODO(),
	bson.D{
		{"dim_cm", bson.D{
			{"$elemMatch", bson.D{
				{"$gt", 22},
				{"$lt", 30},
			}},
		}},
	})

```

### Query for an Element by the Array Index Position

Use [dot notation](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-dot-notation) to specify query conditions for an element at a particular index or position of the array. The array uses zero-based indexing.

**Note:**

When you query using dot notation, the field and nested field must be inside quotation marks.

The following example queries for all documents where the second element in the array `dim_cm` is greater than `25`:

```go

cursor, err := coll.Find(
	context.TODO(),
	bson.D{
		{"dim_cm.1", bson.D{
			{"$gt", 25},
		}},
	})

```

### Query an Array by Array Length

Use the [`$size`](https://www.mongodb.com/docs/manual/reference/operator/query/size.md#mongodb-query-op.-size) operator to query for arrays by number of elements.

The following example selects documents where `tags` has 3 elements:

```go

cursor, err := coll.Find(
	context.TODO(),
	bson.D{
		{"tags", bson.D{
			{"$size", 3},
		}},
	})

```

This page provides examples of query operations on array fields using [MongoDB Compass.](https://www.mongodb.com/docs/compass/current.md#std-label-compass-index)

The examples on this page use the `inventory` collection. Connect to a test database in your MongoDB instance then create the `inventory` collection:

```javascript
[
    { "item": "journal", "qty": 25, "tags": ["blank", "red"], "dim_cm": [ 14, 21 ] },
    { "item": "notebook", "qty": 50, "tags": ["red", "blank"], "dim_cm": [ 14, 21 ] },
    { "item": "paper", "qty": 100, "tags": ["red", "blank", "plain"], "dim_cm": [ 14, 21 ] },
    { "item": "planner", "qty": 75, "tags": ["blank", "red"], "dim_cm": [ 22.85, 30 ] },
    { "item": "postcard", "qty": 45, "tags": ["blue"], "dim_cm": [ 10, 15.25 ] }
]
```

For instructions on inserting documents in MongoDB Compass, see [Insert Documents.](https://www.mongodb.com/docs/manual/tutorial/insert-documents.md#std-label-write-op-insert)

## Match an Array

To specify equality condition on an array, use the query document `{ <field>: <value> }` where `<value>` is the exact array to match, including the order of the elements.

The following example queries for all documents where `tags` is an array with exactly two elements, `"red"` and `"blank"`, in the specified order:

Copy the following filter into the Compass query bar and click Find:

```javascript
{ tags: ["red", "blank"] }
```

![Query array matching exactly](/images/compass-array-match-exact.png)

To find an array that contains both `"red"` and `"blank"` regardless of order or other elements in the array, use the [`$all`](https://www.mongodb.com/docs/manual/reference/operator/query/all.md#mongodb-query-op.-all) operator:

Copy the following filter into the Compass query bar and click Find:

```javascript
{ tags: { $all: ["red", "blank"] } }
```

![Query array matching all criteria](/images/compass-array-match-all.png)

## Query an Array for an Element

To query if the array field contains at least *one* element with the specified value, use the filter `{ <field>: <value> }` where `<value>` is the element value.

The following example queries for all documents where the `tags` array contains the string `"red"` as one of its elements:

Copy the following filter into the Compass query bar and click Find:

```javascript
{ tags: "red" }
```

![Query array matching multiple criteria](/images/compass-array-elem-match.png)

To specify conditions on the elements in the array field, use [query operators](https://www.mongodb.com/docs/manual/reference/mql/query-predicates.md#std-label-query-selectors) in the [query filter document:](https://www.mongodb.com/docs/manual/core/documents-other-uses.md#std-label-document-query-filter)

```javascript
{ <array field>: { <operator1>: <value1>, ... } }
```

The following example queries for all documents where the array `dim_cm` contains at least one element whose value is greater than `25`:

Copy the following filter into the Compass query bar and click Find:

```javascript
{ dim_cm: { $gt: 25 } }
```

## Specify Multiple Conditions for Array Elements

When you specify compound conditions on array elements, you can query for documents where either:

- A single array element meets all the specified conditions

- Different array elements collectively meet all the conditions, with each element satisfying one or more conditions

### Query an Array with Compound Filter Conditions on the Array Elements

The following example queries for documents where the `dim_cm` array contains elements that in some combination satisfy the query conditions. One element can satisfy the greater than `15` condition and another element can satisfy the less than `20` condition, or a single element can satisfy both:

Copy the following filter into the Compass query bar and click Find:

```javascript
{ dim_cm: { $gt: 15, $lt: 20 } }
```

![Query array using a compound filter](/images/compass-array-compound-filter.png)

### Query for an Array Element that Meets Multiple Criteria

Use the [`$elemMatch`](https://www.mongodb.com/docs/manual/reference/operator/query/elemmatch.md#mongodb-query-op.-elemMatch) operator to specify multiple criteria on array elements so that at least one array element satisfies all the specified criteria.

The following example queries for documents where the `dim_cm` array contains at least one element that is both greater than ([`$gt`](https://www.mongodb.com/docs/manual/reference/operator/query/gt.md#mongodb-query-op.-gt)) `22` and less than ([`$lt`](https://www.mongodb.com/docs/manual/reference/operator/query/lt.md#mongodb-query-op.-lt)) `30`:

Copy the following filter into the Compass query bar and click Find:

```javascript
{ dim_cm: { $elemMatch: { $gt: 22, $lt: 30 } } }
```

![Query array by multiple conditions](/images/compass-array-compound-multiple-criteria.png)

### Query for an Element by the Array Index Position

Use [dot notation](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-dot-notation) to specify query conditions for an element at a particular index or position of the array. The array uses zero-based indexing.

**Note:**

When you query using dot notation, the field and nested field must be inside quotation marks.

The following example queries for all documents where the second element in the array `dim_cm` is greater than `25`:

Copy the following filter into the Compass query bar and click Find:

```javascript
{ "dim_cm.1": { $gt: 25 } }
```

![Query array by index](/images/compass-array-match-by-index.png)

### Query an Array by Array Length

Use the [`$size`](https://www.mongodb.com/docs/manual/reference/operator/query/size.md#mongodb-query-op.-size) operator to query for arrays by number of elements.

The following example selects documents where `tags` has 3 elements:

Copy the following filter into the Compass query bar and click Find:

```javascript
{ "tags": { $size: 3 } }
```

## Query an Array with MongoDB Atlas

The example in this section uses the [sample movies dataset](https://www.mongodb.com/docs/atlas/sample-data/sample-mflix/). To learn how to load the sample dataset into your MongoDB Atlas deployment, see [Load Sample Data.](https://www.mongodb.com/docs/atlas/sample-data/#std-label-load-sample-data)

To query an array in MongoDB Atlas, follow these steps:

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

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

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

   In the sidebar, click Clusters under the Database heading.

   The [Clusters](https://cloud.mongodb.com/go?l=https%3A%2F%2Fcloud.mongodb.com%2Fv2%2F%3Cproject%3E%23%2Fclusters) page displays.

2. Navigate to the collection.

   For the cluster that contains the sample data, click Browse Collections.

   In the left navigation pane, select the `sample_mflix` database.

   Select the `movies` collection.

3. Specify a query filter document.

   To query a document that contains an array, specify a [query filter document](https://www.mongodb.com/docs/manual/core/documents-other-uses.md#std-label-document-query-filter). A query filter document uses [query operators](https://www.mongodb.com/docs/manual/core/csfle/reference/supported-operations.md#std-label-csfle-supported-query-operators) to specify search conditions. Use the following example documents to query array fields in the `sample_mflix.movies` collection.

   To apply a query filter, copy an example document into the Filter search bar and click Apply.

## Match an Array

To specify an equality condition on an array, use the query document `{ <field>: <value> }` where `<value>` is the exact array to match, including the order of the elements. The following example finds documents where `genres` contains the `["Action", "Comedy"]` array in the specified order:

```text
{ genres: ["Action", "Comedy"] }
```

To find an array that contains both `Action` and `Comedy` regardless of order or other elements in the array, use the [`$all`](https://www.mongodb.com/docs/manual/reference/operator/query/all.md#mongodb-query-op.-all) operator:

```text
{ genres: { $all: ["Action", "Comedy"] } }
```

## Query an Array for an Element

To query if the array field contains at least one element with the specified value, use the filter `{ <field>: <value> }` where `<value>` is the element value.

The following example queries for all documents where the `genres` field contains the string `Short` as one of its elements:

```text
{ genres: "Short" }
```

To specify conditions on the elements in the array field, use [query operators](https://www.mongodb.com/docs/manual/reference/mql/query-predicates.md#std-label-query-selectors) in the [query filter document:](https://www.mongodb.com/docs/manual/core/documents-other-uses.md#std-label-document-query-filter)

```text
{ <array field>: { <operator1>: <value1>, ... } }
```

The following example uses the [`$nin`](https://www.mongodb.com/docs/manual/reference/operator/query/nin.md#mongodb-query-op.-nin) operator to query for all documents where the `genres` field does not contain `Drama`:

```text
{ genres: { $nin: ["Drama"] } }
```

## Specify Multiple Conditions for Array Elements

When you specify compound conditions on array elements, you can query for documents where either:

- A single array element meets all the specified conditions

- Different array elements collectively meet all the conditions, with each element satisfying one or more conditions

### Query an Array with Compound Filter Conditions on the Array Elements

The following example queries for documents where the `cast` array contains elements that in some combination satisfy the query conditions. The following filter uses the [`$regex`](https://www.mongodb.com/docs/manual/reference/operator/query/regex.md#mongodb-query-op.-regex) and [`$eq`](https://www.mongodb.com/docs/manual/reference/operator/query/eq.md#mongodb-query-op.-eq) operators to return documents where a single array element ends in `Olsen` and another element equals `Mary-Kate Olsen` or a single element that satisfies both conditions:

```text
{ cast: { $regex: "Olsen$", $eq: "Mary-Kate Olsen" } }
```

This query filter returns movies that include `Mary-Kate
    Olsen` in their cast, and movies that include both `Mary-Kate Olsen` and `Ashley Olsen` in their cast.

### Query for an Array Element that Meets Multiple Criteria

Use the [`$elemMatch`](https://www.mongodb.com/docs/manual/reference/operator/query/elemmatch.md#mongodb-query-op.-elemMatch) operator to specify multiple criteria on array elements so that at least one array element satisfies all the specified criteria.

The following example uses the [`$elemMatch`](https://www.mongodb.com/docs/manual/reference/operator/query/elemmatch.md#mongodb-query-op.-elemMatch) and [`$ne`](https://www.mongodb.com/docs/manual/reference/operator/query/ne.md#mongodb-query-op.-ne) operators to query for documents where `languages` contains at least one element that is both not `null` and does not equal `English`:

```text
{ languages: { $elemMatch: { $ne: null, $ne: "English" } } }
```

### Query for an Element by the Array Index Position

Use [dot notation](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-dot-notation) to specify query conditions for an element at a particular index or position of the array. The array uses zero-based indexing.

**Note:**

When you query using dot notation, the field and nested field must be inside quotation marks.

The following example uses the [`$ne`](https://www.mongodb.com/docs/manual/reference/operator/query/ne.md#mongodb-query-op.-ne) operator to query for all documents where the first element in the `countries` array is not equal to `USA`:

```text
{ "countries.0": { $ne: "USA" } }
```

### Query an Array by Array Length

Use the [`$size`](https://www.mongodb.com/docs/manual/reference/operator/query/size.md#mongodb-query-op.-size) operator to query for arrays by number of elements.

The following example selects documents where `genres` has 3 elements:

```text
{ genres: { $size: 3 } }
```

## Additional Query Tutorials

For additional query examples, see:

- [Read Documents](https://www.mongodb.com/docs/manual/tutorial/query-documents.md)

- [Query on Embedded/Nested Documents](https://www.mongodb.com/docs/manual/tutorial/query-embedded-documents.md)

- [Query an Array of Embedded Documents](https://www.mongodb.com/docs/manual/tutorial/query-array-of-documents.md)