0b9d5a5ae4
### What? Fixes links in Queries/Operators table for `within` and `intersects` operator descriptions. ### Why? So that they point to the correct destination in the docs. ### How? Changes to `docs/queries/overview.mdx` See here: 
181 lines
8.4 KiB
Plaintext
181 lines
8.4 KiB
Plaintext
---
|
|
title: Querying your Documents
|
|
label: Overview
|
|
order: 10
|
|
desc: Payload provides a querying language through all APIs, allowing you to filter or search through documents within a Collection.
|
|
keywords: query, documents, overview, documentation, Content Management System, cms, headless, javascript, node, react, nextjs
|
|
---
|
|
|
|
In Payload, "querying" means filtering or searching through Documents within a [Collection](../configuration/collections). 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](/docs/local-api/overview) - Extremely fast, direct-to-database access
|
|
- [REST API](/docs/rest-api/overview) - Standard HTTP endpoints for querying and mutating data
|
|
- [GraphQL](/docs/graphql/overview) - 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](#operators) through your request:
|
|
|
|
```ts
|
|
const query = {
|
|
color: {
|
|
equals: 'blue',
|
|
},
|
|
}
|
|
```
|
|
|
|
_The exact query syntax will depend on the API you are using, but the concepts are the same across all APIs. [More details](#writing-queries)._
|
|
|
|
<Banner>
|
|
<strong>Tip:</strong>
|
|
You can also use queries within [Access Control](../access-control/overview) functions.
|
|
</Banner>
|
|
|
|
## Operators
|
|
|
|
The following operators are available for use in queries:
|
|
|
|
| Operator | Description |
|
|
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| `equals` | The value must be exactly equal. |
|
|
| `not_equals` | The query will return all documents where the value is not equal. |
|
|
| `greater_than` | For numeric or date-based fields. |
|
|
| `greater_than_equal` | For numeric or date-based fields. |
|
|
| `less_than` | For numeric or date-based fields. |
|
|
| `less_than_equal` | For numeric or date-based fields. |
|
|
| `like` | Case-insensitive string must be present. If string of words, all words must be present, in any order. |
|
|
| `contains` | Must contain the value entered, case-insensitive. |
|
|
| `in` | The value must be found within the provided comma-delimited list of values. |
|
|
| `not_in` | The value must NOT be within the provided comma-delimited list of values. |
|
|
| `all` | The value must contain all values provided in the comma-delimited list. |
|
|
| `exists` | Only return documents where the value either exists (`true`) or does not exist (`false`). |
|
|
| `near` | For distance related to a [Point Field](../fields/point) comma separated as `<longitude>, <latitude>, <maxDistance in meters (nullable)>, <minDistance in meters (nullable)>`. |
|
|
| `within` | For [Point Fields](../fields/point) to filter documents based on whether points are inside of the given area defined in GeoJSON. [Example](../fields/point#querying-within) |
|
|
| `intersects` | For [Point Fields](../fields/point) to filter documents based on whether points intersect with the given area defined in GeoJSON. [Example](../fields/point#querying-intersects) |
|
|
|
|
<Banner type="success">
|
|
<strong>Tip:</strong>
|
|
If you know your users will be querying on certain fields a lot, add `index: true` to the Field Config. This will speed up searches using that field immensely.
|
|
</Banner>
|
|
|
|
### 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:
|
|
|
|
```ts
|
|
const query = {
|
|
or: [ // highlight-line
|
|
{
|
|
color: {
|
|
equals: 'mint',
|
|
},
|
|
},
|
|
{
|
|
and: [ // highlight-line
|
|
{
|
|
color: {
|
|
equals: 'white',
|
|
},
|
|
},
|
|
{
|
|
featured: {
|
|
equals: false,
|
|
},
|
|
},
|
|
],
|
|
},
|
|
],
|
|
}
|
|
```
|
|
|
|
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:
|
|
|
|
```js
|
|
const query = {
|
|
'artists.featured': {
|
|
// nested property name to filter on
|
|
exists: true, // operator to use and boolean value that needs to be true
|
|
},
|
|
}
|
|
```
|
|
|
|
## 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](../local-api/overview) supports the `find` operation that accepts a raw query object:
|
|
|
|
```ts
|
|
const getPosts = async () => {
|
|
const posts = await payload.find({
|
|
collection: 'posts',
|
|
where: {
|
|
color: {
|
|
equals: 'mint',
|
|
},
|
|
},
|
|
})
|
|
|
|
return posts
|
|
}
|
|
```
|
|
|
|
### GraphQL API
|
|
|
|
All `find` queries in the [GraphQL API](../graphql/overview) support the `where` argument that accepts a raw query object:
|
|
|
|
```ts
|
|
query {
|
|
Posts(where: { color: { equals: mint } }) {
|
|
docs {
|
|
color
|
|
}
|
|
totalDocs
|
|
}
|
|
}
|
|
```
|
|
|
|
### REST API
|
|
|
|
With the [REST API](../rest-api/overview), 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`](https://www.npmjs.com/package/qs-esm) package to parse your JSON / object-formatted queries into query strings:
|
|
|
|
```ts
|
|
import { stringify } from 'qs-esm'
|
|
|
|
const query = {
|
|
color: {
|
|
equals: 'mint',
|
|
},
|
|
// This query could be much more complex
|
|
// and QS would handle it beautifully
|
|
}
|
|
|
|
const getPosts = async () => {
|
|
const stringifiedQuery = stringify(
|
|
{
|
|
where: query, // ensure that `qs` adds the `where` property, too!
|
|
},
|
|
{ addQueryPrefix: true },
|
|
)
|
|
|
|
const response = await fetch(`http://localhost:3000/api/posts${stringifiedQuery}`)
|
|
// Continue to handle the response below...
|
|
}
|
|
```
|