Queries_

Many list endpoints in Appwrite allow you to filter, sort, and paginate results using queries. Appwrite provides a common set of syntax to build queries.

Query class

Appwrite SDKs provide a Query class to help you build queries. The Query class has methods for each type of supported query operation.

Building queries

Queries are passed to an endpoint through the queries parameter as an array of query strings, which can be generated using the Query class.

Each query method is logically separated via AND operations. For OR operation, pass multiple values into the query method separated by commas. For example Query.equal('title', ['Avatar', 'Lord of the Rings']) will fetch the movies Avatar or Lord of the Rings.

Query operators

Select

The select operator allows you to specify which fields should be returned from a document. This optimizes response size and retrieves only the data you need.

Use selection patterns

Optimize performance

Optimize response size - Only select the fields you actually need. Smaller responses are faster to transfer and parse.

Reduce database load - Selecting fewer fields reduces database processing time, especially for large documents.

Comparison operators

Equal

Returns document if field is equal to any value in the provided array.

Not equal

Returns document if field is not equal to any value in the provided array.

Less than

Returns document if field is less than the provided value.

Less than or equal

Returns document if field is less than or equal to the provided value.

Greater than

Returns document if field is greater than the provided value.

Greater than or equal

Returns document if field is greater than or equal to the provided value.

Between

Returns document if field value falls between the two values. The boundary values are inclusive and can be strings or numbers.

Not between

Returns documents if the field value is outside the range defined by the two values (strictly less than start OR strictly greater than end). Works with strings or numbers. Boundary values are excluded.

Null checks

Is null

Returns documents where field value is null.

Is not null

Returns documents where field value is not null.

String operations

Starts with

Returns documents if a string field starts with a substring.

Not starts with

Returns documents if a string field does not start with a substring.

Ends with

Returns documents if a string field ends with a substring.

Not ends with

Returns documents if a string field does not end with a substring.

Contains

Returns documents if the array field contains the specified elements or if a string field contains the specified substring.

Not contains

Returns documents if the array field does not contain the specified elements, or if a string field does not contain the specified substring.

Search

Searches string fields for provided keywords. Requires a full-text index on queried fields.

Not search

Returns documents if a string field does not match the full-text search query. Requires a full-text index on queried fields.

Logical operators

AND

Returns document if it matches all of the nested sub-queries in the array passed in.

OR

Returns document if it matches any of the nested sub-queries in the array passed in.

Ordering

Order descending

Orders results in descending order by field.

Order ascending

Orders results in ascending order by field.

Pagination

Limit

Limits the number of results returned by the query. Used for pagination.

Offset

Offset the results returned by skipping some of the results. Used for pagination.

Cursor after

Places the cursor after the specified resource ID. Used for pagination.

Cursor before

Places the cursor before the specified resource ID. Used for pagination.

Time helpers

Built-in helpers for filtering by creation and update timestamps using ISO 8601 date-time strings (for example, "2025-01-01T00:00:00Z").

Created before

Returns documents created before the given date.

Created after

Returns documents created after the given date.

Updated before

Returns documents updated before the given date.

Updated after

Returns documents updated after the given date.

Complex queries

You can create complex queries by combining AND and OR operations. For example, to find items that are either books under $20 or magazines under $10:

This example demonstrates how to combine OR and AND operations. The query uses Query.or() to match either condition: books under $20 OR magazines under $10. Each condition within the OR is composed of two AND conditions - one for the category and one for the price threshold. The database will return documents that match either of these combined conditions.