From 9470a183ff9d9da560bf462d3c00b01e93d263cf Mon Sep 17 00:00:00 2001
From: Gavin Mendel-Gleason <gavin@terminusdb.com>
Date: Thu, 19 Jan 2023 00:16:59 +0100
Subject: [PATCH 1/2] Adding GraphQL back links and paths

---
 .../graphql-reference/graphql_query.md        | 100 +++++++++++++++++-
 1 file changed, 99 insertions(+), 1 deletion(-)

diff --git a/guides/reference-guides/graphql-reference/graphql_query.md b/guides/reference-guides/graphql-reference/graphql_query.md
index ef33930f..0f9883df 100644
--- a/guides/reference-guides/graphql-reference/graphql_query.md
+++ b/guides/reference-guides/graphql-reference/graphql_query.md
@@ -3,8 +3,8 @@
 GraphQL queries are composed of:
 
 * Queries
-* Fields
 * Arguments
+* Fields
 
 Each Class in TerminusDB automatically generates a top-level Query. Each property of the class automatically generates both arguments and fields.
 
@@ -360,3 +360,101 @@ query {
    }
 }
 ```
+
+## Fields
+
+Each TerminusDB class has associated with it, some number of
+fields. These fields include each field which is defined on the class.
+
+For instance, given the TerminusDB class:
+
+```json
+{ "@type" : "Class",
+  "@id" : "Person",
+  "name" : "xsd:string",
+  "dob" : "xsd:dateTime",
+  "friend" : {"@type" : "Set", "@class" : "Person" }}
+```
+
+We have a query field for each of `name`, `dob` and `friend`. However
+we also have the following specially defined fields:
+
+### `_id`
+
+This returns the fully qualified URI of the given instance of the
+`Person` class being returned.
+
+### `_type`
+
+This returns the class at which this instance is instantiated. This is
+useful when a super-class is queried, as we can obtain what concrete
+subclass it corresponds to.
+
+### Backlinks: `_PROPERTY_of_CLASS`
+
+The *backlink* is a way to find all instances which *point* to a given
+class. The backlink is generated automatically for every edge which
+terminates at the current class.
+
+For example, with the Person class:
+
+```json
+{ "@type" : "Class",
+  "@id" : "Person",
+  "name" : "xsd:string",
+  "dob" : "xsd:dateTime",
+  "friend" : {"@type" : "Set", "@class" : "Person" }}
+```
+
+We automatically get the backlink `_friend_of_Person` which says which
+people view us as their friends.
+
+For instance, we can construct the following query:
+
+```graphql
+{
+  Person{
+    name
+    _friend_of_Person{
+      name
+    }
+  }
+}
+```
+
+Which will find the name of every person who views the top level
+`Person` us as their friend (i.e. has a `friend` link to the current
+person).
+
+### Path Queries: `_path_to_CLASS`
+
+A path query allows us to use regular graph expressions to follow
+links from the current object to another object of class `CLASS`.
+
+Using the `Person` example:
+
+```json
+{ "@type" : "Class",
+  "@id" : "Person",
+  "name" : "xsd:string",
+  "dob" : "xsd:dateTime",
+  "friend" : {"@type" : "Set", "@class" : "Person" }}
+```
+
+We can find everyone within 2-degrees of separation with the following
+path query:
+
+```json
+{
+  Person{
+    name
+    _path_to_Person(path: "friend{1,3}"){
+      name
+    }
+  }
+}
+```
+
+See the [complete syntax for path
+queries](../../../guides/how-to-guides/query-data/path-queries.md) for
+more details on the semantics of the path argument.

From 2fa88a9d212fcc5915d3852fa21e04bf124c2c99 Mon Sep 17 00:00:00 2001
From: Oliver <88653154+OJ423@users.noreply.github.com>
Date: Thu, 19 Jan 2023 09:33:43 +0000
Subject: [PATCH 2/2] Grammar Updates

---
 .../graphql-reference/graphql_query.md                 | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/guides/reference-guides/graphql-reference/graphql_query.md b/guides/reference-guides/graphql-reference/graphql_query.md
index 0f9883df..c7428c31 100644
--- a/guides/reference-guides/graphql-reference/graphql_query.md
+++ b/guides/reference-guides/graphql-reference/graphql_query.md
@@ -364,7 +364,7 @@ query {
 ## Fields
 
 Each TerminusDB class has associated with it, some number of
-fields. These fields include each field which is defined on the class.
+fields. These fields include each field that is defined in the class.
 
 For instance, given the TerminusDB class:
 
@@ -392,7 +392,7 @@ subclass it corresponds to.
 
 ### Backlinks: `_PROPERTY_of_CLASS`
 
-The *backlink* is a way to find all instances which *point* to a given
+The *backlink* is a way to find all instances that *point* to a given
 class. The backlink is generated automatically for every edge which
 terminates at the current class.
 
@@ -406,7 +406,7 @@ For example, with the Person class:
   "friend" : {"@type" : "Set", "@class" : "Person" }}
 ```
 
-We automatically get the backlink `_friend_of_Person` which says which
+We automatically get the backlink `_friend_of_Person` that says which
 people view us as their friends.
 
 For instance, we can construct the following query:
@@ -422,14 +422,14 @@ For instance, we can construct the following query:
 }
 ```
 
-Which will find the name of every person who views the top level
+This will find the name of every person who views the top level
 `Person` us as their friend (i.e. has a `friend` link to the current
 person).
 
 ### Path Queries: `_path_to_CLASS`
 
 A path query allows us to use regular graph expressions to follow
-links from the current object to another object of class `CLASS`.
+links from the current object to another object of `CLASS`.
 
 Using the `Person` example: