## 1. Project Overview & Quickstart (dgraph-io/dgraph) [](https://github.com/dgraph-io/dgraph/stargazers) [](https://github.com/dgraph-io/dgraph/commits/main/) [](https://goreportcard.com/report/github.com/dgraph-io/dgraph) [](https://hub.docker.com/r/dgraph/dgraph) Dgraph is a horizontally scalable and distributed GraphQL database with a graph backend. It provides ACID transactions, consistent replication, and linearizable reads. It's built from the ground up to perform a rich set of queries. Being a native GraphQL database, it tightly controls how the data is arranged on disk to optimize for query performance and throughput, reducing disk seeks and network calls in a cluster. Dgraph's goal is to provide Google production-level scale and throughput, with low enough latency to serve real-time user queries over terabytes of structured data. Dgraph supports [GraphQL query syntax](https://docs.dgraph.io/graphql), and responds in [JSON](http://www.json.org/) and [Protocol Buffers](https://developers.google.com/protocol-buffers/) over [GRPC](http://www.grpc.io/) and HTTP. Dgraph is written using the Go Programming Language. ## Status Dgraph is at [version v25][rel] and is production-ready. Apart from the vast open source community, it is being used in production at multiple Fortune 500 companies. [rel]: https://github.com/dgraph-io/dgraph/releases/tag/v25.0.0 ## Supported Platforms Dgraph officially supports the Linux/amd64 and Linux/arm64 architectures. In order to take advantage of memory performance gains and other architecture-specific advancements in Linux, we dropped official support for Mac and Windows in 2021, see [this blog post](https://discuss.dgraph.io/t/dropping-support-for-windows-and-mac/12913) for more information. You can still build and use Dgraph on other platforms (for live or bulk loading for instance), but support for platforms other than Linux/amd64 and Linux/arm64 is not available. Running Dgraph in a Docker environment is the recommended testing and deployment method. ## Install with Docker If you're using Docker, you can use the [official Dgraph image](https://hub.docker.com/r/dgraph/dgraph/). ```bash docker pull dgraph/dgraph:latest ``` For more information on a variety Docker deployment methods including Docker Compose and Kubernetes, see the [docs](https://docs.dgraph.io/installation/). ## Run a Quick Standalone Cluster ```bash docker run -it -p 8080:8080 -p 9080:9080 -v ~/dgraph:/dgraph dgraph/standalone:latest ``` ## Install from Source If you want to install from source, install Go 1.27+ or later and the following dependencies: ### Ubuntu ```bash sudo apt-get update sudo apt-get install build-essential ``` ### Build and Install Then clone the Dgraph repository and use `make install` to install the Dgraph binary in the directory named by the GOBIN environment variable, which defaults to $GOPATH/bin or $HOME/go/bin if the GOPATH environment variable is not set. ```bash git clone https://github.com/dgraph-io/dgraph.git cd dgraph make setup make install ``` ## Get Started **To get started with Dgraph, follow:** - [Installation to queries in 4 quick steps](https://docs.dgraph.io/quick-start). - Tutorial and presentation videos on [YouTube channel](https://www.youtube.com/playlist?list=PLzOEKEHv-5e3u2Tgv52O2rs5u3md58JON). ## Is Dgraph the right choice for me? - Do you have more than 10 SQL tables connected via foreign keys? - Do you have sparse data, which doesn't elegantly fit into SQL tables? - Do you want a simple and flexible schema, which is readable and maintainable over time? - Do you care about speed and performance at scale? If the answers to the above are YES, then Dgraph would be a great fit for your application. Dgraph provides NoSQL like scalability while providing SQL like transactions and the ability to select, filter, and aggregate data points. It combines that with distributed joins, traversals, and graph operations, which makes it easy to build applications with it. ## Dgraph compared to other graph DBs | Features | Dgraph | Neo4j | Janus Graph | | ----------------------------------- | ----------------------------- | -------------------------------------------------------- | ------------------------------------- | | Architecture | Sharded and Distributed | Single server (+ replicas in enterprise) | Layer on top of other distributed DBs | | Replication | Consistent | None in community edition (only available in enterprise) | Via underlying DB | | Data movement for shard rebalancing | Automatic | Not applicable (all data lies on each server) | Via underlying DB | | Language | GraphQL inspired | Cypher | Gremlin | | Protocols | Grpc / HTTP + JSON / RDF | Bolt + Cypher | Websocket / HTTP | | Transactions | Distributed ACID transactions | Single server ACID transactions | Not typically ACID | | Full-Text Search | Native support | Native support | Via External Indexing System | | Regular Expressions | Native support | Native support | Via External Indexing System | | Geo Search | Native support | External support only | Via External Indexing System | | License | Apache 2.0 | GPL v3 | Apache 2.0 | ## Users - **Dgraph official documentation is present at [docs.dgraph.io](https://docs.dgraph.io).** - For general information and questions, visit [Github discussions](https://github.com/dgraph-io/dgraph/discussions). - Please see [releases tab](https://github.com/dgraph-io/dgraph/releases) to find the latest release and corresponding release notes. ## Developers Please see [Contributing to Dgraph](https://github.com/dgraph-io/dgraph/blob/main/CONTRIBUTING.md) for guidelines on contributions. ## Client Libraries The Dgraph team maintains several [officially supported client libraries](https://docs.dgraph.io/clients/). There are also libraries contributed by the community [unofficial client libraries](https://docs.dgraph.io/clients/unofficial-clients). ## ## Contact - Please use [Github discussions](https://github.com/dgraph-io/dgraph/discussions) for questions, feature requests and discussions. - Please use [GitHub Issues](https://github.com/dgraph-io/dgraph/issues) for filing bugs or feature requests. ## 2. Official Technical Reference & Guides (dgraph-io/dgraph-docs) # Dgraph Documentation To read the official Dgraph documentation that is published from this repository, please see https://docs.dgraph.io/. ## Technology Stack This documentation site is built with [Docusaurus](https://docusaurus.io/), a modern static website generator optimized for documentation. ## Documentation Structure The documentation is organized into four main sections, each managed by its own Docusaurus content plugin: 1. **Docs** (`/`) - Core Dgraph database documentation including DQL, administration, installation, and design concepts 2. **GraphQL** (`/graphql`) - GraphQL API documentation, schema, queries, mutations, and custom resolvers 3. **Ratel UI** (`/ratel`) - Documentation for the Ratel web-based UI tool 4. **Tutorials** (`/learn`) - Step-by-step tutorials and learning paths for different user types Each section has its own sidebar navigation configured in: - `sidebars.ts` - Docs sidebar - `sidebars-graphql.ts` - GraphQL sidebar - `sidebars-ratel.ts` - Ratel sidebar - `sidebars-learn.ts` - Tutorials sidebar ## Running Locally ### Prerequisites - [Node.js](https://nodejs.org/) version 20.0 or higher - npm or yarn package manager ### Setup and Run 1. Navigate to the Docusaurus directory: ```bash cd docusaurus-docs ``` 2. Install dependencies: ```bash npm install ``` 3. Start the development server: ```bash npm start ``` 4. Open [http://localhost:3000](http://localhost:3000) in your browser. The site will automatically reload when you make changes to the documentation files. ### Build for Production To build a production-ready static site: ```bash npm run build ``` The built site will be in the `build/` directory. You can serve it locally with: ```bash npm run serve ``` ### Testing the current version When testing locally you can set ``` includeCurrentVersion: true, ``` in the docs or graphql plugin in `docusaurus.config.ts`. This will expose `next` in the version selector, so you can view the current (non versioned) documentation. ## Versioning Documentation is versioned for the **docs** and **graphql** sections. Versioned content lives in: - `docs_versioned_docs/` and `docs_versioned_sidebars/` (and `docs_versions.json`) - `graphql_versioned_docs/` and `graphql_versioned_sidebars/` (and `graphql_versions.json`) The folders `docs/` and `docs-graphql/` are the **“next”** (unreleased) content. They appear in the version dropdown as **“next”** only when running the site locally with `includeCurrentVersion: true` in `docusaurus.config.ts`. **When deployed, the site serves only versioned documentation** (e.g. v25.4, v25.3, v25.2); the “next” content is not shown on the live site. **Where to edit:** - **For the next release:** Edit the page in `docs/` or `docs-graphql/`. Those are the only places that represent the upcoming release. - **For the current release (what’s live):** Apply the same change in the corresponding versioned folder (e.g. `docs_versioned_docs/version-v25.4/...` or `graphql_versioned_docs/version-v25.4/...` for the latest). If a fix or clarification should be in the current release, duplicate the change there. **Note for reviewers:** The “Edit this page” link always points to the “next” page (`docs/` or `docs-graphql/`). When reviewing PRs, check whether the change should also be ported back to the current version’s versioned folder. To create a new version: 1. Use the Docusaurus CLI: `npm run docusaurus docs:version:docs ` `npm run docusaurus docs:version:graphql ` 2. This creates a new version snapshot of the current docs ## Deployment The documentation site is automatically deployed to CloudFlare: - **Main branch** (`main`) → Deployed to production at `https://docs.dgraph.io` - **Preview branches** (`preview/*`) → Deployed as preview deployments for review The deployment process is handled automatically via CloudFlare Pages integration with GitHub. ## Contribution Guidelines As a contributor to Dgraph documentation, we ask that you do the following: - **Label your PR for easy management**: Your PR title should be in the following format: **Topic (area): details**. The **topic** is either "Docs", "Nav" (aka, navigation), or "Chore" (for build fixes, cherry-picks, etc). The **area** is the feature (i.e. "GraphQL"), area of the docs (i.e., "Deployment"), or "Other" (for typo fixes and other bugfix PRs). So, example PR names include: *Docs(GraphQL): Document the @deprecated annotation* - **Technical writing style**: As much as possible, please follow technical writing style conventions (More on this below). - **(Dgraph core team only)**: Include the ID of any issues/tickets related to your PR in the description (i.e., "Fixes DGRAPH-12345" or "Per DGRAPH-54321"). ### Technical Writing Style Please follow the [Dgraph Documentation Style Guide](documentation-style-guide.md) for writing conventions, formatting, and best practices. **Note:** Please don't let these style conventions stop you from creating a PR to share your contribution to Dgraph Docs! PR reviewers can help with style guide issues. ### References In Docusaurus, use standard Markdown links for internal references. For example, to reference a term in the glossary: ```markdown [UID](/dgraph-glossary#uid) ``` ## File Structure ``` docusaurus-docs/ ├── docs/ # Main documentation content ├── docs-graphql/ # GraphQL documentation ├── docs-ratel/ # Ratel UI documentation ├── docs-learn/ # Tutorials and learning content ├── docs_versioned_docs/ # Versioned documentation snapshots ├── sidebars.ts # Main docs sidebar configuration ├── sidebars-graphql.ts # GraphQL sidebar configuration ├── sidebars-ratel.ts # Ratel sidebar configuration ├── sidebars-learn.ts # Tutorials sidebar configuration ├── docusaurus.config.ts # Main Docusaurus configuration └── src/ # Custom components and styles ```