API Reference: Read

Read Requests provide the ability to retrieve sets of Tuples as provided by one or more filters. Read Requests are rarely used, as Expand Requests are almost always the desired behavior.

Read Requests are bulk operations that can issue multiple filters in one request. Filters are specified as a Tuple along with a list of fields. If a field is not present in the Filter list, its value will be ignored and that field will be treated as a wildcard.

gRPC Endpoint#

ACLServer.Expand

Request#

Parameters#

note

It is recommended to specify the at_revision Zookie value, which will return the namespace's configuration as of the logical timestamp represented by that Zookie.

NameTypeRequired
tuplesetsRelationTupleFilterYes
at_revisionZookieNo (but recommended)

Request Definition#

It is required that the corresponding Filter ID must be present in the Filters list if any of the follow fields are set:

  • object_id
  • relation
  • userset
message ReadRequest {
repeated RelationTupleFilter tuplesets = 1;
Zookie at_revision = 2;
}
message RelationTupleFilter {
enum Filter {
UNKNOWN = 0; OBJECT_ID = 1; RELATION = 2; USERSET = 4;
}
string namespace = 1;
string object_id = 2;
string relation = 3;
ObjectAndRelation userset = 5;
repeated Filter filters = 6;
}
Additional Protocol Buffer definitions used
message ObjectAndRelation {
string namespace = 1;
string object_id = 2;
string relation = 3;
}
message Zookie { string token = 1; }

Request Example#

Read all the direct relationships for my note taking app's user 2112:

{
tuplesets: [
{
namespace: "mynotetakingapp/note"
userset: {
namespace: "mynotetakingapp/user"
object_id: "2112"
relation: "..."
}
filters: [ 4 ]
}
]
at_revision: { token: "CAESAggB" }
}

Response#

Response Definition#

message ReadResponse {
message Tupleset { repeated RelationTuple tuples = 1; }
repeated Tupleset tuplesets = 1;
Zookie revision = 2;
}
Additional Protocol Buffer definitions used
message RelationTuple {
ObjectAndRelation object_and_relation = 1;
User user = 2;
}
message ObjectAndRelation {
string namespace = 1;
string object_id = 2;
string relation = 3;
}
message User {
oneof user_oneof {
uint64 user_id = 1;
ObjectAndRelation userset = 2;
}
}
message Zookie { string token = 1; }

Response Example#

{
tuplesets {
tuples {
object_and_relation {
namespace: "mynotetakingapp/note"
object_id: "2112"
relation: "editor"
}
user {
userset {
namespace: "mynotetakingapp/user"
object_id: "213"
relation: "..."
}
}
}
tuples {
object_and_relation {
namespace: "mynotetakingapp/note"
object_id: "2112"
relation: "viewer"
}
user {
userset {
namespace: "mynotetakingapp/user"
object_id: "539"
relation: "..."
}
}
}
}
revision { token: "CAESAggG" }
}

Errors#

  • INVALID_ARGUMENT: a provided value has failed to semantically validate
  • FAILED_PRECONDITION: a specified namespace or relation does not exist
  • OUT_OF_RANGE: the specified zookie is too old to be used

For more generic failures, see the gRPC Status Code documentation.

Code Samples#

Code Sample Parameter Values
Parameter NameValueDescription
Tenant SlugThe slug for your tenant
TokenYour token
NamespaceThe namespace of the Tuples that will be read.
User namespaceThe namespace for users in your Tenant
User IDThe ID of the user that will filter Tuples.
ZookieThe opaque token that signifies a read should be as fresh as the write that produced this token.
grpcurl -rpc-header "authorization: Bearer t_my_token" -d \
'{
"tuplesets": [
{
"namespace": "someslug/mynamespace",
"userset": {
"namespace": "someslug/user",
"object_id": "someuserid",
"relation": "..."
},
"filters": [ 4 ]
}
],
"at_revision": { "token": "someopaquevalue" }
}' \
grpc.authzed.com:443 ACLService/Read