-
Notifications
You must be signed in to change notification settings - Fork 46
feat: new page (querying data) #451
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
6 commits
Select commit
Hold shift + click to select a range
195b866
feat: new page (querying data)
miparnisari 77a072d
Update app/spicedb/concepts/querying-data/page.mdx
sohanmaheshwar 1af9367
address feedback
miparnisari aa56e26
moar changes
miparnisari 7f304e3
update protecting a list endpoint
miparnisari 49113bb
Make some edits
tstirrat15 File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,167 @@ | ||
| import { Callout } from "nextra/components"; | ||
|
|
||
| # Querying Data | ||
|
|
||
| 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. | ||
|
|
||
| <Callout type="info"> | ||
| In most of the APIs below, if you want to be able to read your write, you can | ||
| pass a `consistency` parameter to the queries. Use either `fully_consistent` | ||
| or `at_least_as_fresh(revision)` depending on how strict you need to be. See | ||
| [Consistency](consistency) for more details. | ||
| </Callout> | ||
|
|
||
| <Callout type="important"> | ||
| When invoking any of our APIs, you can send a header `X-Request-ID=somevalue` | ||
| and it will be echoed back in the response, which makes correlating logs or | ||
| tracing requests easy. | ||
| </Callout> | ||
|
|
||
| ## Check Permission | ||
|
|
||
| Send: | ||
|
|
||
| - Subject Type | ||
| - Subject ID | ||
| - Permission (or relation) | ||
| - Object Type | ||
| - Object ID | ||
|
|
||
| Receive: | ||
|
|
||
| - Yes/no (or a provisional response if missing caveat data) | ||
|
|
||
| [`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. | ||
|
|
||
| You can debug a check locally with `zed permission check resource:someresource somepermission user:someuser --explain` to understand how the decision was made. | ||
|
|
||
| When your schema uses [caveats](caveats) and you don't provide all the required context in the request parameters, the API will tell you that in the response that the result is "conditional" instead of simply denying or allowing, and it's up to you to inspect that result. | ||
|
|
||
| The `subject` of the query can be a single user (e.g. `user:someuser`) or a set of users (e.g. `group:engineering#member`). | ||
|
|
||
| ### CheckBulkPermissions | ||
|
|
||
| Send Many: | ||
|
|
||
| - Subject Type | ||
| - Subject ID | ||
| - Permission (or relation) | ||
| - Object Type | ||
| - Object ID | ||
|
|
||
| Receive Many: | ||
|
|
||
| - Yes/no (or a provisional response if missing caveat data) | ||
|
|
||
| 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. | ||
|
|
||
| It's also the recommended way to ask "what permissions does a given subject have on a resource?" | ||
| Make a check for each permission in your schema. This will require you to update calling code when you add permissions, | ||
| but the consuming code will need to be changed to include the logic associated with the new permission in any case. | ||
|
|
||
| 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. | ||
|
|
||
| ## LookupResources | ||
|
|
||
| Send Many: | ||
|
|
||
| - Subject Type | ||
| - Subject ID | ||
| - Permission (or relation) | ||
| - Object Type | ||
|
|
||
| Receive many: | ||
|
|
||
| - Object ID | ||
|
|
||
| [`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. | ||
|
|
||
| It's a good way to do [prefiltering of results](/spicedb/modeling/protecting-a-list-endpoint#filtering-with-lookupresources) in | ||
| a List endpoint, but it's a heavy request that can cause performance problems when more than 10k results are involved. | ||
| In that case we recommend postfiltering with [CheckBulk](#checkbulkpermissions), and if that still doesn't work, | ||
| we recommend evaluating [Materialize](/authzed/concepts/authzed-materialize). | ||
|
|
||
| ## LookupSubjects | ||
|
|
||
| Send Many: | ||
|
|
||
| - Subject Type | ||
| - Permission (or relation) | ||
| - Object Type | ||
| - Object ID | ||
|
|
||
| Receive many: | ||
|
|
||
| - Subject ID | ||
|
|
||
| [`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. | ||
|
|
||
| It's commonly used to drive UIs and APIs that list users with given permission or set of permissions, such as a table of Admins | ||
| on a particular Organization. | ||
|
|
||
| Note that LookupSubjects will do a full path walk between an object and a subject, and will consider all valid paths between object and subject. | ||
| If you are looking to find all the subjects that are on a specific relation, use `ReadRelationships` instead of `LookupSubjects`. | ||
|
|
||
| If your schema includes exclusions and wildcards, the response can include a list of subjects that have been explicitly excluded. | ||
|
|
||
| For example, if the schema is | ||
|
|
||
| ```zed | ||
| definition user {} | ||
|
|
||
| definition document { | ||
| relation blocked: user | ||
| relation view: user:* | ||
| permission viewer = view - blocked | ||
| } | ||
| ``` | ||
|
|
||
| and the relationships are | ||
|
|
||
| ```relationship filename="Relationships" | ||
| document:finance#view@user:* | ||
| document:finance#blocked@user:anne | ||
| document:finance#blocked@user:bob | ||
| ``` | ||
|
|
||
| Then `LookupSubjects` for `document:finance` will return a response of the form `{user:* - [user:anne,user:bob]}`. | ||
|
|
||
| ## ReadRelationships | ||
|
|
||
| [`ReadRelationships`](https://buf.build/authzed/api/docs/main:authzed.api.v1#authzed.api.v1.PermissionsService.ReadRelationships) is intended a an escape hatch, | ||
| and should only be considered if no other API matches your use case. | ||
|
|
||
| It's considerably more flexible in that you can send any combination of: | ||
|
|
||
| - Subject Type | ||
| - Subject ID | ||
| - Permission (or relation) | ||
| - Object Type | ||
| - Object ID | ||
|
|
||
| And receive all relationships that match that filter, but it comes with some important caveats: | ||
|
|
||
| - It's generally less optimized than the `Check` and `Lookup` APIs because of that flexibility | ||
| - 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. | ||
| - The indexes in the backing [datastores](/spicedb/concepts/datastores) are optimized around the `Check` and `Lookup` APIs, so it's possible to | ||
| craft a `ReadRelationships` request that misses indexes and requires a full table scan. This is because covering all combinations of filters | ||
| with an index would impact write performance too much. | ||
|
|
||
| Some use cases where `ReadRelationships` may be warranted: | ||
|
|
||
| - 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 | ||
| - Admin UIs that show lists of roles or relationships between objects | ||
|
|
||
| ## Watch | ||
|
|
||
| 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. | ||
|
|
||
| ## ExpandPermissionTree | ||
|
|
||
| This [ExpandPermissionTree](https://buf.build/authzed/api/docs/main:authzed.api.v1#authzed.api.v1.PermissionsService.ExpandPermissionTree) API | ||
| comes from the [Zanzibar Paper](https://authzed.com/zanzibar#2.4.5-expand). It allows you to examine the subtree of relationships | ||
| 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. | ||
|
|
||
| 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 | ||
| repeatedly to get a full picture of a subtree. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
provisional or conditional?