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

docs: lowercases dir names

Browse Source
This commit is contained in:
James
2021-01-06 08:37:29 -05:00
parent 2624b0c34b
commit 2b37bfd93e
45 changed files with 0 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

201
docs/queries/overview.mdx Normal file
View File

@@ -0,0 +1,201 @@
---
title: Querying your Documents
label: Overview
order: 10
---
Payload provides an extremely granular querying language through all APIs. Each API takes the same syntax and fully supports all options.
<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.
</Banner>
### Simple queries
For example, say you have a collection as follows:
```js
const Post = {
slug: 'posts',
fields: [
{
name: 'color',
type: 'select',
options: [
'mint',
'dark-gray',
'white',
],
},
{
name: 'featured',
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:
```js
const query = {
color: { // 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.
### Operators
| 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` | The value must partially match. |
| `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. |
| `exists` | Only return documents where the value either exists (`true`) or does not exist (`false`). |
<Banner type="success">
<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.
</Banner>
### And / Or Logic
In addition to defining simple queries, you can join multiple queries together using simple AND / OR logic. Let's take the above `Post` collection for example and write a more complex query usnig AND / OR:
```js
const query = {
or: [ // array of OR conditions
{
color: {
equals: 'mint',
},
},
{
and: [ // nested array of AND conditions
{
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.
### GraphQL Find Queries
All GraphQL `find` queries support the `where` argument, which accepts queries exactly as detailed above.
**For example:**
```
query {
Posts(where: { color: { equals: mint } }) {
docs {
color
}
totalDocs
}
}
```
### REST Queries
With the REST API, you can use the full power of Payload queries as well but they become a bit more unwieldy the more complex that they get.
Simple queries are fairly straightforward to write. To understand the syntax, you need to understand how Express and similar languages would go about parsing a complex URL search string into a JSON object. For example, the above [simple query](#simple-queries) would be parsed into a string like this:
**`https://localhost:3000/api/posts?where[color][equals]=mint`**
This one isn't too bad, but more complex queries get unavoidably more difficult to write as query strings. For this reason, we recommend to use the extremely helpful and ubiquitous [`qs`](https://www.npmjs.com/package/qs) package to parse your JSON / object-formatted queries into query strings for use with the REST API.
**For example, using fetch:**
```js
import qs from 'qs';
const query = {
color: {
equals: 'mint',
},
// This query could be much more complex
// and QS would handle it beautifully
}
const getPosts = async () => {
const stringifiedQuery = qs.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...
}
```
### Local API Queries
The Local API's `find` operation accepts an object exactly how you write it. For example:
```js
const getPosts = async () => {
const posts = await payload.find({
collection: 'posts',
where: {
color: {
equals: 'mint',
},
},
});
return posts;
}
```
## 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.
**REST example:**
**`https://localhost:3000/api/posts?sort=-createdAt`**
**GraphQL example:**
```
query {
Posts(sort: "-createdAt") {
docs {
color
}
}
}
```
**Local API example:**
```js
const getPosts = async () => {
const posts = await payload.find({
collection: 'posts',
sort: '-createdAt',
});
return posts;
}
```

58
docs/queries/pagination.mdx Normal file
View File

@@ -0,0 +1,58 @@
---
title: Pagination
label: Pagination
order: 20
---
All collection `find` queries are paginated automatically. Responses are returned with top-level meta data related to pagination, and returned documents are nested within a `docs` array.
**`Find` response properties:**
| Property | Description |
| ------------- | ---------------------------------------------------------- |
| docs | Array of documents in the collection |
| totalDocs | Total available documents within the collection |
| limit | Limit query parameter - defaults to `10` |
| totalPages | Total pages available, based upon the `limit` queried for |
| page | Current page number |
| pagingCounter | `number` of the first doc on the current page |
| hasPrevPage | `true/false` if previous page exists |
| hasNextPage | `true/false` if next page exists |
| prevPage | `number` of previous page, `null` if it doesn't exist |
| nextPage | `number` of next page, `null` if it doesn't exist |
**Example response:**
```js
{
// Document Array // highlight-line
"docs": [
{
"title": "Page Title",
"description": "Some description text",
"priority": 1,
"createdAt": "2020-10-17T01:19:29.858Z",
"updatedAt": "2020-10-17T01:19:29.858Z",
"id": "5f8a46a1dd05db75c3c64760"
}
],
// Metadata // highlight-line
"totalDocs": 6,
"limit": 1,
"totalPages": 6,
"page": 1,
"pagingCounter": 1,
"hasPrevPage": false,
"hasNextPage": true,
"prevPage": null,
"nextPage": 2
}
```
## Pagination controls
All Payload APIs support the pagination controls below. With them, you can create paginated lists of documents within your application:
| Control | Description |
| --------- | ----------------------------------------------------------------------------------------- |
| `limit` | Limits the number of documents returned |
| `page` | Get a specific page number |