Get stored relationship tuples
The Read API returns the tuples from a certain store that match a query filter specified in the body of the request.
The API doesn’t guarantee order by any field.
It is different from the /stores/{store_id}/expand API in that it only returns relationship tuples that are stored in the system and satisfy the query.
In the body:
tuple_keyis optional. If not specified, it returns all tuples in the store.tuple_key.objectis mandatory iftuple_keyis specified. It can be a full object (e.g.,type:object_id) or type only (e.g.,type:).tuple_key.useris mandatory if tuple_key is specified in the case thetuple_key.objectis a type only. If tuple_key.user is specified, it needs to be a full object (e.g.,type:user_id).
Examples
Query for all objects in a type definition
To query for all objects that user:bob has reader relationship in the document type definition, call read API with body of
{
"tuple_key": {
"user": "user:bob",
"relation": "reader",
"object": "document:"
}
}
The API returns tuples and a continuation token, similar to:
{
"tuples": [
{
"key": {
"user": "user:bob",
"relation": "reader",
"object": "document:2021-budget"
},
"timestamp": "2021-10-06T15:32:11.128Z"
}
],
"continuation_token": "eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ=="
}
This means that user:bob has a reader relationship with 1 document document:2021-budget. Note that this API, unlike the List Objects API, does not evaluate the tuples in the store.
The continuation token is empty if there are no more tuples to query.
Query for all stored relationship tuples that have a particular relation and object
To query for all users that have reader relationship with document:2021-budget, call read API with body of
{
"tuple_key": {
"object": "document:2021-budget",
"relation": "reader"
}
}
The API returns something similar to:
{
"tuples": [
{
"key": {
"user": "user:bob",
"relation": "reader",
"object": "document:2021-budget"
},
"timestamp": "2021-10-06T15:32:11.128Z"
}
],
"continuation_token": "eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ=="
}
This means that document:2021-budget has 1 reader (user:bob). Note that, even if the model said that all writers are also readers, the API does not return writers such as user:anne because it only returns tuples and does not evaluate them.
Query for all users with all relationships for a particular document
To query for all users that have any relationship with document:2021-budget, call read API with body of
{
"tuple_key": {
"object": "document:2021-budget"
}
}
The API returns something similar to:
{
"tuples": [
{
"key": {
"user": "user:anne",
"relation": "writer",
"object": "document:2021-budget"
},
"timestamp": "2021-10-05T13:42:12.356Z"
},
{
"key": {
"user": "user:bob",
"relation": "reader",
"object": "document:2021-budget"
},
"timestamp": "2021-10-06T15:32:11.128Z"
}
],
"continuation_token": "eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ=="
}
This means that document:2021-budget has 1 reader (user:bob) and 1 writer (user:anne).
Path Parameters
Body
Controls the consistency preference for this request. Default value is UNSPECIFIED, which has the same behavior as MINIMIZE_LATENCY.
UNSPECIFIED, MINIMIZE_LATENCY, HIGHER_CONSISTENCY "MINIMIZE_LATENCY"
"eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ=="
1 <= x <= 10050