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
Copy file name to clipboardExpand all lines: app/spicedb/concepts/querying-data/page.mdx
+95-10Lines changed: 95 additions & 10 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,7 +2,7 @@ import { Callout } from "nextra/components";
2
2
3
3
# Querying Data
4
4
5
-
This page walks through the main ways to query data in SpiceDB. The options are listed from most preferred to least preferred in terms of performance, but the right choice always depends on your use case.
5
+
This page walks through the main ways to query data in SpiceDB. The options are listed roughly in the order of how often you should be calling them, and roughly in order of their expected performance. Choose the one that makes sense for your use case, but consider whether your use case actually requires the call you're looking at.
6
6
7
7
<Callouttype="info">
8
8
In most of the APIs below, if you want to be able to read your write, you can
@@ -19,6 +19,18 @@ This page walks through the main ways to query data in SpiceDB. The options are
19
19
20
20
## Check Permission
21
21
22
+
Send:
23
+
24
+
- Subject Type
25
+
- Subject ID
26
+
- Permission (or relation)
27
+
- Object Type
28
+
- Object ID
29
+
30
+
Receive:
31
+
32
+
- Yes/no (or a provisional response if missing caveat data)
33
+
22
34
[`CheckPermission`](https://buf.build/authzed/api/docs/main:authzed.api.v1#authzed.api.v1.PermissionsService.CheckPermission) is the go-to for most access checks. It’s designed for high-traffic workloads.
23
35
24
36
You can debug a check locally with `zed permission check resource:someresource somepermission user:someuser --explain` to understand how the decision was made.
@@ -29,21 +41,69 @@ The `subject` of the query can be a single user (e.g. `user:someuser`) or a set
29
41
30
42
### CheckBulkPermissions
31
43
44
+
Send Many:
45
+
46
+
- Subject Type
47
+
- Subject ID
48
+
- Permission (or relation)
49
+
- Object Type
50
+
- Object ID
51
+
52
+
Receive Many:
53
+
54
+
- Yes/no (or a provisional response if missing caveat data)
55
+
32
56
If your app needs to do multiple checks (for example, for various subjects), use the [`CheckBulkPermissions`](https://buf.build/authzed/api/docs/main:authzed.api.v1#authzed.api.v1.PermissionsService.CheckBulkPermissions) API. It's great for UI workloads where you need to check multiple permissions at once: think tables, lists, and dashboards.
33
57
58
+
It's also the recommended way to ask "what permissions does a given subject have on a resource?"
59
+
Make a check for each permission in your schema. This will require you to update calling code when you add permissions,
60
+
but the consuming code will need to be changed to include the logic associated with the new permission in any case.
61
+
34
62
It's always preferable to perform one call to `CheckBulkPermissions` with N checks than N calls to `CheckPermission`, unless you don't want to wait for the N checks to finish.
35
63
36
64
## LookupResources
37
65
38
-
[`LookupResources`](https://buf.build/authzed/api/docs/main:authzed.api.v1#authzed.api.v1.PermissionsService.LookupResources) is a good choice when you need to find all resources of a given type that a specific subject can access. It supports cursoring and works well for moderate result sizes.
66
+
Send Many:
67
+
68
+
- Subject Type
69
+
- Subject ID
70
+
- Permission (or relation)
71
+
- Object Type
72
+
73
+
Receive many:
39
74
40
-
If you’re expecting more than ~10,000 results, this isn't ideal. See [this](../modeling/protecting-a-list-endpoint#checking-with-checkbulkpermissions) for more details.
[`LookupResources`](https://buf.build/authzed/api/docs/main:authzed.api.v1#authzed.api.v1.PermissionsService.LookupResources) is a good choice when you need to find all resources of a given type that a specific subject can access. It supports cursoring and works well for moderate result sizes.
78
+
79
+
It's a good way to do [prefiltering of results](/spicedb/modeling/protecting-a-list-endpoint#filtering-with-lookupresources) in
80
+
a List endpoint, but it's a heavy request that can cause performance problems when more than 10k results are involved.
81
+
In that case we recommend postfiltering with [CheckBulk](#checkbulkpermissions), and if that still doesn't work,
82
+
we recommend evaluating [Materialize](/authzed/concepts/authzed-materialize).
43
83
44
84
## LookupSubjects
45
85
46
-
[`LookupSubjects`](https://buf.build/authzed/api/docs/main:authzed.api.v1#authzed.api.v1.PermissionsService.LookupSubjects) returns all subjects that have access to a specific resource. It does not support cursoring, and the response includes a list of objects that have been explicitly excluded.
Then `LookupSubjects` for `document:finance` will return a response of the form `{user:* - [user:anne,user:bob]}`.
69
129
70
-
If you are looking to find all the subjects that are on a specific relation, use `ReadRelationships` instead of `LookupSubjects`.
71
-
72
130
## ReadRelationships
73
131
74
-
[`ReadRelationships`](https://buf.build/authzed/api/docs/main:authzed.api.v1#authzed.api.v1.PermissionsService.ReadRelationships) should be your last resort. It's slower, it doesn't populate or use the permissions cache, and it won't evaluate caveats. Use it only when you truly need raw relationship data and none of the higher-level APIs fit the job.
132
+
[`ReadRelationships`](https://buf.build/authzed/api/docs/main:authzed.api.v1#authzed.api.v1.PermissionsService.ReadRelationships) is intended a an escape hatch,
133
+
and should only be considered if no other API matches your use case.
134
+
135
+
It's considerably more flexible in that you can send any combination of:
136
+
137
+
- Subject Type
138
+
- Subject ID
139
+
- Permission (or relation)
140
+
- Object Type
141
+
- Object ID
142
+
143
+
And receive all relationships that match that filter, but it comes with some important caveats:
144
+
145
+
- It's generally less optimized than the `Check` and `Lookup` APIs because of that flexibility
146
+
- It does no caching. The `Check` and `Lookup` APIs gain much of their performance by caching the results of subproblem computation; `ReadRelationships` does no caching and will go directly to the database every time.
147
+
- The indexes in the backing [datastores](/spicedb/concepts/datastores) are optimized around the `Check` and `Lookup` APIs, so it's possible to
148
+
craft a `ReadRelationships` request that misses indexes and requires a full table scan. This is because covering all combinations of filters
149
+
with an index would impact write performance too much.
150
+
151
+
Some use cases where `ReadRelationships` may be warranted:
152
+
153
+
- Deleting all relationships in a subtree, where a simple [RelationshipFilter](https://buf.build/authzed/api/docs/main:authzed.api.v1#authzed.api.v1.RelationshipFilter) in a [DeleteRelationships](https://buf.build/authzed/api/docs/main:authzed.api.v1#authzed.api.v1.DeleteRelationshipsRequest) would be insufficient
154
+
- Admin UIs that show lists of roles or relationships between objects
75
155
76
156
## Watch
77
157
78
-
The Watch API is not meant to answer permission questions but to serve other use-cases, like auditing. See [this](watch) for more details.
158
+
The Watch API is not meant to answer permission questions but to serve other use-cases, like auditing. See [the Watch API documentation](/spicedb/concepts/watch) for more details.
79
159
80
160
## ExpandPermissionTree
81
161
82
-
This [ExpandPermissionTree](https://buf.build/authzed/api/docs/main:authzed.api.v1#authzed.api.v1.PermissionsService.ExpandPermissionTree) API is useful in scenarios where your UI needs to show which users _and groups_ have access to something.
162
+
This [ExpandPermissionTree](https://buf.build/authzed/api/docs/main:authzed.api.v1#authzed.api.v1.PermissionsService.ExpandPermissionTree) API
163
+
comes from the [Zanzibar Paper](https://authzed.com/zanzibar#2.4.5-expand). It allows you to examine the subtree of relationships
164
+
around a particular point in the graph, and is useful in scenarios like your UI needing to show which users _and groups_ have access to something.
165
+
166
+
In practice we don't see many uses of this API, especially because it only resolves one "hop" in the graph at a time and must be called
## How do I get all of the permissions a subject has on a resource?
64
+
65
+
There isn't an API that answers this question directly. Instead, you should use the
66
+
[`CheckBulkPermissions`](https://buf.build/authzed/api/docs/main:authzed.api.v1#authzed.api.v1.PermissionsService.CheckBulkPermissions) API and send a check for each of the permissions you want to check.
67
+
68
+
It means that you'll need to update your permission checks when you add a new permission, but you'd need to update the calling code
69
+
to handle the concept that a new permission represents anyway.
0 commit comments