2.1.Comparison Operators

¶ 2.1.1. Comparison Operators List

¶ 2.1.2. $eq

Specifies equality condition. The $eq operator matches documents where the value of a field equals the specified value.

{ <field>: { $eq: <value> } }

The $eq expression is equivalent to { field: <value> }.

§ 2.1.2.1. A collection for Examples

The following examples query against the inventory collection with the following documents:

{ _id: 1, item: { name: "ab", code: "123" }, qty: 15, tags: [ "A", "B", "C" ] }
{ _id: 2, item: { name: "cd", code: "123" }, qty: 20, tags: [ "B" ] }
{ _id: 3, item: { name: "ij", code: "456" }, qty: 25, tags: [ "A", "B" ] }
{ _id: 4, item: { name: "xy", code: "456" }, qty: 30, tags: [ "B", "A" ] }
{ _id: 5, item: { name: "mn", code: "000" }, qty: 20, tags: [ [ "A", "B" ], "C" ] }

§ 2.1.2.2. Example of Equals a Specified Value

The following example queries the inventory collection to select all documents where the value of the qty field equals 20:

tim.X("inventory").Get( { qty: { $eq: 20 } } )

The query is equivalent to:

tim.X("inventory").Get( { qty: 20 } )

Both queries match the following documents:

{ _id: 2, item: { name: "cd", code: "123" }, qty: 20, tags: [ "B" ] }
{ _id: 5, item: { name: "mn", code: "000" }, qty: 20, tags: [ [ "A", "B" ], "C" ] }

§ 2.1.2.3. Example of Field in Embedded Document Equals a Value

The following example queries the inventory collection to select all documents where the value of the name field in the item document equals "ab". To specify a condition on a field in an embedded document, use the dot notation.

tim.X("inventory").Get( { "item.name": { $eq: "ab" } } )

The query is equivalent to:

tim.X("inventory").Get( { "item.name": "ab" } )

Both queries match the following document:

{ _id: 1, item: { name: "ab", code: "123" }, qty: 15, tags: [ "A", "B", "C" ] }

§ 2.1.2.4. Example of Array Element Equals a Value

The following example queries the inventory collection to select all documents where the tags array contains an element with the value "B" :

tim.X("inventory").Get( { tags: { $eq: "B" } } )

The query is equivalent to:

tim.X("inventory").Get( { tags: "B" } )

Both queries match the following documents:

{ _id: 1, item: { name: "ab", code: "123" }, qty: 15, tags: [ "A", "B", "C" ] }
{ _id: 2, item: { name: "cd", code: "123" }, qty: 20, tags: [ "B" ] }
{ _id: 3, item: { name: "ij", code: "456" }, qty: 25, tags: [ "A", "B" ] }
{ _id: 4, item: { name: "xy", code: "456" }, qty: 30, tags: [ "B", "A" ] }

§ 2.1.2.5. Example of Equals an Array Value

If the specified <value> is an array, X-Server matches documents where the <field> matches the array exactly or the <field> contains an element that matches the array exactly. The order of the elements matters. The following example queries the inventory collection to select all documents where the tags array equals exactly the specified array or the tags array contains an element that equals the array [ "A", "B" ].

tim.X("inventory").Get( { tags: { $eq: [ "A", "B" ] } } )

The query is equivalent to:

tim.X("inventory").Get( { tags: [ "A", "B" ] } )

Both queries match the following documents:

{ _id: 3, item: { name: "ij", code: "456" }, qty: 25, tags: [ "A", "B" ] }
{ _id: 5, item: { name: "mn", code: "000" }, qty: 20, tags: [ [ "A", "B" ], "C" ] }

¶ 2.1.3. $gt

Syntax: {field: {$gt: value} } $gt selects those documents where the value of the field is greater than (i.e. >) the specified value. Consider the following example:

tim.X("inventory").Get( { qty: { $gt: 20 } } )

This query will select all documents in the inventory collection where the qty field value is greater than 20.

Consider the following example that uses the $gt operator with a field from an embedded document:

tim.X("inventory").Set( { "carrier.fee": { $gt: 2 } }, { $set: { price: 9.99 } } )

This Set operation will set the value of the price field in the first document found containing the embedded document carrier whose fee field value is greater than 2.

To set the value of the price field in all documents containing the embedded document carrier whose fee field value is greater than 2, specify the multi:true option in the Set method:

tim.X("inventory").Set(
{ "carrier.fee": { $gt: 2 } },
{ $set: { price: 9.99 } },
{ multi: true }
);

¶ 2.1.4. $gte

Syntax: {field: {$gte: value} } $gte selects the documents where the value of the field is greater than or equal to (i.e. >=) a specified value (e.g. value.) Consider the following example:

tim.X("inventory").Get( { qty: { $gte: 20 } } )

This query would select all documents in inventory where the qty field value is greater than or equal to 20.

Consider the following example which uses the $gte operator with a field from an embedded document:

tim.X("inventory").Set( { "carrier.fee": { $gte: 2 } }, { $set: { price: 9.99 } } )

This tim.X("inventory").Set operation will set the value of the price field that contain the embedded document carrier whose fee field value is greater than or equal to 2.

¶ 2.1.5. $in

The $in operator selects the documents where the value of a field equals any value in the specified array. To specify an $in expression, use the following prototype:

{ field: { $in: [<value1>, <value2>, ... <valueN> ] } }

If the field holds an array, then the $in operator selects the documents whose field holds an array that contains at least one element that matches a value in the specified array (e.g. <value1>, <value2>, etc.)

§ 2.1.5.1. Use the $in Operator to Match Values

Consider the following example:

tim.X("inventory").Get( { qty: { $in: [ 5, 15 ] } } )

This query selects all documents in the inventory collection where the qty field value is either 5 or 15. Although you can express this query using the $or operator, choose the $in operator rather than the $or operator when performing equality checks on the same field.

§ 2.1.5.2. Use the $in Operator to Match Values in an Array

The collection inventory contains documents that include the field tags, as in the following:

{ _id: 1, item: "abc", qty: 10, tags: [ "school", "clothing" ], sale: false }

Then, the following tim.X("inventory").Set operation will set the sale field value to true where the tags field holds an array with at least one element matching either "appliances" or "school".

tim.X("inventory").Set(
{ tags: { $in: ["appliances", "school"] } },
{ $set: { sale:true } }
);

§ 2.1.5.3. Use the $in Operator with a Regular Expression

The $in operator can specify matching values using regular expressions of the form /pattern/. You cannot use $regex operator expressions inside an $in.

Consider the following example:

tim.X("inventory").Get( { tags: { $in: [ /^be/, /^st/ ] } } )

This query selects all documents in the inventory collection where the tags field holds an array that contains at least one element that starts with either be or st.

¶ 2.1.6. $lt

Syntax: {field: {$lt: value} } $lt selects the documents where the value of the field is less than (i.e.

For most data types, comparison operators only perform comparisons on fields where the JSON type matches the query value’s type.

Consider the following example:

tim.X("inventory").Get( { qty: { $lt: 20 } } )

This query will select all documents in the inventory collection where the qty field value is less than 20.

Consider the following example which uses the $lt operator with a field from an embedded document:

tim.X("inventory").Set( { "carrier.fee": { $lt: 20 } }, { $set: { price: 9.99 } } )

This Set() operation will set the price field value in the documents that contain the embedded document carrier whose fee field value is less than 20.

¶ 2.1.7. $lte

Syntax: { field: { $lte: value} }

$lte selects the documents where the value of the field is less than or equal to (i.e.

For most data types, comparison operators only perform comparisons on fields where the JSON type matches the query value’s type. Consider the following example:

tim.X("inventory").Get( { qty: { $lte: 20 } } )

This query will select all documents in the inventory collection where the qty field value is less than or equal to 20.

Consider the following example which uses the $lt operator with a field from an embedded document: tim.X("inventory").Set( { "carrier.fee": { $lte: 5 } }, { $set: { price: 9.99 } } ) This Set() operation will set the price field value in the documents that contain the embedded document carrier whose fee field value is less than or equal to 5.

¶ 2.1.8. $ne

Syntax: {field: {$ne: value} }

$ne selects the documents where the value of the field is not equal to the specified value. This includes documents that do not contain the field.

For comparison of different JSON type values, see the specified JSON comparison order.

Consider the following example:

tim.X("inventory").Get( { qty: { $ne: 20 } } )

This query will select all documents in the inventory collection where the qty field value does not equal 20, including those documents that do not contain the qty field.

Consider the following example which uses the $ne operator with a field in an embedded document:

tim.X("inventory").Set( { "carrier.state": { $ne: "NY" } }, { $set: { qty: 20 } } ) This Set() operation will set the qty field value in the documents that contain the embedded document carrier whose state field value does not equal “NY”, or where the state field or the carrier embedded document do not exist.

The inequality operator $ne is not very selective since it often matches a large portion of the index. As a result, in many cases, a $ne query with an index may perform no better than a $ne query that must scan all documents in a collection.

¶ 2.1.9. $nin

Syntax: { field: { $nin: [,...]} }

$nin selects the documents where:

the field value is not in the specified array or the field does not exist. For comparison of different JSON type values, see the specified JSON comparison order.

Consider the following query:

tim.X("inventory").Get( { qty: { $nin: [ 5, 15 ] } } )

This query will select all documents in the inventory collection where the qty field value does not equal 5 nor 15. The selected documents will include those documents that do not contain the qty field.

If the field holds an array, then the $nin operator selects the documents whose field holds an array with no element equal to a value in the specified array (e.g.,, etc.).

Consider the following query:

tim.X("inventory").Set( { tags: { $nin: [ "appliances", "school" ] } }, { $set: { sale: false } } )

This Set() operation will set the sale field value in the inventory collection where the tags field holds an array with no elements matching an element in the array ["appliances", "school"] or where a document does not contain the tags field.

The inequality operator $nin is not very selective since it often matches a large portion of the index. As a result, in many cases, a $nin query with an index may perform no better than a $nin query that must scan all documents in a collection.