You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Adds `select` which is used to specify the field projection for local
and rest API calls. This is available as an optimization to reduce the
payload's of requests and make the database queries more efficient.
Includes:
- [x] generate types for the `select` property
- [x] infer the return type by `select` with 2 modes - include (`field:
true`) and exclude (`field: false`)
- [x] lots of integration tests, including deep fields / localization
etc
- [x] implement the property in db adapters
- [x] implement the property in the local api for most operations
- [x] implement the property in the rest api
- [x] docs
---------
Co-authored-by: Dan Ribbens <dan.ribbens@gmail.com>
|`collection`| Required for Collection operations. Specifies the Collection slug to operate against. |
83
-
|`data`| The data to use within the operation. Required for `create`, `update`. |
84
-
|`depth`|[Control auto-population](../queries/depth) of nested relationship and upload fields. |
85
-
|`locale`| Specify [locale](/docs/configuration/localization) for any returned documents. |
86
-
|`fallbackLocale`| Specify a [fallback locale](/docs/configuration/localization) to use for any returned documents. |
87
-
|`overrideAccess`| Skip access control. By default, this property is set to true within all Local API operations. |
88
-
|`overrideLock`| By default, document locks are ignored (`true`). Set to `false` to enforce locks and prevent operations when a document is locked by another user. [More details](../admin/locked-documents). |
89
-
|`user`| If you set `overrideAccess` to `false`, you can pass a user to use against the access control checks. |
90
-
|`showHiddenFields`| Opt-in to receiving hidden fields. By default, they are hidden from returned documents in accordance to your config. |
91
-
|`pagination`| Set to false to return all documents and avoid querying for document counts. |
92
-
|`context`|[Context](/docs/hooks/context), which will then be passed to `context` and `req.context`, which can be read by hooks. Useful if you want to pass additional information to the hooks which shouldn't be necessarily part of the document, for example a `triggerBeforeChange` option which can be read by the BeforeChange hook to determine if it should run or not. |
93
-
|`disableErrors`| When set to `true`, errors will not be thrown. Instead, the `findByID` operation will return `null`, and the `find` operation will return an empty documents array. |
94
-
|`disableTransaction`| When set to `true`, a [database transactions](../database/transactions) will not be initialized. |
|`collection`| Required for Collection operations. Specifies the Collection slug to operate against. |
83
+
|`data`| The data to use within the operation. Required for `create`, `update`. |
84
+
|`depth`|[Control auto-population](../queries/depth) of nested relationship and upload fields. |
85
+
|`locale`| Specify [locale](/docs/configuration/localization) for any returned documents. |
86
+
|`select`| Specify [select](../queries/select) to control which fields to include to the result. |
87
+
|`fallbackLocale`| Specify a [fallback locale](/docs/configuration/localization) to use for any returned documents. |
88
+
|`overrideAccess`| Skip access control. By default, this property is set to true within all Local API operations. |
89
+
|`overrideLock`| By default, document locks are ignored (`true`). Set to `false` to enforce locks and prevent operations when a document is locked by another user. [More details](../admin/locked-documents). |
90
+
|`user`| If you set `overrideAccess` to `false`, you can pass a user to use against the access control checks. |
91
+
|`showHiddenFields`| Opt-in to receiving hidden fields. By default, they are hidden from returned documents in accordance to your config. |
92
+
|`pagination`| Set to false to return all documents and avoid querying for document counts. |
93
+
|`context`|[Context](/docs/hooks/context), which will then be passed to `context` and `req.context`, which can be read by hooks. Useful if you want to pass additional information to the hooks which shouldn't be necessarily part of the document, for example a `triggerBeforeChange` option which can be read by the BeforeChange hook to determine if it should run or not. |
94
+
|`disableErrors`| When set to `true`, errors will not be thrown. Instead, the `findByID` operation will return `null`, and the `find` operation will return an empty documents array. |
95
+
|`disableTransaction`| When set to `true`, a [database transactions](../database/transactions) will not be initialized. |
95
96
96
97
_There are more options available on an operation by operation basis outlined below._
You may not need the full data from your Local API / REST queries, but only some specific fields. The select fields API can help you to optimize those cases.
10
+
11
+
## Local API
12
+
13
+
To specify select in the [Local API](../local-api/overview), you can use the `select` option in your query:
14
+
15
+
```ts
16
+
// Include mode
17
+
const getPosts =async () => {
18
+
const posts =awaitpayload.find({
19
+
collection: 'posts',
20
+
select: {
21
+
text: true,
22
+
// select a specific field from group
23
+
group: {
24
+
number: true
25
+
},
26
+
// select all fields from array
27
+
array: true,
28
+
}, // highlight-line
29
+
})
30
+
31
+
returnposts
32
+
}
33
+
34
+
// Exclude mode
35
+
const getPosts =async () => {
36
+
const posts =awaitpayload.find({
37
+
collection: 'posts',
38
+
// Select everything except for array and group.number
39
+
select: {
40
+
array: false,
41
+
group: {
42
+
number: false
43
+
}
44
+
}, // highlight-line
45
+
})
46
+
47
+
returnposts
48
+
}
49
+
```
50
+
51
+
52
+
<Bannertype="warning">
53
+
<strong>Important:</strong>
54
+
To perform querying with `select` efficiently, it works on the database level. Because of that, your `beforeRead` and `afterRead` hooks may not receive the full `doc`.
55
+
</Banner>
56
+
57
+
58
+
## REST API
59
+
60
+
To specify select in the [REST API](../rest-api/overview), you can use the `select` parameter in your query:
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.
69
+
70
+
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:
71
+
72
+
```ts
73
+
import { stringify } from'qs-esm'
74
+
75
+
const select = {
76
+
text: true,
77
+
group: {
78
+
number: true
79
+
}
80
+
// This query could be much more complex
81
+
// and QS would handle it beautifully
82
+
}
83
+
84
+
const getPosts =async () => {
85
+
const stringifiedQuery =stringify(
86
+
{
87
+
select, // ensure that `qs` adds the `select` property, too!
0 commit comments