DQL Anatomy (Repost from internal discussion)

[MichelDiz]

Update:

This is a repost from an internal discussion with some good info on DQL anatomy. Dear reader, don’t be confused with some parallel comment. There were a lot of comments in the original post that I choose to leave out of this.

Facets

Facets are extra information that you can add to an edge. It is often used for metadata or to reduce CPU usage as Facets are not indexed. As facets are not first-class citizens, they cannot be queried directly. You need to query Node and then apply the functions to Facets. In the same query.

A “Summary”

Here we have the summary of all keywords used in queries.

Query Anatomy

This one was the first.

Above we have an example of Query using practically all DQL functions and directives. Except Facets and Fragments.

Showing all Root query parameters.

Var Block

Var blocks are blocks that are not shown in the query. It’s generally used to do complex queries, math, and other things that don’t need to be seen in the response.

Two Blocks

In DQL you can have a cascade of blocks doing various N functions. And they are interconnected through variables.

Performance Tip: The more blocks you can split your query, the better. Because each block is executed concurrently. This implies a faster execution of your query.

Aggregation Query

Aggregation block is where we consolidate data from a query.

Fragments

Fragments is an inspiration from GraphQL. It is used to organize the blocks in the query and avoid repetition in very large queries.

[dmai (Daniel Mai)]

General feedback

Let’s rename root function’s label from “Function Name” to “Root Function”. And “Root Arguments” to “Function Arguments”.

Also, let’s try to start simple and try to explain things once. For example, there’s no need to repeat “Query”, “Query Block”, “Block Name”, “Start”, “End”, etc. for every diagram unless it’s relevant.

The syntax highlighting/coloring is great, but feels like a distraction and I’m not sure what to focus on in the query. We can use colored text to guide the viewer on what’s important to focus on, and make the rest of the query not as colorful.

On the subject of making things simple, each example should try to focus on no more than a few ideas. For the facets diagram, we should only need to focus on how @facets behaves: how to query them, how to filter them, and how they can be aliased. Anything else is a distraction, such as predicate-level aliases (“Other_friends”) or labeling the rest of the diagram.

Feedback for “Summary”

In “Summary”, there’s the left-hand list of all the keywords—some of them are actually functions and function arguments. The list can be split into keywords and functions. Something like the table below, but better. The function arguments should be specifically associated with the functions it can be used in instead of a general list.

Keywords	Functions	Function Arguments
query	expand()	first
fragment	val()	offset
func	math()	after
var	shortest()	orderasc
_all_	count()	orderdesc
_predicate_	anyofterms()	from
_forward_	allofterms()	to
_reverse_	anyoftext()	numpaths
as	alloftext()	maxweight
		depth
		loop

It’ll probably be better to have separate diagrams/slides about each type of thing: how expand works, shortest path, full-text functions, etc.

The “Directives on Queries, Directive on Schemas, Annotations” table is too sparse. It’s good that each row are related to each other, but the empty columns looks like missing features or something. The info can be conveyed more clearly in a different format (like, per-feature sections in the summary.

As I mentioned in the table above, count() is a function, not an Annotation. The only things in that table that could be classified as annotations are “@” lang tags and “~” reverse edges. Aliases are something else, really.

If there’s some way for me to directly help with editing these diagrams that’d be great.

[paulftw (Paul Korzhyk)]

Just saw this. Monumental work!

I didn’t know I could write query myQuery { ... } but it works in Ratel

[MichelDiz]

Did some changes based on you feedback:

@dmai

For example, there’s no need to repeat “Query”, “Query Block”, “Block Name”, “Start”, “End”, etc. for every diagram unless it’s relevant.

I left it because it’s kind of part of the concept I was inspired by. Where it shows where a block begins and ends. Just as some code editors do.

@dmai

make the rest of the query not as colorful.

That’s also inspired by the concept. No color gets weird, lifeless.

@dmai

On the subject of making things simple, each example should try to focus on no more than a few ideas. For the facets diagram, we should only need to focus on how @facets behaves: how to query them, how to filter them, and how they can be aliased. Anything else is a distraction, such as predicate-level aliases (“Other_friends”) or labeling the rest of the diagram.

I’ll work a bit more on the Facets.

@dmai

It’ll probably be better to have separate diagrams/slides about each type of thing: how expand works, shortest path, full-text functions, etc.

Also see what I can do for it.

Query Anatomy

This one was the first.

Facets

A “Summary”

Var Block

Two Blocks

Aggregation Query

Fragments

[dmai (Daniel Mai)]

@MichelDiz

I left it because it’s kind of part of the concept I was inspired by. Where it shows where a block begins and ends. Just as some code editors do.

I think it’s great and we should keep it, but it doesn’t necessarily need to be repeated for every single query example if a previous one already covered it. I find the diagram has a lot of noise instead of being focused on the single topic.

For example: Once the user already knows the structure of the query from previous diagrams, they can look at the Facets diagram and only need to focus on the specific parts about facets:

This is what I’m proposing—let me know what you think.

@MichelDiz

That’s also inspired by the concept. No color gets weird, lifeless.

I’m a fan of colors. But I think they should be used sparingly and to highlight the important parts. See the above example I shared. Colors are only used for the facet parts since this particular code anatomy is supposed to demonstrate facets. Everything else is either previously covered or not important to understanding how to query for facets.

And when we use colors, we should standardize the color usage. e.g., predicates should also be a certain color across all the anatomies.

[MichelDiz]

@dmai

but it doesn’t necessarily need to be repeated for every single query example if a previous one already covered it.

Well, each of one of these will be separated or in a single topic like an infographic? If they get separated, loses context.

But I Remember that, infographics are very colorful. Like crazy.

I think if we had an interactive page (HTML, JS) where when passing the mouse cursor it would focus on the objective of the piece. It would be interesting this dynamic of color and not color.

Let’s understand what is the destiny of this.

I’ve changed the facets query example:

[MichelDiz]

New Drafts

[Juri]

I’ve found this post randomly now through someone posting it in the discord channel

this is extremely useful knowledge/help please add that to the official docs