Merge pull request #123 from authzed/update-import-bulk-documentation

Update documentation of BulkImportRelationshipsRequest

authzed/api/v1/experimental_service.proto

@@ -222,9 +222,10 @@ message BulkCheckPermissionResponseItem {
 // BulkImportRelationshipsRequest represents one batch of the streaming
 // BulkImportRelationships API. The maximum size is only limited by the backing
 // datastore, and optimal size should be determined by the calling client
-// experimentally. Any relationships within the same request are guaranteed to
-// be written in a single transaction. If any of the relationships already
-// exist, the transaction will fail and no relationships will be written.
+// experimentally. When BulkImport is invoked and receives its first request message,
+// a transaction is opened to import the relationships. All requests sent to the same
+// invocation are executed under this single transaction. If a relationship already
+// exists within the datastore, the entire transaction will fail with an error.
 message BulkImportRelationshipsRequest {
   repeated Relationship relationships = 1
       [ (validate.rules).repeated .items.message.required = true ];

authzed/api/v1/permission_service.proto

@@ -670,7 +670,10 @@ message ResolvedSubject {
 // ImportBulkRelationshipsRequest represents one batch of the streaming
 // ImportBulkRelationships API. The maximum size is only limited by the backing
 // datastore, and optimal size should be determined by the calling client
-// experimentally.
+// experimentally. When ImportBulk is invoked and receives its first request message,
+// a transaction is opened to import the relationships. All requests sent to the same
+// invocation are executed under this single transaction. If a relationship already
+// exists within the datastore, the entire transaction will fail with an error.
 message ImportBulkRelationshipsRequest {
   repeated Relationship relationships = 1
       [ (validate.rules).repeated .items.message.required = true ];