chore: updating the types of valid read calls someone can make (#988)

Author: tylernix

docs/content/interacting/relationship-queries.mdx

@@ -198,13 +198,34 @@ The [Read API](/api/service#Relationship%20Tuples/Read) is an API endpoint that
 
 Read can be called if you need to get all the stored relationship tuples that relate:
 
-1. [a particular user to any objects of a specific type with a particular relation](#1-a-particular-user-to-any-objects-of-a-specific-type-with-a-particular-relation)
-2. [a particular user to any objects of a specific type with any relation](#2-a-particular-user-to-any-objects-of-a-specific-type-with-any-relation)
-3. [a particular object to any user with a particular relation](#3-a-particular-object-to-any-user-with-a-particular-relation)
+1. [**user + relation + object**](#1-read-a-tuple-related-to-a-particular-user-relation-and-object)
+2. [**user + relation + object type**](#2-read-all-tuples-related-to-a-particular-user-relation-and-object-type)
+3. [**user + object** with any relation](#3-read-all-tuples-related-to-a-particular-user-and-object-with-any-relation)
+4. [**user + object type** with any relation](#4-read-all-tuples-related-to-a-particular-user-and-object-type-with-any-relation)
+5. [**relation + object** for any user](#5-read-all-tuples-related-to-a-particular-relation-and-object-for-any-user)
+6. [**object** with any user and relation](#6-read-all-tuples-related-to-a-particular-object-with-any-user-or-relation)
+7. [**all** with any user, relation, or object](#7-read-all-tuples-for-any-user-relation-or-object)
 
-#### 1. A particular user to any objects of a specific type with a particular relation
+#### 1. Read a tuple related to a particular user, relation, and object
 
-For example, to query all the stored relationship tuples `bob` has a `writer` relationship with, one can ask
+For example, to query if `bob` has a `writer` relationship on `document:planning` (essentially finding out if a tuple exists), one can ask
+
+<ReadRequestViewer
+  user={'user:bob'}
+  relation={'writer'}
+  object={'document:planning'}
+  tuples={[
+    {
+      user: 'user:bob',
+      relation: 'writer',
+      object: 'document:planning',
+    },
+  ]}
+/>
+
+#### 2. Read all tuples related to a particular user, relation, and object type
+
+For example, to query all the stored relationship tuples `bob` has a `writer` relationship with on type `document:`, one can ask
 
 <ReadRequestViewer
   user={'user:bob'}
@@ -219,9 +240,25 @@ For example, to query all the stored relationship tuples `bob` has a `writer` re
   ]}
 />
 
-#### 2. A particular user to any objects of a specific type with any relation
+#### 3. Read all tuples related to a particular user and object with any relation
+
+For example, to query all the stored relationship tuples `bob` has on type `document:planning`, one can ask
+
+<ReadRequestViewer
+  user={'user:bob'}
+  object={'document:planning'}
+  tuples={[
+    {
+      user: 'user:bob',
+      relation: 'writer',
+      object: 'document:planning',
+    },
+  ]}
+/>
+
+#### 4. Read all tuples related to a particular user and object type with any relation
 
-For example, to query all the stored relationship tuples in which `bob` is related to objects of type `document` as any relation, one can issue the following call:
+For example, to query all the stored relationship tuples `bob` has on object type `document:`, one can ask
 
 <ReadRequestViewer
   user={'user:bob'}
@@ -235,9 +272,9 @@ For example, to query all the stored relationship tuples in which `bob` is relat
   ]}
 />
 
-#### 3. A particular object to any user with a particular relation
+#### 5. Read all tuples related to a particular relation and object for any user
 
-For example, to query all the stored relationship tuples in which any user is related to `document:planning` as a `writer`, one can issue the following call:
+For example, to query all the stored relationship tuples which have the `writer` relation on object `document:planning`, one can ask
 
 <ReadRequestViewer
   relation={'writer'}
@@ -251,6 +288,35 @@ For example, to query all the stored relationship tuples in which any user is re
   ]}
 />
 
+#### 6. Read all tuples related to a particular object with any user or relation
+
+For example, to query all the stored relationship tuples for object `document:planning`, one can ask
+
+<ReadRequestViewer
+  object={'document:planning'}
+  tuples={[
+    {
+      user: 'user:bob',
+      relation: 'writer',
+      object: 'document:planning',
+    },
+  ]}
+/>
+
+#### 7. Read all tuples for any user, relation, or object
+
+For example, to query all stored relationship tuples, one can ask
+
+<ReadRequestViewer
+  tuples={[
+    {
+      user: 'user:bob',
+      relation: 'writer',
+      object: 'document:planning',
+    },
+  ]}
+/>
+
 ### Caveats and when not to use it
 
 The Read API will only return all the stored relationships that match the query specification.