Review TypeQL reference to ensure it is up to date #980

krishnangovindraj · 2025-08-07T11:25:24Z

Goal

Updates to TypeQL reference pages

Implementation

krishnangovindraj

Flag stuff to that needs to be done for myself

reference/modules/ROOT/pages/typeql/expressions/index.adoc

reference/modules/ROOT/pages/typeql/patterns/disjunctions.adoc

krishnangovindraj · 2025-08-07T20:37:18Z

reference/modules/ROOT/pages/typeql/patterns/index.adoc

@@ -3,7 +3,7 @@
 This reference covers the usage of patterns in TypeQL.

 == Scopes and operations
-
+// TODO: Must update.


TODO: This is actually the ideal state but I'm not sure we'll ever implement it.

reference/modules/ROOT/pages/typeql/patterns/optionals.adoc

krishnangovindraj · 2025-08-07T20:37:48Z

reference/modules/ROOT/pages/typeql/pipelines/delete.adoc

-delete ( <variable> | has <variable> of <variable> | links ( <variable> [ , ... ] ) of <variable> ); [ ... ]
+delete
+    ( <variable> | has <variable> of <variable> | links ( <variable> [ , ... ] ) of <variable> );
+    [ ... ]


Is this better or worse?

reference/modules/ROOT/pages/typeql/pipelines/limit.adoc

krishnangovindraj · 2025-08-07T20:39:18Z

reference/modules/ROOT/pages/typeql/pipelines/match.adoc

@@ -13,7 +13,7 @@ match <pattern>
 where `<pattern>` 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 we can say this, we don't need to akwardly mention that update & delete can't be the first stage in the pipelines.

reference/modules/ROOT/pages/typeql/pipelines/match.adoc

krishnangovindraj · 2025-08-07T20:40:23Z

reference/modules/ROOT/pages/typeql/pipelines/with.adoc

@@ -1,22 +1,26 @@
-= With stage


I don't like calling it a stage if it's not in the pipeline.

reference/modules/ROOT/pages/typeql/statements/fun.adoc

reference/modules/ROOT/pages/typeql/pipelines/insert.adoc

reference/modules/ROOT/pages/typeql/pipelines/limit.adoc

reference/modules/ROOT/pages/typeql/pipelines/match.adoc

krishnangovindraj · 2025-08-11T14:04:16Z

reference/modules/ROOT/pages/typeql/functions/index.adoc

@@ -43,6 +43,8 @@ type signature `... -> { A, B }`
 returns stream `{ $a, $b }`
 |===

+// TODO: Compare to rules


farost

Comments & approve

core-concepts/modules/ROOT/pages/typeql/glossary.adoc

farost · 2025-08-12T12:48:44Z

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).


Suggested change

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 refer to all its supertypes).

Subtypes, no?

"in a constraint to refer to all its subtypes" is wrong, you don't refer to subtypes of anything through isa. If you want your idea of referencing abstract types through concrete subtypes to be expressed, we need to find another sentence

At least fix the , / .

Reworked. Check again pls?

reference/modules/ROOT/pages/typeql/expressions/index.adoc

reference/modules/ROOT/pages/typeql/patterns/disjunctions.adoc

farost · 2025-08-12T12:54:54Z

reference/modules/ROOT/pages/typeql/patterns/disjunctions.adoc


+// [,typeql]


What are you going to do with these commented out things?

I can either keep them around, or remove them with a commit SHA saying "This commit actually refers to the other behaviour"

Either remove or move or put a huge explicit todo

Removed and replaced with a comment

farost · 2025-08-12T12:57:06Z

reference/modules/ROOT/pages/typeql/patterns/index.adoc

 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.


I don't really understand the structure of this - point with a full sentence "Exceptionally, .... ." splitting a bullet-point list of * written in lowercase (naturally)

I don't really know where to fit it.

Not here or not this way at least... it's currently read as:

But it does not appear outside of the block, Exceptionaly, ...., it counts as appearing in the parent conjunction. or, the entire...

farost · 2025-08-12T12:58:11Z

reference/modules/ROOT/pages/typeql/pipelines/delete.adoc

-delete ( <variable> | has <variable> of <variable> | links ( <variable> [ , ... ] ) of <variable> ); [ ... ]
+delete
+    ( <variable> | has <variable> of <variable> | links ( <variable> [ , ... ] ) of <variable> );
+    [ ... ]


reference/modules/ROOT/pages/typeql/pipelines/limit.adoc

flyingsilverfin · 2025-08-12T19:48:51Z

reference/modules/ROOT/pages/typeql/patterns/optionals.adoc

@@ -1,6 +1,101 @@
 = Optionals

+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.


insert or delete stages

flyingsilverfin · 2025-08-12T19:49:22Z

reference/modules/ROOT/pages/typeql/patterns/optionals.adoc

 [NOTE]
 ====
-Coming soon.
+Optional patterns are banned in `put` stages.


TBH i still have to think about this, but yah probably

krishnangovindraj commented Aug 7, 2025

View reviewed changes

TypeQL reference review

ea54a07

krishnangovindraj force-pushed the docathon-typeql-reference-check branch from 550300d to ea54a07 Compare August 7, 2025 20:45

krishnangovindraj added 4 commits August 8, 2025 15:38

low hanging fruit from self review

974d5d6

Write up Optional pattern reference

0697d5d

Expand expressions index.adoc

3e67df5

Add TODO in functions page

5906282

krishnangovindraj commented Aug 11, 2025

View reviewed changes

krishnangovindraj added 5 commits August 11, 2025 16:55

Small updates for variable scoping

9e19286

Patterns index update

d1be311

Add optionals to index of patterns

3345566

More optionals text

eb21986

Remove some TODOs

0d50539

krishnangovindraj requested review from flyingsilverfin and farost August 12, 2025 11:48

krishnangovindraj self-assigned this Aug 12, 2025

krishnangovindraj added the domain: query label Aug 12, 2025

krishnangovindraj marked this pull request as ready for review August 12, 2025 11:48

krishnangovindraj requested a review from alexjpwalker as a code owner August 12, 2025 11:48

farost approved these changes Aug 12, 2025

View reviewed changes

krishnangovindraj added 4 commits August 12, 2025 15:40

Remove the use of operators to refer to connectives

00d865f

PR suggestions

97a83df

Missed bits

13f8cea

Remove the commented out lines in favour of a comment with the sha

662c1f5

flyingsilverfin reviewed Aug 12, 2025

View reviewed changes

flyingsilverfin approved these changes Aug 12, 2025

View reviewed changes

krishnangovindraj added 3 commits August 13, 2025 11:58

Add delete stage to optionals ref

67d1495

Fix up abstract

4c0d425

Comma after e.g.

2550362

krishnangovindraj merged commit 6af175e into typedb:3.x-development Aug 13, 2025
2 checks passed

	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 refer to all its supertypes).

Review TypeQL reference to ensure it is up to date #980

Review TypeQL reference to ensure it is up to date #980

Uh oh!

Conversation

krishnangovindraj commented Aug 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Goal

Implementation

Uh oh!

krishnangovindraj left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

farost left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

krishnangovindraj commented Aug 7, 2025 •

edited

Loading