Querying your Documents
In Payload, "querying" means filtering or searching through Documents within a Collection. The querying language in Payload is designed to be simple and powerful, allowing you to filter Documents with extreme precision through an intuitive and standardized structure.
Payload provides three common APIs for querying your data:
- Local API - Extremely fast, direct-to-database access
- REST API - Standard HTTP endpoints for querying and mutating data
- GraphQL - A full GraphQL API with a GraphQL Playground
Each of these APIs share the same underlying querying language, and fully support all of the same features. This means that you can learn Payload's querying language once, and use it across any of the APIs that you might use.
To query your Documents, you can send any number of Operators through your request:
The exact query syntax will depend on the API you are using, but the concepts are the same across all APIs. More details.
Operators
The following operators are available for use in queries:
Operator | Description |
---|---|
| The value must be exactly equal. |
| The query will return all documents where the value is not equal. |
| For numeric or date-based fields. |
| For numeric or date-based fields. |
| For numeric or date-based fields. |
| For numeric or date-based fields. |
| Case-insensitive string must be present. If string of words, all words must be present, in any order. |
| Must contain the value entered, case-insensitive. |
| The value must be found within the provided comma-delimited list of values. |
| The value must NOT be within the provided comma-delimited list of values. |
| The value must contain all values provided in the comma-delimited list. Note: currently this operator is supported only with the MongoDB adapter. |
| Only return documents where the value either exists ( |
| For distance related to a Point Field comma separated as |
| For Point Fields to filter documents based on whether points are inside of the given area defined in GeoJSON. Example |
| For Point Fields to filter documents based on whether points intersect with the given area defined in GeoJSON. Example |
And / Or Logic
In addition to defining simple queries, you can join multiple queries together using AND / OR logic. These can be nested as deeply as you need to create complex queries.
To join queries, use the and
or or
keys in your query object:
Written in plain English, if the above query were passed to a find
operation, it would translate to finding posts where either the color
is mint
OR the color
is white
AND featured
is set to false.
Nested properties
When working with nested properties, which can happen when using relational fields, it is possible to use the dot notation to access the nested property. For example, when working with a Song
collection that has a artists
field which is related to an Artists
collection using the name: 'artists'
. You can access a property within the collection Artists
like so:
Writing Queries
Writing queries in Payload is simple and consistent across all APIs, with only minor differences in syntax between them.
Local API
The Local API supports the find
operation that accepts a raw query object:
GraphQL API
All find
queries in the GraphQL API support the where
argument that accepts a raw query object:
REST API
With the REST API, you can use the full power of Payload queries, but they are written as query strings instead:
https://localhost:3000/api/posts?where[color][equals]=mint
To understand the syntax, you need to understand that complex URL search strings are parsed into a JSON object. This one isn't too bad, but more complex queries get unavoidably more difficult to write.
For this reason, we recommend to use the extremely helpful and ubiquitous qs-esm
package to parse your JSON / object-formatted queries into query strings:
Performance
There are several ways to optimize your queries. Many of these options directly impact overall database overhead, response sizes, and/or computational load and can significantly improve performance.
When building queries, combine as many of these strategies together as possible to ensure your queries are as performant as they can be.
Indexes
Build Indexes for fields that are often queried or sorted by.
When your query runs, the database will not search the entire document to find that one field, but will instead use the index to quickly locate the data.
This is done by adding index: true
to the Field Config for that field:
To learn more, see the Indexes documentation.
Depth
Set the Depth to only the level that you need to avoid populating unnecessary related documents.
Relationships will only populate down to the specified depth, and any relationships beyond that depth will only return the ID of the related document.
To learn more, see the Depth documentation.
Limit
Set the Limit if you can reliably predict the number of matched documents, such as when querying on a unique field.
To learn more, see the Limit documentation.
Select
Use the Select API to only process and return the fields you need.
This will reduce the amount of data returned from the request, and also skip processing of any fields that are not selected, such as running their field hooks.
This is a basic example, but there are many ways to use the Select API, including selecting specific fields, excluding fields, etc.
To learn more, see the Select documentation.
Pagination
Disable Pagination if you can reliably predict the number of matched documents, such as when querying on a unique field.
To learn more, see the Pagination documentation.