From 46961aa366f46f0c42d8bfb64073b8a27d54d51f Mon Sep 17 00:00:00 2001
From: Marion Schleifer <marion@hasura.io>
Date: Thu, 8 Oct 2020 12:24:14 +0200
Subject: [PATCH] add cli and api workflow

---
 .../core/schema/table-relationships/track.rst | 103 +++++++++++++++++-
 1 file changed, 100 insertions(+), 3 deletions(-)

diff --git a/docs/graphql/core/schema/table-relationships/track.rst b/docs/graphql/core/schema/table-relationships/track.rst
index 619ff97facd47..3c14637331993 100644
--- a/docs/graphql/core/schema/table-relationships/track.rst
+++ b/docs/graphql/core/schema/table-relationships/track.rst
@@ -16,10 +16,12 @@ Introduction
 ------------
 
 It is possible to have relationships in your underlying database without having them tracked and exposed over the GraphQL API. 
-For example, this can be the case when you import a database schema into Hasura. This page explains how to track relationships.
+For example, this can be the case when you import a database schema into Hasura. This page explains how to track relationships and therefore expose them over the GraphQL API.
 
-Tracking a relationship
------------------------
+.. _track_single_relationships:
+
+Tracking a single relationship
+------------------------------
 
 Assuming the relevant tables are tracked, but not the relationships, a single relationship can be tracked as follows:
 
@@ -36,8 +38,97 @@ Assuming the relevant tables are tracked, but not the relationships, a single re
 
   .. tab:: CLI
 
+    You can track relationships in the ``tables.yaml`` file inside the ``metadata`` directory:
+
+    **Object relationship**
+
+    .. code-block:: yaml
+       :emphasize-lines: 4-7
+
+        - table:
+            schema: public
+            name: article
+          object_relationships:
+          - name: author
+            using:
+              foreign_key_constraint_on: author_id
+        - table:
+            schema: public
+            name: author
+
+    **Array relationship**
+
+    .. code-block:: yaml
+      :emphasize-lines: 11-18
+
+        - table:
+            schema: public
+            name: article
+          object_relationships:
+          - name: author
+            using:
+              foreign_key_constraint_on: author_id
+        - table:
+            schema: public
+            name: author
+          array_relationships:
+          - name: articles
+            using:
+              foreign_key_constraint_on:
+                column: author_id
+                table:
+                  schema: public
+                  name: article
+
+    Apply the metadata by running:
+
+    .. code-block:: bash
+
+      hasura metadata apply
+
   .. tab:: API
 
+    You can track an object relationship by using the :ref:`create_object_relationship metadata API <create_object_relationship>`:
+
+    .. code-block:: http
+
+      POST /v1/query HTTP/1.1
+      Content-Type: application/json
+      X-Hasura-Role: admin
+
+      {
+        "type": "create_object_relationship",
+        "args": {
+          "table": "article",
+          "name": "author",
+          "using": {
+            "foreign_key_constraint_on": "author_id"
+          }
+        }
+      }
+
+    You can track an array relationship by using the :ref:`create_array_relationship metadata API <create_array_relationship>`:
+
+    .. code-block:: http
+
+      POST /v1/query HTTP/1.1
+      Content-Type: application/json
+      X-Hasura-Role: admin
+
+      {
+        "type": "create_array_relationship",
+        "args": {
+          "table": "author",
+          "name": "articles",
+          "using": {
+            "foreign_key_constraint_on" : {
+              "table" : "article",
+              "column" : "author_id"
+            }
+          }
+        }
+      }
+
 Tracking all relationships
 --------------------------
 
@@ -56,4 +147,10 @@ Assuming the relevant tables are tracked, but not the relationships, all availab
 
   .. tab:: CLI
 
+    When working with the CLI, all relationships must be added manually, as described in the :ref:`previous section <track_single_relationships>`.
+    You can use a script to automate this process.
+
   .. tab:: API
+
+    When working with the API, all relationships must be added manually, as described in the :ref:`previous section <track_single_relationships>`.
+    You can use a script to automate this process.