Query parameters & clauses

Query examples in this content are shown unencoded to make them easier to read. Keep in mind that you might need to encode query strings if you're sending them as part of URLs, such as when you're executing them with the cURL tool.

Optimizing queries

As a best practice, you should include no more than 3 parameters in your queries. The API will not prevent you from submitting a query with more than 3 parameters; however, due to the nature of NoSQL, queries with many parameters can quickly become very inefficient.

Order by

You can return query results that are sorted in the order you specify. Use the order by clause to specify the property to sort by, along with the order in which results should be sorted. The syntax for the clause is as follows:

Limit

When your query might return more results than you want to display to the user at once, you can use the limit parameter with cursors or API methods to manage the display of results. By default, query results are limited to 10 at a time. You can adjust this by setting the limit parameter to a value you prefer.

For example, you might execute a query that could potentially return hundreds of results, but you want to display 20 of those at a time to users. To do this, your code sets the limit parameter to 20 when querying for data, then provides a way for the user to request more of the results when they're ready.

You would use the following parameters in your query:

Parameter

Type

Description

limit

integer

Number of results to return. The maximum number of results is 1,000. Specifying a limit greater than 1,000 will result in a limit of 1,000.

You can also use the limit parameter on a request without a query string. The following example is shorthand for selecting all books and limiting by 100 at a time:

/books?limit=100

Using a limit on a DELETE can help you manage the amount of time it takes to delete data. For example you can delete all of the books, 1000 at a time, with the following:

DELETE /books?limit=1000

Keep in mind that DELETE operations can take longer to execute. Yet even though the DELETE query call might time out (such as with a very large limit), the operation will continue on the server even if the client stops waiting for the result.

For example:

Select all users whose name starts with fred, and returns the first 50 results: