DQL Anatomy (Repost from internal discussion)

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

A “Summary”

Query Anatomy

This one was the first.

Var Block

Two Blocks

Aggregation Query

Fragments

1 Like

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.

2 Likes

Just saw this. Monumental work!

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

2 Likes

Did some changes based on you feedback:

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.

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

I’ll work a bit more on the Facets.

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

1 Like

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.

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.

1 Like

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:

1 Like

New Drafts

3 Likes

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