feat(docs): Port GraphQL docs to v20.07

wiki/config.toml

@@ -1,17 +1,25 @@
+canonifyURLs = true
 languageCode = "en-us"
 theme = "hugo-docs"
-canonifyURLs = true
 
 [markup.goldmark.renderer]
 unsafe = true
 
 [markup.highlight]
-noClasses = false
+codeFences = true
+guessSyntax = false
+hl_Lines = ""
+lineNoStart = 1
+lineNos = false
+lineNumbersInTable = true
+noClasses = true
+style = "vs"
+tabWidth = 4
 
 [markup.tableOfContents]
-  endLevel = 3
-  ordered = false
-  startLevel = 2
+endLevel = 3
+ordered = false
+startLevel = 2
 
 # set by build script: title, baseurl
-title = "Dgraph Documentation"
+title = "Dgraph Documentation"

wiki/content/_index.md

@@ -10,13 +10,37 @@ title = "Dgraph Documentation"
 
 **Welcome to the official Dgraph documentation.**
 
-Dgraph is an open-source, scalable, distributed, highly available and fast graph database, designed from the ground up to be run in production.
+Designed from the ground up to be run in production, Dgraph is the native GraphQL database with a graph backend. It is open-source, scalable, distributed, highly available and lightning fast.
 
 ## Using Dgraph
 
 <section class="toc">
   <div class="container">
     <div class="row row-no-padding">
+      <div class="col-12 col-sm-6">
+        <div class="section-item">
+          <div class="section-name">
+            <a href="{{< relref "graphql/overview/index.md">}}">
+              GraphQL
+            </a>
+          </div>
+          <p class="section-desc">
+            Get Started with GraphQL 
+          </p>
+        </div>
+      </div>
+      <div class="col-12 col-sm-6">
+        <div class="section-item">
+          <div class="section-name">
+            <a href="{{< relref "slash-graphql/introduction.md">}}">
+              Slash GraphQL
+            </a>
+          </div>
+          <p class="section-desc">
+            Slash GraphQL Provides /graphql Backend for Your App
+          </p>
+        </div>
+      </div>
       <div class="col-12 col-sm-6">
         <div class="section-item">
           <div class="section-name">
@@ -157,18 +181,6 @@ Dgraph is an open-source, scalable, distributed, highly available and fast graph
 <section class="toc">
   <div class="container">
     <div class="row row-no-padding">
-      <div class="col-12 col-sm-6">
-        <div class="section-item">
-          <div class="section-name">
-            <a href="https://slack.dgraph.io">
-              Slack
-            </a>
-          </div>
-          <p class="section-desc">
-            Chat instantly to the Dgraph community and engineers.
-          </p>
-        </div>
-      </div>
       <div class="col-12 col-sm-6">
         <div class="section-item">
           <div class="section-name">

wiki/content/dql/_index.md

@@ -0,0 +1,7 @@
++++
+title = "DQL"
+[menu.main]
+  url = "/dql/"
+  identifier = "dql"
+  weight = 4
++++

wiki/content/get-started/index.md

@@ -5,6 +5,7 @@ aliases = ["/get-started-old"]
   url = "/get-started"
   name = "Get Started"
   identifier = "get-started"
+  parent = "dql"
   weight = 2
 +++
 

wiki/content/graphql/_index.md

@@ -0,0 +1,7 @@
++++
+title = "GraphQL"
+[menu.main]
+  url = "/graphql/"
+  identifier = "graphql"
+  weight = 3
++++

wiki/content/graphql/admin/index.md

@@ -0,0 +1,140 @@
++++
+title = "Admin"
+[menu.main]
+  url = "/graphql/admin/"
+  name = "Admin"
+  identifier = "graphql-admin"
+  parent = "graphql"
+  weight = 12
++++
+
+The admin API and how to run Dgraph with GraphQL.
+
+## Running
+
+The simplest way to start with Dgraph GraphQL is to run the all-in-one Docker image.
+
+```
+docker run -it -p 8080:8080 dgraph/standalone:master
+```
+
+That brings up GraphQL at `localhost:8080/graphql` and `localhost:8080/admin`, but is intended for quickstart and doesn't persist data.
+
+## Advanced Options
+
+Once you've tried out Dgraph GraphQL, you'll need to move past the `dgraph/standalone` and run and deploy Dgraph instances.
+
+Dgraph is a distributed graph database.  It can scale to huge data and shard that data across a cluster of Dgraph instances.  GraphQL is built into Dgraph in its Alpha nodes. To learn how to manage and deploy a Dgraph cluster to build an App check Dgraph's [Dgraph docs](https://docs.dgraph.io/), and, in particular, the [deployment guide](https://docs.dgraph.io/deploy/).
+
+GraphQL schema introspection is enabled by default, but can be disabled with the `--graphql_introspection=false` when starting the Dgraph alpha nodes.
+
+## Dgraph's schema
+
+Dgraph's GraphQL runs in Dgraph and presents a GraphQL schema where the queries and mutations are executed in the Dgraph cluster.  So the GraphQL schema is backed by Dgraph's schema.
+
+**Warning: this means if you have a Dgraph instance and change its GraphQL schema, the schema of the underlying Dgraph will also be changed!**
+
+## /admin
+
+When you start Dgraph with GraphQL, two GraphQL endpoints are served.
+
+At `/graphql` you'll find the GraphQL API for the types you've added.  That's what your app would access and is the GraphQL entry point to Dgraph.  If you need to know more about this, see the quick start, example and schema docs.
+
+At `/admin` you'll find an admin API for administering your GraphQL instance.  The admin API is a GraphQL API that serves POST and GET as well as compressed data, much like the `/graphql` endpoint.
+
+Here are the important types, queries, and mutations from the admin schema.
+
+```graphql
+type GQLSchema {
+	id: ID!
+	schema: String! 
+	generatedSchema: String!
+}
+
+type UpdateGQLSchemaPayload {
+	gqlSchema: GQLSchema
+}
+
+input UpdateGQLSchemaInput {
+	set: GQLSchemaPatch!
+}
+
+input GQLSchemaPatch {
+	schema: String!
+}
+
+type Query {
+	getGQLSchema: GQLSchema
+	health: Health
+}
+
+type Mutation {
+	updateGQLSchema(input: UpdateGQLSchemaInput!) : UpdateGQLSchemaPayload
+}
+```
+
+You'll notice that the /admin schema is very much the same as the schemas generated by Dgraph GraphQL.
+
+* The `health` query lets you know if everything is connected and if there's a schema currently being served at `/graphql`.
+* The `getGQLSchema` query gets the current GraphQL schema served at `/graphql`, or returns null if there's no such schema.
+* The `updateGQLSchema` mutation allows you to change the schema currently served at `/graphql`.
+
+## First Start
+
+On first starting with a blank database:
+
+* There's no schema served at `/graphql`.
+* Querying the `/admin` endpoint for `getGQLSchema` returns `"getGQLSchema": null`.
+* Querying the `/admin` endpoint for `health` lets you know that no schema has been added.
+
+## Adding Schema
+
+Given a blank database, running the `/admin` mutation:
+
+```graphql
+mutation {
+  updateGQLSchema(
+    input: { set: { schema: "type Person { name: String }"}})
+  {
+    gqlSchema {
+      schema
+      generatedSchema
+    }
+  }
+}
+```
+
+would cause the following.
+
+* The `/graphql` endpoint would refresh and now serves the GraphQL schema generated from type `type Person { name: String }`: that's Dgraph type `Person` and predicate `Person.name: string .`; see [here](/graphql/dgraph) for how to customize the generated schema.
+* The schema of the underlying Dgraph instance would be altered to allow for the new `Person` type and `name` predicate.
+* The `/admin` endpoint for `health` would return that a schema is being served.
+* The mutation returns `"schema": "type Person { name: String }"` and the generated GraphQL schema for `generatedSchema` (this is the schema served at `/graphql`).
+* Querying the `/admin` endpoint for `getGQLSchema` would return the new schema.
+
+## Migrating Schema
+
+Given an instance serving the schema from the previous section, running an `updateGQLSchema` mutation with the following input
+
+```graphql
+type Person {
+    name: String @search(by: [regexp])
+    dob: DateTime
+}
+```
+
+changes the GraphQL definition of `Person` and results in the following.
+
+* The `/graphql` endpoint would refresh and now serves the GraphQL schema generated from the new type.
+* The schema of the underlying Dgraph instance would be altered to allow for `dob` (predicate `Person.dob: datetime .` is added, and `Person.name` becomes `Person.name: string @index(regexp).`) and indexes are rebuilt to allow the regexp search.
+* The `health` is unchanged.
+* Querying the `/admin` endpoint for `getGQLSchema` now returns the updated schema.
+
+## Removing from Schema
+
+Adding a schema through GraphQL doesn't remove existing data (it would remove indexes).  For example, starting from the schema in the previous section and running `updateGQLSchema` with the initial `type Person { name: String }` would have the following effects.
+
+* The `/graphql` endpoint would refresh to serve the schema built from this type.
+* Thus field `dob` would no longer be accessible and there'd be no search available on `name`.
+* The search index on `name` in Dgraph would be removed.
+* The predicate `dob` in Dgraph is left untouched - the predicate remains and no data is deleted.

wiki/content/graphql/api/_index.md

@@ -0,0 +1,8 @@
++++
+title = "The API"
+[menu.main]
+  url = "/graphql/api/"
+  identifier = "api"
+  parent = "graphql"
+  weight = 5
++++

wiki/content/graphql/api/api-overview.md

@@ -0,0 +1,23 @@
++++
+title = "Overview"
+[menu.main]
+    parent = "api"
+    identifier = "api-overview"
+    weight = 1   
++++
+
+How to use the GraphQL API. 
+
+Dgraph serves [spec-compliant
+GraphQL](https://graphql.github.io/graphql-spec/June2018/) over HTTP to two endpoints: `/graphql` and `/admin`. 
+
+
+In Slash GraphQL `/graphql` and `/admin` are served from the domain of your backend, which will be something like `https://YOUR-SUBDOMAIN.REGION.aws.cloud.dgraph.io`. If you are running a self-hosted Dgraph instance that will be at the alpha port and url (which defaults to `http://localhost:8080` if you aren't changing any settings).
+
+In each case, both GET and POST requests are served.
+
+- `/graphql` is where you'll find the GraphQL API for the types you've added. That is the single GraphQL entry point for your apps to Dgraph.
+
+- `/admin` is where you'll find an admin API for administering your GraphQL instance. That's where you can update your GraphQL schema, perform health checks of your backend, and more.
+
+This section covers the API served at `/graphql`. See [Admin](/graphql/admin) to learn more about the admin API.

wiki/content/graphql/api/errors.md

@@ -0,0 +1,24 @@
++++
+title = "GraphQL Error Propagation"
+[menu.main]
+    parent = "api"
+    name = "GraphQL Errors"
+    weight = 6   
++++
+
+<!-- this needs something else?  probably an example to help explain better?-->
+
+Before returning query and mutation results, Dgraph uses the types in the schema to apply GraphQL [value completion](https://graphql.github.io/graphql-spec/June2018/#sec-Value-Completion) and [error handling](https://graphql.github.io/graphql-spec/June2018/#sec-Errors-and-Non-Nullability).  That is, `null` values for non-nullable fields, e.g. `String!`, cause error propagation to parent fields.  
+
+In short, the GraphQL value completion and error propagation mean the following.
+
+* Fields marked as nullable (i.e. without `!`) can return `null` in the json response.
+* For fields marked as non-nullable (i.e. with `!`) Dgraph never returns null for that field.
+* If an instance of type has a non-nullable field that has evaluated to null, the whole instance results in null.
+* Reducing an object to null might cause further error propagation.  For example, querying for a post that has an author with a null name results in null: the null name (`name: String!`) causes the author to result in null, and a null author causes the post (`author: Author!`) to result in null.
+* Error propagation for lists with nullable elements, e.g. `friends [Author]`, can result in nulls inside the result list.
+* Error propagation for lists with non-nullable elements results in null for `friends [Author!]` and would cause further error propagation for `friends [Author!]!`.
+
+Note that, a query that results in no values for a list will always return the empty list `[]`, not `null`, regardless of the nullability.  For example, given a schema for an author with `posts: [Post!]!`, if an author has not posted anything and we queried for that author, the result for the posts field would be `posts: []`.  
+
+A list can, however, result in null due to GraphQL error propagation.  For example, if the definition is `posts: [Post!]`, and we queried for an author who has a list of posts.  If one of those posts happened to have a null title (title is non-nullable `title: String!`), then that post would evaluate to null, the `posts` list can't contain nulls and so the list reduces to null.

wiki/content/graphql/api/fragments.md

@@ -0,0 +1,22 @@
++++
+title = "GraphQL Fragements"
+[menu.main]
+    parent = "api"
+    name = "GraphQL Fragements"
+    weight = 4   
++++
+
+Documentation on GraphQL fragments is coming soon.
+
+<!--using GraphQL fragments with Dgraph - there's fragments in the request as well as the type fragments to talk about**
+
+Case 1:
+you can see an example of a fragment here https://github.com/dgraph-io/graphql-sample-apps/blob/mjc/discuss/discuss-clone/src/components/operations.graphql
+
+and here https://github.com/dgraph-io/dgraph/blob/5a67b9497fdb4a2c67638e3fc2601d628aa238f0/graphql/e2e/common/fragment.go#L15-L26 and here https://github.com/dgraph-io/dgraph/blob/5a67b9497fdb4a2c67638e3fc2601d628aa238f0/graphql/e2e/common/fragment.go#L117-L153
+
+Case 2: (on types)
+You can see how fragments on types works here https://github.com/dgraph-io/dgraph/blob/5a67b9497fdb4a2c67638e3fc2601d628aa238f0/graphql/e2e/common/query.go#L1179-L1196
+
+
+This page should describe what fragments are used for (case 1 is reuse, case 2 is different results per type) and show how to submit a query with fragments and what the answer will look like.-->