From ea54a07427903f1174b0447c74551c10a0f47c65 Mon Sep 17 00:00:00 2001 From: Krishnan Govindraj Date: Thu, 7 Aug 2025 22:43:36 +0200 Subject: [PATCH 01/17] TypeQL reference review --- .../modules/ROOT/pages/typeql/glossary.adoc | 1 + .../pages/typeql/queries-as-functions.adoc | 4 ++-- .../typeql/query-variables-patterns.adoc | 22 +++++++++---------- .../pages/typeql/annotations/abstract.adoc | 3 +-- .../ROOT/pages/typeql/annotations/card.adoc | 1 + .../ROOT/pages/typeql/expressions/index.adoc | 2 ++ .../ROOT/pages/typeql/functions/index.adoc | 2 +- .../modules/ROOT/pages/typeql/keywords.adoc | 4 ++-- .../pages/typeql/patterns/disjunctions.adoc | 2 ++ .../ROOT/pages/typeql/patterns/index.adoc | 2 +- .../ROOT/pages/typeql/patterns/negations.adoc | 5 +++-- .../ROOT/pages/typeql/patterns/optionals.adoc | 1 + .../ROOT/pages/typeql/pipelines/delete.adoc | 4 +++- .../ROOT/pages/typeql/pipelines/fetch.adoc | 2 +- .../ROOT/pages/typeql/pipelines/insert.adoc | 2 +- .../ROOT/pages/typeql/pipelines/limit.adoc | 2 +- .../ROOT/pages/typeql/pipelines/match.adoc | 3 ++- .../ROOT/pages/typeql/pipelines/update.adoc | 4 ++-- .../ROOT/pages/typeql/pipelines/with.adoc | 14 +++++++----- .../ROOT/pages/typeql/schema/redefine.adoc | 2 +- .../pages/typeql/statements/contains.adoc | 1 - .../ROOT/pages/typeql/statements/fun.adoc | 2 ++ .../ROOT/pages/typeql/statements/index.adoc | 12 +++------- .../ROOT/pages/typeql/statements/isa.adoc | 2 +- .../ROOT/pages/typeql/statements/like.adoc | 1 - .../modules/ROOT/partials/typeql/nav.adoc | 2 -- 26 files changed, 53 insertions(+), 49 deletions(-) delete mode 100644 reference/modules/ROOT/pages/typeql/statements/contains.adoc delete mode 100644 reference/modules/ROOT/pages/typeql/statements/like.adoc diff --git a/core-concepts/modules/ROOT/pages/typeql/glossary.adoc b/core-concepts/modules/ROOT/pages/typeql/glossary.adoc index 57630fbe6..faf1272e0 100644 --- a/core-concepts/modules/ROOT/pages/typeql/glossary.adoc +++ b/core-concepts/modules/ROOT/pages/typeql/glossary.adoc @@ -2,6 +2,7 @@ This page lists out terms reused across pages in this section, and links to where they are introduced. +A more complete list can be found in the xref:{page-version}@reference::typeql/keywords.adoc[] in the TypeQL reference. * xref:{page-version}@core-concepts::typeql/constraining-data.adoc#definition-annotation[Annotation]: Language fragments mainly used to add additional constraint to types. * xref:{page-version}@core-concepts::typeql/query-variables-patterns.adoc#definition-answer[Answer]: A mapping of variables to the concepts the pattern "matched" in the database. diff --git a/core-concepts/modules/ROOT/pages/typeql/queries-as-functions.adoc b/core-concepts/modules/ROOT/pages/typeql/queries-as-functions.adoc index bc335fc0d..741ee6779 100644 --- a/core-concepts/modules/ROOT/pages/typeql/queries-as-functions.adoc +++ b/core-concepts/modules/ROOT/pages/typeql/queries-as-functions.adoc @@ -42,7 +42,7 @@ using the reduce return modifier. [,typeql] .Find the number of posts by a page ---- -fun post_count($page: page) -> { integer }: +fun post_count($page: page) -> integer: match $posting isa posting, links (posted: $page); return count($post); @@ -50,7 +50,7 @@ return count($post); [NOTE] ==== -Since `reduce` can be used with `groupby`, the `reduce` modifier returns a stream. +`reduce` returns a single answer, since it aggregates all answers into one. ==== == Cyclic functions & tabling diff --git a/core-concepts/modules/ROOT/pages/typeql/query-variables-patterns.adoc b/core-concepts/modules/ROOT/pages/typeql/query-variables-patterns.adoc index 8eb8ce7ff..dc1c3f42b 100644 --- a/core-concepts/modules/ROOT/pages/typeql/query-variables-patterns.adoc +++ b/core-concepts/modules/ROOT/pages/typeql/query-variables-patterns.adoc @@ -125,10 +125,8 @@ See xref:{page-version}@core-concepts::typeql/schema-data.adoc[]. Variable names are unique within a pipeline - every usage of a variable with a certain name refers to the same variable. -In the following sections, the term [[definition-local-variable]]"local" is used to mean +In the following sections, the term [[definition-internal-variable]]"internal" is used to mean a variable is bound in that pattern but not in its parent. -This contrasts with the usage in programming languages where it refers to the scope of a variable name. -As mentioned above, the scope of variable names in TypeQL is the xref:{page-version}@core-concepts::typeql/query-clauses.adoc[pipeline]. == Disjunctions, negations & optionals @@ -159,7 +157,7 @@ An answer to any pattern in the disjunction is an answer to the disjunction. A variable is "bound" in a disjunction if it is bound in every branch of the disjunction. Variables which are present in & bound by only some of the branches of the disjunction -(and not present outside it) are considered "local" to that disjunction. +(and not present outside it) are considered "internal" to that disjunction. ---- match @@ -174,7 +172,7 @@ $p isa person, has name $p-name; }; ---- -Here, `$emp`, `$company`, `$edu`, `$institute` are local to their patterns. +Here, `$emp`, `$company`, `$edu`, `$institute` are internal to their patterns. `$p` occurs outside the disjunction. `$org-name` is present in every-branch and returned by the disjunction. @@ -203,11 +201,11 @@ Any variable that is present both outside and inside the negation is considered and *must* be bound before matching the negated pattern. This requires that the variable is bound in the parent conjunction. -Variables that are present only inside the negation are considered local to the negation. +Variables that are present only inside the negation are considered internal to the negation. A negation without any inputs is extremely unusual. [NOTE] ==== -Local variables are not bound by the negation, +internal variables are not bound by the negation, since the negation is satisfied only if there are no answers to the negated pattern. ==== @@ -221,7 +219,7 @@ match }; ---- -Here, `$p` is an input to the negation. `$e, $c` are local. The query returns: +Here, `$p` is an input to the negation. `$e, $c` are internal. The query returns: ---- ------------- $p-name | isa name "Jeff" @@ -322,7 +320,7 @@ Finished. Total rows: 3 [NOTE] ==== -Optional variables *are* bound by the optional block and not local to it. +Optional variables *are* bound by the optional block and not internal to it. ==== == Notes on variables @@ -476,14 +474,14 @@ This will return any persons `$p1` & `$p2` when either (1) `$p1` is employed by *any* and `$p2` attended *any* institute; or (2) `$p2` is employed by *any* company and `$p1` attended *any* institute. -Notice `$company` is "local" to both the first and second disjunctions (The same is the case for `$institute`). +Notice `$company` is "internal" to both the first and second disjunctions (The same is the case for `$institute`). TypeQL throws a "disjoint variable re-use" error for such cases. ==== Valid variable scopes: From these, it can be seen that a variable is either: -1. Local to one branch of one disjunction. -2. Local to one negation. +1. Internal to one branch of one disjunction. +2. Internal to one negation. 3. Bound & present in the answer of the pipeline. == The select statement diff --git a/reference/modules/ROOT/pages/typeql/annotations/abstract.adoc b/reference/modules/ROOT/pages/typeql/annotations/abstract.adoc index ceb95e78f..dea96615a 100644 --- a/reference/modules/ROOT/pages/typeql/annotations/abstract.adoc +++ b/reference/modules/ROOT/pages/typeql/annotations/abstract.adoc @@ -20,8 +20,7 @@ The `@abstract` annotation does not accept any arguments. // tag::description[] When defined for a type, the `@abstract` annotation enforces the `abstract` constraint, making the type abstract. -An abstract type cannot be a direct type for an instance. -Thus, a concrete subtype is required for instances creation, and an abstract type can be used as a query target to retrieve information about its subtypes. +An abstract type cannot be instantiated. but can be used in a query (e.g. in an `isa` constraint to refer to all its subtypes). // end::description[] [,typeql] diff --git a/reference/modules/ROOT/pages/typeql/annotations/card.adoc b/reference/modules/ROOT/pages/typeql/annotations/card.adoc index 99bd67cfe..e603dac5e 100644 --- a/reference/modules/ROOT/pages/typeql/annotations/card.adoc +++ b/reference/modules/ROOT/pages/typeql/annotations/card.adoc @@ -25,6 +25,7 @@ The `@card` annotation can be defined for any `` of: `owns`, `relates It accepts either a range argument or a single scalar argument. Arguments must be integers. +- Both bounds are inclusive. - A partially unbounded range `N..` has an infinite upper bound. - The minimal lower bound is `0` and must be explicitly specified (e.g., use `0..M` instead of `..M`). - A single scalar argument `N` is shorthand for `N..N` and means "exactly N". diff --git a/reference/modules/ROOT/pages/typeql/expressions/index.adoc b/reference/modules/ROOT/pages/typeql/expressions/index.adoc index 928e8bb9d..03eb4e1ab 100644 --- a/reference/modules/ROOT/pages/typeql/expressions/index.adoc +++ b/reference/modules/ROOT/pages/typeql/expressions/index.adoc @@ -3,6 +3,8 @@ This reference covers the usage of expressions in TypeQL. +// TODO: This article is a stub. + [cols-3] -- .xref:{page-version}@reference::typeql/expressions/literals.adoc[] diff --git a/reference/modules/ROOT/pages/typeql/functions/index.adoc b/reference/modules/ROOT/pages/typeql/functions/index.adoc index 0165f7e7e..9b563a68a 100644 --- a/reference/modules/ROOT/pages/typeql/functions/index.adoc +++ b/reference/modules/ROOT/pages/typeql/functions/index.adoc @@ -5,7 +5,7 @@ // tag::description[] Functions provide powerful abstractions of query logic. They are a cornerstone of the functional xref:{page-version}@reference::typeql/data-model.adoc[query programming model], and generalize logic programs à la Datalog. -Functions calls can be nested, recursive, and negated. There syntax natively embeds into TypeQL’s declarative pattern language. +Functions calls can be nested, recursive, and negated. Their syntax natively embeds into TypeQL’s declarative pattern language. // end::description[] [[fun_types]] diff --git a/reference/modules/ROOT/pages/typeql/keywords.adoc b/reference/modules/ROOT/pages/typeql/keywords.adoc index 748064c74..2c1a61ed3 100644 --- a/reference/modules/ROOT/pages/typeql/keywords.adoc +++ b/reference/modules/ROOT/pages/typeql/keywords.adoc @@ -129,10 +129,10 @@ Constructs a xref:{page-version}@reference::typeql/statements/let-eq.adoc[], use Constructs a xref:{page-version}@reference::typeql/statements/let-in.adoc[], used to assign a stream or list element to a variable. `contains`:: -Constructs a xref:{page-version}@reference::typeql/statements/contains.adoc[], used to specify that a stream or list contains a data instance, or that a string contains a specified substring. +Constructs a xref:{page-version}@reference::typeql/statements/comparisons.adoc#_string_comparison[], used to specify that a string contains a specified substring. `like`:: -Constructs a xref:{page-version}@reference::typeql/statements/like.adoc[], used to specify that a string matches a specified regex pattern. +Constructs a xref:{page-version}@reference::typeql/statements/comparisons.adoc#_string_comparison[], used to specify that a string matches a specified regex pattern. === Identity statements diff --git a/reference/modules/ROOT/pages/typeql/patterns/disjunctions.adoc b/reference/modules/ROOT/pages/typeql/patterns/disjunctions.adoc index 72de6ee30..a22899960 100644 --- a/reference/modules/ROOT/pages/typeql/patterns/disjunctions.adoc +++ b/reference/modules/ROOT/pages/typeql/patterns/disjunctions.adoc @@ -33,6 +33,8 @@ or { == Behavior +// TODO: needs update. Do not merge + Disjunctions may appear in `match` stages, where they behave as follows. * *Optionality*. An output variable whose xref:{page-version}@reference::typeql/patterns/index.adoc[scope] is the branch of a disjunction becomes an xref:{page-version}@reference::typeql/data-model.adoc[optional] variable. This means the variable may be left empty `()` in the output of the match stage. For example: diff --git a/reference/modules/ROOT/pages/typeql/patterns/index.adoc b/reference/modules/ROOT/pages/typeql/patterns/index.adoc index 2d180c851..01d697731 100644 --- a/reference/modules/ROOT/pages/typeql/patterns/index.adoc +++ b/reference/modules/ROOT/pages/typeql/patterns/index.adoc @@ -4,7 +4,7 @@ This reference covers the usage of patterns in TypeQL. == Scopes and operations - +// TODO: Must update. Pattern comprise statements containing variables. Given a pattern, the *scope* of a variable is: * the block `{ ... }` in which variable appears at top-level (i.e., not nested in further `{...}`) but it does not appear outside of the block, diff --git a/reference/modules/ROOT/pages/typeql/patterns/negations.adoc b/reference/modules/ROOT/pages/typeql/patterns/negations.adoc index 6fcb8c7f0..ce35cc348 100644 --- a/reference/modules/ROOT/pages/typeql/patterns/negations.adoc +++ b/reference/modules/ROOT/pages/typeql/patterns/negations.adoc @@ -1,7 +1,8 @@ = Negations :page-aliases: {page-version}@reference::typeql/patterns/negation.adoc -Negations can be used to exclude certain subpatterns from your query results. +Negations can be used to exclude certain subpatterns from your query results - + an answer is excluded if it matches the subpattern. == Syntax @@ -38,7 +39,7 @@ Negations may appear in `match` stages of data pipelines or functions, where the * *Internal variables*. Variable whose scope lies inside an excluded pattern are not returned as part of the stage's output (i.e., such variables are xref:{page-version}@reference::typeql/data-model.adoc#modes[internal] variables). * *Satisfaction*. A pattern with a negation will return those outputs which satisfy the pattern outside the negation, but do not satisfy the excluded pattern for _any_ choice of internal variables in that pattern. -* *Recursion*. When using recursive function with negations care need to be taken that evaluation of the negation does not depend on the recursive function call itself (in other words, TypeDB works with https://en.wikipedia.org/wiki/Stratification_(mathematics)#In_mathematical_logic[stratified negation]). +* *Recursion*. When using recursive functions with negations, care needs to be taken that evaluation of the negation does not depend on the recursive function call itself (in other words, TypeDB works with https://en.wikipedia.org/wiki/Stratification_(mathematics)#In_mathematical_logic[stratified negation]). == Examples diff --git a/reference/modules/ROOT/pages/typeql/patterns/optionals.adoc b/reference/modules/ROOT/pages/typeql/patterns/optionals.adoc index 94f51e487..4277c645c 100644 --- a/reference/modules/ROOT/pages/typeql/patterns/optionals.adoc +++ b/reference/modules/ROOT/pages/typeql/patterns/optionals.adoc @@ -1,4 +1,5 @@ = Optionals +// TODO [NOTE] ==== diff --git a/reference/modules/ROOT/pages/typeql/pipelines/delete.adoc b/reference/modules/ROOT/pages/typeql/pipelines/delete.adoc index 3d59a8af6..bbd5448c4 100644 --- a/reference/modules/ROOT/pages/typeql/pipelines/delete.adoc +++ b/reference/modules/ROOT/pages/typeql/pipelines/delete.adoc @@ -10,7 +10,9 @@ The body of a delete stage is a sequence of delete statements. [,typeql] ---- -delete ( | has of | links ( [ , ... ] ) of ); [ ... ] +delete + ( | has of | links ( [ , ... ] ) of ); + [ ... ] ---- == Behavior diff --git a/reference/modules/ROOT/pages/typeql/pipelines/fetch.adoc b/reference/modules/ROOT/pages/typeql/pipelines/fetch.adoc index 0504ec290..335227935 100644 --- a/reference/modules/ROOT/pages/typeql/pipelines/fetch.adoc +++ b/reference/modules/ROOT/pages/typeql/pipelines/fetch.adoc @@ -2,13 +2,13 @@ :page-aliases: {page-version}@typeql::pipelines/fetch.adoc Fetch is primarily used to convert row answers into document (JSON) answers. +The `fetch` clause is **terminal**, meaning that it cannot be followed by any other pipeline stage. [#syntax] == Syntax A fetch stage can follow any other stage that produces rows (e.g., xref:{page-version}@reference::typeql/pipelines/match.adoc[match], xref:{page-version}@reference::typeql/pipelines/insert.adoc[insert]). It starts with the keyword `fetch` followed by curly braces `{}` with a fetch body inside of it. -The `fetch` clause is **terminal**, meaning that it cannot be followed by any other pipeline stage. .Pipeline syntax [,typeql] diff --git a/reference/modules/ROOT/pages/typeql/pipelines/insert.adoc b/reference/modules/ROOT/pages/typeql/pipelines/insert.adoc index 553180109..8c0c9b673 100644 --- a/reference/modules/ROOT/pages/typeql/pipelines/insert.adoc +++ b/reference/modules/ROOT/pages/typeql/pipelines/insert.adoc @@ -35,7 +35,7 @@ The output is then a stream of input rows extended with the newly inserted value [#_validation] == Validation - +// TODO: The first 3 can be type-inference errors, do they need to fail the transaction? Attempting to insert the following fail immediately and terminate the transaction: * an instance of an xref:{page-version}@reference::typeql/annotations/abstract.adoc[abstract] type, diff --git a/reference/modules/ROOT/pages/typeql/pipelines/limit.adoc b/reference/modules/ROOT/pages/typeql/pipelines/limit.adoc index 92ba509aa..dd9623953 100644 --- a/reference/modules/ROOT/pages/typeql/pipelines/limit.adoc +++ b/reference/modules/ROOT/pages/typeql/pipelines/limit.adoc @@ -13,7 +13,7 @@ limit ; == Example Match all friends of friends of a given person, sorted by the number of mutual friends, highest to lowest. Return first 10. - +// TODO: Are we missing a desc? [,typeql] ---- match diff --git a/reference/modules/ROOT/pages/typeql/pipelines/match.adoc b/reference/modules/ROOT/pages/typeql/pipelines/match.adoc index 10e39b0c4..636bba871 100644 --- a/reference/modules/ROOT/pages/typeql/pipelines/match.adoc +++ b/reference/modules/ROOT/pages/typeql/pipelines/match.adoc @@ -13,7 +13,7 @@ match where `` denotes a valid xref:{page-version}@reference::typeql/patterns/index.adoc[pattern]. == Behavior - +// TODO: This should true for all pipelines. Why have it here? * If a query pipeline start with a match clause, then the first match stage is given the empty row `{}` as its only input. * For each input row, the match stage outputs all combinations of data for its xref:{page-version}@reference::typeql/data-model.adoc#modes[output variables] (i.e., those variables that have not already been bound in earlier stages, and which are not xref:{page-version}@reference::typeql/data-model.adoc#modes[internal] to the stage). * It passes each output together with its inputs as a combined row to the next stage. @@ -89,3 +89,4 @@ match select $type, $value; ---- +// TODO: The VIP example doesn't work in TypeQL any more. \ No newline at end of file diff --git a/reference/modules/ROOT/pages/typeql/pipelines/update.adoc b/reference/modules/ROOT/pages/typeql/pipelines/update.adoc index 6deba1f91..b5a9a4cd3 100644 --- a/reference/modules/ROOT/pages/typeql/pipelines/update.adoc +++ b/reference/modules/ROOT/pages/typeql/pipelines/update.adoc @@ -22,11 +22,11 @@ Role tags can be omitted if there is only a single role the role player can play Update stages cannot bind new variables. -If there is no data to existing replace, the operation is equivalent to xref:{page-version}@reference::typeql/pipelines/insert.adoc[insert]. +If there is no existing data to replace, the operation is equivalent to xref:{page-version}@reference::typeql/pipelines/insert.adoc[insert]. == Execution -The update stage must be preceded by other stages. The body of the update stage is executed once for each input row. The output is then a stream equivalent to the input rows, as no variables are modified. +The update stage must be preceded by other stages. The body of the update stage is executed once for each input row. In case multiple rows will update the same data, only the last update will persist. The output is then a stream equivalent to the input rows, as no variables are modified. == Validation diff --git a/reference/modules/ROOT/pages/typeql/pipelines/with.adoc b/reference/modules/ROOT/pages/typeql/pipelines/with.adoc index 0e75293eb..de184c287 100644 --- a/reference/modules/ROOT/pages/typeql/pipelines/with.adoc +++ b/reference/modules/ROOT/pages/typeql/pipelines/with.adoc @@ -1,13 +1,17 @@ -= With stage += Preamble -The `with` stage in a data pipeline allows the local declaration of functions, which can then be used as part of the pipeline. +The preamble of a pipeline allows the local declaration of functions using `with` statements. +These functions can be called from the pipeline, and from other premable functions. == Syntax [,typeql] ---- with -... # continue pipeline, may call functions in patterns +[with ] +... + + ---- where `` is a xref:{page-version}@reference::typeql/functions/writing.adoc#declaration[function declaration]. @@ -15,8 +19,8 @@ where `` is a xref:{page-version}@reference::typeql/functi == Behavior // TODO: is this true? -* The `with` stages in a data pipeline must precede any other kind of stage (together, all `with` stages are referred to as the pipeline *preamble*) -* `with` stages *must* be followed by other data pipeline stages, i.e. `with` stages by themselves do not consitute a valid data pipeline. +* The `with` declarations in a data pipeline must precede the pipeline. +* `with` declarations *must* be followed by a data pipeline, i.e. `with` stages by themselves do not consitute a valid data query. * Function declarations in the preamble of a data pipeline are only valid within that pipeline (declared functions may be called in `match` and `fetch` stages). == Validation diff --git a/reference/modules/ROOT/pages/typeql/schema/redefine.adoc b/reference/modules/ROOT/pages/typeql/schema/redefine.adoc index 9a216b6f5..06dc34393 100644 --- a/reference/modules/ROOT/pages/typeql/schema/redefine.adoc +++ b/reference/modules/ROOT/pages/typeql/schema/redefine.adoc @@ -62,7 +62,7 @@ redefine email value string @regex("^.*@typedb\.com$"); .Redefining type interface's annotation with arguments [,typeql] ---- -redefine redefine post owns tag @card(0..5); +redefine post owns tag @card(0..5); ---- .Redefining relates specialization diff --git a/reference/modules/ROOT/pages/typeql/statements/contains.adoc b/reference/modules/ROOT/pages/typeql/statements/contains.adoc deleted file mode 100644 index 01701fa19..000000000 --- a/reference/modules/ROOT/pages/typeql/statements/contains.adoc +++ /dev/null @@ -1 +0,0 @@ -= `contains` statement diff --git a/reference/modules/ROOT/pages/typeql/statements/fun.adoc b/reference/modules/ROOT/pages/typeql/statements/fun.adoc index d0ab8d911..e49056a53 100644 --- a/reference/modules/ROOT/pages/typeql/statements/fun.adoc +++ b/reference/modules/ROOT/pages/typeql/statements/fun.adoc @@ -1,2 +1,4 @@ = `fun` statement :page-aliases: {page-version}@reference::typeql/statements/rule.adoc + +// TODO \ No newline at end of file diff --git a/reference/modules/ROOT/pages/typeql/statements/index.adoc b/reference/modules/ROOT/pages/typeql/statements/index.adoc index b8d168bba..c6aa2b5bc 100644 --- a/reference/modules/ROOT/pages/typeql/statements/index.adoc +++ b/reference/modules/ROOT/pages/typeql/statements/index.adoc @@ -41,7 +41,7 @@ The comma separation is required before a `` if its `` alrea [NOTE] ==== -The first two predicates in the example above do not require a comma. +The first predicates in the example above do not require a comma. However, every simple statement can be separated by commas if preferred. ==== @@ -212,16 +212,10 @@ Used to assign a stream or list element to a variable. Used to specify that two variables represent the same data instance. **** -.xref:{page-version}@reference::typeql/statements/contains.adoc[] +.xref:{page-version}@reference::typeql/statements/comparisons.adoc[] [.clickable] **** -Used to specify that a stream or list contains a data instance. -**** - -.xref:{page-version}@reference::typeql/statements/like.adoc[] -[.clickable] -**** -Used to specify that a string matches a specified regex pattern +Equality, inequality, and string comparisons between values. **** -- diff --git a/reference/modules/ROOT/pages/typeql/statements/isa.adoc b/reference/modules/ROOT/pages/typeql/statements/isa.adoc index aef249f42..72db51e96 100644 --- a/reference/modules/ROOT/pages/typeql/statements/isa.adoc +++ b/reference/modules/ROOT/pages/typeql/statements/isa.adoc @@ -38,7 +38,7 @@ The `isa!` keyword can be used to match all instances of a type _excluding subty match $person isa! person; ---- -=== Matching owner types +=== Matching types of an instance The `isa` keyword can be used to match all types of an instance. diff --git a/reference/modules/ROOT/pages/typeql/statements/like.adoc b/reference/modules/ROOT/pages/typeql/statements/like.adoc deleted file mode 100644 index eb08bcf6c..000000000 --- a/reference/modules/ROOT/pages/typeql/statements/like.adoc +++ /dev/null @@ -1 +0,0 @@ -= `like` statement diff --git a/reference/modules/ROOT/partials/typeql/nav.adoc b/reference/modules/ROOT/partials/typeql/nav.adoc index bd0ac4bbb..1db0ebc26 100644 --- a/reference/modules/ROOT/partials/typeql/nav.adoc +++ b/reference/modules/ROOT/partials/typeql/nav.adoc @@ -43,8 +43,6 @@ *** xref:{page-version}@reference::typeql/statements/is.adoc[is] *** xref:{page-version}@reference::typeql/statements/let-eq.adoc[let ... =] *** xref:{page-version}@reference::typeql/statements/let-in.adoc[let ... in] -*** xref:{page-version}@reference::typeql/statements/contains.adoc[contains] -*** xref:{page-version}@reference::typeql/statements/like.adoc[like] *** xref:{page-version}@reference::typeql/statements/label.adoc[label] *** xref:{page-version}@reference::typeql/statements/iid.adoc[iid] *** xref:{page-version}@reference::typeql/statements/comparisons.adoc[] From 974d5d68aa6ceab216d00dc4a29fedbac48f426e Mon Sep 17 00:00:00 2001 From: Krishnan Govindraj Date: Fri, 8 Aug 2025 15:38:08 +0200 Subject: [PATCH 02/17] low hanging fruit from self review --- .../ROOT/pages/typeql/pipelines/insert.adoc | 1 - .../ROOT/pages/typeql/pipelines/limit.adoc | 3 +-- .../ROOT/pages/typeql/pipelines/match.adoc | 6 ++--- .../ROOT/pages/typeql/statements/fun.adoc | 26 ++++++++++++++++++- 4 files changed, 28 insertions(+), 8 deletions(-) diff --git a/reference/modules/ROOT/pages/typeql/pipelines/insert.adoc b/reference/modules/ROOT/pages/typeql/pipelines/insert.adoc index 8c0c9b673..303ce3a75 100644 --- a/reference/modules/ROOT/pages/typeql/pipelines/insert.adoc +++ b/reference/modules/ROOT/pages/typeql/pipelines/insert.adoc @@ -35,7 +35,6 @@ The output is then a stream of input rows extended with the newly inserted value [#_validation] == Validation -// TODO: The first 3 can be type-inference errors, do they need to fail the transaction? Attempting to insert the following fail immediately and terminate the transaction: * an instance of an xref:{page-version}@reference::typeql/annotations/abstract.adoc[abstract] type, diff --git a/reference/modules/ROOT/pages/typeql/pipelines/limit.adoc b/reference/modules/ROOT/pages/typeql/pipelines/limit.adoc index dd9623953..7a9ebecb3 100644 --- a/reference/modules/ROOT/pages/typeql/pipelines/limit.adoc +++ b/reference/modules/ROOT/pages/typeql/pipelines/limit.adoc @@ -13,7 +13,6 @@ limit ; == Example Match all friends of friends of a given person, sorted by the number of mutual friends, highest to lowest. Return first 10. -// TODO: Are we missing a desc? [,typeql] ---- match @@ -22,6 +21,6 @@ match friendship (friend: $friend, friend: $possible-friend); not { friendship (friend: $person, friend: $possible-friend); }; reduce $num-mutuals = count($friend) within $possible-friend; -sort $num-mutuals; +sort $num-mutuals desc; limit 10; ---- diff --git a/reference/modules/ROOT/pages/typeql/pipelines/match.adoc b/reference/modules/ROOT/pages/typeql/pipelines/match.adoc index 636bba871..d114ea88b 100644 --- a/reference/modules/ROOT/pages/typeql/pipelines/match.adoc +++ b/reference/modules/ROOT/pages/typeql/pipelines/match.adoc @@ -70,13 +70,13 @@ match ---- -1. Find users that are either VIP, or are admins with access level > 9000, in which case we also want to retrieve their exact access level. +1. Find users that are either VIP, or are admins with access level > 9000. + [,typeql] ---- match $x isa user; - { $x isa VIP; } or { $x isa admin, has access-level $lvl; $lvl > 9000; }; + { $x isa VIP; } or { $x isa admin, has access-level > 9000; }; ---- 1. Find all attributes that are set for a specific user, return them together with their type; @@ -88,5 +88,3 @@ match $x has $type $value; select $type, $value; ---- - -// TODO: The VIP example doesn't work in TypeQL any more. \ No newline at end of file diff --git a/reference/modules/ROOT/pages/typeql/statements/fun.adoc b/reference/modules/ROOT/pages/typeql/statements/fun.adoc index e49056a53..1720368ba 100644 --- a/reference/modules/ROOT/pages/typeql/statements/fun.adoc +++ b/reference/modules/ROOT/pages/typeql/statements/fun.adoc @@ -1,4 +1,28 @@ = `fun` statement :page-aliases: {page-version}@reference::typeql/statements/rule.adoc -// TODO \ No newline at end of file +The `fun` keyword is used to define & undefine xref:reference::typeql/functions/index.adoc[]. + +A function can be defined as follows: +[,typeql] +---- +define +fun () -> : + + +---- + +A function can be undefined using: +---- +undefine fun ; +---- + + +A function's signature and implementation can be re-defined as follows: +[,typeql] +---- +redefine +fun () -> : + + +---- From 0697d5dc0315819bfbedfa75b4f1a3f45e7c7e7b Mon Sep 17 00:00:00 2001 From: Krishnan Govindraj Date: Mon, 11 Aug 2025 13:21:25 +0200 Subject: [PATCH 03/17] Write up Optional pattern reference --- .../ROOT/pages/typeql/patterns/optionals.adoc | 95 ++++++++++++++++++- .../ROOT/pages/typeql/statements/fun.adoc | 1 - 2 files changed, 93 insertions(+), 3 deletions(-) diff --git a/reference/modules/ROOT/pages/typeql/patterns/optionals.adoc b/reference/modules/ROOT/pages/typeql/patterns/optionals.adoc index 4277c645c..9b9455ae1 100644 --- a/reference/modules/ROOT/pages/typeql/patterns/optionals.adoc +++ b/reference/modules/ROOT/pages/typeql/patterns/optionals.adoc @@ -1,7 +1,98 @@ = Optionals -// TODO + +Optional patterns can be used in `match` stages to optionally match a pattern, +or in `insert` stages to insert a pattern *if* all the variables involved are bound. + +== Syntax & Basic behaviour +[,typeql] +---- +try { }; +---- + +=== match +Variables which are present only in the `try` block are considered optional. +If the *entire* optional pattern matches the data, it returns an answer per match. +If it has no matches, it produces a single answer with all optional variables bound to `None`. + +[,typeql] +---- +match + $person isa person; + try { + $_ isa marriage, links (spouse: $person, spouse: $spouse); + }; +---- + + +=== insert +Optional insert patterns will execute only if ALL variables present in them are bound. + +[,typeql] +---- +match + $person isa person; + try { + $_ isa marriage, links (spouse: $person, spouse: $spouse); + }; +insert + $policy isa policy; + $policy links (covered: $person); + try { $policy links (covered: $spouse); }; +---- [NOTE] ==== -Coming soon. +Optional patterns are banned in `put` stages. ==== + +== Behaviour in match clauses +=== Single origin +In the stage that it first occurs, An optional variable may only occur in a single try-block. +[,typeql] +---- +match + $person isa person; + try { + $_ isa marriage, links (spouse: $person, spouse: $spouse); + }; + try { + $policy isa policy, links (covered: $spouse); # Invalid + }; +---- + +=== Optional variables in subsequent stages +An optional variable can be used in subsequent stages. +An unbound optional variable will cause the pattern to fail. + +The following is a valid way to express the intent of the example above: +[,typeql] +---- +match + $person isa person; + try { + $_ isa marriage, links (spouse: $person, spouse: $spouse); + }; +match + try { + $policy isa policy, links (covered: $spouse); + }; +---- + + +=== Nested try blocks +Optional patterns can be nested. This is also an option for the previous example +[,typeql] +---- +match + $person isa person; + try { + $_ isa marriage, links (spouse: $person, spouse: $spouse); + try { + $policy isa policy, links (covered: $spouse); # Ok + }; + }; +---- + +=== Disallowed in negations +Optional patterns may not occur in negations, as they can have no effect on the result of the query - +they can neither fail the pattern, nor bind any variables for use outside the negation. diff --git a/reference/modules/ROOT/pages/typeql/statements/fun.adoc b/reference/modules/ROOT/pages/typeql/statements/fun.adoc index 1720368ba..1ff2856db 100644 --- a/reference/modules/ROOT/pages/typeql/statements/fun.adoc +++ b/reference/modules/ROOT/pages/typeql/statements/fun.adoc @@ -17,7 +17,6 @@ A function can be undefined using: undefine fun ; ---- - A function's signature and implementation can be re-defined as follows: [,typeql] ---- From 3e67df5b48ad29309f4274842a685c72da7c8100 Mon Sep 17 00:00:00 2001 From: Krishnan Govindraj Date: Mon, 11 Aug 2025 16:01:32 +0200 Subject: [PATCH 04/17] Expand expressions index.adoc --- .../ROOT/pages/typeql/expressions/index.adoc | 28 +++++++++++++++++-- 1 file changed, 26 insertions(+), 2 deletions(-) diff --git a/reference/modules/ROOT/pages/typeql/expressions/index.adoc b/reference/modules/ROOT/pages/typeql/expressions/index.adoc index 03eb4e1ab..a7c8b6fda 100644 --- a/reference/modules/ROOT/pages/typeql/expressions/index.adoc +++ b/reference/modules/ROOT/pages/typeql/expressions/index.adoc @@ -1,10 +1,34 @@ = Expressions :page-aliases: {page-version}@typeql::expressions.adoc -This reference covers the usage of expressions in TypeQL. +A TypeQL expression uses operators and functions to +compute a value from other values. It uses the following syntax: +[,typeql] +---- +let = ; +---- +Examples: +[,typeql] +---- +let $x = 5; -// TODO: This article is a stub. +let $y = $x * 3.1; +let $z = ceil($y + 1); +---- + +== Validation +The following rules apply to variables involved in expressions: + +* The variables used in the right-hand side of an expression must be bound to either attribute or values. +* The attribute may be of various attribute-types as long as they all have the same value-type. +* A value variable must be assigned to exactly once. + +During compilation, the types of every subexpression is resolved and the expression-tree is constructed. +If any function which is passed an argument which does not match the expected type, +or any operator which is not defined for the given combination of types, will fail compilation with an error. + +== Explore expressions [cols-3] -- .xref:{page-version}@reference::typeql/expressions/literals.adoc[] From 5906282d5e363bad4fbca5ede5a6cf6b22d80576 Mon Sep 17 00:00:00 2001 From: Krishnan Govindraj Date: Mon, 11 Aug 2025 16:01:44 +0200 Subject: [PATCH 05/17] Add TODO in functions page --- reference/modules/ROOT/pages/typeql/functions/index.adoc | 2 ++ 1 file changed, 2 insertions(+) diff --git a/reference/modules/ROOT/pages/typeql/functions/index.adoc b/reference/modules/ROOT/pages/typeql/functions/index.adoc index 9b563a68a..2e392f8a3 100644 --- a/reference/modules/ROOT/pages/typeql/functions/index.adoc +++ b/reference/modules/ROOT/pages/typeql/functions/index.adoc @@ -43,6 +43,8 @@ type signature `... -> { A, B }` returns stream `{ $a, $b }` |=== +// TODO: Compare to rules + == Explore functions [cols-3] From 9e192862696e31ad0b5e2ba781e3b10e056b9daa Mon Sep 17 00:00:00 2001 From: Krishnan Govindraj Date: Mon, 11 Aug 2025 16:55:29 +0200 Subject: [PATCH 06/17] Small updates for variable scoping --- .../pages/typeql/patterns/disjunctions.adoc | 205 +++++++++++------- .../ROOT/pages/typeql/patterns/index.adoc | 1 + .../ROOT/pages/typeql/patterns/optionals.adoc | 4 +- 3 files changed, 132 insertions(+), 78 deletions(-) diff --git a/reference/modules/ROOT/pages/typeql/patterns/disjunctions.adoc b/reference/modules/ROOT/pages/typeql/patterns/disjunctions.adoc index a22899960..91ecdfc13 100644 --- a/reference/modules/ROOT/pages/typeql/patterns/disjunctions.adoc +++ b/reference/modules/ROOT/pages/typeql/patterns/disjunctions.adoc @@ -10,7 +10,7 @@ Disjunctive patterns can be used in `match` stages. They allow queries to match { } or { } [ or { } ... ] ; ---- -The individual blocks `{ }` of a disjunction are called it *branches*. +The individual blocks `{ }` of a disjunction are called its *branches*. [NOTE] ==== @@ -25,105 +25,160 @@ Moreover, since disjunctions are themselves patterns, they can also be nested, e ---- { } or { - { } - or { }; + { } or { }; }; ---- ==== == Behavior +A disjunction pattern is satisfied if one of its branches is satisfied. -// TODO: needs update. Do not merge - -Disjunctions may appear in `match` stages, where they behave as follows. - -* *Optionality*. An output variable whose xref:{page-version}@reference::typeql/patterns/index.adoc[scope] is the branch of a disjunction becomes an xref:{page-version}@reference::typeql/data-model.adoc[optional] variable. This means the variable may be left empty `()` in the output of the match stage. For example: -+ --- +=== Variable scopes +A variable which appears in every branch will appear in the answers to the disjunction, +and is considered to be in the scope of the parent pattern. +Results to the following query will contain answers for `$x` and `$id`: [,typeql] ---- match $x isa $user; - { $x has email $e; } or { $x has phone $p; }; -select $e, $p; + { $x has email $id; } or { $x has phone $id; }; ---- -will return users that have either mobile phone or email attributes. The output rows of this match stage may be of the form ----- -{ $e="some@other.com", $p=() } -{ $e=(), $p="+1234" } -{ $e=(), $p="+1235" } -{ $e="none@other.com", $p=() } ----- --- -* *Satisfaction*. A disjunction pattern is satisfied if one of its branches is satisfied, while variables bound in the other branches are left empty. For example, -+ --- +A variable which occurs in only one branch AND not outside the disjunction is considered local to the branch. +Results to the following query will only contain answers for `$x`: [,typeql] ---- match $x isa $user; - { $x has email $e; } or { $x has phone $p; } or { $x has address $a; } ----- -may output ----- -{ $e="some@other.com", $p=(), $a=() } -{ $e=(), $p="+1234", $a=() } -{ $e=(), $p=(), $a="1 Big Street, New City, NC1234" } ----- -but will never output ----- -{ $e=(), $p="+1234", $a="1 Big Street, New City, NC1234" } ----- --- - -* *Deduplication*. Outputs do not get duplicated if they satisfy multiple branches of the disjunction at the same time (in other words, branches are not executed "one after the other"). For example, the query -+ --- -[,typeql] ----- -match - $x isa $user; $y isa $user; - { following(follower: $x, followed: $y); } - or { following(follower: $y, followed:$x); }; ----- -will output each `{ $x=..., $y=... }` row exactly once, even if both `$x` follows `$y` and `$y` follows `$x`. ----- -{ $x=0x1, $y=0x3 } -{ $x=0x7, $y=0x2 } + { $x has email $e; } or { $x has phone $p; }; ---- -where each row satisfies both branches at the same time. --- -== Validation - -Recall that each variable must have a xref:{page-version}@reference::typeql/patterns/index.adoc[unique scope]. Therefore, the following pattern would be invalid. +In line with the unique scope principle, a variable which is local to more than one pattern is invalid. +The following query is invalid as $e has multiple scopes. [,typeql] ---- match $x isa $user; - { following(follower: $x, followed: $y); } - or { following(follower: $y, followed:$x); }; ----- -Indeed, the variable `$y` does _not_ have a unique scope: it appears at the top-level of both branches of the disjunction. + { $x has email $e; } or { $x has phone $p; }; + not { $e contains "@typedb.com"; }; +---- + + + + + +// [,typeql] +// ---- +// match +// $x isa $user; +// { $x has email $e; } or { $x has phone $p; }; +// select $e, $p; +// ---- + + +// An output variable whose xref:{page-version}@reference::typeql/patterns/index.adoc[scope] is the branch of a disjunction becomes an xref:{page-version}@reference::typeql/data-model.adoc[optional] variable. This means the variable may be left empty `()` in the output of the match stage. For example: +// +// -- +// [,typeql] +// ---- +// match +// $x isa $user; +// { $x has email $e; } or { $x has phone $p; }; +// select $e, $p; +// ---- +// will return users that have either mobile phone or email attributes. The output rows of this match stage may be of the form +// ---- +// { $e="some@other.com", $p=() } +// { $e=(), $p="+1234" } +// { $e=(), $p="+1235" } +// { $e="none@other.com", $p=() } +// ---- +// -- + +// === Satisfaction +// A disjunction pattern is satisfied if one of its branches is satisfied, while variables bound in the other branches are left empty. +// For example, +// +// -- +// [,typeql] +// ---- +// match +// $x isa $user; +// { $x has email $e; } or { $x has phone $p; } or { $x has address $a; } +// ---- +// may output +// ---- +// { $e="some@other.com", $p=(), $a=() } +// { $e=(), $p="+1234", $a=() } +// { $e=(), $p=(), $a="1 Big Street, New City, NC1234" } +// ---- +// but will never output +// ---- +// { $e=(), $p="+1234", $a="1 Big Street, New City, NC1234" } +// ---- +// -- +// +// * *Deduplication*. Outputs do not get duplicated if they satisfy multiple branches of the disjunction at the same time (in other words, branches are not executed "one after the other"). For example, the query +// + +// -- +// [,typeql] +// ---- +// match +// $x isa $user; $y isa $user; +// { following(follower: $x, followed: $y); } +// or { following(follower: $y, followed:$x); }; +// ---- +// will output each `{ $x=..., $y=... }` row exactly once, even if both `$x` follows `$y` and `$y` follows `$x`. +// ---- +// { $x=0x1, $y=0x3 } +// { $x=0x7, $y=0x2 } +// ---- +// where each row satisfies both branches at the same time. +// -- +// +// == Validation +// +// Recall that each variable must have a xref:{page-version}@reference::typeql/patterns/index.adoc[unique scope]. Therefore, the following pattern would be invalid. +// [,typeql] +// ---- +// match +// $x isa $user; +// { following(follower: $x, followed: $y); } +// or { following(follower: $y, followed:$x); }; +// ---- +// Indeed, the variable `$y` does _not_ have a unique scope: it appears at the top-level of both branches of the disjunction. +// +// == Examples +// +// 1. Retrieve phone numbers of a specific user _if available_: +// + +// -- +// [,typeql] +// ---- +// match +// $x isa user, has username "john_1"; +// { $x has phone $p; } or { not { $x has phone $np; }; }; +// ---- +// Note that `$p` and `$np` have different variable names to ensure the xref:{page-version}@reference::typeql/patterns/index.adoc[unique scope principle]. +// -- +// +// 1. Retrieve friends and friends of friends of a user; +// + +// -- +// [,typeql] +// ---- +// match +// $x isa user, has username "john_1"; +// $y isa user; +// { friendship($x, $y); } +// or { friendship($x, $z); friendship($z, $y); }; +// select $x, $y; # omit $z from results +// ---- +// -- == Examples - -1. Retrieve phone numbers of a specific user _if available_: -+ --- -[,typeql] ----- -match - $x isa user, has username "john_1"; - { $x has phone $p; } or { not { $x has phone $np; }; }; ----- -Note that `$p` and `$np` have different variable names to ensure the xref:{page-version}@reference::typeql/patterns/index.adoc[unique scope principle]. --- - 1. Retrieve friends and friends of friends of a user; + --- [,typeql] ---- match @@ -131,6 +186,4 @@ match $y isa user; { friendship($x, $y); } or { friendship($x, $z); friendship($z, $y); }; -select $x, $y; # omit $z from results ---- --- diff --git a/reference/modules/ROOT/pages/typeql/patterns/index.adoc b/reference/modules/ROOT/pages/typeql/patterns/index.adoc index 01d697731..0973c111f 100644 --- a/reference/modules/ROOT/pages/typeql/patterns/index.adoc +++ b/reference/modules/ROOT/pages/typeql/patterns/index.adoc @@ -8,6 +8,7 @@ This reference covers the usage of patterns in TypeQL. Pattern comprise statements containing variables. Given a pattern, the *scope* of a variable is: * the block `{ ... }` in which variable appears at top-level (i.e., not nested in further `{...}`) but it does not appear outside of the block, +- Exceptionally, if the variable appears in all branches of a disjunction, it counts as appearing in the parent conjunction. * or, the entire pattern itself if the variable appears at the top-level of the pattern itself. A key principle of valid TypeQL pattern is: diff --git a/reference/modules/ROOT/pages/typeql/patterns/optionals.adoc b/reference/modules/ROOT/pages/typeql/patterns/optionals.adoc index 9b9455ae1..27505cc84 100644 --- a/reference/modules/ROOT/pages/typeql/patterns/optionals.adoc +++ b/reference/modules/ROOT/pages/typeql/patterns/optionals.adoc @@ -3,7 +3,7 @@ Optional patterns can be used in `match` stages to optionally match a pattern, or in `insert` stages to insert a pattern *if* all the variables involved are bound. -== Syntax & Basic behaviour +== Syntax & Basic behavior [,typeql] ---- try { }; @@ -45,7 +45,7 @@ insert Optional patterns are banned in `put` stages. ==== -== Behaviour in match clauses +== Behavior in match clauses === Single origin In the stage that it first occurs, An optional variable may only occur in a single try-block. [,typeql] From d1be311fe1bbe856f0c7930d7dd5752461b6cca6 Mon Sep 17 00:00:00 2001 From: Krishnan Govindraj Date: Tue, 12 Aug 2025 11:42:34 +0200 Subject: [PATCH 07/17] Patterns index update --- reference/modules/ROOT/pages/typeql/patterns/index.adoc | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/reference/modules/ROOT/pages/typeql/patterns/index.adoc b/reference/modules/ROOT/pages/typeql/patterns/index.adoc index 0973c111f..30d45a431 100644 --- a/reference/modules/ROOT/pages/typeql/patterns/index.adoc +++ b/reference/modules/ROOT/pages/typeql/patterns/index.adoc @@ -3,8 +3,7 @@ This reference covers the usage of patterns in TypeQL. -== Scopes and operations -// TODO: Must update. +== Scopes Pattern comprise statements containing variables. Given a pattern, the *scope* of a variable is: * the block `{ ... }` in which variable appears at top-level (i.e., not nested in further `{...}`) but it does not appear outside of the block, @@ -15,9 +14,9 @@ A key principle of valid TypeQL pattern is: > *_Every variable must have a unique scope._* -While a statement by itself is an (elementary) patterns, *operations* allow us to construct larger and more interesting patterns from smaller ones, and they create new scopes of variables. +== Operations -== Operation reference +While a statement by itself is an (elementary) patterns, *operations* allow us to construct larger and more interesting patterns from smaller ones, and they create new scopes of variables. [cols-3] -- From 3345566348f1e0daf08cdcd8ab3f7839d051e22b Mon Sep 17 00:00:00 2001 From: Krishnan Govindraj Date: Tue, 12 Aug 2025 11:46:43 +0200 Subject: [PATCH 08/17] Add optionals to index of patterns --- reference/modules/ROOT/pages/typeql/patterns/index.adoc | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/reference/modules/ROOT/pages/typeql/patterns/index.adoc b/reference/modules/ROOT/pages/typeql/patterns/index.adoc index 30d45a431..aeb14a18b 100644 --- a/reference/modules/ROOT/pages/typeql/patterns/index.adoc +++ b/reference/modules/ROOT/pages/typeql/patterns/index.adoc @@ -37,4 +37,10 @@ Use of disjunctions to allow for several branches in a query to be executed in p **** Use of negations to exclude patterns from your query results. **** --- + +.xref:{page-version}@reference::typeql/patterns/optionals.adoc[] +[.clickable] +**** +Use of optionals for optionally matching subpatterns. +**** +-- \ No newline at end of file From eb2198666b4a533655bdc5b661b4a2678c1a49bb Mon Sep 17 00:00:00 2001 From: Krishnan Govindraj Date: Tue, 12 Aug 2025 12:11:09 +0200 Subject: [PATCH 09/17] More optionals text --- reference/modules/ROOT/pages/typeql/patterns/optionals.adoc | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/reference/modules/ROOT/pages/typeql/patterns/optionals.adoc b/reference/modules/ROOT/pages/typeql/patterns/optionals.adoc index 27505cc84..049a74472 100644 --- a/reference/modules/ROOT/pages/typeql/patterns/optionals.adoc +++ b/reference/modules/ROOT/pages/typeql/patterns/optionals.adoc @@ -22,7 +22,8 @@ match $_ isa marriage, links (spouse: $person, spouse: $spouse); }; ---- - +Here, `$spouse` will be bound to the spouse if `$person` is in a `marriage`. +Else, `$spouse` will be bound to `None` === insert Optional insert patterns will execute only if ALL variables present in them are bound. @@ -39,6 +40,8 @@ insert $policy links (covered: $person); try { $policy links (covered: $spouse); }; ---- +If `$person` is in a marriage, the match stage will bind `$spouse` +and the insert stage will add them to the policy. [NOTE] ==== From 0d505397208a8fd630393da42c28f127e8833fd9 Mon Sep 17 00:00:00 2001 From: Krishnan Govindraj Date: Tue, 12 Aug 2025 13:46:00 +0200 Subject: [PATCH 10/17] Remove some TODOs --- .../ROOT/pages/typeql/entities-relations-attributes.adoc | 1 - core-concepts/modules/ROOT/pages/typeql/index.adoc | 1 - reference/modules/ROOT/pages/typeql/functions/index.adoc | 2 -- reference/modules/ROOT/pages/typeql/pipelines/match.adoc | 1 - reference/modules/ROOT/pages/typeql/pipelines/with.adoc | 1 - 5 files changed, 6 deletions(-) diff --git a/core-concepts/modules/ROOT/pages/typeql/entities-relations-attributes.adoc b/core-concepts/modules/ROOT/pages/typeql/entities-relations-attributes.adoc index b58c4ece2..4ac105bba 100644 --- a/core-concepts/modules/ROOT/pages/typeql/entities-relations-attributes.adoc +++ b/core-concepts/modules/ROOT/pages/typeql/entities-relations-attributes.adoc @@ -1,6 +1,5 @@ = Entities, Relations, Attributes :page-aliases: {page-version}@typeql::data_model.adoc -// TODO: Out links to manual / fundamentals articles TypeDB implements the Polymorphic Entity-Relation-Attribute (PERA) data model. A TypeDB schema defines a hierarchy of these types and how they interact with each other through interface types. diff --git a/core-concepts/modules/ROOT/pages/typeql/index.adoc b/core-concepts/modules/ROOT/pages/typeql/index.adoc index 9d4bde56d..4927a6228 100644 --- a/core-concepts/modules/ROOT/pages/typeql/index.adoc +++ b/core-concepts/modules/ROOT/pages/typeql/index.adoc @@ -21,7 +21,6 @@ The relevant sections of the reference are linked at the end of each page. [.clickable] **** A gentle introduction to the PERA data model - Entities, relations, attributes -// TODO: Or: Introduces the TypeQL data model - entities, relations, and attributes - and what it means to "own" attributes and "play" roles in relations. **** diff --git a/reference/modules/ROOT/pages/typeql/functions/index.adoc b/reference/modules/ROOT/pages/typeql/functions/index.adoc index 2e392f8a3..9b563a68a 100644 --- a/reference/modules/ROOT/pages/typeql/functions/index.adoc +++ b/reference/modules/ROOT/pages/typeql/functions/index.adoc @@ -43,8 +43,6 @@ type signature `... -> { A, B }` returns stream `{ $a, $b }` |=== -// TODO: Compare to rules - == Explore functions [cols-3] diff --git a/reference/modules/ROOT/pages/typeql/pipelines/match.adoc b/reference/modules/ROOT/pages/typeql/pipelines/match.adoc index d114ea88b..605a9676c 100644 --- a/reference/modules/ROOT/pages/typeql/pipelines/match.adoc +++ b/reference/modules/ROOT/pages/typeql/pipelines/match.adoc @@ -13,7 +13,6 @@ match where `` denotes a valid xref:{page-version}@reference::typeql/patterns/index.adoc[pattern]. == Behavior -// TODO: This should true for all pipelines. Why have it here? * If a query pipeline start with a match clause, then the first match stage is given the empty row `{}` as its only input. * For each input row, the match stage outputs all combinations of data for its xref:{page-version}@reference::typeql/data-model.adoc#modes[output variables] (i.e., those variables that have not already been bound in earlier stages, and which are not xref:{page-version}@reference::typeql/data-model.adoc#modes[internal] to the stage). * It passes each output together with its inputs as a combined row to the next stage. diff --git a/reference/modules/ROOT/pages/typeql/pipelines/with.adoc b/reference/modules/ROOT/pages/typeql/pipelines/with.adoc index de184c287..a2dc96f98 100644 --- a/reference/modules/ROOT/pages/typeql/pipelines/with.adoc +++ b/reference/modules/ROOT/pages/typeql/pipelines/with.adoc @@ -18,7 +18,6 @@ where `` is a xref:{page-version}@reference::typeql/functi == Behavior -// TODO: is this true? * The `with` declarations in a data pipeline must precede the pipeline. * `with` declarations *must* be followed by a data pipeline, i.e. `with` stages by themselves do not consitute a valid data query. * Function declarations in the preamble of a data pipeline are only valid within that pipeline (declared functions may be called in `match` and `fetch` stages). From 00d865f0e5bf5df666b203ed9179105c299712f0 Mon Sep 17 00:00:00 2001 From: Krishnan Govindraj Date: Tue, 12 Aug 2025 15:40:30 +0200 Subject: [PATCH 11/17] Remove the use of operators to refer to connectives --- reference/modules/ROOT/pages/typeql/patterns/index.adoc | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/reference/modules/ROOT/pages/typeql/patterns/index.adoc b/reference/modules/ROOT/pages/typeql/patterns/index.adoc index aeb14a18b..7b92dad0d 100644 --- a/reference/modules/ROOT/pages/typeql/patterns/index.adoc +++ b/reference/modules/ROOT/pages/typeql/patterns/index.adoc @@ -14,9 +14,11 @@ A key principle of valid TypeQL pattern is: > *_Every variable must have a unique scope._* -== Operations +== Combining patterns -While a statement by itself is an (elementary) patterns, *operations* allow us to construct larger and more interesting patterns from smaller ones, and they create new scopes of variables. +TypeQL allows us to construct larger and more interesting patterns from smaller ones, +allowing us to express more than simple conjunctions. +They can also create new scopes of variables. [cols-3] -- From 97a83df8e3ea7783bce1988a7df3250ddf1b35b3 Mon Sep 17 00:00:00 2001 From: Krishnan Govindraj Date: Tue, 12 Aug 2025 15:51:35 +0200 Subject: [PATCH 12/17] PR suggestions --- core-concepts/modules/ROOT/pages/typeql/glossary.adoc | 2 +- .../modules/ROOT/pages/typeql/expressions/index.adoc | 6 +++--- .../modules/ROOT/pages/typeql/patterns/disjunctions.adoc | 8 ++++---- reference/modules/ROOT/pages/typeql/patterns/index.adoc | 5 +++-- reference/modules/ROOT/pages/typeql/pipelines/limit.adoc | 1 + 5 files changed, 12 insertions(+), 10 deletions(-) diff --git a/core-concepts/modules/ROOT/pages/typeql/glossary.adoc b/core-concepts/modules/ROOT/pages/typeql/glossary.adoc index faf1272e0..c9180b5f4 100644 --- a/core-concepts/modules/ROOT/pages/typeql/glossary.adoc +++ b/core-concepts/modules/ROOT/pages/typeql/glossary.adoc @@ -2,7 +2,7 @@ This page lists out terms reused across pages in this section, and links to where they are introduced. -A more complete list can be found in the xref:{page-version}@reference::typeql/keywords.adoc[] in the TypeQL reference. +A more complete list can be found in the xref:{page-version}@reference::typeql/keywords.adoc[TypeQL reference]. * xref:{page-version}@core-concepts::typeql/constraining-data.adoc#definition-annotation[Annotation]: Language fragments mainly used to add additional constraint to types. * xref:{page-version}@core-concepts::typeql/query-variables-patterns.adoc#definition-answer[Answer]: A mapping of variables to the concepts the pattern "matched" in the database. diff --git a/reference/modules/ROOT/pages/typeql/expressions/index.adoc b/reference/modules/ROOT/pages/typeql/expressions/index.adoc index a7c8b6fda..6acd0cc84 100644 --- a/reference/modules/ROOT/pages/typeql/expressions/index.adoc +++ b/reference/modules/ROOT/pages/typeql/expressions/index.adoc @@ -20,11 +20,11 @@ let $z = ceil($y + 1); == Validation The following rules apply to variables involved in expressions: -* The variables used in the right-hand side of an expression must be bound to either attribute or values. -* The attribute may be of various attribute-types as long as they all have the same value-type. +* The variables used on the right-hand side of an expression must be bound to either attributes or values. +* The attribute may be of various attribute types as long as they all have the same value-type. * A value variable must be assigned to exactly once. -During compilation, the types of every subexpression is resolved and the expression-tree is constructed. +During compilation, the types of every subexpression are resolved and the expression-tree is constructed. If any function which is passed an argument which does not match the expected type, or any operator which is not defined for the given combination of types, will fail compilation with an error. diff --git a/reference/modules/ROOT/pages/typeql/patterns/disjunctions.adoc b/reference/modules/ROOT/pages/typeql/patterns/disjunctions.adoc index 91ecdfc13..d3a621341 100644 --- a/reference/modules/ROOT/pages/typeql/patterns/disjunctions.adoc +++ b/reference/modules/ROOT/pages/typeql/patterns/disjunctions.adoc @@ -34,7 +34,7 @@ or { A disjunction pattern is satisfied if one of its branches is satisfied. === Variable scopes -A variable which appears in every branch will appear in the answers to the disjunction, +A variable that appears in every branch will appear in the answers to the disjunction, and is considered to be in the scope of the parent pattern. Results to the following query will contain answers for `$x` and `$id`: [,typeql] @@ -44,7 +44,7 @@ match { $x has email $id; } or { $x has phone $id; }; ---- -A variable which occurs in only one branch AND not outside the disjunction is considered local to the branch. +A variable that occurs in only one branch AND not outside the disjunction is considered local to the branch. Results to the following query will only contain answers for `$x`: [,typeql] ---- @@ -53,8 +53,8 @@ match { $x has email $e; } or { $x has phone $p; }; ---- -In line with the unique scope principle, a variable which is local to more than one pattern is invalid. -The following query is invalid as $e has multiple scopes. +In line with the unique scope principle, a variable that is local to more than one pattern is invalid. +The following query is invalid as `$e` has multiple scopes. [,typeql] ---- match diff --git a/reference/modules/ROOT/pages/typeql/patterns/index.adoc b/reference/modules/ROOT/pages/typeql/patterns/index.adoc index 7b92dad0d..4ff98b511 100644 --- a/reference/modules/ROOT/pages/typeql/patterns/index.adoc +++ b/reference/modules/ROOT/pages/typeql/patterns/index.adoc @@ -6,10 +6,11 @@ This reference covers the usage of patterns in TypeQL. == Scopes Pattern comprise statements containing variables. Given a pattern, the *scope* of a variable is: -* the block `{ ... }` in which variable appears at top-level (i.e., not nested in further `{...}`) but it does not appear outside of the block, -- Exceptionally, if the variable appears in all branches of a disjunction, it counts as appearing in the parent conjunction. +* the block `{ ... }` in which variable appears at top-level (i.e., not nested in further `{...}`) but it does not appear outside of the block. * or, the entire pattern itself if the variable appears at the top-level of the pattern itself. +Exceptionally, if the variable appears in all branches of a disjunction, it counts as appearing in the parent pattern. + A key principle of valid TypeQL pattern is: > *_Every variable must have a unique scope._* diff --git a/reference/modules/ROOT/pages/typeql/pipelines/limit.adoc b/reference/modules/ROOT/pages/typeql/pipelines/limit.adoc index 7a9ebecb3..b220d2311 100644 --- a/reference/modules/ROOT/pages/typeql/pipelines/limit.adoc +++ b/reference/modules/ROOT/pages/typeql/pipelines/limit.adoc @@ -13,6 +13,7 @@ limit ; == Example Match all friends of friends of a given person, sorted by the number of mutual friends, highest to lowest. Return first 10. + [,typeql] ---- match From 13f8cea673b77b47ffd2baeba52d0993b468d919 Mon Sep 17 00:00:00 2001 From: Krishnan Govindraj Date: Tue, 12 Aug 2025 15:53:39 +0200 Subject: [PATCH 13/17] Missed bits --- core-concepts/modules/ROOT/pages/typeql/schema-data.adoc | 2 +- reference/modules/ROOT/pages/typeql/expressions/index.adoc | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/core-concepts/modules/ROOT/pages/typeql/schema-data.adoc b/core-concepts/modules/ROOT/pages/typeql/schema-data.adoc index 1614c6859..0bf5407f2 100644 --- a/core-concepts/modules/ROOT/pages/typeql/schema-data.adoc +++ b/core-concepts/modules/ROOT/pages/typeql/schema-data.adoc @@ -26,7 +26,7 @@ insert ---- Inserting a new instance will fail if the type is abstract. In the case of attributes, -the value must also be of the value-type specified by the attribute, and satisfy all value constraints defined on the type. +the value must also be of the value type specified by the attribute, and satisfy all value constraints defined on the type. [#_iid] Remember that inserted entities and relations don't have a natural identifier in your domain unless you provide one. The caveat here is that TypeDB generates an instance ID (`iid`, which you'll see in output logs) for your inserted entities and relations. However, it is recommended that you create meaningful identifiers, especially keys, when needing to refer to specific entities or relations. diff --git a/reference/modules/ROOT/pages/typeql/expressions/index.adoc b/reference/modules/ROOT/pages/typeql/expressions/index.adoc index 6acd0cc84..3f5ef5703 100644 --- a/reference/modules/ROOT/pages/typeql/expressions/index.adoc +++ b/reference/modules/ROOT/pages/typeql/expressions/index.adoc @@ -21,10 +21,10 @@ let $z = ceil($y + 1); The following rules apply to variables involved in expressions: * The variables used on the right-hand side of an expression must be bound to either attributes or values. -* The attribute may be of various attribute types as long as they all have the same value-type. +* The attribute may be of various attribute types as long as they all have the same value type. * A value variable must be assigned to exactly once. -During compilation, the types of every subexpression are resolved and the expression-tree is constructed. +During compilation, the types of every subexpression are resolved, and the expression tree is constructed. If any function which is passed an argument which does not match the expected type, or any operator which is not defined for the given combination of types, will fail compilation with an error. From 662c1f59555782ce09237eb3e1f6482b7d754259 Mon Sep 17 00:00:00 2001 From: Krishnan Govindraj Date: Tue, 12 Aug 2025 15:56:29 +0200 Subject: [PATCH 14/17] Remove the commented out lines in favour of a comment with the sha --- .../pages/typeql/patterns/disjunctions.adoc | 115 +----------------- 1 file changed, 3 insertions(+), 112 deletions(-) diff --git a/reference/modules/ROOT/pages/typeql/patterns/disjunctions.adoc b/reference/modules/ROOT/pages/typeql/patterns/disjunctions.adoc index d3a621341..b22fe9824 100644 --- a/reference/modules/ROOT/pages/typeql/patterns/disjunctions.adoc +++ b/reference/modules/ROOT/pages/typeql/patterns/disjunctions.adoc @@ -63,118 +63,9 @@ match not { $e contains "@typedb.com"; }; ---- - - - - -// [,typeql] -// ---- -// match -// $x isa $user; -// { $x has email $e; } or { $x has phone $p; }; -// select $e, $p; -// ---- - - -// An output variable whose xref:{page-version}@reference::typeql/patterns/index.adoc[scope] is the branch of a disjunction becomes an xref:{page-version}@reference::typeql/data-model.adoc[optional] variable. This means the variable may be left empty `()` in the output of the match stage. For example: -// -// -- -// [,typeql] -// ---- -// match -// $x isa $user; -// { $x has email $e; } or { $x has phone $p; }; -// select $e, $p; -// ---- -// will return users that have either mobile phone or email attributes. The output rows of this match stage may be of the form -// ---- -// { $e="some@other.com", $p=() } -// { $e=(), $p="+1234" } -// { $e=(), $p="+1235" } -// { $e="none@other.com", $p=() } -// ---- -// -- - -// === Satisfaction -// A disjunction pattern is satisfied if one of its branches is satisfied, while variables bound in the other branches are left empty. -// For example, -// -// -- -// [,typeql] -// ---- -// match -// $x isa $user; -// { $x has email $e; } or { $x has phone $p; } or { $x has address $a; } -// ---- -// may output -// ---- -// { $e="some@other.com", $p=(), $a=() } -// { $e=(), $p="+1234", $a=() } -// { $e=(), $p=(), $a="1 Big Street, New City, NC1234" } -// ---- -// but will never output -// ---- -// { $e=(), $p="+1234", $a="1 Big Street, New City, NC1234" } -// ---- -// -- -// -// * *Deduplication*. Outputs do not get duplicated if they satisfy multiple branches of the disjunction at the same time (in other words, branches are not executed "one after the other"). For example, the query -// + -// -- -// [,typeql] -// ---- -// match -// $x isa $user; $y isa $user; -// { following(follower: $x, followed: $y); } -// or { following(follower: $y, followed:$x); }; -// ---- -// will output each `{ $x=..., $y=... }` row exactly once, even if both `$x` follows `$y` and `$y` follows `$x`. -// ---- -// { $x=0x1, $y=0x3 } -// { $x=0x7, $y=0x2 } -// ---- -// where each row satisfies both branches at the same time. -// -- -// -// == Validation -// -// Recall that each variable must have a xref:{page-version}@reference::typeql/patterns/index.adoc[unique scope]. Therefore, the following pattern would be invalid. -// [,typeql] -// ---- -// match -// $x isa $user; -// { following(follower: $x, followed: $y); } -// or { following(follower: $y, followed:$x); }; -// ---- -// Indeed, the variable `$y` does _not_ have a unique scope: it appears at the top-level of both branches of the disjunction. -// -// == Examples -// -// 1. Retrieve phone numbers of a specific user _if available_: -// + -// -- -// [,typeql] -// ---- -// match -// $x isa user, has username "john_1"; -// { $x has phone $p; } or { not { $x has phone $np; }; }; -// ---- -// Note that `$p` and `$np` have different variable names to ensure the xref:{page-version}@reference::typeql/patterns/index.adoc[unique scope principle]. -// -- -// -// 1. Retrieve friends and friends of friends of a user; -// + -// -- -// [,typeql] -// ---- -// match -// $x isa user, has username "john_1"; -// $y isa user; -// { friendship($x, $y); } -// or { friendship($x, $z); friendship($z, $y); }; -// select $x, $y; # omit $z from results -// ---- -// -- +// Note: A version of this document exists for the version of disjunctions +// that could return None values for branch-local variables. +// Revert to 19fb67756bfb76018315c6c7b380913683ca052c if needed (2025/08/08). == Examples 1. Retrieve friends and friends of friends of a user; From 67d1495549c1f3c8ead0c32f4ed3caa10f100e3e Mon Sep 17 00:00:00 2001 From: Krishnan Govindraj Date: Wed, 13 Aug 2025 11:58:38 +0200 Subject: [PATCH 15/17] Add delete stage to optionals ref --- reference/modules/ROOT/pages/typeql/patterns/optionals.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/reference/modules/ROOT/pages/typeql/patterns/optionals.adoc b/reference/modules/ROOT/pages/typeql/patterns/optionals.adoc index 049a74472..73090e768 100644 --- a/reference/modules/ROOT/pages/typeql/patterns/optionals.adoc +++ b/reference/modules/ROOT/pages/typeql/patterns/optionals.adoc @@ -25,8 +25,8 @@ match Here, `$spouse` will be bound to the spouse if `$person` is in a `marriage`. Else, `$spouse` will be bound to `None` -=== insert -Optional insert patterns will execute only if ALL variables present in them are bound. +=== insert & delete +Optional patterns in insert or delete stages will execute only if ALL the variables present in them are bound. [,typeql] ---- From 4c0d425ae3a69ea1c29d6f5e9678f87d69220461 Mon Sep 17 00:00:00 2001 From: Krishnan Govindraj Date: Wed, 13 Aug 2025 12:01:22 +0200 Subject: [PATCH 16/17] Fix up abstract --- reference/modules/ROOT/pages/typeql/annotations/abstract.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/modules/ROOT/pages/typeql/annotations/abstract.adoc b/reference/modules/ROOT/pages/typeql/annotations/abstract.adoc index dea96615a..00b5f1d79 100644 --- a/reference/modules/ROOT/pages/typeql/annotations/abstract.adoc +++ b/reference/modules/ROOT/pages/typeql/annotations/abstract.adoc @@ -20,7 +20,7 @@ The `@abstract` annotation does not accept any arguments. // tag::description[] When defined for a type, the `@abstract` annotation enforces the `abstract` constraint, making the type abstract. -An abstract type cannot be instantiated. but can be used in a query (e.g. in an `isa` constraint to refer to all its subtypes). +An abstract type cannot be instantiated, but can be used in a query (e.g. in an `isa` constraint to match instances of its subtypes). // end::description[] [,typeql] From 2550362e2c18e57ca404ffd20e9b3a45e35ea872 Mon Sep 17 00:00:00 2001 From: Krishnan Govindraj Date: Wed, 13 Aug 2025 12:02:14 +0200 Subject: [PATCH 17/17] Comma after e.g. --- reference/modules/ROOT/pages/typeql/annotations/abstract.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/modules/ROOT/pages/typeql/annotations/abstract.adoc b/reference/modules/ROOT/pages/typeql/annotations/abstract.adoc index 00b5f1d79..e0eb45794 100644 --- a/reference/modules/ROOT/pages/typeql/annotations/abstract.adoc +++ b/reference/modules/ROOT/pages/typeql/annotations/abstract.adoc @@ -20,7 +20,7 @@ The `@abstract` annotation does not accept any arguments. // tag::description[] When defined for a type, the `@abstract` annotation enforces the `abstract` constraint, making the type abstract. -An abstract type cannot be instantiated, but can be used in a query (e.g. in an `isa` constraint to match instances of its subtypes). +An abstract type cannot be instantiated, but can be used in a query (e.g., in an `isa` constraint to match instances of its subtypes). // end::description[] [,typeql]