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

Specification

Applies 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> }.

Example

db.find({ filter: { name: { $eq: "ozzy" } } });
// same as:
db.find({ filter: { name: "ozzy" } });

Not equal $ne

Specification

Applies 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.

Example

// selecting all documents where "name"
// does not equal "ozzy"
db.find({ filter: { name: { $ne: "ozzy" } } });

Greater than $gt

Specification

Applies 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.

Example

// 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

Specification

Applies 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.

Example

// 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

Specification

Applies 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.

Example

// 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

Specification

Applies 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.

Example

// 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

Specification

Applies 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.

Example

// 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

Specification

Applies 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.

Example

// 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

Specification

Applies 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.

Example

// 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

Specification

Applies 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.

Example

// find documents where the "name" field
// is a string.
db.find({ filter: { name: { $type: "string" } } });

Evaluation operators

Modulo $mod

Specification

Applies 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).

Example

// 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

Specification

Applies to: string fields only.

Syntax: { <fieldName> : { $regex: <RegExp> } }.

Explanation: Selects documents which tests true for a given regular expression.

Example

// select documents where the "name"
// field starts with either "a" or "A".
db.find({ filter: { name: { $regex: /^a/i } } });

Array operators

All contained $all

Specification

Applies 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.

Example

// select documents where the "tags"
// field is an array that has "music" & "art"
db.find({ filter: { tags: { $all: [ "music", "art" ] } } });

Element match $elemMatch

Specification

Applies 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.

Example

// 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

Specification

Applies 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.

Example

// 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

Specification

Syntax:

{
    $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.

Example

/**
* 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

Specification

Syntax:

{
    $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.

Example

/**
* Select a document where the "name" is not "alex"
* and the age is not 13
*/

db.find({ filter: {
    $nor: [
        { $name: "alex" },
        { $age: 13 }
    ]
}})

$or

Specification

Syntax:

{
    $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.

Example

/**
* Select a document where the "name" is not "alex"
* or the age is not 13
*/

db.find({ filter: {
    $or: [
        { $name: "alex" },
        { $age: 13 }
    ]
}})

$where

Specification

Syntax:

{
    $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.

Example

/**
* 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

Specification

Syntax:

{
    $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".

This operator is not strongly typed, as the typescript compiler is unable to decide what would be the type of a dot noted deeply nested field. In fact, this limitation is the reason for placing dot notation access to field in a separate operator, since placing them at the top level would disable all type checks performed by typescript.

Due to this limitation, although it is perfectly supported, It is strongly advised to avoid embedded documents when possible.

Example

/**
* 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"]
        }
    }
}})