Quickstart

Go from an empty Dgraph database to a running GraphQL API in just one step; just define the schema of your graph and how you’d like to search it; Dgraph does the rest.

We’re overhauling Dgraph’s docs to make them clearer and more approachable. If you notice any issues during this transition or have suggestions, please let us know.

When you write an app that implements GraphQL over a REST endpoint or maybe over a relational database, you know that GraphQL issues many queries to translate the REST/relational data into something that looks like a graph. You also have to be familiar with the GraphQL types, fields, and resolvers. However, with Dgraph you can generate a running GraphQL API with the associated graph backend just by deploying the GraphQL schema of your API. Dgraph does the rest!

Step 1: Run Dgraph

The easiest way to get Dgraph up and running is on Hypermode.

Step 2: Deploy a GraphQL Schema

1. In the Schema tab of the console, paste the following schema:

   type Product {
     productID: ID!
     name: String @search(by: [term])
     reviews: [Review] @hasInverse(field: about)
   }
   
   type Customer {
     username: String! @id @search(by: [hash, regexp])
     reviews: [Review] @hasInverse(field: by)
   }
   
   type Review {
     id: ID!
     about: Product!
     by: Customer!
     comment: String @search(by: [fulltext])
     rating: Int @search
   }
   

2. Click deploy

   You now have a GraphQL API up and running and a graph database as a backend.

Step 3: Test your GraphQL API

You can access the GraphQL endpoint with any GraphQL clients such as GraphQL Playground, Insomnia, GraphiQL, Altair or Postman.

If you want to use those clients, copy the GraphQL endpoint from the Cloud dashboard.

You may want to use the introspection capability of the client to explore the schema, queries, and mutations that were generated by Dgraph.

A first GraphQL mutation

To populate the database,

1. Open the API Explorer tab

2. Paste the following code into the text area:

   mutation {
     addProduct(
       input: [
         { name: "GraphQL on Dgraph" }
         { name: "Dgraph: The GraphQL Database" }
       ]
     ) {
       product {
         productID
         name
       }
     }
     addCustomer(input: [{ username: "Michael" }]) {
       customer {
         username
       }
     }
   }
   

3. Click Execute Query .

   The GraphQL server returns a JSON response similar to this:

   {
     "data": {
       "addProduct": {
         "product": [
           {
             "productID": "0x2",
             "name": "GraphQL on Dgraph"
           },
           {
             "productID": "0x3",
             "name": "Dgraph: The GraphQL Database"
           }
         ]
       },
       "addCustomer": {
         "customer": [
           {
             "username": "Michael"
           }
         ]
       }
     },
     "extensions": {
       "requestID": "b155867e-4241-4cfb-a564-802f2d3808a6"
     }
   }
   

A second GraphQL mutation

Because the schema defined Customer with the field username: String! @id, the username field acts like an ID, so we can identify customers just with their names.

Products, on the other hand, had productID: ID!, so they’ll get an auto-generated ID which are returned by the mutation.

1. Paste the following mutation in the text area of the API Explorer tab.

2. Your ID for the product might be different than 0x2. Make sure to replace the product ID with the ID from the response of the previous mutation.

3. Execute the mutation

   mutation {
     addReview(
       input: [
         {
           by: { username: "Michael" }
           about: { productID: "0x2" }
           comment: "Fantastic, easy to install, worked great.  Best GraphQL server available"
           rating: 10
         }
       ]
     ) {
       review {
         comment
         rating
         by {
           username
         }
         about {
           name
         }
       }
     }
   }
   

   This time, the mutation result queries for the author making the review and the product being reviewed, so it’s gone deeper into the graph to get the result than just the mutation data.

   {
     "data": {
       "addReview": {
         "review": [
           {
             "comment": "Fantastic, easy to install, worked great.  Best GraphQL server available",
             "rating": 10,
             "by": {
               "username": "Michael"
             },
             "about": {
               "name": "GraphQL on Dgraph"
             }
           }
         ]
       }
     },
     "extensions": {
       "requestID": "11bc2841-8c19-45a6-bb31-7c37c9b027c9"
     }
   }
   

GraphQL queries

With Dgraph, you get powerful graph search built into your GraphQL API. The schema for search is generated from the schema document that we started with and automatically added to the GraphQL API for you.

Remember the definition of a review.

type Review {
    ...
    comment: String @search(by: [fulltext])
    ...
}

The directive @search(by: [fulltext]) tells Dgraph we want to be able to search for comments with full-text search.

Dgraph took that directive and the other information in the schema, and built queries and search into the API.

Let’s find all the products that were easy to install.

1. Paste the following query in the text area of the API Explorer tab.

2. Execute the mutation

   query {
     queryReview(filter: { comment: { alloftext: "easy to install" } }) {
       comment
       by {
         username
       }
       about {
         name
       }
     }
   }
   

What reviews did you get back? It’ll depend on the data you added, but you’ll at least get the initial review we added.

Maybe you want to find reviews that describe best GraphQL products and give a high rating.

query {
  queryReview(
    filter: { comment: { alloftext: "best GraphQL" }, rating: { ge: 10 } }
  ) {
    comment
    by {
      username
    }
    about {
      name
    }
  }
}

How about we find the customers with names starting with “Mich” and the five products that each of those liked the most.

query {
  queryCustomer(filter: { username: { regexp: "/Mich.*/" } }) {
    username
    reviews(order: { asc: rating }, first: 5) {
      comment
      rating
      about {
        name
      }
    }
  }
}

Conclusion

Dgraph allows you to have a fully functional GraphQL API in minutes with a highly scalable graph backend to serve complex nested queries. Moreover, you can update or change your schema freely and just re-deploy new versions. For GraphQL in Dgraph, you just concentrate on defining the schema of your graph and how you’d like to search that graph. Dgraph does the rest.

What’s next

Learn more about GraphQL schema and Dgraph directives.