Query API
Field equality, comparison operators (at field level) and logical operators (at top level).
The Query API is very similar to MongoDB, You can select documents based on field equality or use comparison operators ($lt, $lte, $gt, $gte, $in, $nin, $ne, $eq). You can also use logical operators $or, $and, $not and $where.
Field equality
To specify equality conditions, use { <FieldName> : <Value> } expressions in the query filter document. This is the most basic and straight forward query.
An example of this query would go like this:
// select all documents where the name is "ozzy"
db.find({ filter: {name: "ozzy"} });
// select all documents where
// the age is exactly 27
// and height is exactly 180
db.find({
filter: {
age: 27,
height: 180
}
});Field level operators
Syntax: { <fieldName>: { <operator>:<specification> } }
Comparison operators
Equal $eq
$eqApplies to: any field type.
Syntax: { <fieldName> : { $eq: <value> } }.
Explanation: Specifies equality condition. The $eq operator matches documents where the value of a field equals the specified value. It is equivalent to { <FieldName> : <Value> }.
db.find({ filter: { name: { $eq: "ozzy" } } });
// same as:
db.find({ filter: { name: "ozzy" } });Not equal $ne
$neApplies to: any field type.
Syntax: { <fieldName> : { $ne: <value> } }.
Explanation: $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.
// selecting all documents where "name"
// does not equal "ozzy"
db.find({ filter: { name: { $ne: "ozzy" } } });Greater than $gt
$gtApplies to: number & Date fields.
Syntax: { <fieldName> : { $gt: <value> } }.
Explanation: $gt selects those documents where the value of the field is greater than (i.e. >) the specified value.
// applied on a number field
db.find({ filter: { year: { $gt: 9 } } });
// applied on a date field
db.find({
filter:{
createdAt: { $gt: new Date(1588134729462) }
}
});Less than $lt
$ltApplies to: number & Date fields.
Syntax: { <fieldName> : { $lt: <value> } }.
Explanation: $lt selects those documents where the value of the field is less than (i.e. <) the specified value.
// applied on a number field
db.find({ filter: { year: { $lt: 9 } } });
// applied on a date field
db.find({
filter:{
createdAt: { $lt: new Date(1588134729462) }
}
});Greater than or equal $gte
$gteApplies to: number & Date fields.
Syntax: { <fieldName> : { $gte: <value> } }.
Explanation: $gte selects those documents where the value of the field is greater than or equal to (i.e. >=) the specified value.
// applied on a number field
db.find({ filter: { year: { $gte: 9 } } });
// applied on a date field
db.find({
filter:{
createdAt: { $gte: new Date(1588134729462) }
}
});Less than or equal $lte
$lteApplies to: number & Date fields.
Syntax: { <fieldName> : { $lte: <value> } }.
Explanation: $lte selects those documents where the value of the field is less than or equal to (i.e. <=) the specified value.
// applied on a number field
db.find({ filter: { year: { $lte: 9 } } });
// applied on a date field
db.find({
filter:{
createdAt: { $lte: new Date(1588134729462) }
}
});In $in
$inApplies to: any field type.
Syntax: { <fieldName> : { $in: [<value1>, <value2>, ... etc] } }.
Explanation: The $in operator selects the documents where the value of a field equals any value in the specified array.
// find documents where the "name"
// field is one of the specified
// in the array
db.find({ filter: { name: { $in: ["alex", "john", "dina"] } } });Not in $nin
$ninApplies to: any field type.
Syntax: { <fieldName> : { $nin: [<value1>, <value2>, ... etc] } }.
Explanation: $nin selects the documents where: the field value is not in the specified array or the field does not exist.
// find documents where the "name"
// field value is not one of the
// specified values in the array
db.find({ filter: { name: { $in: ["alex", "john", "dina"] } } });Element operators
Exists $exists
$existsApplies to: any field type.
Syntax: { <fieldName> : { $exists: <boolean> } }.
Explanation: When <boolean> is true, $exists matches the documents that contain the field, including documents where the field value is null. If <boolean> is false, the query returns only the documents that do not contain the field.
// select documents where the "name"
// field is defined, even if it is null
db.find({ filter: { name: { $exists: true } } });
// select documents where the "name"
// field is not defined
db.find({ filter: { name: { $exists: false} } });Type $type
$typeApplies to: any field type.
Syntax: { <fieldName> : { $type: <specification> } }.
Explanation: $type selects documents where the value of the field is an instance of the specified type. Type specification can be one of the following:
"string""number""boolean""undefined""array""null""date""object"
Although rare, but this is useful for when a field can have different type.
// find documents where the "name" field
// is a string.
db.find({ filter: { name: { $type: "string" } } });Evaluation operators
Modulo $mod
$modApplies to: number & Date fields.
Syntax: { <fieldName> : { $mod: [divisor, remainder] } }.
Explanation: Select documents where the value of a field divided by a divisor has the specified remainder (i.e. perform a modulo operation to select documents).
// select documents where the "years" field
// is an even number
db.find({ filter: {
years: {
$mod: [2,0]
}
}});
// select documents where the "years" field
// is an odd number
db.find({ filter: {
years: {
$mod: [2,1]
}
}});Regular expression testing $regex
$regexApplies to: string fields only.
Syntax: { <fieldName> : { $regex: <RegExp> } }.
Explanation: Selects documents which tests true for a given regular expression.
// select documents where the "name"
// field starts with either "a" or "A".
db.find({ filter: { name: { $regex: /^a/i } } });Array operators
All contained $all
$allApplies to: array fields only.
Syntax: { <fieldName> : { $all: [<value1>, <value2>,...etc] } }.
Explanation: The $all operator selects the documents where the value of a field is an array that contains all the specified elements.
// select documents where the "tags"
// field is an array that has "music" & "art"
db.find({ filter: { tags: { $all: [ "music", "art" ] } } });Element match $elemMatch
$elemMatchApplies to: array fields only.
Syntax: {<fieldName>:{$elemMatch:{<query1>,<query2>,...etc}}}.
Explanation: The $elemMatch operator matches documents that contain an array field with at least one element that matches all the specified query criteria.
// select documents where the "nums"
// field has an even number
// less than 8
// and greater than 0
db.find({
filter: {
nums: {
$elemMatch: {
$mod: [2, 0],
$lt: 8,
$gt: 0,
}
}
}
});Size $size
$sizeApplies to: array fields only.
Syntax: { <fieldName> : { $size: number } }.
Explanation: The $size operator matches any array with the number of elements (length of the array) specified by the argument.
// select documents where the "tags"
// field is an array that has 10 elements.
db.find({ filter: { tags: { $size: 10 } } });Field level operators on the array element
The array fields has the operators $all, $elemMatch and $size specific for them, nonetheless all the other aforementioned operators can be applied on the array, and would return true if any element in the array matches them.
$eq: matches an array that has an element equal to the value specified by the operator.$ne: matches an array that has an element other than the value specified by the operator.$gt: matches an array of numbers that has a number greater than the value specified by the operator.$lt: matches an array of numbers that has a number less than the value specified by the operator.$gte: matches an array of numbers that has a number greater than or equals to the value specified by the operator.$lte: matches an array of numbers that has a number less than or equal to the value specified by the operator.$in: matches an array that has any of the values specified by the operator.$nin: matches an array that has none of the values specified by the operator.$exists: will match any given array.$type: will match the array if the specification for the operator is "array".$mod: matches an array if it has a number that when divided by the divider would given the remainder specified by the operator.$regex: matches an array of strings that has a string that would return true when tested by the regex given by this operator.
Negation
All the above operators can be negated using the $not operator.
// find all documents
// where they have "tags" that is not of length 10
db.find({ filter: { tags: { $not: { $size: 10 } } } });
// similar to $ne
db.find({ filter: { name: { $not: { $eq: "ozzy" } } } });
// find documents where the "name" field
// is a not a string
db.find({ filter: { name: { $not: { $type: "string" } } } });
// select documents where the "tags"
// field is an array that doesn't have "music" & "art"
db.find({ filter: { tags: { $not: { $all: [ "music", "art" ] } } } });
// select documents where the "years" field
// is an even number
db.find({ filter: {
years: {
$not: {
$mod: [2,1]
}
}
}});
// ...etc Top level operators
$and
$andSyntax:
{
$and: [
<query1>,
<query2>,
<query3>,
...etc
]
}Explanation: $and performs a logical AND operation on an array of two or more expressions (e.g. <field level query 1>, <field level query 2> , etc.) and selects the documents that satisfy all the expressions in the array. The $and operator uses short-circuit evaluation. If the first expression (e.g. <field level query 1>) evaluates to false, TyDB will not evaluate the remaining expressions.
/**
* Select a document where the name
* isn't equal to "alex" and the property exists
*/
db.find({ filter: {
$and: [
{ $name: { $ne:"alex" } },
{ $name: { $exists: true } }
]
}})$nor
$norSyntax:
{
$nor: [
<query1>,
<query2>,
<query3>,
...etc
]
}Explanation: $nor performs a logical NOR operation on an array of one or more query expression and selects the documents that fail all the query expressions in the array.
/**
* Select a document where the "name" is not "alex"
* and the age is not 13
*/
db.find({ filter: {
$nor: [
{ $name: "alex" },
{ $age: 13 }
]
}})$or
$orSyntax:
{
$or: [
<query1>,
<query2>,
<query3>,
...etc
]
}Explanation: The $or operator performs a logical OR operation on an array of two or more expressions and selects the documents that satisfy at least one of the expressions.
/**
* Select a document where the "name" is not "alex"
* or the age is not 13
*/
db.find({ filter: {
$or: [
{ $name: "alex" },
{ $age: 13 }
]
}})$where
$whereSyntax:
{
$where: (this: Model) => boolean
}Explanation: Matches the documents that when evaluated by the given function, would return true. **The $where provides greater flexibility, but requires that the database processes the JavaScript expression or function for each document in the collection. Reference the document in the JavaScript expression or function using this.
/**
* Select a document where the "name"
* is 5 charecters long and ends with "x"
*/
db.find({ filter: {
$where: function () {
// DO NOT use arrow function here
return this.name.length === 5 && this.name.endsWith("x");
}
}})$deep
$deepSyntax:
{
$deep: {
"an.embedded.document.field": <query>
}
}Explanation: This is the only operator that TyDB offers while MongoDB doesn't. Use this operator when trying to apply a query on a deeply nested properties (i.e. embedded documents), like: "employee.address.street".
/**
* Select a document where it has a "name" object,
* which have "first" and "last" properties.
* "first" property must be either "alex" or "john".
* "last" property must be either "corvi" or "cena"
*/
db.find({ filter: {
$deep: {
"name.first": {
$in: ["alex", "john"]
},
"name.last": {
$in: ["corvi", "cena"]
}
}
}})Last updated
Was this helpful?