Documentation feedback

Hello, I am evaluating Dgraph and just wanted to provide some feedback about the documentation.

As someone with experience in RDBMS and SQL, one of the first things I would like to know is how would I model my data differently in a graph database like Dgraph. What are the options/ways that I can model my data? What are the possible structures that can be used?

For example, in an RDBMS I can use tables with rows that have columns defined in a schema, and I can use foreign keys to create relations between tables.

What can I do with Dgraph?

I have glanced over the documentation and I have seen that there are (I think) Nodes, Edges, Facets, Predicates(?) and Schemas(?) and I don’t know what else. Problem is I don’t know what these are and how they relate to each other.

The documentation at:

Starts with “Get Started” which tells me how to install Dgraph, add some data and do some queries. But at this stage, as I am on Windows, I just want to evaluate without having to install anything.

Now again the “Tour” also requires me to install a local Dgraph in order to follow it. So I haven’t done it.

Then the next topic in the documentation is “Query Language” and then “Mutations”. At this point I want to know how I would design and define my data model before querying or mutating it or going into the details of the “Query Language”.

What I need is something that explains how you would (and how you can) model your data in Dgraph and what these basic concepts of Nodes, Edges, Predicates etc. actually mean starting at a high level before going into actual query language code.

Also a few simple but illustrative examples would be very helpful so people new to Dgraph can see how common patterns in typical RDBMS data models would (and should) be translated to Dgraph. Again, begin with a high level explaining the concepts of Nodes, Edges, Predicates and whatever needs to be understood etc. and display the design in clear diagram form, and only then show how it would translate to the query language.

I saw one of your talks (the one in Singapore) on Youtube, and it was very interesting. However, nowhere in the documentation can I find clear explanations of how one would design the data model. I think this is a very important topic and people who are coming from RDBMSs need to be given the correct picture as this is a completely new paradigm to them meaning old best practices are no longer valid and new ones must be learned.

I think the Tour might answer these questions, but it feels like having to go through an online course plus setting up a VM just to be able to get a basic idea of what Dgraph can do is a bit of a pain. A simple documentation page would easily answer them.

There are no tools specifically for this, yet. What is recommended is to understand how schema creation logic works (which is simple) and then model DIY according to your business logic

Technically with a Graph database you can make absolutely every possible structure. Companies like Facebook, Google and others use complex graph models.
All relations in the Dgraph are made through UIDs in Edges predicates. And in the Dgraph every relation you can add extra information in Facets. There are no tables, columns or anything like that. It’s another paradigm.

So try out this playground
All queries are the same as those used in all documentation. You are free to do any testing there, just mutations that do not.

If you want to do only tests you would recommend using “play with docker” you have 3 hours to train. Just use Dgraph’s Docker images and test.

There is also the possibility of doing a Tour, it is recommended. But you need a docker instance running. Dgraph has binaries for Windows.


Well all of this is in the documentation and on the Tour.

Technically every DB you need to do this. From SQL to MongoDB LOL xD
But in Dgraph’s case I believe it’s easy to learn using only the documentation and examples. 1 month and you are already mastering it


1 Like

Hello Chanon,

What you describe isn’t specific to dgraph.

Here’s what I’ve learned with graph db modeling:

  1. Start with writing simple English sentences. In your previous example of ToDo… A sentence could be: user has a task.

  2. Then pick the nouns… They are typically great candidates for nodes.

  3. The verbs, adverbs, sometimes adjectives are good candidates for edges; or in case of dgraph, predicates.

  4. Next the attributes of nodes can become properties ( in a property graph) or in the case of dgraph, they can be realized as additional predicates. Ex. User has age. In graph db like Titan or DSE graph, this would be property of the node.; In dgraph age would be another object with “has” as predicate.

  5. Unlike in rdbms, edges can also have properties (think of this as attributes in relationship in rdbms - which means building a complex linking table). In dgraph this appears as facets. Titan etc. Support edge properties like node properties.

Then, one struggles with “normalize” or “denormalize” as one does with rdbms. This I’ve learned comes with practice. I’ll give (perhaps simplistic) example… let’s say you want to order the tasks for a user.

Based on the above, the English sentences for this “biz requirement” would be, “a task has order”… So “order” is a property of the task… Or it could be property of the relationship between user and task (I’m stretching in this use case…). So you could make order a facet or predicate. NOTE: making something a node property or predicate in dgraph means, adding another “node”.

If I remember correctly DSE has some tutorials on moving from rdbms… And there are few you tube videos… And I’ve found the English sentences way the simplest and easiest.

After a basic schema, one starts to build applications and with that comes queries… What one queries on, can alter the schema… For instance, we figured out that when we have to query by facets, it is best to promote that edge attribute as a predicate (rather than bringing all facets into the application to do app based filtering).

Then it’s a bit of rinse and repeat…

Hope that helps…



Thank you for both responses.

But in Dgraph’s case I believe it’s easy to learn using only the documentation and examples.

I guess I will have to try. Thanks for pointing to the Windows binaries!

Here’s what I’ve learned with graph db modeling:

Thank you very much. Yes, something like this (but expanded) is exactly what I am talking about.

My post here isn’t intended as some kind of criticism or whining, but rather a suggestion that I think will help with adoption of the product, and is speaking from the POV of someone new to Dgraph and graph databases who has mostly experience in RDMBS (which I think is a very large group or rather the biggest group)

Even NoSQL databases have pages about how data can (and should) be modelled in them, and NoSQL are a lot simpler to understand:

Again, no problem, I will try out the Tour with the Windows binaries.

1 Like

Thanks for the feed/suggestion, I’ll work this idea from modeling for documentation.