Quick Start
You might be familiar with GraphQL types, fields and resolvers. Perhaps you’ve written an app that adds GraphQL over a REST endpoint or maybe over a relational database. If so, you know how GraphQL sits over those sources and issues many queries to translate the REST/relational data into something that looks like a graph.
There’s none of that with Dgraph : you can generate a running GraphQL API with the associated graph backend just by dpeloying the GraphQL schema of your API; Dgraph does the rest.
Prerequisite : Run Dgraph
The easiest way to get Dgraph up and running is to provision a Dgraph Cloud backend.
Deploy a GraphQL Schema
Access the Dgraph Cloud console.
- 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
}
and Click deploy
That’s it, now you’ve got a GraphQL API up and running and a graph database as a backend.
Testing your GraphQL API
We will simply 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,
- open the API Explorer tab
- paste the following code into the text area
- click on the Execute Query button.
mutation {
addProduct(input: [
{ name: "GraphQL on Dgraph"},
{ name: "Dgraph: The GraphQL Database"}
]) {
product {
productID
name
}
}
addCustomer(input: [{ username: "Michael"}]) {
customer {
username
}
}
}
The GraphQL server will return a json response like:
{
"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.
- Paste the following mutation in the text area of the API Explorer tab.
- 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.
- Paste the following query in the text area of the API Explorer tab.
- 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
}
}
}
}
Discussion
Dgraph allows you to have a fully functional GraphQL API in minutes with a highly performant graph backlend 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.