feat: Add experimental count relationships by filter to Materialize API

Author: josephschorr

authzed/api/materialize/v0/relationships.proto

@@ -0,0 +1,35 @@
+syntax = "proto3";
+package authzed.api.materialize.v0;
+
+import "buf/validate/validate.proto";
+import "validate/validate.proto";
+import "authzed/api/v1/core.proto";
+import "authzed/api/v1/permission_service.proto";
+
+option go_package = "github.com/authzed/authzed-go/proto/authzed/api/materialize/v0";
+option java_multiple_files = true;
+option java_package = "com.authzed.api.materialize.v0";
+
+service RelationshipsService {
+  // EXPERIMENTAL: CountRelationships returns the count of relationships for a given filter.
+  rpc ExperimentalCountRelationshipsByFilter(ExperimentalCountRelationshipsByFilterRequest) returns (ExperimentalCountRelationshipsByFilterResponse) {}
+}
+
+message ExperimentalCountRelationshipsByFilterRequest {
+    // relationship_filter specifies the filter to apply when counting relationships.
+    authzed.api.v1.RelationshipFilter relationship_filter = 1 [
+        (validate.rules).message.required = true,
+        (buf.validate.field).required = true
+    ];
+}
+
+message ExperimentalCountRelationshipsByFilterResponse {
+  // relationship_count is the count of relationships that match the filter.
+  uint64 relationship_count = 1;
+
+  // read_at is the ZedToken at which the relationship count applies.
+  authzed.api.v1.ZedToken read_at = 2 [
+    (validate.rules).message.required = true,
+    (buf.validate.field).required = true
+  ];
+}

docs/apidocs.swagger.json

@@ -1946,6 +1946,20 @@
         }
       }
     },
+    "ExperimentalCountRelationshipsByFilterResponse": {
+      "type": "object",
+      "properties": {
+        "relationshipCount": {
+          "type": "string",
+          "format": "uint64",
+          "description": "relationship_count is the count of relationships that match the filter."
+        },
+        "readAt": {
+          "$ref": "#/definitions/ZedToken",
+          "description": "read_at is the ZedToken at which the relationship count applies."
+        }
+      }
+    },
     "ExperimentalCountRelationshipsRequest": {
       "type": "object",
       "properties": {
@@ -3164,7 +3178,7 @@
         },
         "optionalTransactionMetadata": {
           "type": "object",
-          "description": "optional_transaction_metadata is an optional field that returns the transaction metadata\ngiven to SpiceDB during the transaction that produced the changes in this response.\nThis field may not exist if no transaction metadata was provided."
+          "description": "optional_transaction_metadata is an optional field that returns the transaction metadata\ngiven to SpiceDB during the transaction that produced the changes in this response.\nThis field may not exist if no transaction metadata was provided, or if multiple pieces\nof metadata were found during the transaction (in which case it is ambiguous which to return)."
         },
         "schemaUpdated": {
           "type": "boolean",
@@ -3173,6 +3187,13 @@
         "isCheckpoint": {
           "type": "boolean",
           "description": "is_checkpoint, if true, indicates that a checkpoint was reached.\nA checkpoint indicates that the server guarantees that the client\nwill not observe any changes at a revision below or equal to the revision in this response."
+        },
+        "fullRevisionMetadata": {
+          "type": "array",
+          "items": {
+            "type": "object"
+          },
+          "description": "full_revision_metadata contains all transaction metadata given to SpiceDB during the\nrevision that produced the changes in this response. Some datastores (such as CockroachDB)\ncan \"merge\" multiple transactions into a single revision (if the changes occurred concurrently),\nso this field is a list of all transaction metadata seen during the revision."
         }
       },
       "description": "WatchResponse contains all mutation events in ascending timestamp order.\nThis excludes relationships that were deleted because they expired.\nThe response includes a field that can be used to resume\nwatching from that point."