Docs

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 Compatibility

Each list endpoint supports different query operations. You can find the supported query methods and attributes in the References section of the Appwrite documentation.

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.

Query Method SDK Method Example Description
Select Query.select(["name", "title"]) Select which attributes should be returned from a document.
Equal Query.equal("title", ["Iron Man"]) Returns document if attribute is equal to any value in the provided array.
Not Equal Query.notEqual("title", ["Iron Man"]) Returns document if attribute is not equal to any value in the provided array.
Less Than Query.lessThan("score", 10) Returns document if attribute is less than the provided value.
Less Than or Equal Query.lessThanEqual("score", 10) Returns document if attribute is less than or equal to the provided value.
Greater Than Query.greaterThan("score", 10) Returns document if attribute is greater than the provided value.
Greater Than or Equal Query.greaterThanEqual("score", 10) Returns document if attribute is greater than or equal to the provided value.
Between 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.
Is Null Query.isNull("name") Returns documents where attribute value is null.
Is Not Null Query.isNotNull("name") Returns documents where attribute value is not null.
Starts With Query.startsWith("name", "Once upon a time") Returns documents if a string attributes starts with a substring.
Ends With Query.endsWith("name", "happily ever after.") Returns documents if a string attributes ends with a substring.
Search Query.search("text", "key words") Searches string attributes for provided keywords. Requires a Full-text index on queried attributes.
Order Descending Query.orderDesc("attribute") Orders results in descending order by attribute. Attribute must be indexed. Pass in an empty string to return in natural order.
Order Ascending Query.orderAsc("attribute") Orders results in ascending order by attribute. Attribute must be indexed. Pass in an empty string to return in natural order.
Limit 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.
Offset Query.offset(0) Offset the results returned by skipping some of the results. Used for pagination.
Cursor After Query.cursorAfter("62a7...f620") Places the cursor after the specified resource ID. Used for pagination.
Cursor Before 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".

  • Web

    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)
        ]
    );
  • Flutter

    import 'package:appwrite/appwrite.dart';
    
    void main() async {
        final client = Client()
            .setEndpoint('https://cloud.appwrite.io/v1')
            .setProject('[PROJECT_ID]');
    
        final databases = Databases(client);
    
        try {
            final documents = await databases.listDocuments(
                '[DATABASE_ID]',
                '[COLLECTION_ID]',
                [
                    Query.equal('title', ['Avatar', 'Lord of the Rings']),
                    Query.greaterThan('year', 1999)
                ]
            );
        } on AppwriteException catch(e) {
            print(e);
        }
    }
  • Android

    import io.appwrite.Client
    import io.appwrite.Query
    import io.appwrite.services.Databases
    
    suspend fun main() {
        val client = Client(applicationContext)
            .setEndpoint('https://cloud.appwrite.io/v1')
            .setProject('[PROJECT_ID]');
    
        val databases = Databases(client)
    
        try {
            val documents = databases.listDocuments(
                databaseId = "[DATABASE_ID]",
                collectionId = "[COLLECTION_ID]",
                queries = listOf(
                    Query.equal("title", listOf("Avatar", "Lord of the Rings")),
                    Query.greaterThan("year", 1999)
                )
            )
        } catch (e: AppwriteException) {
            Log.e("Appwrite", e.message)
        }
    }
  • Apple

    import Appwrite
    import AppwriteModels
    
    func main() async throws {
        let client = Client()
            .setEndpoint("https://cloud.appwrite.io/v1")
            .setProject("[PROJECT_ID]")
    
        let databases = Databases(client)
    
        do {
            let documents = try await databases.listDocuments(
                databaseId: "[DATABASE_ID]",
                collectionId: "[COLLECTION_ID]",
                queries: [
                    Query.equal("title", ["Avatar", "Lord of the Rings"]),
                    Query.greaterThan("year", 1999)
                ]
            )
        } catch {
            print(error.localizedDescription)
        }
    }
  • GraphQL

    query {
        databasesListDocuments(
            databaseId: "[DATABASE_ID]",
            collectionId: "[COLLECTION_ID]"
            queries: ["equal(\"title\", [\"Avatar\", \"Lord of the Rings\"])", "greaterThan(\"year\", 1999)"]
        ) {
            total
            documents {
                _id
                data
            }
        }
    }

Ordering Results

When querying using the listDocuments endpoint, you can specify the order of the documents returned using the Query.orderAsc() and Query.orderDesc() query methods.

  • Web

    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.orderAsc('title'),
        ]
    );
  • Flutter

    import 'package:appwrite/appwrite.dart';
    
    void main() async {
        final client = Client()
            .setEndpoint('https://cloud.appwrite.io/v1')
            .setProject('[PROJECT_ID]');
    
        final databases = Databases(client);
    
        try {
            final documents = await databases.listDocuments(
                databaseId: '[DATABASE_ID]',
                collectionId: '[COLLECTION_ID]',
                queries: [
                    Query.orderAsc('title')
                ]
            );
        } on AppwriteException catch(e) {
            print(e);
        }
    }
  • Android

    import io.appwrite.Client
    import io.appwrite.Query
    import io.appwrite.services.Databases
    
    suspend fun main() {
        val client = Client(applicationContext)
            .setEndpoint('https://cloud.appwrite.io/v1')
            .setProject('[PROJECT_ID]');
    
        val databases = Databases(client)
    
        try {
            val documents = databases.listDocuments(
                databaseId = "[DATABASE_ID]",
                collectionId = "[COLLECTION_ID]",
                queries = [
                    Query.orderAsc("title")
                ]
            )
        } catch (e: AppwriteException) {
            Log.e("Appwrite", e.message)
        }
    }
  • Apple

    import Appwrite
    import AppwriteModels
    
    func main() async throws {
        let client = Client()
            .setEndpoint('https://cloud.appwrite.io/v1')
            .setProject('[PROJECT_ID]');
    
        let databases = Databases(client)
    
        do {
            let documents = try await databases.listDocuments(
                databaseId: "[DATABASE_ID]",
                collectionId: "[COLLECTION_ID]",
                queries: [
                    Query.orderAsc("title")
                ]
            )
        } catch {
            print(error.localizedDescription)
        }
    }
  • GraphQL

    query {
        databasesListDocuments(
            databaseId: "[DATABASE_ID]",
            collectionId: "[COLLECTION_ID]"
            queries: ["orderAsc(\"title\")"]
        ) {
            total
            documents {
                _id
                data
            }
        }
    }

To sort based on multiple attributes, simply provide multiple query methods.

  • Web

    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.orderAsc('title'), // Order by title in ascending order
            Query.orderDesc('year'), // Order by year in descending order
        ]
    );
  • Flutter

    import 'package:appwrite/appwrite.dart';
    
    void main() async {
        final client = Client()
            .setEndpoint("https://cloud.appwrite.io/v1")
            .setProject("[PROJECT_ID]");
    
        final databases = Databases(client);
        try {
            final documents = await databases.listDocuments(
                databaseId: '[DATABASE_ID]',
                collectionId: '[COLLECTION_ID]',
                queries: [
                    Query.orderAsc('title'), // Order by title in ascending order
                    Query.orderDesc('year')  // Order by year in descending order
                ]
            );
        } on AppwriteException catch(e) {
            print(e);
        }
    }
  • Android

    import io.appwrite.Client
    import io.appwrite.Query
    import io.appwrite.services.Databases
    
    suspend fun main() {
        val client = Client(applicationContext)
            .setEndpoint("https://cloud.appwrite.io/v1")
            .setProject("[PROJECT_ID]")
    
        val databases = Databases(client)
    
        try {
            val documents = databases.listDocuments(
                databaseId = "[DATABASE_ID]",
                collectionId = "[COLLECTION_ID]",
                queries = [
                    Query.orderAsc("title"), // Order by title in ascending order
                    Query.orderDesc("year")  // Order by year in descending order
                ]
            )
        } catch (e: AppwriteException) {
            Log.e("Appwrite", e.message)
        }
    }
  • Apple

    import Appwrite
    import AppwriteModels
    
    func main() async throws {
        let client = Client()
          .setEndpoint("https://cloud.appwrite.io/v1")
          .setProject("[PROJECT_ID]")
    
        let databases = Databases(client)
    
        do {
            let documents = try await databases.listDocuments(
                databaseId: "[DATABASE_ID]",
                collectionId: "[COLLECTION_ID]",
                queries: [
                    Query.orderAsc("title"), // Order by title in ascending order
                    Query.orderDesc("year")  // Order by year in descending order
                ]
            )
        } catch {
            print(error.localizedDescription)
        }
    }
  • GraphQL

    query {
        databasesListDocuments(
            databaseId: "[DATABASE_ID]",
            collectionId: "[COLLECTION_ID]"
            queries: ["orderAsc(\"title\")", "orderDesc(\"year\")"]
        ) {
            total
            documents {
                _id
                data
            }
        }
    }

In the example above, the movies returned will be first sorted by title in ascending order, then sorted by year in descending order.