Documentation Revamp

A quick update on some recent activities.
The engineering team is steadily improving our code base and should announce our v23 soon. I’m personally looking forward to this major step as the merge of our cloud branch and community branch will be a starting point to implement new features. It will also purge a good list of issues.

But today I wanted to share the work we are doing on the documentation. We are revamping the documentation step by step to improve usability and help new Dgraph users as well as seasoned practitioners to leverage the power of Dgraph.
We are reviewing each page and organizing the content more clearly into concept, task, tutorial, or reference pages. We are also taking the opportunity to re-test the instructions and correct them when needed. We are also including some of the great work of the community.

For example you may want to check

Other technical pages are also being reviewed :

We are also doing some technical work to have the search working on the older versions. It was broken and we had to review the logic between Hugo, Netlify, Algolia crawler and indexes. Some fun scripting involved and some hiccups to expect as I’m testing the solution at the moment. So don’t worry if you see some messages about the current version in the doc. I’ll post when the search capability will be fully functional.

It’s a tedious work but very rewarding as it’s an opportunity for the team to go into some feature details. As I used to say, It’s surprising what you can learn by just reading the doc ! But the doc has to be readable.

It’s a continuous effort and we expect to have the whole doc revamped this quarter. We will also review all the tutorials.
Feel free to share you advice on the tutorials you found useful and the ones you would like to see !


The search box now works on the older releases !

We have deployed the doc of v22.0 and v21.03 ( the 2 versions officially supported) but we will put 21.12 back in the doc site too.
If you urgently need the v21.12 doc it is available here

BTW I have seen the suggestion to use Dgraph instead of Algolia. That’s a good idea for a project :
anyone interested in building a crawler, indexer and metadata management solution based on Dgraph ? :slight_smile:


That would be a nice Showcase. If it uses Knowledge Graph logic it would be a killer project.

Just throwing out there that this would be a perfect example of the need for fuzzy full text search. Algolia and elastic do this out of the box.


Absolutely :slight_smile:

Hey @Raphael I’m confused, are you saying your cloud branch (that we can’t access) and community branch are gonna be merged ? or are you just saying that they both will get those new features in ?


@cscetbon yes, the Dgraph engine running in our Cloud and the engine available on community branch will be the same ! Starting at the next release, we want Dgraph new features and bug corrections to be available on Cloud and on community at the same time. It’s a big change !
The Cloud offering has a some management tooling and UIs (the Cloud console) that will stay private.


The documentation revamp continues.

You might be interested in JSON mutation format where we put explanations requested and provided by the community about JSON, blank node, relationships etc…, It’s now in the doc, as requested.

DQL mutation syntax is also better introduced.

The GraphQL Quick Start has also been simplified.

We have also merged the Cloud doc so we can better reference common concepts in the doc.

We had recent requests about the @auth directive, and more broadly about how to secure Dgraph cluster and your GraphQL API. We are working at integrating the different explanations from Discuss posts, current documentation and tutorials to clearly explain Dgraph.Authorization schema annotation , GraphQL anonymous access (cloud feature), @auth directive.


Nice, I think these are much easier to follow! As a suggestion for the future, also having client specific versions would help a lot of people (e.g. Python, Go, JS etc). This is because the syntax for set, delete, upsert etc varies a little and currently users still have to translate that part.

1 Like

Thanks for the feedabck @RJKeevil. For the clients, we would like to clarify GraphQL clients (make it clear that we don’t have a GraphQL client but we work well with any popular GraphQL client), programmatic clients (Go, Java, python…) and UI clients (Ratel and more to come).

For the programmatic clients, could you clarify your request for the versions : do you think we should align the client version with Dgraph version and have the clients built with the Dgraph build or are you referring to a separate doc page for clients so you can browse the client version history ?

Hi Raphael, I mean that in page, in “set block” you have examples/tabs for json and RDF. I think it would be more useful to show how to do this in Python, Golang or Javascript, as now as a user I need to translate that json example into how the client actually expects a query to be provided. An example would be like the Qdrant docs, that give a python equivalent for each htttp call (Collections - Qdrant)

Thanks, we will do that …

1 Like

I actually disagree with this. Other languages should have a separate place in the docs.

There is NO correlation between dql, graphql, rdf, json etc…

This is completely different than javascript, python, golang, c#

The tabs for rdf vs json are a completely different concept. @Raphael - I find the changes here highly valuable, and you should not add python or any language on this page.

There should be a separate place for python programmers to understand the concepts.


Thanks for the comment @jdgamble555. We where debating how to organize the client documentation : either by tasks (use cases) and give the different flavors on each task, or by technology and describe all the tasks you can do with the python client, go client, … (as it is now) .
I guess when you are a python developer , you are not really interested in all the Go examples.
The organization of the client doc by language seems a better approach.
Let’s give a try at our client doc improvement and we will pay attention to the community feedback.

I had the crawler and metadata, now trying to use Dgraph instead neo4j, but it’s complicate to find Dgraph’s experts

I think that has some of the nicer docs I’ve read through recently.

They have the general concepts and specific information at the top level and then the majority of the information one layer down under SDK/ specific language / sdk integrations in their own sections / getting started flows.

On sign up they basically ask if you are implementing Clerk with any of these x frameworks. If you click one it takes you to the getting started for that specific framework.

They also use in case thats of any interest.


We have started to include elements about GraphQL and DQL interoperability. We also included elements from @amaster507 paper (thank you) and explained the differences between GraphQL schema and Dgraph types and predicates. We also started to list some benefits (and risks) by covering GraphQL data ingestion and data cleaning using DQL. It’s a work in progress and a place to put community tips on those subjects.

The doc has also a new section about design concepts at

We have also moved the “clients” section in DQL to clarify that Dgraph clients are DQL only and created a section GraphQL Client - GraphQL to explain the /graphql endpoint and headers better and to clarify the usage of GraphQL tools (IDE and clients).

We are working now on consolidating the Dgraph Administration documentation.

You will also notice that we have moved tutorials close to the documentation pages and organized them by roles targeting application developers, data engineers, and administrators. It’s at Dgraph Tutorials - Learn

Please let me know if you have good resources or ideas to create some Dgraph administration tutorials…


I would just add that you can’t currently use custom dql for mutations, and technically you could execute DQL in lambdas.

Use DQL in GraphQL - GraphQL dql (


1 Like

These pages are looking good. Glad to see some of this cleared up directly in the docs. Interesting to see tuts being brought back beside the docs, it all sometimes to be a big circle. :wink: