Become a master of the database using Appwrite's new query API

With Appwrite 0.12, we made Appwrite harder, better, faster, stronger with many new additions to the Database! One of these recent changes is the Query API which has been completely rewritten to give you unparalleled control over your database queries using Appwrite.

🤔 What is Appwrite?

If you're wondering what Appwrite is, you're missing out! Appwrite is open source backend-as-a-service that abstracts all the complexity involved in building a modern application by providing you with a set of REST APIs for your core backend needs. Appwrite handles user authentication and authorization, file storage, real-time APIs, cloud functions, webhooks and the subject of today, databases.

👀 So what changed?

In Appwrite 0.12, the syntax for queries has been rewritten to make it easier and provide greater control to developers. In all our SDKs we have introduced a new Query class to abstract all the logic behind query creation. The new Query class enables IDE auto-completion and makes it easier to develop your project without having to constantly refer to the documentation to see what queries are available to you.

🧑‍💻 How do I use the Query class?

Using the Query class is easy! When using an API endpoint that supports queries, you pass an array of Queries instead of the previously used strings.

For example, if we had a movies collection, and wanted to search for Avatar in the movie title, we can now use:

const { Client, Database, Query } = require('appwrite');

const client = new Client(); 
const database = new Database(client); 
database.listDocuments('movies', [
  Query.equal('title', 'Avatar')
]);

As you can see here, we are using the Query class's .equal function, which checks for values that exactly match the provided one within the attribute you specify ( title in this case ).

You can also search for multiple values within these queries, equivalent to a database OR command. Let's say we'd like to search for movies with Avatar or Scott Pilgrim vs the World in the title. The code would look like this:

database.listDocuments('movies', [
  Query.equal('title', ['Avatar', 'Scott Pilgrim vs the World'])
]);

Now, what about AND conditions? They are simple. Just add them to the main array of queries.

For instance, if we were to search for movies released after 2010 but before 2020, the query would look something like this:

database.listDocuments('movies', [
  Query.greater('year', 2010)
  Query.lesser('year', 2020)
]);

There's also the greaterEqual and lesserEqual queries. These are exactly the same as the greater and lesser queires, but also check for equality. For instance, we could rewrite the above query to also include results from 2010 and 2020 as follows:

database.listDocuments('movies', [
  Query.greaterEqual('year', 2010)
  Query.lesserEqual('year', 2020)
]);

We can also use the search query to search for a substring within a string. For instance, if we wanted to search for movies with Lord of the rings in the title, we could use:

database.listDocuments('movies', [
  Query.search('title', 'Lord of the rings')
]);

When using a search query, please ensure that you have created a Fulltext index for the attribute you're querying for.

There are also notEqual queries. This is the opposite of the equal function. If you wanted to search for movies that we not called Avatar, you could use:

database.listDocuments('movies', [
  Query.notEqual('title', 'Avatar')
]);

Not only that, but you can also combine AND with OR like this:

database.listDocuments('movies', [
  Query.greater('year', 2010)
  Query.search('actors', ['Adam Sandler', 'Steve Buscemi'])
]);

This code will get all the movies after 2010 that has either Adam Sandler or Steve Buscemi.

As you can see, the possibilities are endless with Queries, and there are loads of them to use. You can look at all possible operations in our querying guide.

To use queries, you must have correctly set indexes on your attributes so Appwrite can efficiently search through your records. You can learn more about supported indexes in Appwrite in our docs.

🎬 Conclusion

As you can see, the new Query API is undoubtedly easier to use however that's not the only advantage of this new API! It also allows new OR queries and is significantly faster in benchmarks. The revamped Query API is just one of the many changes in Appwrite 0.12! Check out the full changelog here.

We'd love to hear your feedback on how we can make Appwrite better. Feel free to hop onto our Discord server or start a Github discussion to let us know how you're using Appwrite!

📚 Learn more

You can use following resources to learn more and get help regarding Appwrite and it's services

🚀 Appwrite Github
📜 Appwrite Docs
💬 Discord Community