Docs erratas
perhaps we need a channel for errata as there are some small spelling mistakes and i dont want to dominate this channel?
42 Replies
This can be a start
no
s on labels
sentence ends abruptly and lacks ending
from this page https://typedb.com/docs/typeql/
built instead of build
Incomplete text, relation roles can be played by entities or relations, this is not explained. This is a key difference between TypeDB and any other graph, so you mut say it!!! Thus, the sentence should be extended by saying something like
or, better, when you mention roles you should define what type of objects can play roles!!!!!!
Incorrect, structs are not a type. They are a sub-type of the attribute type. There are only 3 type in typedb, entity, relation, attribute, so the below text is inconsistent, consider revising 3 and 4 to reflect the fact that attributes can be primitve or structured
Again, lists are not a type. Attributes can be either primitive or structured, Either can be defined singly or as a list. the entire Attribute section needs to be reconsidered, as it is poorly constructed atm
A schema query, implies that i am querying the schema, i can query against the schema to retrieve data, but this is poorly phrased, remove the word schema, or change it to say
Should be a full stop instead of a colon. The sentences should read
there is no $u variable
there is a definition of what it is, bit no example showing its use. If you cant use it yet, then remove it, else show and example of Optional variables
Confusing text on anonymous variables:
1. Why is it useful?
2. When would i use it?
3. How do i use it (example)?
Illogical to have the numbers backward, why is function 1 called from function2? Why make the user mentally reverse the numbers? Surely it will be 10x clearer if you reverse the numbers, so it makes some kind of logical sense, also reword it
What is a non-type variable, why not just say variable
Stage should be Stages
----------------
Whew, the first two pages properly checked, see above
Thank you for the feedback! Extremely appreciated
@core We'll need to have an iteration through these points with the incoming docs update
I'd guess the author stopped halfway through the explanation of stratification. "Stratification ensures function 1 is fully evaluated before function 2"
Good set of questions.
Why is it useful? It's not returned by the stage and they don't cause duplicates.
So you should be able to do:
Examples of use:
* When you don't care about a variable as long as there's atleast one. This prevents duplicating $x if they have multiple addresses
-
match $x isa person, has address $_;
* There's an irrelevant subpattern you need to traverse, that you don't want blowing up your answers:
- match $x isa person, has name "John"; $_ isa friendship, links ($x,$_1); $_ isa friendship, links($_1, $y);
I hope these work, because I don't use them much myself since I'm usually debugging and want the answers for every variable.
Can you achieve the same with an explicit distinct and select? I think so.I'll do more over time lads, and just keep posting it here
@georgii or @krishnan have either of you started fixing these yet?
Not me. Figured we'd do it during the next doc run
Same, that's what I said above
What does this statement actually mean?? Can it be interpreted without additional info??? I cant understand it, how does it differ from key??? What is it meant to do?
Consider completely revising the description
FWIW
@unique is a lot like @key, except a concept can only own one key attribute, but any number of unique attributes. Each attribute can still only have one owner though.
You can think of @key as @unique + @card(1)hmm thank you, i did find it in the TypeQL manual with a better description, @Joshua and i were also talking about the issue of modelling a dict, where it would be nice to have a unique, key for each value but only for that object, so unique is more useful if it can be scoped
so, a global unique and a local unique are both useful
Question:, looking through the keyword glossary, I see the word "struct". Is struct implemented, or is this just forewarning?
https://typedb.com/docs/typeql/keywords#_statements
If it is forewarning, should I include the keyword "list"??
Structs and lists are not yet implemented.
struct is a reserved keyword, list is also a keyword, but weak, it's used as an aggregation function reduce $xs = list($x);
The list type is denoted with [], e.g. person[].ok, thank you. I thought Lists were still to be implemented, can i use a list for a role?
is lists the same or different to cardinality?
Lists aren't implemented yet, no. You can use
list as a role name, it's not reserved.oh riught, when they are implemented, you may change the cardinality to suit
i was looking at one to many, and thinking list
They're not intrinsically related. Lists in schema are about ordering, i.e. ordered attribute ownerships for a concept and ordered role players for a role in a relation.
aah, of course, the ordering, i was thinking of just many, so the card 1 to many is like the old grakn unordered list?
Anyway, thanks
In the SubTyping Section, there is no detail on subtyping attributes, or relations for that matter. When subtyping attributes, does one use an abstracting keyword for the supertype?
What is the correct approach for attribute subtyping??
https://typedb.com/docs/manual/schema/schema_structure#_subtyping_and_inheritance
Question: When Defining Cardinality Constraints for Role Traits, are they specified on the Source Relation, or the Role object's (entity or relation)??
In this doc the card annotation is shown being marked on an entity's plays trait. Do I take this to mean that generally in the schema, relation role cardinality is marked on the end object type, rather than the source relation?
https://typedb.com/docs/typeql/annotations/card#_usage
If so, this really needs to be clearly explained for both, attribute ownership and role playing
It's not explained because there is no difference for all the kinds in the schema (maybe we can just state it explicitly). There is a special case of value types which is explained on the next page, though
Since 3.0.x (I don't remember the specific patch version), attribute supertypes can be non-abstract
do attribute supertypes have to have a value?
or can they swing value types?
I felt like the section you reference shows a representative example to answer your question.
You better avoid saying "role trait". Roles are separate types. Relations have two role-related traits: relating and roleplaying (roleplaying is also available for entities).
When declaring
relates, you can set the cardinality of this relates: restrictions for the number of roleplayers of this role for a relation instance.
When declaring plays, you can set the cardinality for this plays: restrictions for the number of times an instance can play this role.
We may extend my explanation above in the docs.
https://typedb.com/docs/manual/schema/types#_attribute_types
We definitely need to think about how to merge/reorganize these two pages as the questions may arise earlier. But there is also a chance that you have these questions only because you're migrating from 2.xtrue, plus i am somewhat retentive on docs to be fair, so i ponder them and mull the words them over
crazy that i can declare relation cardinality on either plays or relates keywords
Why so? It's quite basic even in SQL 🙂 One-to-many, one-to-one, and it's specified for each direction
And even more representative with TypeDB graph visualization: 3 types of traits (edges), 3 separate cardinalities
For other edges, the unchanged default is
0..1 (sub, value, etc)They're not the same though from what I gather.
Declaring a
relation friendship relates friend @card(2) means an instance of friendship can have at most 2 friend roles.
Declaring entity person plays friendship:friend @card(1..) means a person must play the role of friend in atleast one friendship relation.
I hope that's what you were askingaah, thats a gotcha for certain, so if you use the card annotation, the instance must have at least one copy??
One copy of what?
the attribute data, or the plays object
No,
@card(0..) is a valid cardinality
entity person has name @card(0..); would allow a person with no name to existmost of the lists in Stix are unordered, so this seems like the perfect annotation to have on repeat
thank you, i will use that everywhere, cutting and pasting now actually, hahaha