Add analyze documentation (#1008)

## Goal
Adds analyze documentation to diver core-concepts

## Implementation
Also updates driver dependencies to 3.7.0

Author: krishnangovindraj

core-concepts/modules/ROOT/examples/driver/analyze_query.py

@@ -0,0 +1,31 @@
+#tag::analyze[]
+with driver.transaction(DB_NAME, TransactionType.READ) as tx:
+    # 1. Send the analyze request
+    promise = tx.analyze("""
+        match { $x isa user; } or { $x isa company; };
+        fetch { "email": [$x.email] };
+    """)
+
+    # 2. Resolve the promise if you want to access the result or receive an error as an exception
+    analyzed = promise.resolve()
+
+#end::analyze[]
+
+#tag::get_conjunction[]
+pipeline = analyzed.pipeline()
+stages = list(pipeline.stages())
+block_id = stages[0].as_match().block()
+root_conjunction = pipeline.conjunction(block_id)
+
+#end::get_conjunction[]
+
+#tag::get_first_branch_isa[]
+constraints = list(root_conjunction.constraints())
+or_constraint = constraints[0]
+assert or_constraint.is_or()
+branches = [pipeline.conjunction(id) for id in or_constraint.as_or().branches()]
+first_branch_constraints = list(branches[0].constraints())
+first_branch_isa = first_branch_constraints[0]
+assert first_branch_isa.is_isa()
+
+#end::get_first_branch_isa[]

core-concepts/modules/ROOT/pages/drivers/analyze.adoc

@@ -0,0 +1,310 @@
+= Analyzing queries
+:pageTitle: Analyzing queries
+:Summary: Compiling & analyzing TypeDB queries.
+:keywords: typedb, driver, analyze, type-inference, dry-run, validate
+:test-python: true
+
+TypeDB allows the user to "analyze" a query without having it execute against the data.
+During analysis, a query is parsed to the internal representation and type-checked -
+allowing the user to check their query for syntax and typing errors against a schema.
+
+The envisioned use is to facilitate developer tooling around TypeDB, such as
+plugins to validate TypeQL queries when application code is being compiled,
+and debugging type errors.
+Such tools can also be used by AI query-generators to automatically validate generated queries.
+
+This page gives an overview of how to analyze a query and use the response.
+The examples are valid python code using the TypeDB python driver.
+The class definitions are illustrative.
+
+== Analyzing a query
+Analyzing a query follows the same pattern as xref:{page-version}@core-concepts::drivers/queries.adoc[running a query].
+[source,python]
+----
+#!test[]
+#{{
+include::{page-version}@core-concepts::example$driver/python_driver_usage.py[tag=setup_and_schema]
+
+include::{page-version}@core-concepts::example$driver/python_driver_usage.py[tag=data_create]
+
+#}}
+include::{page-version}@core-concepts::example$driver/analyze_query.py[tag=analyze]
+----
+
+== The response
+
+The response is a type-annotated representation of the query.
+The following sections cover the essence,
+but details are left to the xref:#_references[driver reference].
+
+As one would expect, the response contains each part of a TypeQL query:
+A (possibly empty) set of preamble functions, the query-pipeline, and a fetch clause, if present.
+
+[source,python]
+----
+class AnalyzedQuery:
+    def pipeline(self) -> Pipeline
+    def preamble(self) -> Iterator[Function]
+    def fetch(self) -> Optional[Fetch]
+----
+
+=== Pipelines & conjunctions
+TypeQL xref:{page-version}@typeql-reference::/data-model.adoc#_stages[pipelines] are made up of a sequence of stages, some of which may contain conjunctions.
+
+[source,python]
+----
+class Pipeline:
+    def stages(self) -> Iterator[PipelineStage]
+    def conjunction(self, conjunction_id: ConjunctionID) -> Optional[Conjunction]
+    # ...
+----
+The `PipelineStage` instances returned by the `stages()` method follows the familiar pattern
+of having an abstract base class which is a union of all the variants.
+it must be downcast to the appropriate variant using the `is_<variant>` and `as_<variant>` methods.
+
+[source,python]
+----
+class PipelineStage(ABC):
+    def is_match(self) -> bool
+    def as_match(self) -> MatchStage
+    # is_insert, as_insert, is_select, as_select, ...
+
+class MatchStage(PipelineStage):
+    def block(self) -> ConjunctionID
+
+class SelectStage(PipelineStage):
+    def variables(self) -> Iterator[Variable]
+----
+
+Stages such as `Match` and `Insert` hold a `ConjunctionID`.
+This is an indirection which can be used
+to retrieve the actual conjunction using the `Pipeline.conjunction` method.
+
+[source,python]
+----
+#!test[]
+#{{
+include::{page-version}@core-concepts::example$driver/python_driver_usage.py[tag=import_and_constants]
+
+include::{page-version}@core-concepts::example$driver/python_driver_usage.py[tag=driver_create]
+
+include::{page-version}@core-concepts::example$driver/analyze_query.py[tag=analyze]
+
+#}}
+include::{page-version}@core-concepts::example$driver/analyze_query.py[tag=get_conjunction]
+----
+
+From the returned conjunction one can access the constraints,
+as well as the types inferred for the variables in those constraints.
+[source,python]
+----
+class Conjunction:
+    def constraints(self) -> Iterator[Constraint]
+    def annotated_variables(self) -> Iterator[Variable]
+    def variable_annotations(self, variable: Variable) -> Optional[VariableAnnotations]
+----
+
+[NOTE]
+====
+`VariableAnnotations` refer to the types the variable is annotated with by type-inference.
+These are not to be confused with xref:{page-version}@typeql-reference::annotations/index.adoc[schema-annotations]
+====
+
+=== Constraints
+Similar to stages, the `Constraint` instances returned by the `constraints()` method
+must be down-cast to the appropriate variant using the `is/as` methods.
+Sub-patterns such as `or`, `not`, and `try` are also constraints.
+These hold the `ConjunctionID`(s) of the nested conjunctions.
+
+[source,python]
+----
+class Constraint(ABC):
+    def is_isa(self) -> bool
+    def as_isa(self) -> Isa
+    # is_has, as_has, ...
+
+    def is_or(self) -> bool
+    def as_or(self) -> Or
+    # is_not, as_not, is_try, as_try
+
+class Isa(Constraint):
+    # <instance> isa(!) <type>
+    def instance(self) -> ConstraintVertex
+    def type(self) -> ConstraintVertex
+    def exactness(self) -> ConstraintExactness # isa or isa!
+
+# Has, ...
+
+class Or(Constraint):
+    def branches(self) -> Iterator[ConjunctionID]
+# Not, Try
+----
+
+To get the `isa` constraint from the first branch:
+[source,python]
+----
+#!test[]
+#{{
+include::{page-version}@core-concepts::example$driver/python_driver_usage.py[tag=import_and_constants]
+
+include::{page-version}@core-concepts::example$driver/python_driver_usage.py[tag=driver_create]
+
+include::{page-version}@core-concepts::example$driver/analyze_query.py[tags=analyze;get_conjunction]
+
+#}}
+include::{page-version}@core-concepts::example$driver/analyze_query.py[tag=get_first_branch_isa]
+----
+
+==== Constraint vertices
+Although constraints typically apply on variables,
+certain TypeQL constraints allow you to directly specify a type-label or a value.
+Additionally, a `NamedRole` vertex type exists to handle the ambiguity of unscoped role-labels.
+A `ConstraintVertex` is the union of these four.
+
+[NOTE]
+====
+The term `vertex` comes from viewing a query as a constraint graph.
+====
+
+A `ConstraintVertex` can be converted to the appropriate variant using the `is/as` methods.
+
+* A *label* vertex holds the resolved type.
+* A *value* vertex holds the value concept of the appropriate value-type.
+* A *named-role* vertex holds the internal variable and the unscoped name.
+The internal variable can be used to retrieve the resolved role-type(s) using the annotations in the conjunction.
+* A *variable* vertex holds a variable, which can be used in many places.
+
+A variable is shared across constraints. The name of a variable (if it has one) can be read from the pipeline.
+[source,python]
+----
+#!test[]
+#{{
+include::{page-version}@core-concepts::example$driver/python_driver_usage.py[tag=import_and_constants]
+
+include::{page-version}@core-concepts::example$driver/python_driver_usage.py[tag=driver_create]
+
+include::{page-version}@core-concepts::example$driver/analyze_query.py[tags=analyze;get_conjunction;get_first_branch_isa]
+
+#}}
+var_x = first_branch_isa.instance()
+assert var_x.is_variable() and pipeline.get_variable_name(var_x.as_variable()) == "x"
+----
+If the variable is an output of the pipeline, the name can be used to read answers from query responses.
+The possible types of a variable in a conjunction can be read from the annotations in the conjunction.
+
+[NOTE]
+====
+`Variable` and `ConjunctionID` are scoped to a pipeline.
+Trying to resolve either of these using a pipeline other than the one it originated from
+(e.g. a pipeline of a preamble function) is undefined behaviour.
+====
+
+=== Annotations
+Type-checking is a central feature of TypeDB.
+Analyze returns the final set of inferred types for every variable in a conjunction.
+
+[source,python]
+----
+#!test[]
+#{{
+include::{page-version}@core-concepts::example$driver/python_driver_usage.py[tag=import_and_constants]
+
+include::{page-version}@core-concepts::example$driver/python_driver_usage.py[tag=driver_create]
+
+include::{page-version}@core-concepts::example$driver/analyze_query.py[tags=analyze;get_conjunction;get_first_branch_isa]
+
+#}}
+var_x = first_branch_isa.instance().as_variable()
+assert var_x in list(root_conjunction.annotated_variables())
+
+x_annotations_in_root = root_conjunction.variable_annotations(var_x)
+assert x_annotations_in_root.is_instance()
+
+x_types_in_root = list(x_annotations_in_root.as_instance())
+labels = set(map(lambda t: t.get_label(), x_types_in_root))
+assert labels == {"user", "company"}
+----
+
+[NOTE]
+====
+We return annotations per conjunction because a variable may have different types in different conjunctions.
+[source, typeql]
+----
+# user in the left branch, company in the right, Either of them at the root.
+match { $p isa user; } or { $p isa company; };
+----
+or
+[source, typeql]
+----
+match $p has email $email;  # $p is any type that owns email
+match $p has name $name;    # The type of $p must also own name
+----
+====
+
+
+=== Functions
+A `Function` is a pipeline with a set of arguments, and returns.
+[source, python]
+----
+class Function:
+    def body(self) -> Pipeline
+
+    def argument_variables(self) -> Iterator[Variable]
+    def argument_annotations(self) -> Iterator[VariableAnnotations]
+
+    def return_operation(self) -> ReturnOperation
+    def return_annotations(self) -> Iterator[VariableAnnotations]
+----
+
+=== Fetch
+An analyzed `Fetch` is one of a Dictionary, a List, or a collection of values.
+[source,python]
+----
+class Fetch(ABC):
+    # is/as methods
+
+class FetchObject(Fetch):
+    def keys(self) -> Iterator[str]
+    def get(self, key: str) -> Fetch
+
+class FetchList(Fetch):
+    def element(self) -> Fetch
+
+class FetchLeaf(Fetch):
+    def annotations(self) -> Iterator[str]
+----
+The JSON-like structure of the analyzed `Fetch` reflects that of the `Fetch` stage itself,
+with leaves being annotated with the value types.
+
+[source,typeql]
+----
+match $u isa user;
+fetch {
+    "email": [ $u.email ],
+};
+----
+
+To inspect the value-type of the emails:
+[source,python]
+----
+#!test[]
+#{{
+include::{page-version}@core-concepts::example$driver/python_driver_usage.py[tag=import_and_constants]
+
+include::{page-version}@core-concepts::example$driver/python_driver_usage.py[tag=driver_create]
+
+include::{page-version}@core-concepts::example$driver/analyze_query.py[tag=analyze]
+
+#}}
+root_object = analyzed.fetch().as_object()
+email_field = root_object.get("email")
+email_list_element = email_field.as_list().element()
+email_value_types = list(email_list_element.annotations())
+assert email_value_types == ["string"]
+----
+
+== References
+* Analyze reference:
+xref:{page-version}@reference::typedb-grpc-drivers/rust.adoc#_Analyze[rust],
+xref:{page-version}@reference::typedb-grpc-drivers/java.adoc#_Analyze[java],
+xref:{page-version}@reference::typedb-grpc-drivers/python.adoc#_Analyze[python]

core-concepts/modules/ROOT/pages/drivers/index.adoc

@@ -35,6 +35,12 @@ Using transactions with TypeDB drivers.
 Querying with TypeDB drivers.
 ****
 
+.xref:{page-version}@core-concepts::drivers/analyze.adoc[]
+[.clickable]
+****
+Type-checking queries without executing them against data.
+****
+
 .xref:{page-version}@core-concepts::drivers/best-practices.adoc[]
 [.clickable]
 ****

core-concepts/modules/ROOT/partials/nav.adoc

@@ -31,4 +31,5 @@
 ** xref:{page-version}@core-concepts::drivers/authentication.adoc[]
 ** xref:{page-version}@core-concepts::drivers/transactions.adoc[]
 ** xref:{page-version}@core-concepts::drivers/queries.adoc[]
+** xref:{page-version}@core-concepts::drivers/analyze.adoc[]
 ** xref:{page-version}@core-concepts::drivers/best-practices.adoc[]

test/code/runners/python_requirements.txt

@@ -1 +1 @@
-typedb-driver==3.4.0
+typedb-driver==3.7.0

test/code/runners/rust_cargo_toml.toml

@@ -5,6 +5,6 @@ edition = "2021"
 
 [dependencies]
 serde_json = "1.0.114"
-typedb-driver = { version = "3.4.0" }
+typedb-driver = { version = "3.7.0" }
 tokio = "1.43.0"
 futures-util = "0.3.31"

test/content/mock/driver/antora.yml

@@ -1,4 +1,3 @@
 name: external-typedb-driver
 title: Mock driver
 version: '3.x'
-

test/content/mock/driver/modules/ROOT/partials/java/api-reference.adoc

@@ -0,0 +1 @@
+== Analyze

test/content/mock/driver/modules/ROOT/partials/python/api-reference.adoc

@@ -0,0 +1 @@
+== Analyze

test/content/mock/driver/modules/ROOT/partials/rust/api-reference.adoc

@@ -0,0 +1 @@
+== Analyze