tabshift/payloadcms
1
0
Fork 0
Code Issues Pull Requests Actions 3 Packages Projects Releases Wiki Activity

chore: exposes all operator in ts type (#2777)

Browse Source
This commit is contained in:
Jarrod Flesch
2023-06-06 13:47:45 -04:00
committed by GitHub
parent 7a72f2f88d
commit 684c1a81a4
2 changed files with 78 additions and 61 deletions
Download Patch File Download Diff File Expand all files Collapse all files

138
docs/queries/overview.mdx
View File

@@ -9,7 +9,15 @@ keywords: query, documents, overview, documentation, Content Management System,
Payload provides an extremely granular querying language through all APIs. Each API takes the same syntax and fully supports all options. Payload provides an extremely granular querying language through all APIs. Each API takes the same syntax and fully supports all options.
<Banner> <Banner>
<strong>Here, "querying" relates to filtering or searching through documents within a Collection.</strong> You can build queries to pass to Find operations as well as to <a href="/docs/access-control/overview">restrict which documents certain users can access</a> via access control functions. <strong>
Here, "querying" relates to filtering or searching through documents within
a Collection.
</strong>{" "}
You can build queries to pass to Find operations as well as to{" "}
<a href="/docs/access-control/overview">
restrict which documents certain users can access
</a>{" "}
via access control functions.
</Banner> </Banner>
### Simple queries ### Simple queries
@@ -17,60 +25,60 @@ Payload provides an extremely granular querying language through all APIs. Each
For example, say you have a collection as follows: For example, say you have a collection as follows:
```ts ```ts
import { CollectionConfig } from 'payload/types'; import { CollectionConfig } from "payload/types";
export const Post: CollectionConfig = { export const Post: CollectionConfig = {
slug: 'posts', slug: "posts",
fields: [ fields: [
{ {
name: 'color', name: "color",
type: 'select', type: "select",
options: [ options: ["mint", "dark-gray", "white"],
'mint',
'dark-gray',
'white',
],
}, },
{ {
name: 'featured', name: "featured",
type: 'checkbox', type: "checkbox",
} },
] ],
} };
``` ```
You may eventually have a lot of documents within this Collection. If you wanted to find only documents with `color` equal to `mint`, you could write a query as follows: You may eventually have a lot of documents within this Collection. If you wanted to find only documents with `color` equal to `mint`, you could write a query as follows:
```js ```js
const query = { const query = {
color: { // property name to filter on color: {
equals: 'mint', // operator to use and value to compare against // property name to filter on
equals: "mint", // operator to use and value to compare against
}, },
} };
``` ```
The above example demonstrates a simple query but you can get much more complex. The above example demonstrates a simple query but you can get much more complex.
### Operators ### Operators
| Operator | Description | | Operator | Description |
| -------------------- | ------------ | | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `equals` | The value must be exactly equal. | | `equals` | The value must be exactly equal. |
| `not_equals` | The query will return all documents where the value is not 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` | For numeric or date-based fields. |
| `greater_than_equal` | 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` | For numeric or date-based fields. |
| `less_than_equal` | 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. | | `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. | | `contains` | Must contain the value entered, case-insensitive. |
| `in` | The value must be found within the provided comma-delimited list of values. | | `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. | | `not_in` | The value must NOT be within the provided comma-delimited list of values. |
| `exists` | Only return documents where the value either exists (`true`) or does not exist (`false`). | | `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](/docs/fields/point) comma separated as `<longitude>, <latitude>, <maxDistance in meters (nullable)>, <minDistance in meters (nullable)>`. | | `near` | For distance related to a [point field](/docs/fields/point) comma separated as `<longitude>, <latitude>, <maxDistance in meters (nullable)>, <minDistance in meters (nullable)>`. |
<Banner type="success"> <Banner type="success">
<strong>Tip</strong>:<br/> <strong>Tip</strong>:<br />
If you know your users will be querying on certain fields a lot, you can add <strong>index: true</strong> to a field's config which will speed up searches using that field immensely. If you know your users will be querying on certain fields a lot, you can add <strong>
index: true
</strong> to a field's config which will speed up searches using that field immensely.
</Banner> </Banner>
### And / Or Logic ### And / Or Logic
@@ -79,28 +87,30 @@ In addition to defining simple queries, you can join multiple queries together u
```js ```js
const query = { const query = {
or: [ // array of OR conditions or: [
// array of OR conditions
{ {
color: { color: {
equals: 'mint', equals: "mint",
}, },
}, },
{ {
and: [ // nested array of AND conditions and: [
// nested array of AND conditions
{ {
color: { color: {
equals: 'white', equals: "white",
} },
}, },
{ {
featured: { featured: {
equals: false, 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. 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.
@@ -111,10 +121,11 @@ When working with nested properties, which can happen when using relational fiel
```js ```js
const query = { const query = {
'artists.featured': { // nested property name to filter on "artists.featured": {
// nested property name to filter on
exists: true, // operator to use and boolean value that needs to be true exists: true, // operator to use and boolean value that needs to be true
}, },
} };
``` ```
### GraphQL Find Queries ### GraphQL Find Queries
@@ -147,24 +158,29 @@ This one isn't too bad, but more complex queries get unavoidably more difficult
**For example, using fetch:** **For example, using fetch:**
```js ```js
import qs from 'qs'; import qs from "qs";
const query = { const query = {
color: { color: {
equals: 'mint', equals: "mint",
}, },
// This query could be much more complex // This query could be much more complex
// and QS would handle it beautifully // and QS would handle it beautifully
} };
const getPosts = async () => { const getPosts = async () => {
const stringifiedQuery = qs.stringify({ const stringifiedQuery = qs.stringify(
where: query // ensure that `qs` adds the `where` property, too! {
}, { addQueryPrefix: true }); where: query, // ensure that `qs` adds the `where` property, too!
},
{ addQueryPrefix: true }
);
const response = await fetch(`http://localhost:3000/api/posts${stringifiedQuery}`); const response = await fetch(
`http://localhost:3000/api/posts${stringifiedQuery}`
);
// Continue to handle the response below... // Continue to handle the response below...
} };
``` ```
### Local API Queries ### Local API Queries
@@ -174,19 +190,18 @@ The Local API's `find` operation accepts an object exactly how you write it. For
```js ```js
const getPosts = async () => { const getPosts = async () => {
const posts = await payload.find({ const posts = await payload.find({
collection: 'posts', collection: "posts",
where: { where: {
color: { color: {
equals: 'mint', equals: "mint",
}, },
}, },
}); });
return posts; return posts;
} };
``` ```
## Sort ## Sort
Payload `find` queries support a `sort` parameter through all APIs. Pass the `name` of a top-level field to sort by that field in ascending order. Prefix the name of the field with a minus symbol ("-") to sort in descending order. Payload `find` queries support a `sort` parameter through all APIs. Pass the `name` of a top-level field to sort by that field in ascending order. Prefix the name of the field with a minus symbol ("-") to sort in descending order.
@@ -195,6 +210,7 @@ Payload `find` queries support a `sort` parameter through all APIs. Pass the `na
**`https://localhost:3000/api/posts?sort=-createdAt`** **`https://localhost:3000/api/posts?sort=-createdAt`**
**GraphQL example:** **GraphQL example:**
``` ```
query { query {
Posts(sort: "-createdAt") { Posts(sort: "-createdAt") {
@@ -210,10 +226,10 @@ query {
```js ```js
const getPosts = async () => { const getPosts = async () => {
const posts = await payload.find({ const posts = await payload.find({
collection: 'posts', collection: "posts",
sort: '-createdAt', sort: "-createdAt",
}); });
return posts; return posts;
} };
``` ```

1
src/types/index.ts
View File

@@ -9,6 +9,7 @@ export type Operator =
| 'contains' | 'contains'
| 'not_equals' | 'not_equals'
| 'in' | 'in'
| 'all'
| 'not_in' | 'not_in'
| 'exists' | 'exists'
| 'greater_than' | 'greater_than'