Quick Start

When you write an application 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 using the Dgraph Cloud.
You can log in to Dgraph cloud using Sign in with Google, Sign in with GitHub or any other email account that you prefer to use.

1. In the Dgraph cloud console, click Launch new backend.
2. Select a plan, cloud provider, and region that meets your requirements.
3. Type a name for your Dgraph cloud instance.
4. Click Launch
5. A new Dgraph cloud backend is created for you. The URL listed in GraphQL Endpoint is the URL at which Dgraph cloud serves data to your app. You can copy it at any time to use in a GraphQL client application.

Step 2: Deploy a GraphQL Schema

1. In the Schema tab of the Dgraph Cloud 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 use the API Explorer tab of your Dgraph cloud console, but 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 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.
• Follow our GraphQL tutorials to experience rapid application development by building more advanced apps.