Website logo
Legacy DocsPortal
Navigate through spaces
⌘K
Welcome to Ditto
Onboarding
Ditto Basics
SDK Setup Guides
Platform Manual
HTTP API
Change Data Capture
Standard Best Practices
FAQs
Troubleshooting
Support
Docs powered by Archbee
Platform Manual

Query Syntax

21min

At a high-level, queries operate on collections rather than individual documents. Filter, search, and retrieve specific information based on various criteria using Boolean operators, equal and unequal operators, comparison operators, and match operators. 

This article includes an overview of operators and path navigations for building advanced queries in your app, along with real-world examples.

For related information, see the Platform Manual:

  • Data Types
  • Best Practices for CRUD
  • Establishing Relationships

Boolean Operators

When a field property is a boolean data type, use explicit true-false values.

Enclose groups of logical operations with parentheses to ensure Ditto interprets your desired logic correctly.

For example, to find documents with an "isDeleted" boolean property set to "true":

Query
"isDeleted == true"


To find documents with an "isDeleted" boolean property set to "false":

Query
"isDeleted == false"


Equal (==) and Inequality (!=) Operators

To find documents that match a given key-value pair, use the equal operator. Where you specify the key and the number or string value you want to match separated by ==.

For example, to find documents that have a title equal to "Harry Potter":

Query
"title == 'Harry Potter'"


If, instead of finding documents that match, you want to find documents that do not match a given key-value pair, use the inequality operator. Where you specify the key and the value that you don’t want to match separated by !=.

For example, to find documents that are not of the title "Lord of the Rings":

Query
"title != 'Lord of the Rings'"


Comparison Operators: (>=)(>)(<=)(<)

Compare values in documents, set conditions, retrieve specific documents that meet your criteria, and make logical evaluations using the following operators in your query statements.

Ditto supports parsing ISO-8601 date strings, so you can use ISO-8601 formatted date strings in queries for comparison operations. For more information, see Using ISO-8601 for Date Strings.

For example:

To find documents where age field property is less than or equal to the value of 18:

Query
"age <= 18"


To find documents where the age field property is less than the value of 18:

Query
"age < 18"


To find documents where the age field property is greater than or equal to the value of 18:

Query
"age >= 18"


To find documents where the age field property is greater than the value of 18:

Query
"age > 18"


Compound Operators

Perform complex operations in a single executable by using compound operators. A compound operator is a combination of two or more operators in a single executable:

SQL

Ditto

AND

&&

OR

||

NOT

!

contains( )

contains( )

Logical AND Predicate Statements: (&&)

Similar to SQL AND statements, use && for a condition that evaluates to true only when all of its conditions are set to true.

For example, to find documents that have a theme field property equal to "Dark" and a name field property equal to "Light":

Query
"theme == 'Dark' && name == 'Light'


Logical OR Statements: (||)

Similar to SQL OR statements, use || for a logical or predicate statement.

For example, to find documents that are "Tom" or "Arthur":

Query
"name == 'Tom' || name == 'Arthur'"


Logical NOT Statements: (!)

Similar to SQL NOT statements, use ! for logical not predicate statements:

For example, find documents that are neither "Hamilton" nor "Morten":

Query
"name != 'Tom'"


String Operations

Use starts_with(property, test) to test if a field property with a string value starts with a test string.

For example, to find documents with a title field property that begins with "Lord":

Query
"starts_with(title, 'Lord')"


Use ends_with(property, test) to test if a field property with a string value ends with a test string.

For example, to find documents with a title field property that ends with "Rings":

Query
"ends_with(title, 'Rings')"


Use regex(property, test) to see if a field property with a string value passes a regular expression. For more information, see the official Mozilla Developer Network Docs (MDN) > Regular Expressions.

For example, to find documents containing only upper and lowercase letters, numbers, and underscores:

Query
"regex(title, '^([A-Za-z]|[0-9]|_)+$')"

// A title property of "abc129_24A" will pass
// A title property of "abc129_24A  3" will not pass


NULL Values

Use null to check for the existence of a value of a given field.

For example, to find documents with a color field property that has no value:

Query
"color == null"


Array Operators

When handling collections of data that different peers may make concurrent updates to, first consider using an embedded map structure. If necessary, use an array.

The array type in Ditto is a CRDT and behaves differently than the primitive array type. For more information, see the Platform Manual > Data Types.



Operator

Operation

contains(array, value)

Checks for value in the array

Query
"contains(['blue', 'green'], color]"


Date and Time Formats

When parsing date and time strings, use the ISO-8601 standard format, as follows.

For more information, see Platform Manual > Using ISO-8601 for Date Strings.

Query
"created_at >= '2022-04-29T00:55:31.859Z'"


Field Path Navigation

If fields consist of alphanumeric characters or include underscores, use any of the following notations to navigate document properties.

  • For fields that are alphanumeric or include underscores, use dot notation:
Query
"name.last == 'Turing'"

  • For all other scenarios, use bracket notation:
Query
"work['street-line'] == '678 Johnson Street'"




Updated 25 Oct 2023
Did this page help you?
PREVIOUS
Platform Manual
NEXT
Data Types
Docs powered by Archbee
TABLE OF CONTENTS
Boolean Operators
Equal (==) and Inequality (!=) Operators
Comparison Operators: (>=)(>)(<=)(<)
Compound Operators
Logical AND Predicate Statements: (&&)
Logical OR Statements: (||)
Logical NOT Statements: (!)
String Operations
NULL Values
Array Operators
Date and Time Formats
Field Path Navigation
Docs powered by Archbee