Quick Start

Overview

Traditional GraphQL implementations require significant overhead when building on top of REST endpoints or relational databases. Developers must manually translate REST/relational data models into graph structures, implement resolvers for each field, and manage the numerous queries generated during this translation process.

Dgraph simplifies this workflow by providing a schema-first approach. By deploying your GraphQL schema, Dgraph automatically generates a fully functional GraphQL API with a native graph database backend—eliminating the need for manual resolver implementation and data translation layers.

Step 1: Run Dgraph

The easiest way to get Dgraph up and running is to install a Learning Environment.

Step 2: Deploy a GraphQL Schema

Create a file schema.graphql with the following content.

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
}

Push the schema to Dgraph

From a terminal window

curl --data-binary '@./schema.graphql --header 'content-type: application/octet-stream'  http://localhost:8080/admin/schema

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.

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,

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

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.

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.

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.

Execute the query

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 performant 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.