Filter operators for collections

Use filter (query) operators to find documents in a collection.

All operators are case-sensitive.

Operator type Name Purpose

Operator type	Name	Purpose
Logical query	`$and`	Joins query clauses with a logical `AND`, returning the documents that match the conditions of both clauses.
	`$or`	Joins query clauses with a logical `OR`, returning the documents that match the conditions of either clause.
	`$not`	Returns documents that do not match the conditions of the filter clause.
Range query	`$gt`	Matches documents where the given property is greater than the specified value.
	`$gte`	Matches documents where the given property is greater than or equal to the specified value.
	`$lt`	Matches documents where the given property is less than the specified value.
	`$lte`	Matches documents where the given property is less than or equal to the specified value.
Comparison query	`$eq`	Matches documents where the value of a property equals the specified value. This is the default when you do not specify an operator.
	`$ne`	Matches documents where the value of a property does not equal the specified value.
	`$in`	Match one or more of an array of specified values. For example, `"filter": { "FIELD_NAME": { "$in": [ "VALUE", "VALUE" ] } }`. If you have only one value to match, an array is not necessary, such as `{ "$in": "VALUE" }`. The `$in` operator also functions as a `$contains` operator. For example, a field containing the array `[ 1, 2, 3 ]` will match filters like `{ "$in": [ 2, 6 ] }` or `{ "$in": 1 }`.
	`$nin`	Matches any of the values that are NOT IN the array.
Element query	`$exists`	Matches documents that have the specified property.
Array query	`$all`	Matches arrays that contain all elements in the specified array.
	`$size`	Selects documents where the array has the specified number of elements.

Logical query

$and

Joins query clauses with a logical AND, returning the documents that match the conditions of both clauses.

$or

Joins query clauses with a logical OR, returning the documents that match the conditions of either clause.

$not

Returns documents that do not match the conditions of the filter clause.

Range query

$gt

Matches documents where the given property is greater than the specified value.

$gte

Matches documents where the given property is greater than or equal to the specified value.

$lt

Matches documents where the given property is less than the specified value.

$lte

Matches documents where the given property is less than or equal to the specified value.

Comparison query

$eq

Matches documents where the value of a property equals the specified value. This is the default when you do not specify an operator.

$ne

Matches documents where the value of a property does not equal the specified value.

$in

Match one or more of an array of specified values. For example, "filter": { "FIELD_NAME": { "$in": [ "VALUE", "VALUE" ] } }.

If you have only one value to match, an array is not necessary, such as { "$in": "VALUE" }.

The $in operator also functions as a $contains operator. For example, a field containing the array [ 1, 2, 3 ] will match filters like { "$in": [ 2, 6 ] } or { "$in": 1 }.

$nin

Matches any of the values that are NOT IN the array.

Element query

$exists

Matches documents that have the specified property.

Array query

$all

Matches arrays that contain all elements in the specified array.

$size

Selects documents where the array has the specified number of elements.

Examples

Match values that are present:

"find": {
  "filter": { "preferred_customer": { "$exists": true } }
}

Match values that are equal to the filter value:

"find": {
  "filter": {
    "customer": {
      "$eq": {
        "name": "Jasmine S.",
        "city": "Jersey City"
      }
    }
  }
}

Match values that are not the filter value:

"find": {
  "filter": {
    "$not": {
      "customer.address.state": "NJ"
    }
  }
}

You can use similar $not operators for arrays, such as $nin an $ne.

Match one or more of an array of specified values:

"find": {
  "filter": {
    "customer.address.city": {
      "$in": [ "Jersey City", "Orange" ]
    }
  }
}

If you have only one value to match, an array is not necessary, such as { "$in": "Jersey City" }.

The $in operator also functions as a $contains operator. For example, a field containing the array [ 1, 2, 3 ] will match filters like { "$in": [ 2, 6 ] } or { "$in": 1 }.

Match all specified values:

"find": {
  "filter": {
    "items": {
      "$all": [
        {
          "car": "Sedan",
          "color": "White"
        },
        "Extended warranty"
      ]
    }
  }
}

Compound and/or operators:

"find": {
  "filter": {
    "$and": [
      {
        "$or": [
          { "customer.address.city": "Jersey City" },
          { "customer.address.city": "Orange" }
        ]
      },
      {
        "$or": [
          { "seller.name": "Jim A." },
          { "seller.name": "Tammy S." }
        ]
      }
    ]
  }
}

Compound range operators:

"find": {
  "filter": {
    "$and": [
      { "customer.credit_score": { "$gte": 700 } },
      { "customer.credit_score": { "$lt": 800 } }
    ]
  }
}

Filter on a date:

"find": {
  "filter": { "purchase_date": { "$date": 1690045891 } }
}

This example uses the $and and $or logical operators to retrieve documents matching one condition from each $or clause. In this case, the customer.address.city must be either Jersey City or Orange and the seller.name must be either Jim A. or Tammy S..

"find": {
  "filter": {
    "$and": [
      {
        "$or": [
          { "customer.address.city": "Jersey City" },
          { "customer.address.city": "Orange" }
        ]
      },
      {
        "$or": [
          { "seller.name": "Jim A." },
          { "seller.name": "Tammy S." }
        ]
      }
    ]
  }
}' | jq

For more examples, see the references for commands that use these operators, such as:

Filter operators for collections

Examples

Was this helpful?

Give Feedback