feat: new page (querying data)

Author: miparnisari

app/spicedb/concepts/_meta.ts

@@ -4,6 +4,7 @@ export default {
   relationships: "Writing Relationships",
   caveats: "Writing Relationships with Caveats",
   "expiring-relationships": "Writing Relationships that Expire",
+  "querying-data": "Querying Data",
   commands: "SpiceDB Commands & Parameters",
   consistency: "Consistency",
   datastores: "Datastores",

app/spicedb/concepts/querying-data/page.mdx

@@ -0,0 +1,46 @@
+import { Callout } from "nextra/components";
+import { InlinePlayground } from "@/components/playground";
+
+# Querying Data
+
+This page walks through the main ways to query data in SpiceDB. The options are listed from most preferred to least preferred, but the right choice always depends on your use case.
+
+<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>
+
+## CheckPermissions
+
+[`CheckPermissions`](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 fast, cached, and designed for high-traffic workloads.
+
+You can debug a check locally with `zed permission check resource:someresource somepermission user:someuser --explain` to see how the decision was made.
+
+When your schema uses 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:maria`) or a set of users (e.g. `group:engineering#member`).
+
+For read-your-writes behavior, you should pass a `consistency` parameter to the query. Use either `fully_consistent` or `at_least_as_fresh(revision)` depending on how strict you need to be.
+
+## CheckBulkPermissions
+
+[`CheckBulkPermissions`](https://buf.build/authzed/api/docs/main:authzed.api.v1#authzed.api.v1.PermissionsService.CheckBulkPermissions) is great for UI workloads where you need to check multiple permissions at once: think tables, lists, and dashboards.
+
+## LookupResources
+
+[`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 pagination and works well for moderate result sizes.
+
+If you’re expecting more than ~1,000 results, this isn't ideal. At that point you'll get better performance and cost efficiency from our [Materialize] offering.
+
+[Materialize]: /authzed/concepts/authzed-materialize
+
+## LookupSubjects
+
+[`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’s handy, but it does not support pagination.
+
+Same guidance applies as above: if you’re going to cross the ~1,000-result mark, you’ll want Materialize instead.
+
+## ReadRelationships
+
+[`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.

app/spicedb/getting-started/first-steps/page.mdx

@@ -22,9 +22,9 @@ import { InlinePlayground } from "@/components/playground";
     We've documented the concepts SpiceDB users should understand:
 
     <Cards>
-        <Cards.Card arrow={true} title="Zanzibar" href="../concepts/zanzibar" />
         <Cards.Card arrow={true} title="Writing a Schema" href="../concepts/schema" />
         <Cards.Card arrow={true} title="Writing Relationships" href="../concepts/relationships" />
+        <Cards.Card arrow={true} title="Querying Data" href="../concepts/querying-data" />
     </Cards>
 
     After these, we recommend these concepts for running SpiceDB: