You are looking at the docs for the unreleased master branch of Dgraph. The latest version is v21.03.
Ask a Question

Dgraph Database Overview

Dgraph is a horizontally scalable and distributed GraphQL database with a graph backend. Dgraph is built for the heavy transactional workloads required to power modern apps and websites, but it isn’t limited to only these types of applications. Whether you are looking to power the backend of your app, create elastic search for your website, or build a new database purely for data analysis, Dgraph is up to the task. In fact, it is in production today in the following real-world scenarios:

  • Data unification
  • Customer 360
  • Social media sites
  • Content Management Systems
  • Ecommerce stores
  • Entity resolution
  • HR management applications
  • Master data management
  • Product recommendation engines
  • Real-time chat applications

To learn more about how organizations are using Dgraph, see Dgraph Case Studies.

How does Dgraph work?

Dgraph is not a layer on top of another SQL or No-SQL database such as Postgres or MongoDB. Instead, Dgraph is a new database built from the ground-up to manage data natively in graphs. Dgraph reads data from disk, accesses RAM, and talks over the network using HTTP and gRPC. A single Dgraph database instance consists of multiple entitles, described below in Dgraph architecture, but these three entities work together in a single layer.

What’s behind Dgraph’s GraphQL endpoints?

Dgraph is the world’s first, and at this time only, service to offer a specification-compliant GraphQL endpoint without the need for an additional translation layer in the tech stack. You will not find a hidden layer of GraphQL resolvers in Dgraph. GraphQL is natively executed within the core of Dgraph itself.

Dgraph Query Language (DQL)

Dgraph started out as its own proprietary graph database without support for the native GraphQL endpoint it has today. Early on, Dgraph engineers wanted to use GraphQL, but realized the official GraphQL specification could not support everything that customers would need from a database query language. GraphQL was not created to be a database query language, but it could easily be extended as a database query language.

So, Dgraph Labs forked our language from GraphQL and initially named this language GraphQL+- (“GraphQL, plus or minus”). For simplicity, GraphQL+- has since been renamed to Dgraph Query Language (DQL).

Dgraph and GraphQL

Dgraph was developed around DQL, which like GraphQL, uses a schema to classify and manage data. As Dgraph developed, it drew much attention from the GraphQL community, but developers still faced the challenge that has almost always been present when implementing GraphQL in a tech stack — the need to build a layer of GraphQL resolvers for queries, mutations, and subscriptions. The need for a layer of resolvers required developers to translate GraphQL into DQL, handling middleware, authorization, and custom business logic. Without a resolving layer, developers were not able to utilize the spec compliant, GraphQL community tools that continue to be developed.

In response to user feedback, Dgraph Labs decided to add a spec-compliant GraphQL solution into the core of Dgraph. But unlike other GraphQL solutions, Dgraph’s GraphQL implementation creates a spec-compliant GraphQL API with only developer-provided GraphQL schema. A developer defines types and fields, and applies directives in a GraphQL schema file that is provided to their Dgraph database instance. Dgraph then creates a full-featured CRUD-compliant GraphQL API endpoint, including the queries and mutations that one would expect when working with data under the provided GraphQL schema.

For more information about when and why to use either DQL or GraphQL and a side-by-side comparison, please see the GraphQL vs. DQL blog.

Dgraph architecture

Dgraph is a single layer in your tech stack, but inside the inner workings of a Dgraph database instance, there are three distinct entities:

  • Badger - Dgraph’s custom-built key-value store
  • Ristretto - Dgraph’s custom-built cache
  • Dgraph - the methods and algorithms used to parse DQL (and now GraphQL) and act accordingly

External to the core Dgraph database instance, you will find tools and communication clients to support Dgraph:

  • Ratel - a GUI Layer to work directly with DQL. (Ratel does not work with the graphql)
  • DQL Clients written in Go, C#, Java, JavaScript, and Python.

Dgraph database clusters

Dgraph is designed specifically to distribute data horizontally. You can scale Dgraph and maintain high availability by sharding data and replicating those shards. Dgraph handles the mundane tasks of actually sharding and replicating the data, you just need to setup and configure your Dgraph cluster appropriately. For more information on deloying and managing Dgraph your self, see Production Checklist

Dgraph now offers a fully managed service with high availability. This relieves you from all the stress of deployment and relies upon our team of expert engineers. Continue reading this section for a quick overview of deployment, or skip to the next section to learn more about Dgraph Cloud, our fully managed Dgraph database-as-a-service offering

Running Dgraph database and Dgraph Cloud

You can run Dgraph database in a variety of ways:

  • Fully-managed (hosted): Dgraph Cloud provides Dgraph as a fully-managed cloud service. Dgraph Cloud Shared Instances (formerly called Slash GraphQL) give you the power of Dgraph in a low-cost hosted service running on a shared cluster. Dgraph Cloud Dedicated Instances provide an enterprise-grade service that runs on dedicated cluster instances. To learn more, see Fully-Managed Dgraph.
  • Self-managed: You can use Dgraph on-premises, hosted on your own physical infrastructure. You can also run Dgraph in your AWS, GCP, or Azure cloud infrastructure.
Note The documentation provided on this Dgraph Docs site is applicable to self-managed instances of Dgraph, and also largely applicable to Dgraph Cloud (except for content in the Deploy and Manage section). To learn more about Dgraph Cloud, see Dgraph cloud services docs.

Dgraph Cloud

Dgraph Cloud with shared instances is a fully-managed GraphQL database service that lets you focus on building apps, not managing infrastructure. Dgraph Cloud is built from the ground up to support GraphQL, and uses a graph database structure down to its lowest layers. So it integrates seamlessly with your existing ecosystem of GraphQL tools.

Dgraph Cloud gives you the power of Dgraph database in a hosted environment, providing the flexibility and performance of a horizontally-scalable and distributed GraphQL database with a graph backend, so you don’t need to configure and manage VMs, servers, firewalls, and HTTP endpoints to power your modern apps and websites. Dgraph Cloud with shared instances runs on a shared cluster so we can offer it at a low price. To learn more about Dgraph Cloud, see Dgraph Cloud Overview.

Dgraph Cloud with dedicated instances extends the capabilities of the lower-cost shared instances offering to meet the heavy workloads and other needs of enterprise customers. With Dgraph Cloud, you get dedicated cluster instances, high availability, and the option to run Dgraph in your own virtual private cloud (VPC) or bring your own Kubernetes (BYOK) environment.

Get started

Use the instructions in this section to get started using Dgraph Cloud or self-managed Dgraph today.

Get started with Dgraph Cloud

You can get started with Dgraph Cloud today with a free trial. To use Dgraph Cloud, visit our Pricing Page or Pricing Calculator to get an estimate, or contact us.

Tip Check which Dgraph release version is running on your Dgraph Cloud backend in Dgraph Cloud Settings, and then use the version selector on this page to find docs.

Get started with self-managed Dgraph

To run Dgraph on your own server, see instructions for single-node setup or instructions for cluster setup.

Note Dgraph is designed to run on Linux. As of release v21.03, Dgraph no longer supports installation on Windows or macOS. We recommend using the standalone Docker image to try out Dgraph on Windows or macOS.

To run Dgraph using the standalone Docker image

  1. Download docker: https://www.docker.com/
  2. Create a folder to store Dgraph data outside of the container, as follows: mkdir -p ~/dgraph
  3. Get the Docker standalone image, as follows: docker pull dgraph/standalone
  4. Run the Dgraph Docker standalone image, as follows:
  docker run -it -p 5080:5080 -p 6080:6080 -p 8080:8080 -p 9080:9080 -p 8000:8000 -v ~/dgraph:/dgraph --name dgraph dgraph/standalone:v21.03.0
Tip To run the Docker standalone image for another version of Dgraph, change v21.03.0 in the command shown above to the version number for a previous release, such as v20.11.0.

After following these steps, Dgraph Alpha now runs and listens for HTTP requests on port 8080, and Ratel listens on port 8000.

Dgraph and GraphQL

Because Dgraph is a native GraphQL database, queries across sparse data sets run efficiently. As a native GraphQL database, Dgraph doesn’t have a relational database running in the background, so your data has the ability to grow and change with your app, without the need to add new tables. And when it comes time to deploy a new schema, you can do that in seconds, not hours.

To learn more about Dgraph’s GraphQL implementation, see GraphQL Overview. If you are a SQL user, see: Dgraph for SQL Users.

Dgraph endpoints

Dgraph exposes a variety of HTTP and gRPC endpoints. The type of Dgraph cluster node that exposes each endpoint (Alpha or Zero) is noted with each endpoint description below:

DQL endpoints

  • /query - used to make query requests with DQL (Alpha)
  • /mutate - used to send mutations in DQL (Alpha)

GraphQL endpoints

  • /graphql - used to host the GraphQL API, rewriting GraphQL to DQL (Alpha)
  • /admin - used to administer the Dgraph cluster (Alpha)

Other endpoints

  • /alter - used to alter the DQL schema (Alpha)
  • /health - used to query the health (Alpha)
  • /login - used to log-in an ACL user, and provides them with a JWT. (Enterprise Feature)
  • /state - used to view information about the nodes that are part of the cluster. (Zero)
  • /assign - used allocate a range of UIDs and request timestamps. (Zero)
  • /removeNode - used to remove a dead Zero or Alpha node from a cluster. (Zero)
  • /moveTablet - used to force move tablets to a group. (Zero)
  • /enterpriseLicense - used to apply an enterprise license to a cluster. (Zero)

Glossary of Dgraph and GraphQL terms

Term Definition Learn More
Dgraph Cloud A fully-managed GraphQL database service powered by Dgraph database. Dgraph Cloud documentation
Badger A fast, open-source key-value database written in pure Go that provides the disk layer for Dgraph database. Badger documentation
data node A basic unit of data representing an entity in a graph database. Nodes are connected by edges and have predicates (or fields) that contain node data.
Dgraph Alpha A server node that serves data to clients of Dgraph database, and also provides administrator endpoints. Dgraph Alpha documentation
Dgraph database A horizontally-scalable and distributed GraphQL database with a graph backend.
Dgraph Query Language (DQL) A query language that extends and modifies GraphQL to support deep queries for modern apps. Formerly known as GraphQL+-. DQL documentation
Dgraph Zero A server node that controls a Dgraph database cluster. Dgraph Zero documentation
edge A relationship between two data nodes in a graph database.
field See predicate.
GraphQL An open-source query language for APIs and a runtime for fulfilling those queries. Dgraph GraphQL documentation
object See data node.
server node A server that makes up part of a server cluster. See Dgraph Alpha and Dgraph Zero. Dgraph Cluster Setup documentation
superflag A Dgraph CLI flag that contains one or more options used to specify command settings. Dgraph Cluster Setup documentation
predicate A property of a data node in a graph database; also a discrete piece of information available to request in a graph database.