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.
Default pagination behavior
By default, results are limited to the first 25 items. You can change this through pagination.
Query operators
Select
The select operator allows you to specify which columns should be returned from a row. This is essential for optimizing response size, controlling which relationship data loads, and only retrieving the data you need.
Select relationship data
With opt-in relationship loading, you must explicitly select relationship data. This gives you fine-grained control over performance and payload size.
Get rows without relationships
By default, rows return only their own fields:
Load all relationship data
Use the * wildcard to load all fields from related rows:
Select specific relationship fields
For precise control, select only specific fields from related rows:
Load nested relationships
You can also load relationships of relationships:
Use selection patterns
| Pattern | Description | Use case |
["field1", "field2"] | Specific columns only | Minimize response size |
["*"] | All row columns | Get complete row data |
["*", "relationName.*"] | Row + all relationship fields | Load row with complete related data |
["field1", "relationName.field2"] | Specific fields from row and relationships | Precise data loading |
["*", "relationName.field1", "relationName.field2"] | All row fields + specific relationship fields | Partial relationship loading |
["relationName.*", "relationName.nestedRelation.*"] | Nested relationship loading | Load relationships of relationships |
Optimize performance
Optimize response size - Only select the fields you actually need. Smaller responses are faster to transfer and parse.
Control relationship loading - Related rows are not loaded by default. Use explicit selection to load only the relationships you need.
Reduce database load - Selecting fewer fields reduces database processing time, especially for large rows.
Related rows
By default, relationship columns contain only row IDs. To load the actual related row data, you must explicitly include relationship fields in your select query. Learn more about relationship performance optimization.
Comparison operators
Equal
Returns row if column is equal to any value in the provided array. Also supported for spatial types.
Not equal
Returns row if column is not equal to any value in the provided array. Also supported for spatial types.
Less than
Returns row if column is less than the provided value.
Less than or equal
Returns row if column is less than or equal to the provided value.
Greater than
Returns row if column is greater than the provided value.
Greater than or equal
Returns row if column is greater than or equal to the provided value.
Between
Returns row if column value falls between the two values. The boundary values are inclusive and can be strings or numbers.
Not between
Returns rows if the column 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 rows where column value is null.
Is not null
Returns rows where column value is not null.
String operations
Starts with
Returns rows if a string column starts with a substring.
Not starts with
Returns rows if a string column does not start with a substring.
Ends with
Returns rows if a string column ends with a substring.
Not ends with
Returns rows if a string column does not end with a substring.
Contains
Returns rows if the array column contains the specified elements or if a string column contains the specified substring. Also supported for spatial types.
Not contains
Returns rows if the array column does not contain the specified elements, or if a string column does not contain the specified substring. Also supported for spatial types.
Search
Searches string columns for provided keywords. Requires a full-text index on queried columns.
Not search
Returns rows if a string column does not match the full-text search query. Requires a full-text index on queried columns.
Logical operators
AND
Returns row if it matches all of the nested sub-queries in the array passed in.
OR
Returns row if it matches any of the nested sub-queries in the array passed in.
Ordering
Order descending
Orders results in descending order by column. Column must be indexed.
Order ascending
Orders results in ascending order by column. Column must be indexed.
Order random
Orders results in random order.
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 rows created before the given date.
Created after
Returns rows created after the given date.
Updated before
Returns rows updated before the given date.
Updated after
Returns rows updated after the given date.
Geo queries and spatial operations
Geo queries enable geographic operations on spatial columns. Coordinates are specified as [longitude, latitude] arrays. Distance measurements can be specified in meters or degrees.
For conceptual information about spatial data types, spatial columns and indexing, see Geo queries.
Additional supported queries
In addition to the spatial-specific operations below, the query helpers equal, notEqual, contains, and notContains are also supported on spatial columns. This lets you match or exclude exact spatial values, check whether a geometry collection contains a geometry or not.
Distance equal
Returns rows where the spatial column is exactly the specified distance from a point.
Distance not equal
Returns rows where the spatial column is not exactly the specified distance from a point.
Distance greater than
Returns rows where the spatial column is more than the specified distance from a point.
Distance less than
Returns rows where the spatial column is less than the specified distance from a point.
Intersects
Returns rows where the spatial column intersects with the provided geometry.
Not intersects
Returns rows where the spatial column does not intersect with the provided geometry.
Overlaps
Returns rows where the spatial column overlaps with the provided geometry.
Not overlaps
Returns rows where the spatial column does not overlap with the provided geometry.
Touches
Returns rows where the spatial column touches the provided geometry.
Not touches
Returns rows where the spatial column does not touch the provided geometry.
Crosses
Returns rows where the spatial column crosses the provided geometry.
Not crosses
Returns rows where the spatial column does not cross the provided geometry.
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 rows that match either of these combined conditions.