3.x docs refinements and feedback collection

[farost]

This issue contains all mentions, links, and details about the requested changes for 3.x docs, as well as general feedback on the current state of the documentation. TypeDB devs will be updating the description with the actual set of points.

When removing a point from the list, please consider leaving an issue comment to explain why it is being removed (fixed / not relevant / ...).

Docs erratas

• A thread from modeller with different erratas to address

Feedback

• From elgud:

I am finding the 2.x documentation more useful than the 3.x documentation, which has a lot missing. Some of which is tantalising such as list and struct.

• A collection from @flyingsilverfin
• Contains & Likes are listed as a statement (from anupam)

[flyingsilverfin]

Recorded feedback from clients & users:

• I tried to get the community version of TypeDB to work. Managed to download and get everything to work.

  • So now to try to create a schema and some data. I figured out how TypeDB studio works. I created a draft schema. It compiled and I committed it. So far, so good.
  • But I am struggling with inserting data. What is the best way to do this when you want to insert say 40 entities with relations in one file? Does anyone have an example I could work from?
  • [have you seen crash course] Yes, I tried all that repeatedly. But the examples are very small with just one or two variables.
  • They provide no clues regarding how to enter a chunk of data at once. A considerably

• Note equivalence between Links and isa Relation(players)

• Python tutorial is not easy to follow

  • Single-block of text initially, then step-by-step, in the order of the code, not out of order!!

• On https://typedb.com/docs/typeql/statements/relates, we should expand what role as role does/means (subtyping + abstractness)!

[flyingsilverfin]

We should add an example of recursion reachability && limited-depth recursion to our docs:

fun parents_of($child: Node) -> { Node }:
  match
    {(parent: $parent, child: $child) isa hierarchy;} or 
    {
     (parent: $intermediate, child: $child) isa hierarchy; 
      let $parent in parents_of($intermediate);
    };
  return { $parent };

with limit:

fun parents_of($child: Node, depth: integer) -> { Node }:
  match
    $depth > 0;
    {
      { (parent: $parent, child: $child) isa hierarchy; } 
    or 
      {
       let $new_depth = $depth - 1;
       (parent: $intermediate, child: $child) isa hierarchy; 
        let $parent in parents_of($intermediate, $new_depth);
      }
    };

  return { $parent };

[flyingsilverfin]

We should clarify somewhere in TypeQL statements is order agnostic (order doesn't matter), when it comes to determining execution of the query. There are only a few things the users can do to mandate ordering: stages in a pipeline are executed in-order, and functions & expressions & comparators must run after their arguments have been determined.

[farost]

Stages / operators:

has there been some drift over time in how TypeQL 3.x refers to stages vs. operators? in some places (https://typedb.com/docs/typeql/#:~:text=read%20and%20write%20stages,insert%2C%20delete%2C%20…%E2%80%8B))), select, sort, reduce are referred to as stages, then in other places (https://typedb.com/docs/typeql/pipelines/#:~:text=not%20already%20exist.-,Stream%20manipulation%20stages,-Select%20operator, https://typedb.com/docs/typeql/pipelines/select) they are referred to as operators, not to be confused with operator expressions (https://typedb.com/docs/typeql/expressions/operators)

[farost]

https://discord.com/channels/665254494820368395/983769458269114408/1379017184948260874

Give a more explicit description of rollback / commit operation and their effect on the state of the transaction

[farost]

Reading types is not on the surface of the Manual https://discord.com/channels/665254494820368395/983769458269114408/1381419823879159840