Cloud Queries
The state of your application is typically built by users. useCloudState hook allows your application users to read and write data from their own state.
If you're building a todo application, your users might set their own todos in their own user space.
This is convenient because users are guaranteed to be mutating their own state. An authenticated user can only make changes to their own state.


But sometimes, you have to find answers to questions that require aggregation of the entirety of the user space. Some of these questions may:
  1. 1.
    What are the total number of todos completed by all of the users today?
  2. 2.
    Who are the top 5 most productive users?
Cloud query framework allows you to construct queries that lets you ask questions like these and effeciently aggregate the entire user space across your app. It then exposes these answers as derived data in a read-only capacity to any authenticated user.

What is a cloud query?

A cloud query contains a pipeline of operators that execute sequentially. The pipeline consists of:
  1. 1.
    One or more query operators.
  2. 2.
    An optional finalizer function that executes last.
The input to this pipeline would be the entirety of your application's user space. The output from this function would be a JSON object.
Ultimately, you can name the pipeline, for example, completedTodosCount, and get the result of that query from any client, by using the useCloudQuery hook.
Although the pipeline has access to all of the user data while processing the pipeline, since the processing is done server-side, the source user data is never exposed to the client, unless you make it so - via the returned result.

Creating a Cloud Query

You can create a Cloud Query via the playground in the admin console.
Once you've added the necessary operators and optionally written the finalizer function, you can give your query an id, and it will be stored on the server. This id will act as the queryId in useCloudQuery call on the client.


Sometimes, it becomes necessary to change the behaviour of the Cloud Query based on some user input, or another dynamic value. By default, Cloud Queries do not accept any input from the client, other than the queryId.
For example, a user might want to search a todo by it's description. In this instance the search text becomes a user input to the query. You can instruct the Cloud Query to accept a parameter by defining it as a $data.value.
In this case, an example Query Operator that takes in the searchText variable would look like:
equals('user.todos.description', '$data.searchText')
Once you define this $data.value property, you should be able to feed it values in the playground and test its behaviour.
Variables can only be accept JSON primitive values. These are:
  • strings
  • numbers
  • booleans
  • null

Automatic Refetching

When the source of your Cloud Query gets mutated by the authenticated user with the current session, it gets automatically refetched.
Given this example Cloud Query with two operators:
equals('user.todos.description', '$data.searchText')
If the current user mutates their user.todos.description at any point via a useCloudState hook, the Cloud Query above will get refetched.