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 a method for each type of supported query.
Example | Description |
Query.select(["name", "title"]) | Select which attributes should be returned from a document. |
Query.and([Query.lessThan("size", 10), Query.greaterThan("size", 5)]) | Returns document if it matches all of the nested sub-queries in the array passed in. |
Query.or([Query.lessThan("size", 5), Query.greaterThan("size", 10)]) | Returns document if it matches any of the nested sub-queries in the array passed in. |
Query.equal("title", ["Iron Man"]) | Returns document if attribute is equal to any value in the provided array. |
Query.notEqual("title", ["Iron Man"]) | Returns document if attribute is not equal to any value in the provided array. |
Query.lessThan("score", 10) | Returns document if attribute is less than the provided value. |
Query.lessThanEqual("score", 10) | Returns document if attribute is less than or equal to the provided value. |
Query.greaterThan("score", 10) | Returns document if attribute is greater than the provided value. |
Query.greaterThanEqual("score", 10) | Returns document if attribute is greater than or equal to the provided value. |
Query.between("price", 5, 10) | Returns document if attribute value falls between the two values. The boundary values are inclusive and can be strings or numbers. |
Query.isNull("name") | Returns documents where attribute value is null. |
Query.isNotNull("name") | Returns documents where attribute value is not null. |
Query.startsWith("name", "Once upon a time") | Returns documents if a string attributes starts with a substring. |
Query.endsWith("name", "happily ever after.") | Returns documents if a string attributes ends with a substring. |
Query.contains("ingredients", ['apple', 'banana']) | Returns documents if a the array attribute contains the specified elements. |
Query.contains("name", "Tom") | Returns documents if a string attributes is like the pattern specified. |
Query.search("text", "key words") | Searches string attributes for provided keywords. Requires a full-text index on queried attributes. |
Query.orderDesc("attribute") | Orders results in descending order by attribute. Attribute must be indexed. Pass in an empty string to return in natural order. |
Query.orderAsc("attribute") | Orders results in ascending order by attribute. Attribute must be indexed. Pass in an empty string to return in natural order. |
Query.limit(25) | Limits the number of results returned by the query. Used for pagination. If the limit query is not used, the limit defaults to 25 results. |
Query.offset(0) | Offset the results returned by skipping some of the results. Used for pagination. |
Query.cursorAfter("62a7...f620") | Places the cursor after the specified resource ID. Used for pagination. |
Query.cursorBefore("62a7...a600") | Places the cursor before the specified resource ID. Used for pagination. |
Example | Description |
Query::select(["name", "title"]) | Select which attributes should be returned from a document. |
Query::or([Query::lessThan("size", 5), Query::greaterThan("size", 10)]) | Returns document if it matches any of the nested sub-queries in the array passed in. |
Query::and([Query::lessThan("size", 10), Query::greaterThan("size", 5)]) | Returns document if it matches all of the nested sub-queries in the array passed in. |
Query::equal("title", ["Iron Man"]) | Returns document if attribute is equal to any value in the provided array. |
Query::notEqual("title", ["Iron Man"]) | Returns document if attribute is not equal to any value in the provided array. |
Query::lessThan("score", 10) | Returns document if attribute is less than the provided value. |
Query::lessThanEqual("score", 10) | Returns document if attribute is less than or equal to the provided value. |
Query::greaterThan("score", 10) | Returns document if attribute is greater than the provided value. |
Query::greaterThanEqual("score", 10) | Returns document if attribute is greater than or equal to the provided value. |
Query::between("price", 5, 10) | Returns document if attribute value falls between the two values. The boundary values are inclusive and can be strings or numbers. |
Query::isNull("name") | Returns documents where attribute value is null. |
Query::isNotNull("name") | Returns documents where attribute value is not null. |
Query::startsWith("name", "Once upon a time") | Returns documents if a string attributes starts with a substring. |
Query::endsWith("name", "happily ever after.") | Returns documents if a string attributes ends with a substring. |
Query::contains("ingredients", ['apple', 'banana']) | Returns documents if a the array attribute contains the specified elements. |
Query::contains("name", "Tom") | Returns documents if a string attributes is like the pattern specified. |
Query::search("text", "key words") | Searches string attributes for provided keywords. Requires a full-text index on queried attributes. |
Query::orderDesc("attribute") | Orders results in descending order by attribute. Attribute must be indexed. Pass in an empty string to return in natural order. |
Query::orderAsc("attribute") | Orders results in ascending order by attribute. Attribute must be indexed. Pass in an empty string to return in natural order. |
Query::limit(25) | Limits the number of results returned by the query. Used for pagination. If the limit query is not used, the limit defaults to 25 results. |
Query::offset(0) | Offset the results returned by skipping some of the results. Used for pagination. |
Query::cursorAfter("62a7...f620") | Places the cursor after the specified resource ID. Used for pagination. |
Query::cursorBefore("62a7...a600") | Places the cursor before the specified resource ID. Used for pagination. |
Example | Description |
Query.select(["name", "title"]) | Select which attributes should be returned from a document. |
Query.or([Query.less_than("size", 5), Query.greater_than("size", 10)]) | Returns document if it matches any of the nested sub-queries in the array passed in. |
Query.and([Query.less_than("size", 10), Query.greater_than("size", 5)]) | Returns document if it matches all of the nested sub-queries in the array passed in. |
Query.equal("title", ["Iron Man"]) | Returns document if attribute is equal to any value in the provided array. |
Query.not_equal("title", ["Iron Man"]) | Returns document if attribute is not equal to any value in the provided array. |
Query.less_than("score", 10) | Returns document if attribute is less than the provided value. |
Query.less_than_equal("score", 10) | Returns document if attribute is less than or equal to the provided value. |
Query.greater_than("score", 10) | Returns document if attribute is greater than the provided value. |
Query.greater_than_equal("score", 10) | Returns document if attribute is greater than or equal to the provided value. |
Query.between("price", 5, 10) | Returns document if attribute value falls between the two values. The boundary values are inclusive and can be strings or numbers. |
Query.is_null("name") | Returns documents where attribute value is null. |
Query.is_not_null("name") | Returns documents where attribute value is not null. |
Query.starts_with("name", "Once upon a time") | Returns documents if a string attributes starts with a substring. |
Query.ends_with("name", "happily ever after.") | Returns documents if a string attributes ends with a substring. |
Query.contains("ingredients", ['apple', 'banana']) | Returns documents if a the array attribute contains the specified elements. |
Query.contains("name", "Tom") | Returns documents if a string attributes is like the pattern specified. |
Query.search("text", "key words") | Searches string attributes for provided keywords. Requires a full-text index on queried attributes. |
Query.order_desc("attribute") | Orders results in descending order by attribute. Attribute must be indexed. Pass in an empty string to return in natural order. |
Query.order_asc("attribute") | Orders results in ascending order by attribute. Attribute must be indexed. Pass in an empty string to return in natural order. |
Query.limit(25) | Limits the number of results returned by the query. Used for pagination. If the limit query is not used, the limit defaults to 25 results. |
Query.offset(0) | Offset the results returned by skipping some of the results. Used for pagination. |
Query.cursor_after("62a7...f620") | Places the cursor after the specified resource ID. Used for pagination. |
Query.cursor_before("62a7...a600") | Places the cursor before the specified resource ID. Used for pagination. |
Example | Description |
Query.select(["name", "title"]) | Select which attributes should be returned from a document. |
Query.or([Query.less_than("size", 5), Query.greater_than("size", 10)]) | Returns document if it matches any of the nested sub-queries in the array passed in. |
Query.and([Query.less_than("size", 10), Query.greater_than("size", 5)]) | Returns document if it matches all of the nested sub-queries in the array passed in. |
Query.equal("title", ["Iron Man"]) | Returns document if attribute is equal to any value in the provided array. |
Query.not_equal("title", ["Iron Man"]) | Returns document if attribute is not equal to any value in the provided array. |
Query.less_than("score", 10) | Returns document if attribute is less than the provided value. |
Query.less_than_equal("score", 10) | Returns document if attribute is less than or equal to the provided value. |
Query.greater_than("score", 10) | Returns document if attribute is greater than the provided value. |
Query.greater_than_equal("score", 10) | Returns document if attribute is greater than or equal to the provided value. |
Query.between("price", 5, 10) | Returns document if attribute value falls between the two values. The boundary values are inclusive and can be strings or numbers. |
Query.is_null("name") | Returns documents where attribute value is null. |
Query.is_not_null("name") | Returns documents where attribute value is not null. |
Query.starts_with("name", "Once upon a time") | Returns documents if a string attributes starts with a substring. |
Query.ends_with("name", "happily ever after.") | Returns documents if a string attributes ends with a substring. |
Query.contains("ingredients", ['apple', 'banana']) | Returns documents if a the array attribute contains the specified elements. |
Query.contains("name", "Tom") | Returns documents if a string attributes is like the pattern specified. |
Query.search("text", "key words") | Searches string attributes for provided keywords. Requires a full-text index on queried attributes. |
Query.order_desc("attribute") | Orders results in descending order by attribute. Attribute must be indexed. Pass in an empty string to return in natural order. |
Query.order_asc("attribute") | Orders results in ascending order by attribute. Attribute must be indexed. Pass in an empty string to return in natural order. |
Query.limit(25) | Limits the number of results returned by the query. Used for pagination. If the limit query is not used, the limit defaults to 25 results. |
Query.offset(0) | Offset the results returned by skipping some of the results. Used for pagination. |
Query.cursor_after("62a7...f620") | Places the cursor after the specified resource ID. Used for pagination. |
Query.cursor_before("62a7...a600") | Places the cursor before the specified resource ID. Used for pagination. |
Example | Description |
Query.select(["name", "title"]) | Select which attributes should be returned from a document. |
Query.and([Query.lessThan("size", 10), Query.greaterThan("size", 5)]) | Returns document if it matches all of the nested sub-queries in the array passed in. |
Query.or([Query.lessThan("size", 5), Query.greaterThan("size", 10)]) | Returns document if it matches any of the nested sub-queries in the array passed in. |
Query.equal("title", ["Iron Man"]) | Returns document if attribute is equal to any value in the provided array. |
Query.notEqual("title", ["Iron Man"]) | Returns document if attribute is not equal to any value in the provided array. |
Query.lessThan("score", 10) | Returns document if attribute is less than the provided value. |
Query.lessThanEqual("score", 10) | Returns document if attribute is less than or equal to the provided value. |
Query.greaterThan("score", 10) | Returns document if attribute is greater than the provided value. |
Query.greaterThanEqual("score", 10) | Returns document if attribute is greater than or equal to the provided value. |
Query.between("price", 5, 10) | Returns document if attribute value falls between the two values. The boundary values are inclusive and can be strings or numbers. |
Query.isNull("name") | Returns documents where attribute value is null. |
Query.isNotNull("name") | Returns documents where attribute value is not null. |
Query.startsWith("name", "Once upon a time") | Returns documents if a string attributes starts with a substring. |
Query.endsWith("name", "happily ever after.") | Returns documents if a string attributes ends with a substring. |
Query.contains("ingredients", ['apple', 'banana']) | Returns documents if a the array attribute contains the specified elements. |
Query.contains("name", "Tom") | Returns documents if a string attributes is like the pattern specified. |
Query.search("text", "key words") | Searches string attributes for provided keywords. Requires a full-text index on queried attributes. |
Query.orderDesc("attribute") | Orders results in descending order by attribute. Attribute must be indexed. Pass in an empty string to return in natural order. |
Query.orderAsc("attribute") | Orders results in ascending order by attribute. Attribute must be indexed. Pass in an empty string to return in natural order. |
Query.limit(25) | Limits the number of results returned by the query. Used for pagination. If the limit query is not used, the limit defaults to 25 results. |
Query.offset(0) | Offset the results returned by skipping some of the results. Used for pagination. |
Query.cursorAfter("62a7...f620") | Places the cursor after the specified resource ID. Used for pagination. |
Query.cursorBefore("62a7...a600") | Places the cursor before the specified resource ID. Used for pagination. |
Example | Description |
Query.select(["name", "title"]) | Select which attributes should be returned from a document. |
Query.and([Query.lessThan("size", 10), Query.greaterThan("size", 5)]) | Returns document if it matches all of the nested sub-queries in the array passed in. |
Query.or([Query.lessThan("size", 5), Query.greaterThan("size", 10)]) | Returns document if it matches any of the nested sub-queries in the array passed in. |
Query.equal("title", ["Iron Man"]) | Returns document if attribute is equal to any value in the provided array. |
Query.notEqual("title", ["Iron Man"]) | Returns document if attribute is not equal to any value in the provided array. |
Query.lessThan("score", 10) | Returns document if attribute is less than the provided value. |
Query.lessThanEqual("score", 10) | Returns document if attribute is less than or equal to the provided value. |
Query.greaterThan("score", 10) | Returns document if attribute is greater than the provided value. |
Query.greaterThanEqual("score", 10) | Returns document if attribute is greater than or equal to the provided value. |
Query.between("price", 5, 10) | Returns document if attribute value falls between the two values. The boundary values are inclusive and can be strings or numbers. |
Query.isNull("name") | Returns documents where attribute value is null. |
Query.isNotNull("name") | Returns documents where attribute value is not null. |
Query.startsWith("name", "Once upon a time") | Returns documents if a string attributes starts with a substring. |
Query.endsWith("name", "happily ever after.") | Returns documents if a string attributes ends with a substring. |
Query.contains("ingredients", ['apple', 'banana']) | Returns documents if a the array attribute contains the specified elements. |
Query.contains("name", "Tom") | Returns documents if a string attributes is like the pattern specified. |
Query.search("text", "key words") | Searches string attributes for provided keywords. Requires a full-text index on queried attributes. |
Query.orderDesc("attribute") | Orders results in descending order by attribute. Attribute must be indexed. Pass in an empty string to return in natural order. |
Query.orderAsc("attribute") | Orders results in ascending order by attribute. Attribute must be indexed. Pass in an empty string to return in natural order. |
Query.limit(25) | Limits the number of results returned by the query. Used for pagination. If the limit query is not used, the limit defaults to 25 results. |
Query.offset(0) | Offset the results returned by skipping some of the results. Used for pagination. |
Query.cursorAfter("62a7...f620") | Places the cursor after the specified resource ID. Used for pagination. |
Query.cursorBefore("62a7...a600") | Places the cursor before the specified resource ID. Used for pagination. |
Example | Description |
Query.select(["name", "title"]) | Select which attributes should be returned from a document. |
Query.and([Query.lessThan("size", 10), Query.greaterThan("size", 5)]) | Returns document if it matches all of the nested sub-queries in the array passed in. |
Query.or([Query.lessThan("size", 5), Query.greaterThan("size", 10)]) | Returns document if it matches any of the nested sub-queries in the array passed in. |
Query.equal("title", ["Iron Man"]) | Returns document if attribute is equal to any value in the provided array. |
Query.notEqual("title", ["Iron Man"]) | Returns document if attribute is not equal to any value in the provided array. |
Query.lessThan("score", 10) | Returns document if attribute is less than the provided value. |
Query.lessThanEqual("score", 10) | Returns document if attribute is less than or equal to the provided value. |
Query.greaterThan("score", 10) | Returns document if attribute is greater than the provided value. |
Query.greaterThanEqual("score", 10) | Returns document if attribute is greater than or equal to the provided value. |
Query.between("price", 5, 10) | Returns document if attribute value falls between the two values. The boundary values are inclusive and can be strings or numbers. |
Query.isNull("name") | Returns documents where attribute value is null. |
Query.isNotNull("name") | Returns documents where attribute value is not null. |
Query.startsWith("name", "Once upon a time") | Returns documents if a string attributes starts with a substring. |
Query.endsWith("name", "happily ever after.") | Returns documents if a string attributes ends with a substring. |
Query.contains("ingredients", ['apple', 'banana']) | Returns documents if a the array attribute contains the specified elements. |
Query.contains("name", "Tom") | Returns documents if a string attributes is like the pattern specified. |
Query.search("text", "key words") | Searches string attributes for provided keywords. Requires a full-text index on queried attributes. |
Query.orderDesc("attribute") | Orders results in descending order by attribute. Attribute must be indexed. Pass in an empty string to return in natural order. |
Query.orderAsc("attribute") | Orders results in ascending order by attribute. Attribute must be indexed. Pass in an empty string to return in natural order. |
Query.limit(25) | Limits the number of results returned by the query. Used for pagination. If the limit query is not used, the limit defaults to 25 results. |
Query.offset(0) | Offset the results returned by skipping some of the results. Used for pagination. |
Query.cursorAfter("62a7...f620") | Places the cursor after the specified resource ID. Used for pagination. |
Query.cursorBefore("62a7...a600") | Places the cursor before the specified resource ID. Used for pagination. |
Example | Description |
Query.select(["name", "title"]) | Select which attributes should be returned from a document. |
Query.and([Query.lessThan("size", 10), Query.greaterThan("size", 5)]) | Returns document if it matches all of the nested sub-queries in the array passed in. |
Query.or([Query.lessThan("size", 5), Query.greaterThan("size", 10)]) | Returns document if it matches any of the nested sub-queries in the array passed in. |
Query.equal("title", ["Iron Man"]) | Returns document if attribute is equal to any value in the provided array. |
Query.notEqual("title", ["Iron Man"]) | Returns document if attribute is not equal to any value in the provided array. |
Query.lessThan("score", 10) | Returns document if attribute is less than the provided value. |
Query.lessThanEqual("score", 10) | Returns document if attribute is less than or equal to the provided value. |
Query.greaterThan("score", 10) | Returns document if attribute is greater than the provided value. |
Query.greaterThanEqual("score", 10) | Returns document if attribute is greater than or equal to the provided value. |
Query.between("price", 5, 10) | Returns document if attribute value falls between the two values. The boundary values are inclusive and can be strings or numbers. |
Query.isNull("name") | Returns documents where attribute value is null. |
Query.isNotNull("name") | Returns documents where attribute value is not null. |
Query.startsWith("name", "Once upon a time") | Returns documents if a string attributes starts with a substring. |
Query.endsWith("name", "happily ever after.") | Returns documents if a string attributes ends with a substring. |
Query.contains("ingredients", ['apple', 'banana']) | Returns documents if a the array attribute contains the specified elements. |
Query.contains("name", "Tom") | Returns documents if a string attributes is like the pattern specified. |
Query.search("text", "key words") | Searches string attributes for provided keywords. Requires a full-text index on queried attributes. |
Query.orderDesc("attribute") | Orders results in descending order by attribute. Attribute must be indexed. Pass in an empty string to return in natural order. |
Query.orderAsc("attribute") | Orders results in ascending order by attribute. Attribute must be indexed. Pass in an empty string to return in natural order. |
Query.limit(25) | Limits the number of results returned by the query. Used for pagination. If the limit query is not used, the limit defaults to 25 results. |
Query.offset(0) | Offset the results returned by skipping some of the results. Used for pagination. |
Query.cursorAfter("62a7...f620") | Places the cursor after the specified resource ID. Used for pagination. |
Query.cursorBefore("62a7...a600") | Places the cursor before the specified resource ID. Used for pagination. |
Example | Description |
Query.select(["name", "title"]) | Select which attributes should be returned from a document. |
Query.and([Query.lessThan("size", 10), Query.greaterThan("size", 5)]) | Returns document if it matches all of the nested sub-queries in the array passed in. |
Query.or([Query.lessThan("size", 5), Query.greaterThan("size", 10)]) | Returns document if it matches any of the nested sub-queries in the array passed in. |
Query.equal("title", ["Iron Man"]) | Returns document if attribute is equal to any value in the provided array. |
Query.notEqual("title", ["Iron Man"]) | Returns document if attribute is not equal to any value in the provided array. |
Query.lessThan("score", 10) | Returns document if attribute is less than the provided value. |
Query.lessThanEqual("score", 10) | Returns document if attribute is less than or equal to the provided value. |
Query.greaterThan("score", 10) | Returns document if attribute is greater than the provided value. |
Query.greaterThanEqual("score", 10) | Returns document if attribute is greater than or equal to the provided value. |
Query.between("price", 5, 10) | Returns document if attribute value falls between the two values. The boundary values are inclusive and can be strings or numbers. |
Query.isNull("name") | Returns documents where attribute value is null. |
Query.isNotNull("name") | Returns documents where attribute value is not null. |
Query.startsWith("name", "Once upon a time") | Returns documents if a string attributes starts with a substring. |
Query.endsWith("name", "happily ever after.") | Returns documents if a string attributes ends with a substring. |
Query.contains("ingredients", ['apple', 'banana']) | Returns documents if a the array attribute contains the specified elements. |
Query.contains("name", "Tom") | Returns documents if a string attributes is like the pattern specified. |
Query.search("text", "key words") | Searches string attributes for provided keywords. Requires a full-text index on queried attributes. |
Query.orderDesc("attribute") | Orders results in descending order by attribute. Attribute must be indexed. Pass in an empty string to return in natural order. |
Query.orderAsc("attribute") | Orders results in ascending order by attribute. Attribute must be indexed. Pass in an empty string to return in natural order. |
Query.limit(25) | Limits the number of results returned by the query. Used for pagination. If the limit query is not used, the limit defaults to 25 results. |
Query.offset(0) | Offset the results returned by skipping some of the results. Used for pagination. |
Query.cursorAfter("62a7...f620") | Places the cursor after the specified resource ID. Used for pagination. |
Query.cursorBefore("62a7...a600") | Places the cursor before the specified resource ID. Used for pagination. |
Example | Description |
Query.select(["name", "title"]) | Select which attributes should be returned from a document. |
Query.and([Query.lessThan("size", 10), Query.greaterThan("size", 5)]) | Returns document if it matches all of the nested sub-queries in the array passed in. |
Query.or([Query.lessThan("size", 5), Query.greaterThan("size", 10)]) | Returns document if it matches any of the nested sub-queries in the array passed in. |
Query.equal("title", ["Iron Man"]) | Returns document if attribute is equal to any value in the provided array. |
Query.notEqual("title", ["Iron Man"]) | Returns document if attribute is not equal to any value in the provided array. |
Query.lessThan("score", 10) | Returns document if attribute is less than the provided value. |
Query.lessThanEqual("score", 10) | Returns document if attribute is less than or equal to the provided value. |
Query.greaterThan("score", 10) | Returns document if attribute is greater than the provided value. |
Query.greaterThanEqual("score", 10) | Returns document if attribute is greater than or equal to the provided value. |
Query.between("price", 5, 10) | Returns document if attribute value falls between the two values. The boundary values are inclusive and can be strings or numbers. |
Query.isNull("name") | Returns documents where attribute value is null. |
Query.isNotNull("name") | Returns documents where attribute value is not null. |
Query.startsWith("name", "Once upon a time") | Returns documents if a string attributes starts with a substring. |
Query.endsWith("name", "happily ever after.") | Returns documents if a string attributes ends with a substring. |
Query.contains("ingredients", ['apple', 'banana']) | Returns documents if a the array attribute contains the specified elements. |
Query.contains("name", "Tom") | Returns documents if a string attributes is like the pattern specified. |
Query.search("text", "key words") | Searches string attributes for provided keywords. Requires a full-text index on queried attributes. |
Query.orderDesc("attribute") | Orders results in descending order by attribute. Attribute must be indexed. Pass in an empty string to return in natural order. |
Query.orderAsc("attribute") | Orders results in ascending order by attribute. Attribute must be indexed. Pass in an empty string to return in natural order. |
Query.limit(25) | Limits the number of results returned by the query. Used for pagination. If the limit query is not used, the limit defaults to 25 results. |
Query.offset(0) | Offset the results returned by skipping some of the results. Used for pagination. |
Query.cursorAfter("62a7...f620") | Places the cursor after the specified resource ID. Used for pagination. |
Query.cursorBefore("62a7...a600") | Places the cursor before the specified resource ID. Used for pagination. |
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.
import { Client, Databases, Query } from "appwrite";
const client = new Client()
.setEndpoint('https://cloud.appwrite.io/v1')
.setProject('<PROJECT_ID>');
const databases = new Databases(client);
databases.listDocuments(
'<DATABASE_ID>',
'[COLLECTION_ID]',
[
Query.equal('title', ['Avatar', 'Lord of the Rings']),
Query.greaterThan('year', 1999)
]
);