@picked/client 0.0.1-dev.1788925875333 → 0.0.1-dev.1793753513002
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +1 -0
- package/README.md +34 -158
- package/dist/.tsbuildinfo +1 -1
- package/dist/api-ZkaFvphK.cjs +1 -0
- package/dist/{api-DbMJli3H.js → api-nJ3O-8r5.js} +1 -1
- package/dist/cjs/form/index.js +1 -1
- package/dist/cjs/index.js +2 -2
- package/dist/cjs/logic-engine.js +1 -0
- package/dist/cjs/plugins/dom-observer/index.js +1 -1
- package/dist/cjs/plugins/dynamic-experiences/index.js +1 -1
- package/dist/cjs/plugins/experience-browser-storage/index.js +1 -1
- package/dist/cjs/plugins/responses-browser-storage/index.js +1 -1
- package/dist/cjs/plugins/telemetry/index.js +1 -1
- package/dist/cjs/server/index.js +1 -1
- package/dist/cjs/storage.js +1 -0
- package/dist/dom-7g2LZCIp.cjs +1 -0
- package/dist/{dom-BqcToNL0.js → dom-v6ulxr_z.js} +1 -5
- package/dist/esm/form/index.js +5 -16
- package/dist/esm/index.js +576 -615
- package/dist/esm/logic-engine.js +208 -0
- package/dist/esm/plugins/dom-observer/index.js +1 -1
- package/dist/esm/plugins/dynamic-experiences/index.js +4 -4
- package/dist/esm/plugins/experience-browser-storage/index.js +12 -10
- package/dist/esm/plugins/responses-browser-storage/index.js +2 -6
- package/dist/esm/plugins/telemetry/index.js +26 -15
- package/dist/esm/preview/index.js +1 -2
- package/dist/esm/server/index.js +47 -43
- package/dist/esm/storage.js +1 -0
- package/dist/experience-instance-4D6Yk-h0.js +774 -0
- package/dist/experience-instance-D2FAkiPx.cjs +1 -0
- package/dist/plugin-B1kexnbX.js +256 -0
- package/dist/plugin-Bnmk8pN8.cjs +1 -0
- package/dist/preview-channel-BMOEreho.cjs +1 -0
- package/dist/{preview-channel-CSr96XAo.js → preview-channel-CLXVoL_j.js} +2 -5
- package/dist/{version-VvasRUfR.js → preview-unavailable-BaHYVZQD.js} +100 -61
- package/dist/preview-unavailable-ClBw_DDY.cjs +1 -0
- package/dist/provider-BFdnIgeH.cjs +1 -0
- package/dist/provider-C98VWkEj.js +115 -0
- package/dist/{rules-logic-HesIUCu6.js → rules-logic-9hh8y_1b.js} +1 -1
- package/dist/rules-logic-VUbvWqdi.cjs +1 -0
- package/dist/types/data-source/preview-unavailable.d.ts +18 -0
- package/dist/types/data-source/preview-unavailable.d.ts.map +1 -0
- package/dist/types/data-source/provider.d.ts +5 -0
- package/dist/types/data-source/provider.d.ts.map +1 -1
- package/dist/types/data-source/request-observer.d.ts +21 -8
- package/dist/types/data-source/request-observer.d.ts.map +1 -1
- package/dist/types/entities/action/action.d.ts +94 -23
- package/dist/types/entities/action/action.d.ts.map +1 -1
- package/dist/types/entities/experience/experience.d.ts +8 -0
- package/dist/types/entities/experience/experience.d.ts.map +1 -1
- package/dist/types/entities/experience-instance/experience-instance.d.ts +14 -1
- package/dist/types/entities/experience-instance/experience-instance.d.ts.map +1 -1
- package/dist/types/exports.d.ts +1 -0
- package/dist/types/exports.d.ts.map +1 -1
- package/dist/types/index.d.ts +2 -2
- package/dist/types/index.d.ts.map +1 -1
- package/dist/types/lifecycle/rules-logic.d.ts.map +1 -1
- package/dist/types/logic-engine.d.ts +9 -0
- package/dist/types/logic-engine.d.ts.map +1 -1
- package/dist/types/picked.d.ts +38 -8
- package/dist/types/picked.d.ts.map +1 -1
- package/dist/types/plugins/dynamic-experiences/index.d.ts +1 -0
- package/dist/types/plugins/dynamic-experiences/index.d.ts.map +1 -1
- package/dist/types/plugins/dynamic-experiences/plugin.d.ts.map +1 -1
- package/dist/types/plugins/dynamic-experiences/types.d.ts +5 -2
- package/dist/types/plugins/dynamic-experiences/types.d.ts.map +1 -1
- package/dist/types/plugins/experience-browser-storage/plugin.d.ts.map +1 -1
- package/dist/types/plugins/telemetry/plugin.d.ts +2 -0
- package/dist/types/plugins/telemetry/plugin.d.ts.map +1 -1
- package/dist/types/schema-registry.d.ts +34 -0
- package/dist/types/schema-registry.d.ts.map +1 -1
- package/dist/types/server/serialize.d.ts +1 -0
- package/dist/types/server/serialize.d.ts.map +1 -1
- package/dist/types/storage.d.ts +6 -0
- package/dist/types/storage.d.ts.map +1 -0
- package/dist/types/typed-content.d.ts +14 -1
- package/dist/types/typed-content.d.ts.map +1 -1
- package/dist/types/utils/events.d.ts +4 -0
- package/dist/types/utils/events.d.ts.map +1 -1
- package/dist/types/utils/node-tree/min-max-steps-to-leaf.d.ts +16 -6
- package/dist/types/utils/node-tree/min-max-steps-to-leaf.d.ts.map +1 -1
- package/dist/types/utils/node-tree/min-max-steps-to-origin.d.ts +18 -7
- package/dist/types/utils/node-tree/min-max-steps-to-origin.d.ts.map +1 -1
- package/dist/types/utils/node-tree/next-reachable-step-nodes.d.ts +30 -6
- package/dist/types/utils/node-tree/next-reachable-step-nodes.d.ts.map +1 -1
- package/dist/types/utils/node-tree/node-adjacency.d.ts +50 -0
- package/dist/types/utils/node-tree/node-adjacency.d.ts.map +1 -0
- package/dist/types/utils/node-tree/node-tree-index.d.ts +57 -0
- package/dist/types/utils/node-tree/node-tree-index.d.ts.map +1 -0
- package/dist/types/utils/rules-logic.d.ts +3 -2
- package/dist/types/utils/rules-logic.d.ts.map +1 -1
- package/dist/types/utils/search-params.d.ts +20 -0
- package/dist/types/utils/search-params.d.ts.map +1 -1
- package/package.json +39 -13
- package/dist/api-qiqq8lgz.cjs +0 -1
- package/dist/docs/_root.css +0 -101
- package/dist/docs/explanation/conditions-and-the-logic-engine.md +0 -94
- package/dist/docs/explanation/content-references.md +0 -99
- package/dist/docs/explanation/feature-flag-allocation.md +0 -218
- package/dist/docs/explanation/how-picked-works.md +0 -124
- package/dist/docs/explanation/how-pickedql-works.md +0 -76
- package/dist/docs/explanation/pages-and-flows.md +0 -64
- package/dist/docs/explanation/the-content-model.md +0 -87
- package/dist/docs/explanation/the-two-apis.md +0 -68
- package/dist/docs/explanation/why-server-side-rendering.md +0 -76
- package/dist/docs/explanation/workspaces-and-versions.md +0 -71
- package/dist/docs/how-to/add-a-step-field-or-action.md +0 -43
- package/dist/docs/how-to/analytics/index.md +0 -316
- package/dist/docs/how-to/archive-or-delete-a-workspace.md +0 -46
- package/dist/docs/how-to/authenticate-the-cli.md +0 -97
- package/dist/docs/how-to/authenticate-with-a-magic-link.md +0 -40
- package/dist/docs/how-to/authenticate-with-a-password.md +0 -51
- package/dist/docs/how-to/authenticate-with-an-api-key.md +0 -51
- package/dist/docs/how-to/authenticate-with-oauth.md +0 -40
- package/dist/docs/how-to/build-a-flow.md +0 -83
- package/dist/docs/how-to/connect-the-mcp-server.md +0 -38
- package/dist/docs/how-to/create-a-content-entry.md +0 -48
- package/dist/docs/how-to/create-a-project.md +0 -29
- package/dist/docs/how-to/create-an-experience.md +0 -42
- package/dist/docs/how-to/create-and-revoke-an-api-key.md +0 -42
- package/dist/docs/how-to/debug-with-the-chrome-extension.md +0 -57
- package/dist/docs/how-to/define-a-page-layout.md +0 -46
- package/dist/docs/how-to/fill-and-publish-a-page.md +0 -66
- package/dist/docs/how-to/install-the-gtm-template.md +0 -84
- package/dist/docs/how-to/install-the-sdk.md +0 -93
- package/dist/docs/how-to/install-the-vite-plugin.md +0 -69
- package/dist/docs/how-to/invite-and-remove-members.md +0 -34
- package/dist/docs/how-to/point-one-entry-at-another.md +0 -61
- package/dist/docs/how-to/preview-a-workspace.md +0 -28
- package/dist/docs/how-to/publish-a-workspace.md +0 -30
- package/dist/docs/how-to/read-a-feature-flag.md +0 -113
- package/dist/docs/how-to/read-a-referenced-entry.md +0 -109
- package/dist/docs/how-to/register-a-component.md +0 -55
- package/dist/docs/how-to/register-an-action-handler.md +0 -67
- package/dist/docs/how-to/render-a-step-form.md +0 -131
- package/dist/docs/how-to/render-an-unpublished-preview.md +0 -41
- package/dist/docs/how-to/reuse-a-section.md +0 -53
- package/dist/docs/how-to/reuse-a-step-field-or-action.md +0 -28
- package/dist/docs/how-to/roll-back-a-published-version.md +0 -26
- package/dist/docs/how-to/run-an-ab-test.md +0 -49
- package/dist/docs/how-to/run-code-on-a-form-submission.md +0 -125
- package/dist/docs/how-to/server-render-a-page.md +0 -81
- package/dist/docs/how-to/set-a-content-security-policy.md +0 -32
- package/dist/docs/how-to/set-up-mfa.md +0 -69
- package/dist/docs/how-to/switch-workspaces.md +0 -122
- package/dist/docs/how-to/upload-and-use-an-asset.mdx +0 -73
- package/dist/docs/how-to/validate-a-field.md +0 -52
- package/dist/docs/how-to/write-a-condition.md +0 -45
- package/dist/docs/how-to/write-a-predicate.md +0 -60
- package/dist/docs/index.md +0 -59
- package/dist/docs/reference/dashboard/actions.mdx +0 -53
- package/dist/docs/reference/dashboard/api-keys.mdx +0 -38
- package/dist/docs/reference/dashboard/conditions.mdx +0 -42
- package/dist/docs/reference/dashboard/content/asset-library.mdx +0 -63
- package/dist/docs/reference/dashboard/content/blocks.mdx +0 -57
- package/dist/docs/reference/dashboard/content/content-entries.mdx +0 -95
- package/dist/docs/reference/dashboard/content/models.mdx +0 -108
- package/dist/docs/reference/dashboard/content/pages.mdx +0 -61
- package/dist/docs/reference/dashboard/experiences.mdx +0 -51
- package/dist/docs/reference/dashboard/features.mdx +0 -154
- package/dist/docs/reference/dashboard/fields.mdx +0 -106
- package/dist/docs/reference/dashboard/flow-builder/canvas.mdx +0 -58
- package/dist/docs/reference/dashboard/flow-builder/condition-builder.md +0 -57
- package/dist/docs/reference/dashboard/flow-builder/keyboard-shortcuts.md +0 -72
- package/dist/docs/reference/dashboard/flow-builder/nodes.md +0 -63
- package/dist/docs/reference/dashboard/projects.mdx +0 -44
- package/dist/docs/reference/dashboard/reports.mdx +0 -43
- package/dist/docs/reference/dashboard/steps.mdx +0 -37
- package/dist/docs/reference/dashboard/team-management.md +0 -29
- package/dist/docs/reference/dashboard/workspace-versioning.mdx +0 -30
- package/dist/docs/reference/dashboard/workspaces.mdx +0 -76
- package/dist/docs/reference/delivery-api/experience-content.md +0 -152
- package/dist/docs/reference/delivery-api/index.md +0 -45
- package/dist/docs/reference/delivery-api/preview-caching-crawling.md +0 -79
- package/dist/docs/reference/delivery-api/project-config.md +0 -65
- package/dist/docs/reference/delivery-api/workspace-schema.md +0 -85
- package/dist/docs/reference/glossary.md +0 -181
- package/dist/docs/reference/management-api/authentication.md +0 -74
- package/dist/docs/reference/management-api/authorization-and-scopes.md +0 -285
- package/dist/docs/reference/management-api/error-handling.md +0 -233
- package/dist/docs/reference/management-api/pagination.md +0 -192
- package/dist/docs/reference/pickedql/data-sources.md +0 -174
- package/dist/docs/reference/pickedql/dimensions.md +0 -103
- package/dist/docs/reference/pickedql/filtering.md +0 -64
- package/dist/docs/reference/pickedql/index.md +0 -18
- package/dist/docs/reference/pickedql/schema.md +0 -172
- package/dist/docs/reference/pickedql/virtual-functions.md +0 -248
- package/dist/docs/reference/sdk/actions.md +0 -30
- package/dist/docs/reference/sdk/analytics-events.md +0 -445
- package/dist/docs/reference/sdk/conditions.md +0 -147
- package/dist/docs/reference/sdk/content-security-policy.md +0 -21
- package/dist/docs/reference/sdk/content.md +0 -213
- package/dist/docs/reference/sdk/experiences.md +0 -51
- package/dist/docs/reference/sdk/features.md +0 -256
- package/dist/docs/reference/sdk/fields.md +0 -255
- package/dist/docs/reference/sdk/index.md +0 -68
- package/dist/docs/reference/sdk/plugins/create-experience.md +0 -123
- package/dist/docs/reference/sdk/plugins/dynamic-experiences.md +0 -74
- package/dist/docs/reference/sdk/plugins/index.md +0 -29
- package/dist/docs/reference/sdk/plugins/window-object.md +0 -25
- package/dist/docs/reference/sdk/predicates.md +0 -43
- package/dist/docs/reference/sdk/ssr/index.md +0 -33
- package/dist/docs/reference/sdk/ssr/rendering-and-hydration.md +0 -103
- package/dist/docs/reference/sdk/ssr/serialize.md +0 -80
- package/dist/docs/reference/sdk/ssr/slots-and-placements.md +0 -59
- package/dist/docs/reference/sdk/steps.md +0 -86
- package/dist/docs/reference/sdk/type-generation.md +0 -196
- package/dist/docs/reference/tools/chrome-extension.md +0 -16
- package/dist/docs/reference/tools/cli.md +0 -146
- package/dist/docs/reference/tools/image-optimisation-service.md +0 -104
- package/dist/docs/reference/tools/mcp.md +0 -90
- package/dist/docs/reference/tools/vite-plugin.md +0 -163
- package/dist/docs/tutorials/first-api-call.md +0 -228
- package/dist/docs/tutorials/first-experience-in-the-dashboard.mdx +0 -143
- package/dist/docs/tutorials/first-experience.mdx +0 -254
- package/dist/docs/tutorials/first-server-rendered-page.mdx +0 -186
- package/dist/dom-DlLH3FxV.cjs +0 -1
- package/dist/experience-instance-DGk11d8a.js +0 -563
- package/dist/experience-instance-Dej3P1sE.cjs +0 -1
- package/dist/plugin-BcLaCLm1.cjs +0 -1
- package/dist/plugin-De_BJSwE.js +0 -194
- package/dist/preview-channel-Cx0e6fye.cjs +0 -1
- package/dist/provider-C_9u0yGJ.cjs +0 -1
- package/dist/provider-ovM-CBX_.js +0 -98
- package/dist/rules-logic-CGZIYgAI.cjs +0 -1
- package/dist/version-BvLZaTMC.cjs +0 -1
|
@@ -1,233 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
type: reference
|
|
3
|
-
layout: docs
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Errors
|
|
7
|
-
|
|
8
|
-
The Picked API returns an error in the standard GraphQL format. This guide covers the
|
|
9
|
-
shape of an error response, every error code, and what your code must do with each
|
|
10
|
-
one.
|
|
11
|
-
|
|
12
|
-
## Error response shape
|
|
13
|
-
|
|
14
|
-
When an operation fails, the API returns an `errors` array in the response body. Each
|
|
15
|
-
error object holds these fields:
|
|
16
|
-
|
|
17
|
-
```json
|
|
18
|
-
{
|
|
19
|
-
"data": null,
|
|
20
|
-
"errors": [
|
|
21
|
-
{
|
|
22
|
-
"message": "A human-readable description of the error",
|
|
23
|
-
"path": ["mutationName"],
|
|
24
|
-
"extensions": {
|
|
25
|
-
"code": "ERROR_CODE"
|
|
26
|
-
}
|
|
27
|
-
}
|
|
28
|
-
]
|
|
29
|
-
}
|
|
30
|
-
```
|
|
31
|
-
|
|
32
|
-
| Field | Description |
|
|
33
|
-
|-------|-------------|
|
|
34
|
-
| `message` | A description of the error that a person can read. Put it in your log. Do not write code against it. |
|
|
35
|
-
| `path` | The path to the field in the query that made the error. |
|
|
36
|
-
| `extensions.code` | An error code that a machine can read. Write your code against this field. |
|
|
37
|
-
|
|
38
|
-
One response can hold more than one error. The `data` field is `null` when the whole
|
|
39
|
-
operation failed. It holds part of the data when only some fields failed.
|
|
40
|
-
|
|
41
|
-
## Authentication error codes
|
|
42
|
-
|
|
43
|
-
These errors come from a session, an account, OAuth, a magic link, a password
|
|
44
|
-
operation, or MFA. They match the `AuthErrorCode` enum in the schema.
|
|
45
|
-
|
|
46
|
-
| Code | Description |
|
|
47
|
-
|------|-------------|
|
|
48
|
-
| `INVALID_CREDENTIALS` | The email address and the password do not match. |
|
|
49
|
-
| `EMAIL_NOT_CONFIRMED` | The account is there, but nobody verified the email address. See [Authentication](/reference/management-api/authentication#the-mutations). |
|
|
50
|
-
| `USER_NOT_FOUND` | There is no account with that email address. |
|
|
51
|
-
| `USER_ALREADY_EXISTS` | An account with that email address is there already. The API returns this when you create an account. |
|
|
52
|
-
| `WEAK_PASSWORD` | The password is not strong enough. |
|
|
53
|
-
| `INVALID_TOKEN` | The token is invalid or malformed. This covers a verification token, a reset token, and a magic link token. |
|
|
54
|
-
| `TOKEN_EXPIRED` | The token expired. Ask for a new one. |
|
|
55
|
-
| `MFA_CHALLENGE_FAILED` | The MFA verification code is not correct. |
|
|
56
|
-
| `MFA_FACTOR_NOT_FOUND` | That MFA factor is not there, or it belongs to another caller. |
|
|
57
|
-
| `OAUTH_PROVIDER_ERROR` | The exchange with the OAuth provider, such as Google, failed. |
|
|
58
|
-
| `RATE_LIMITED` | Too many requests in a short period. Wait, then try again. |
|
|
59
|
-
|
|
60
|
-
### Example: invalid credentials
|
|
61
|
-
|
|
62
|
-
```json
|
|
63
|
-
{
|
|
64
|
-
"data": {
|
|
65
|
-
"sessionCreate": {
|
|
66
|
-
"session": null,
|
|
67
|
-
"requiresMfa": false,
|
|
68
|
-
"mfaFactors": null
|
|
69
|
-
}
|
|
70
|
-
},
|
|
71
|
-
"errors": [
|
|
72
|
-
{
|
|
73
|
-
"message": "Invalid credentials",
|
|
74
|
-
"path": ["sessionCreate"],
|
|
75
|
-
"extensions": {
|
|
76
|
-
"code": "INVALID_CREDENTIALS"
|
|
77
|
-
}
|
|
78
|
-
}
|
|
79
|
-
]
|
|
80
|
-
}
|
|
81
|
-
```
|
|
82
|
-
|
|
83
|
-
## Authorization error codes
|
|
84
|
-
|
|
85
|
-
An authorization error happens when the caller does not hold the
|
|
86
|
-
[scope](/reference/management-api/authorization-and-scopes) that an operation needs.
|
|
87
|
-
|
|
88
|
-
| Code | Description |
|
|
89
|
-
|------|-------------|
|
|
90
|
-
| `UNAUTHORIZED` | The request carries no valid authentication. It has no `Authorization` header and no `x-api-key` header, or the token is invalid. |
|
|
91
|
-
| `FORBIDDEN` | The caller is authenticated, but it does not hold the scope that the operation needs. |
|
|
92
|
-
|
|
93
|
-
### Example: the scope is not enough
|
|
94
|
-
|
|
95
|
-
A caller that holds `organization/read` only tries to delete an organization. It
|
|
96
|
-
receives this:
|
|
97
|
-
|
|
98
|
-
```json
|
|
99
|
-
{
|
|
100
|
-
"data": {
|
|
101
|
-
"organizationDelete": null
|
|
102
|
-
},
|
|
103
|
-
"errors": [
|
|
104
|
-
{
|
|
105
|
-
"message": "Insufficient permissions",
|
|
106
|
-
"path": ["organizationDelete"],
|
|
107
|
-
"extensions": {
|
|
108
|
-
"code": "FORBIDDEN"
|
|
109
|
-
}
|
|
110
|
-
}
|
|
111
|
-
]
|
|
112
|
-
}
|
|
113
|
-
```
|
|
114
|
-
|
|
115
|
-
## Organization, member, and invitation error codes
|
|
116
|
-
|
|
117
|
-
These errors come from an organization, a member operation, or an invitation. They
|
|
118
|
-
match the `ErrorCode` enum in the schema.
|
|
119
|
-
|
|
120
|
-
### Organization errors
|
|
121
|
-
|
|
122
|
-
| Code | Description |
|
|
123
|
-
|------|-------------|
|
|
124
|
-
| `ORGANIZATION_NOT_FOUND` | That organization is not there, or the caller cannot reach it. |
|
|
125
|
-
| `ORGANIZATION_ALREADY_EXISTS` | An organization with that name is there already. |
|
|
126
|
-
| `SLUG_ALREADY_EXISTS` | Another organization uses that slug already. |
|
|
127
|
-
| `INVALID_SLUG` | The slug holds an invalid character. A slug takes lowercase letters, digits, and hyphens only. |
|
|
128
|
-
|
|
129
|
-
### Member errors
|
|
130
|
-
|
|
131
|
-
| Code | Description |
|
|
132
|
-
|------|-------------|
|
|
133
|
-
| `MEMBER_NOT_FOUND` | That user is not a member of the organization. |
|
|
134
|
-
| `MEMBER_ALREADY_EXISTS` | The user is a member of the organization already. |
|
|
135
|
-
| `CANNOT_REMOVE_PRIMARY_OWNER` | You cannot remove the primary owner of an organization. |
|
|
136
|
-
| `CANNOT_CHANGE_OWN_ROLE` | A member cannot change the role of that same member. Another owner must do it. |
|
|
137
|
-
|
|
138
|
-
### Invitation errors
|
|
139
|
-
|
|
140
|
-
| Code | Description |
|
|
141
|
-
|------|-------------|
|
|
142
|
-
| `INVITATION_NOT_FOUND` | That invitation is not there. |
|
|
143
|
-
| `INVITATION_EXPIRED` | The invitation expired. Nobody can accept it now. |
|
|
144
|
-
| `INVITATION_ALREADY_ACCEPTED` | Somebody accepted the invitation already. |
|
|
145
|
-
|
|
146
|
-
### Project errors
|
|
147
|
-
|
|
148
|
-
| Code | Description |
|
|
149
|
-
|------|-------------|
|
|
150
|
-
| `PROJECT_NOT_FOUND` | That project is not there, or the caller cannot reach it. |
|
|
151
|
-
|
|
152
|
-
### General errors
|
|
153
|
-
|
|
154
|
-
| Code | Description |
|
|
155
|
-
|------|-------------|
|
|
156
|
-
| `VALIDATION_ERROR` | The input failed a validation rule. Read the `message` field to learn which field is invalid. |
|
|
157
|
-
| `INTERNAL_ERROR` | The server met an unexpected error. Try the request again. Contact support when the error continues. |
|
|
158
|
-
|
|
159
|
-
## What your code must do
|
|
160
|
-
|
|
161
|
-
### Look for an error first
|
|
162
|
-
|
|
163
|
-
Check every response for an `errors` array before you read `data`:
|
|
164
|
-
|
|
165
|
-
```javascript
|
|
166
|
-
const response = await fetch('/graphql', {
|
|
167
|
-
method: 'POST',
|
|
168
|
-
headers: {
|
|
169
|
-
'Content-Type': 'application/json',
|
|
170
|
-
'Authorization': `Bearer ${accessToken}`,
|
|
171
|
-
},
|
|
172
|
-
body: JSON.stringify({ query, variables }),
|
|
173
|
-
});
|
|
174
|
-
|
|
175
|
-
const result = await response.json();
|
|
176
|
-
|
|
177
|
-
if (result.errors) {
|
|
178
|
-
for (const error of result.errors) {
|
|
179
|
-
const code = error.extensions?.code;
|
|
180
|
-
|
|
181
|
-
switch (code) {
|
|
182
|
-
case 'UNAUTHORIZED':
|
|
183
|
-
// Send the user to the sign-in page.
|
|
184
|
-
break;
|
|
185
|
-
case 'FORBIDDEN':
|
|
186
|
-
// Show a permissions error.
|
|
187
|
-
break;
|
|
188
|
-
case 'RATE_LIMITED':
|
|
189
|
-
// Wait, then try again.
|
|
190
|
-
break;
|
|
191
|
-
default:
|
|
192
|
-
// Put the message in the log, or show it.
|
|
193
|
-
console.error(error.message);
|
|
194
|
-
}
|
|
195
|
-
}
|
|
196
|
-
}
|
|
197
|
-
```
|
|
198
|
-
|
|
199
|
-
### Refresh a token that expired
|
|
200
|
-
|
|
201
|
-
A request can return `UNAUTHORIZED` while the caller holds a refresh token. Try a
|
|
202
|
-
[session refresh](/reference/management-api/authentication#the-mutations) first. Do not treat it as a
|
|
203
|
-
failure to sign in:
|
|
204
|
-
|
|
205
|
-
```javascript
|
|
206
|
-
if (code === 'UNAUTHORIZED' && refreshToken) {
|
|
207
|
-
const refreshResult = await sessionRefresh(refreshToken);
|
|
208
|
-
if (refreshResult.session) {
|
|
209
|
-
// Try the first request again with the new access token.
|
|
210
|
-
} else {
|
|
211
|
-
// Send the user to the sign-in page.
|
|
212
|
-
}
|
|
213
|
-
}
|
|
214
|
-
```
|
|
215
|
-
|
|
216
|
-
### Read data that is only part complete
|
|
217
|
-
|
|
218
|
-
GraphQL can return part of the data together with an error. Take a query that reads
|
|
219
|
-
an organization and its members. It can succeed for the organization and fail for the
|
|
220
|
-
members, when the caller does not hold `organization_members/read`. The response then
|
|
221
|
-
holds `data` with the organization, and `errors` for the members field. Always read
|
|
222
|
-
both.
|
|
223
|
-
|
|
224
|
-
### Try again after a transient failure
|
|
225
|
-
|
|
226
|
-
`INTERNAL_ERROR` and `RATE_LIMITED` are both transient. For `RATE_LIMITED`, use an
|
|
227
|
-
exponential backoff before you try again. For `INTERNAL_ERROR`, one more try is
|
|
228
|
-
usually enough.
|
|
229
|
-
|
|
230
|
-
## Related
|
|
231
|
-
|
|
232
|
-
- [Authentication](/reference/management-api/authentication)
|
|
233
|
-
- [Your first API call](/tutorials/first-api-call)
|
|
@@ -1,192 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
type: reference
|
|
3
|
-
layout: docs
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Pagination
|
|
7
|
-
|
|
8
|
-
The Picked API paginates every list field that can return a large result. It uses a
|
|
9
|
-
cursor, in the Relay-style pattern. This guide covers the connection pattern and
|
|
10
|
-
shows how to move through a result.
|
|
11
|
-
|
|
12
|
-
## Connection pattern
|
|
13
|
-
|
|
14
|
-
A paginated field returns a **connection** object with this shape:
|
|
15
|
-
|
|
16
|
-
```graphql
|
|
17
|
-
type ExampleConnection {
|
|
18
|
-
edges: [ExampleEdge!]!
|
|
19
|
-
pageInfo: PageInfo!
|
|
20
|
-
totalCount: Int!
|
|
21
|
-
}
|
|
22
|
-
|
|
23
|
-
type ExampleEdge {
|
|
24
|
-
cursor: String!
|
|
25
|
-
node: Example!
|
|
26
|
-
}
|
|
27
|
-
|
|
28
|
-
type PageInfo {
|
|
29
|
-
hasNextPage: Boolean!
|
|
30
|
-
hasPreviousPage: Boolean!
|
|
31
|
-
startCursor: String
|
|
32
|
-
endCursor: String
|
|
33
|
-
}
|
|
34
|
-
```
|
|
35
|
-
|
|
36
|
-
| Field | Description |
|
|
37
|
-
|-------|-------------|
|
|
38
|
-
| `edges` | An ordered list of edges. Each edge holds a `cursor` and a `node`, and the `node` holds the data. |
|
|
39
|
-
| `pageInfo.hasNextPage` | `true` when more results come after the last edge |
|
|
40
|
-
| `pageInfo.hasPreviousPage` | `true` when results come before the first edge |
|
|
41
|
-
| `pageInfo.startCursor` | The cursor of the first edge on the current page |
|
|
42
|
-
| `pageInfo.endCursor` | The cursor of the last edge on the current page |
|
|
43
|
-
| `totalCount` | The number of items on every page together |
|
|
44
|
-
|
|
45
|
-
## Forward pagination with `first` and `after`
|
|
46
|
-
|
|
47
|
-
To move forward through the results, use two arguments. The `first` argument gives
|
|
48
|
-
the page size. The `after` argument gives the cursor to start after.
|
|
49
|
-
|
|
50
|
-
### First page
|
|
51
|
-
|
|
52
|
-
Leave the `after` argument out to read the first page:
|
|
53
|
-
|
|
54
|
-
```graphql
|
|
55
|
-
query {
|
|
56
|
-
organizations(input: { first: 10 }) {
|
|
57
|
-
edges {
|
|
58
|
-
cursor
|
|
59
|
-
node {
|
|
60
|
-
id
|
|
61
|
-
name
|
|
62
|
-
}
|
|
63
|
-
}
|
|
64
|
-
pageInfo {
|
|
65
|
-
hasNextPage
|
|
66
|
-
endCursor
|
|
67
|
-
}
|
|
68
|
-
totalCount
|
|
69
|
-
}
|
|
70
|
-
}
|
|
71
|
-
```
|
|
72
|
-
|
|
73
|
-
### Next page
|
|
74
|
-
|
|
75
|
-
Pass the `endCursor` from the previous response as the `after` argument:
|
|
76
|
-
|
|
77
|
-
```graphql
|
|
78
|
-
query {
|
|
79
|
-
organizations(input: { first: 10, after: "cursor_from_previous_page" }) {
|
|
80
|
-
edges {
|
|
81
|
-
cursor
|
|
82
|
-
node {
|
|
83
|
-
id
|
|
84
|
-
name
|
|
85
|
-
}
|
|
86
|
-
}
|
|
87
|
-
pageInfo {
|
|
88
|
-
hasNextPage
|
|
89
|
-
endCursor
|
|
90
|
-
}
|
|
91
|
-
totalCount
|
|
92
|
-
}
|
|
93
|
-
}
|
|
94
|
-
```
|
|
95
|
-
|
|
96
|
-
## Check for more pages
|
|
97
|
-
|
|
98
|
-
Read the `hasNextPage` field before you ask for the next page:
|
|
99
|
-
|
|
100
|
-
- `hasNextPage: true` — more results are available. Pass `endCursor` as the `after`
|
|
101
|
-
argument of the next request.
|
|
102
|
-
- `hasNextPage: false` — you read every result. Stop here.
|
|
103
|
-
|
|
104
|
-
## Full paginated query example
|
|
105
|
-
|
|
106
|
-
This example reads every member of an organization, one page at a time:
|
|
107
|
-
|
|
108
|
-
```graphql
|
|
109
|
-
# Page 1
|
|
110
|
-
query {
|
|
111
|
-
organization(input: { slug: "my-company" }) {
|
|
112
|
-
members(first: 20) {
|
|
113
|
-
edges {
|
|
114
|
-
cursor
|
|
115
|
-
node {
|
|
116
|
-
id
|
|
117
|
-
userEmail
|
|
118
|
-
role
|
|
119
|
-
joinedAt
|
|
120
|
-
}
|
|
121
|
-
}
|
|
122
|
-
pageInfo {
|
|
123
|
-
hasNextPage
|
|
124
|
-
endCursor
|
|
125
|
-
}
|
|
126
|
-
totalCount
|
|
127
|
-
}
|
|
128
|
-
}
|
|
129
|
-
}
|
|
130
|
-
```
|
|
131
|
-
|
|
132
|
-
If `pageInfo.hasNextPage` is `true`, fetch the next page:
|
|
133
|
-
|
|
134
|
-
```graphql
|
|
135
|
-
# Page 2
|
|
136
|
-
query {
|
|
137
|
-
organization(input: { slug: "my-company" }) {
|
|
138
|
-
members(first: 20, after: "cursor_from_page_1") {
|
|
139
|
-
edges {
|
|
140
|
-
cursor
|
|
141
|
-
node {
|
|
142
|
-
id
|
|
143
|
-
userEmail
|
|
144
|
-
role
|
|
145
|
-
joinedAt
|
|
146
|
-
}
|
|
147
|
-
}
|
|
148
|
-
pageInfo {
|
|
149
|
-
hasNextPage
|
|
150
|
-
endCursor
|
|
151
|
-
}
|
|
152
|
-
totalCount
|
|
153
|
-
}
|
|
154
|
-
}
|
|
155
|
-
}
|
|
156
|
-
```
|
|
157
|
-
|
|
158
|
-
Continue until `hasNextPage` returns `false`.
|
|
159
|
-
|
|
160
|
-
## Paginated fields
|
|
161
|
-
|
|
162
|
-
These fields in the schema return a connection type. They all take the `first` and
|
|
163
|
-
`after` arguments:
|
|
164
|
-
|
|
165
|
-
| Parent Type | Field | Connection Type |
|
|
166
|
-
|------------|-------|----------------|
|
|
167
|
-
| `Query` | `organizations` | `OrganizationConnection` |
|
|
168
|
-
| `User` | `organizations` | `OrganizationConnection` |
|
|
169
|
-
| `User` | `invitations` | `ViewerInvitationConnection` |
|
|
170
|
-
| `Organization` | `members` | `OrganizationMemberConnection` |
|
|
171
|
-
| `Organization` | `invitations` | `OrganizationInvitationConnection` |
|
|
172
|
-
| `Organization` | `projects` | `ProjectConnection` |
|
|
173
|
-
| `Project` | `reports` | `ProjectReportConnection` |
|
|
174
|
-
|
|
175
|
-
All of these fields accept the same `first` and `after` arguments and return the standard `edges`, `pageInfo`, and `totalCount` structure.
|
|
176
|
-
|
|
177
|
-
## Tips
|
|
178
|
-
|
|
179
|
-
- **The default page size** — the API applies a default limit when you leave `first`
|
|
180
|
-
out. Set `first` yourself to make sure that each page has the size you expect.
|
|
181
|
-
- **A cursor is opaque** — treat a cursor string as an opaque token. Do not parse it,
|
|
182
|
-
build it, or change it. Pass it back exactly as the API gave it.
|
|
183
|
-
- **The order is stable** — a connection returns its results in a stable order. The
|
|
184
|
-
same cursor always points at the same position in the result.
|
|
185
|
-
- **Use them with other fields** — you can use the pagination arguments together with
|
|
186
|
-
other query fields. One request that reads an organization and the first page of
|
|
187
|
-
its members is common, and it is efficient.
|
|
188
|
-
|
|
189
|
-
## Related
|
|
190
|
-
|
|
191
|
-
- [Your first API call](/tutorials/first-api-call)
|
|
192
|
-
- [Authorization and scopes](/reference/management-api/authorization-and-scopes)
|
|
@@ -1,174 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
type: reference
|
|
3
|
-
layout: docs
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Data sources
|
|
7
|
-
|
|
8
|
-
PickedQL gives you four virtual tables. Each table is fast for one kind of work. It also gives you three reference tables, and those hold the options of your
|
|
9
|
-
Picked project.
|
|
10
|
-
|
|
11
|
-
## `metrics` — data that PickedQL aggregates each day
|
|
12
|
-
|
|
13
|
-
Use it for a dashboard and to study a trend. There is one row for each unique set of
|
|
14
|
-
dimensions on each day. The dimension columns are there directly, and they need no
|
|
15
|
-
join. Examples are `device_category`, `country_code`, and `utm_source`.
|
|
16
|
-
|
|
17
|
-
```sql
|
|
18
|
-
SELECT device_category, control_users(), variant_users()
|
|
19
|
-
FROM metrics
|
|
20
|
-
WHERE project_id = 'your-project-id'
|
|
21
|
-
GROUP BY device_category
|
|
22
|
-
```
|
|
23
|
-
|
|
24
|
-
## `events` — one row for each event of each user
|
|
25
|
-
|
|
26
|
-
Use it for a deep study, for a funnel, and for a breakdown of your own. There is one
|
|
27
|
-
row for each event of each user. PickedQL joins a dimension column, such as
|
|
28
|
-
`device_category` or `country_code`, when you point at it.
|
|
29
|
-
|
|
30
|
-
```sql
|
|
31
|
-
SELECT user_canonical_id, device_category
|
|
32
|
-
FROM events
|
|
33
|
-
WHERE project_id = 'your-project-id'
|
|
34
|
-
AND variant_type = 'Control'
|
|
35
|
-
```
|
|
36
|
-
|
|
37
|
-
## `features` — one row for each feature flag
|
|
38
|
-
|
|
39
|
-
Use it to count the users, the sessions, and the events for each feature flag and
|
|
40
|
-
bucket. It uses parameterized functions.
|
|
41
|
-
|
|
42
|
-
```sql
|
|
43
|
-
SELECT feature_users('homepage_test', 'control')
|
|
44
|
-
FROM features
|
|
45
|
-
WHERE project_id = 'your-project-id'
|
|
46
|
-
```
|
|
47
|
-
|
|
48
|
-
## `experience_journey` — step transitions for a sankey chart
|
|
49
|
-
|
|
50
|
-
It returns one `source, target, users` row for each edge. You can put those rows
|
|
51
|
-
directly into a sankey chart or a funnel chart. It holds the eight common table
|
|
52
|
-
expressions that a card carried before. Those call `lagInFrame`, remove a duplicate
|
|
53
|
-
between two steps that follow each other, and rank the top paths.
|
|
54
|
-
|
|
55
|
-
Every filter goes in the **outer `WHERE`** clause. PickedQL reads each one as a
|
|
56
|
-
parameter and puts it into the query below. Only `project_id` is necessary. The rest
|
|
57
|
-
are optional, and each has a sensible default.
|
|
58
|
-
|
|
59
|
-
| Parameter, as a WHERE key | What it does |
|
|
60
|
-
|---|---|
|
|
61
|
-
| `project_id` | The tenant filter. It is necessary. |
|
|
62
|
-
| `experience_id` | Limits the rows to one `fact_events.experience_id`. |
|
|
63
|
-
| `starting_step` | Anchors each edge at the first time that a user reaches this `step_id`. With no value, it anchors at the first `step_enter` event of that user. |
|
|
64
|
-
| `targeting_step` | Trims the window of each user at the first time that the user reaches this `step_id`. A user who never reaches it still gives a journey, up to `num_nodes_after_start`. |
|
|
65
|
-
| `num_nodes_after_start` | The size of the forward window from the start step. |
|
|
66
|
-
| `num_nodes_before_target` | The size of the backward window from the target step. It needs `targeting_step`. |
|
|
67
|
-
| `top_n_path` | Keeps the paths with the most users, and drops the rest. |
|
|
68
|
-
| `user_cohort_event` | Limits the rows to a user with at least one `fact_events` row of this `event_type`, such as `'lead_capture'`. Use it for the paths of the users who reached a goal. |
|
|
69
|
-
| `client_local_date` | A filter on the date. It takes `=`, `<`, `<=`, `>`, `>=`, and `BETWEEN`. PickedQL puts it into the `fact_events` read below. |
|
|
70
|
-
| `event_timestamp` | A filter on the timestamp from the server. It takes the same operators as `client_local_date`. |
|
|
71
|
-
|
|
72
|
-
When you set both `num_nodes_after_start` and `num_nodes_before_target`, both tests
|
|
73
|
-
apply. The result is the intersection of the two.
|
|
74
|
-
|
|
75
|
-
```sql
|
|
76
|
-
-- The "overall user journey" sankey.
|
|
77
|
-
-- It uses a forward window. The target step is optional.
|
|
78
|
-
SELECT source, target, users FROM experience_journey
|
|
79
|
-
WHERE project_id = 'your-project-id'
|
|
80
|
-
AND starting_step = 'step-start'
|
|
81
|
-
AND targeting_step = 'step-target'
|
|
82
|
-
AND num_nodes_after_start = 10
|
|
83
|
-
AND client_local_date >= '2026-04-01' -- An optional range of dates.
|
|
84
|
-
AND client_local_date <= '2026-04-30'
|
|
85
|
-
```
|
|
86
|
-
|
|
87
|
-
```sql
|
|
88
|
-
-- The "paths to a target" sankey.
|
|
89
|
-
-- It uses a backward window and it ranks the top paths.
|
|
90
|
-
SELECT source, target, users FROM experience_journey
|
|
91
|
-
WHERE project_id = 'your-project-id'
|
|
92
|
-
AND experience_id = 'exp-123'
|
|
93
|
-
AND starting_step = 'step-start'
|
|
94
|
-
AND targeting_step = 'step-target'
|
|
95
|
-
AND num_nodes_before_target = 5
|
|
96
|
-
AND top_n_path = 10
|
|
97
|
-
```
|
|
98
|
-
|
|
99
|
-
```sql
|
|
100
|
-
-- The "drop-off" sankey. Leave the target step out.
|
|
101
|
-
SELECT source, target, users FROM experience_journey
|
|
102
|
-
WHERE project_id = 'your-project-id'
|
|
103
|
-
AND experience_id = 'exp-123'
|
|
104
|
-
AND starting_step = 'step-start'
|
|
105
|
-
AND num_nodes_after_start = 10
|
|
106
|
-
```
|
|
107
|
-
|
|
108
|
-
```sql
|
|
109
|
-
-- A cohort sankey. It holds the users who reached the goal only.
|
|
110
|
-
SELECT source, target, users FROM experience_journey
|
|
111
|
-
WHERE project_id = 'your-project-id'
|
|
112
|
-
AND starting_step = 'step-start'
|
|
113
|
-
AND targeting_step = 'step-target'
|
|
114
|
-
AND num_nodes_after_start = 10
|
|
115
|
-
AND user_cohort_event = 'lead_capture' -- Users with one or more of these events.
|
|
116
|
-
```
|
|
117
|
-
|
|
118
|
-
The columns that it returns:
|
|
119
|
-
|
|
120
|
-
| Column | Type | Description |
|
|
121
|
-
|---|---|---|
|
|
122
|
-
| `source` | String | The start of the edge, in the form `NN. <step title>`, such as `001. Welcome screen`. PickedQL joins `steps` to find the title. |
|
|
123
|
-
| `target` | String | The end of the edge, in the form `NN. <step title>`. |
|
|
124
|
-
| `users` | `UInt64` | The number of different `user_canonical_id` values that went along this edge. |
|
|
125
|
-
|
|
126
|
-
:::note
|
|
127
|
-
`experience_journey` returns data that PickedQL aggregates first. It does **not**
|
|
128
|
-
support a dimension filter such as `variant_type`, `device_category`, or
|
|
129
|
-
`country_code`. To use one of those, query
|
|
130
|
-
[`events`](#events--one-row-for-each-event-of-each-user) directly and build the
|
|
131
|
-
transitions yourself.
|
|
132
|
-
:::
|
|
133
|
-
|
|
134
|
-
## Reference tables — `steps`, `experiences`, `projects`
|
|
135
|
-
|
|
136
|
-
These reference tables hold the configuration of your Picked project. They have two uses:
|
|
137
|
-
|
|
138
|
-
- **PickedQL joins them onto `events`** when you point at one of their analyst
|
|
139
|
-
columns: `step_title`, `experience_title`, `project_name`, or `project_timezone`.
|
|
140
|
-
- **You can read them directly.** Each one then needs its own tenant filter, so that
|
|
141
|
-
you see only the rows of a project that you can reach.
|
|
142
|
-
|
|
143
|
-
| Source | The tenant filter that it needs |
|
|
144
|
-
|---|---|
|
|
145
|
-
| `steps` | `WHERE project_id = '<project_id>'` |
|
|
146
|
-
| `experiences` | `WHERE project_id = '<project_id>'` |
|
|
147
|
-
| `projects` | `WHERE id = '<project_id>'` |
|
|
148
|
-
|
|
149
|
-
```sql
|
|
150
|
-
-- A direct query that reads the experiences of a project.
|
|
151
|
-
SELECT id, title FROM experiences WHERE project_id = 'your-project-id'
|
|
152
|
-
|
|
153
|
-
-- A direct query that reads the metadata of one project.
|
|
154
|
-
SELECT id, name, timezone FROM projects WHERE id = 'your-project-id'
|
|
155
|
-
```
|
|
156
|
-
|
|
157
|
-
```sql
|
|
158
|
-
-- Pointed at from events. PickedQL adds each LEFT JOIN for you.
|
|
159
|
-
-- The reference tables need no separate tenant filter, because
|
|
160
|
-
-- the event table already limits the join.
|
|
161
|
-
SELECT experience_title, step_title, count(*)
|
|
162
|
-
FROM events
|
|
163
|
-
WHERE project_id = 'your-project-id'
|
|
164
|
-
GROUP BY experience_title, step_title
|
|
165
|
-
```
|
|
166
|
-
|
|
167
|
-
See [Schema, reference tables](/reference/pickedql/schema#steps-experiences-projects) for the full
|
|
168
|
-
column list and the join keys.
|
|
169
|
-
|
|
170
|
-
## Related
|
|
171
|
-
|
|
172
|
-
- [About PickedQL](/explanation/how-pickedql-works) — what the layer expands for you.
|
|
173
|
-
- [Schema](/reference/pickedql/schema)
|
|
174
|
-
- [Analytics queries](/how-to/analytics)
|
|
@@ -1,103 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
type: reference
|
|
3
|
-
layout: docs
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Dimension columns
|
|
7
|
-
|
|
8
|
-
Every data source has dimension columns. The `metrics` table holds them directly. On
|
|
9
|
-
`events` and on `features`, PickedQL adds the `LEFT JOIN` that it needs when you
|
|
10
|
-
point at one. You write no join.
|
|
11
|
-
|
|
12
|
-
## The dimensions
|
|
13
|
-
|
|
14
|
-
| Source | Columns |
|
|
15
|
-
|---|---|
|
|
16
|
-
| `dim_variant` | `variant_type`, `ab_feature_name`, `ab_feature_value` |
|
|
17
|
-
| `dim_device` | `device_category`, `browser_name`, `browser_version`, `os_name`, `os_version`, `platform` |
|
|
18
|
-
| `dim_geo` | `country_code`, `country_name`, `region`, `city` |
|
|
19
|
-
| `dim_utm` | `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content` |
|
|
20
|
-
| `dim_product` | `product_name`, `product_category`, `product_page` |
|
|
21
|
-
| `steps` | `step_title` |
|
|
22
|
-
| `experiences` | `experience_title` |
|
|
23
|
-
| `projects` | `project_name`, `project_timezone` |
|
|
24
|
-
|
|
25
|
-
:::warning
|
|
26
|
-
`dim_variant` describes whether the visitor is a known user. It does **not** hold the variants
|
|
27
|
-
of your feature flags. To count the visitors in one variant, use
|
|
28
|
-
[`feature_users`](/reference/pickedql/virtual-functions#feature-functions-on-features-and-on-events).
|
|
29
|
-
:::
|
|
30
|
-
|
|
31
|
-
The `steps`, `experiences`, and `projects` sources are reference tables, and they come
|
|
32
|
-
from the operational database. PickedQL joins them onto `events` and `fact_events`
|
|
33
|
-
when you point at one of their analyst-facing columns. Each one **also** needs its own
|
|
34
|
-
tenant filter when you query it directly:
|
|
35
|
-
|
|
36
|
-
| Source | The tenant filter that it needs |
|
|
37
|
-
|---|---|
|
|
38
|
-
| `steps`, `experiences` | `WHERE project_id = '<project_id>'` |
|
|
39
|
-
| `projects` | `WHERE id = '<project_id>'`, because the `id` of the row is the project ID |
|
|
40
|
-
|
|
41
|
-
PickedQL also puts a tenant equality in the `ON` clause of each join that it adds.
|
|
42
|
-
Examples are `AND st.project_id = '<project_id>'` and `AND pr.id = '<project_id>'`.
|
|
43
|
-
ClickHouse then reads part of the dimension table and not all of it. PickedQL puts
|
|
44
|
-
the test in `ON` and not in `WHERE`, because a test in `WHERE` would change a
|
|
45
|
-
`LEFT JOIN` into an inner join.
|
|
46
|
-
|
|
47
|
-
Each analyst-facing column name carries a prefix, such as `step_title` and
|
|
48
|
-
`project_name`. The prefix stops a collision between two sources. Both `steps.title`
|
|
49
|
-
and `experiences.title` are there, and you point at them as `step_title` and
|
|
50
|
-
`experience_title`.
|
|
51
|
-
|
|
52
|
-
```sql
|
|
53
|
-
-- Group the events by experience and by step name.
|
|
54
|
-
-- PickedQL joins both `experiences` and `steps` for you.
|
|
55
|
-
SELECT experience_title, step_title, count(*)
|
|
56
|
-
FROM events
|
|
57
|
-
WHERE project_id = 'your-project-id'
|
|
58
|
-
GROUP BY experience_title, step_title
|
|
59
|
-
```
|
|
60
|
-
|
|
61
|
-
An automatic join also works inside a subquery and inside a common table expression.
|
|
62
|
-
Point at a dimension column where you need it, and PickedQL adds the `LEFT JOIN` at
|
|
63
|
-
that level:
|
|
64
|
-
|
|
65
|
-
```sql
|
|
66
|
-
-- Dimension columns inside a common table expression.
|
|
67
|
-
WITH per_step AS (
|
|
68
|
-
SELECT step_title, count(*) AS n
|
|
69
|
-
FROM events
|
|
70
|
-
WHERE project_id = 'your-project-id'
|
|
71
|
-
GROUP BY step_title
|
|
72
|
-
)
|
|
73
|
-
SELECT * FROM per_step ORDER BY n DESC
|
|
74
|
-
|
|
75
|
-
-- Dimension columns inside a nested query.
|
|
76
|
-
SELECT step_title, n FROM (
|
|
77
|
-
SELECT step_title, count(*) AS n FROM events
|
|
78
|
-
WHERE project_id = 'your-project-id'
|
|
79
|
-
GROUP BY step_title
|
|
80
|
-
) sub
|
|
81
|
-
```
|
|
82
|
-
|
|
83
|
-
## Native event columns
|
|
84
|
-
|
|
85
|
-
These columns are on `events` directly, and they need no join:
|
|
86
|
-
|
|
87
|
-
`event_type`, `interaction_type`, `experience_id`, `step_id`, `event_id`, `user_canonical_id`, `session_id`, `client_local_date`, `is_purchase`, `is_cart_add`, `event_meta`.
|
|
88
|
-
|
|
89
|
-
Two of them take a name from the SDK. A filter on a name that does not exist gives an
|
|
90
|
-
empty result set and not an error:
|
|
91
|
-
|
|
92
|
-
| Column | The values that it holds |
|
|
93
|
-
|---|---|
|
|
94
|
-
| `event_type` | The name of the event, such as `step_enter` or `cart_add`. [Analytics events](/reference/sdk/analytics-events) names every one, together with the name of each custom event of your own. |
|
|
95
|
-
| `interaction_type` | The label of the element behind the event. It falls back to `event_type` when the event has no element, so it is **not** the list of interaction types. [Analytics events](/reference/sdk/analytics-events) describes both. |
|
|
96
|
-
|
|
97
|
-
## Related
|
|
98
|
-
|
|
99
|
-
- [About PickedQL](/explanation/how-pickedql-works) — why you write no join.
|
|
100
|
-
- [Data sources](/reference/pickedql/data-sources)
|
|
101
|
-
- [Analytics events](/reference/sdk/analytics-events) — every `event_type` value, and the
|
|
102
|
-
contexts behind these columns.
|
|
103
|
-
- [Analytics queries](/how-to/analytics)
|