Data Store Query Object

A query object is a JavaScript object that contains conditions for matching documents in a collection. Use it to select documents to retrieve, update, or delete.

Pass a query object as an argument to the following methods:

• Collection.find(query)

• Collection.findOne(query)

• Collection.updateOne(query, update)

• Collection.updateMany(query, update)

• Collection.deleteOne(query)

• Collection.deleteMany(query)

For validation messages, see the Errors section of the relevant method.

Before you construct a query object, see the following for guidance:

• Query Object Structure

• Data Store Query Operators

• Data Store Query Rules

• Data Store Query Limits

• Data Store Array Queries

• Syntax

Query Object Structure

A query object uses document field names and logical operator names as properties. For nested object properties, use dot notation, such as profile.country.

Query operators specify conditions for matching document fields. Use them to compare values, match any value in a list, check whether a field exists, or match array elements. For more information about query operators, see Data Store Query Operators.

The following table describes the supported condition types. The syntax uses placeholders for actual field names, values, operators, and query objects.

Condition Type	Description
Direct value match	Matches the field against the specified value. { field: value }
Field operator condition	Applies the specified query operators to the field. If multiple comparison operators are specified, every comparison must be satisfied. { field: { $operator: value } }
Condition group	Combines query objects using $and or $or. Each query object can contain document field conditions, condition groups, or both. { $and: [queryObject, ...] } { $or: [queryObject, ...] }

A query object can contain both field conditions and condition groups. Each property defines a condition. When the object contains multiple properties, their conditions are implicitly combined using AND. A document must satisfy every condition. Property order doesn't affect matching.

An empty query object matches all documents in the collection.

Syntax

The following example combines field conditions, comparison operators, dot notation, and a condition group.

A document matches when all the following conditions are met:

• status equals 'pending'.

• attemptCount is at least 0 and less than 3.

• country within profile equals 'ES'.

• Either priority equals 'high' or tier matches 'gold' or 'platinum'.

Important:

The following code sample shows how to define and use a query. It isn't a functional example. For a complete script example, see N/dataStore Module Script Samples.

            const collection = dataStore.getCollection('checkpoints');

const query = {
    status: 'pending',
    attemptCount: { $gte: 0, $lt: 3 },
    'profile.country': 'ES',
    $or: [
        { priority: 'high' },
        { tier: { $in: ['gold', 'platinum'] } }
    ]
};

const result = await collection.findOne(query); 

          

Related Topics

• N/dataStore Module
• Data Store Update Object
• N/dataStore Module Script Samples

General Notices