From 09ee930ba27839209c5ec13e657024522b48f840 Mon Sep 17 00:00:00 2001
From: Richard Sill <156673635+rsill-neo4j@users.noreply.github.com>
Date: Tue, 14 Jan 2025 11:24:21 +0100
Subject: [PATCH] tags for READ query section (#1133)

---
 modules/ROOT/pages/clauses/match.adoc         | 10 ++++++++++
 .../ROOT/pages/clauses/optional-match.adoc    |  2 ++
 modules/ROOT/pages/clauses/return.adoc        | 12 +++++++++++
 modules/ROOT/pages/clauses/union.adoc         |  4 ++++
 modules/ROOT/pages/clauses/where.adoc         | 20 +++++++++++++++++++
 modules/ROOT/pages/clauses/with.adoc          |  4 ++++
 6 files changed, 52 insertions(+)

diff --git a/modules/ROOT/pages/clauses/match.adoc b/modules/ROOT/pages/clauses/match.adoc
index dbf136f4a..3dffc1a0c 100644
--- a/modules/ROOT/pages/clauses/match.adoc
+++ b/modules/ROOT/pages/clauses/match.adoc
@@ -45,11 +45,13 @@ For more information about finding node patterns, see xref:patterns/fixed-length
 By specifying a pattern with a single node and no labels, all nodes in the graph will be returned.
 
 .Find all nodes in a graph
+// tag::clauses_match_all_nodes[]
 [source, cypher]
 ----
 MATCH (n)
 RETURN n
 ----
+// end::clauses_match_all_nodes[]
 
 .Result
 [role="queryresult",options="header,footer",cols="1*<m"]
@@ -70,11 +72,13 @@ RETURN n
 === Find nodes with a specific label
 
 .Find all nodes with the `Movie` label
+// tag::clauses_match_label[]
 [source, cypher]
 ----
 MATCH (movie:Movie)
 RETURN movie.title
 ----
+// end::clauses_match_label[]
 
 .Result
 [role="queryresult",options="header,footer",cols="1*<m"]
@@ -195,11 +199,13 @@ RETURN movie.title AS movieTitle
 It is possible to introduce a variable to a pattern, either for filtering on relationship properties or to return a relationship.
 
 .Find the types of an aliased relationship
+// tag::clauses_match_relationship_types[]
 [source, cypher]
 ----
 MATCH (:Person {name: 'Oliver Stone'})-[r]->()
 RETURN type(r) AS relType
 ----
+// end::clauses_match_relationship_types[]
 
 [NOTE]
 The above query uses the xref:functions/scalar.adoc#functions-type[`type()` function].
@@ -244,11 +250,13 @@ RETURN a, b
 It is possible to specify the type of a relationship in a relationship pattern by using a colon (`:`) before the relationship type.
 
 .Relationship pattern filtering on the `ACTED_IN` relationship type
+// tag::clauses_match_relationship[]
 [source, cypher]
 ----
 MATCH (:Movie {title: 'Wall Street'})<-[:ACTED_IN]-(actor:Person)
 RETURN actor.name AS actor
 ----
+// end::clauses_match_relationship[]
 
 .Result
 [source, role="queryresult",options="header,footer",cols="1*<m"]
@@ -400,11 +408,13 @@ For more information about how to set parameters, see xref:syntax/parameters.ado
 The `MATCH` clause can also be used to bind whole paths to variables.
 
 .Find all paths matching a pattern
+// tag::clauses_match_path[]
 [source, cypher]
 ----
 MATCH path = ()-[:ACTED_IN]->(movie:Movie)
 RETURN path
 ----
+// end::clauses_match_path[]
 
 .Result
 [role="queryresult",options="header,footer",cols="1*<m"]
diff --git a/modules/ROOT/pages/clauses/optional-match.adoc b/modules/ROOT/pages/clauses/optional-match.adoc
index 44e2dba20..68289328a 100644
--- a/modules/ROOT/pages/clauses/optional-match.adoc
+++ b/modules/ROOT/pages/clauses/optional-match.adoc
@@ -79,12 +79,14 @@ This is because the second `MATCH` clause returns no data (there are no `DIRECTE
 However, replacing the second `MATCH` clause with `OPTIONAL MATCH` does return results.
 This is because, unlike `MATCH`, `OPTIONAL MATCH` enables the value `null` to be passed between clauses.
 
+// tag::clauses_optional_match[]
 [source, cypher]
 ----
 MATCH (p:Person {name: 'Martin Sheen'})
 OPTIONAL MATCH (p)-[r:DIRECTED]->()
 RETURN p.name, r
 ----
+// end::clauses_optional_match[]
 
 .Result
 [role="queryresult",options="header,footer",cols="2*<m"]
diff --git a/modules/ROOT/pages/clauses/return.adoc b/modules/ROOT/pages/clauses/return.adoc
index 323fc40cd..f62810787 100644
--- a/modules/ROOT/pages/clauses/return.adoc
+++ b/modules/ROOT/pages/clauses/return.adoc
@@ -32,11 +32,13 @@ CREATE
 To return a node, list it in the `RETURN` clause:
 
 .Query
+// tag::clauses_return_node[]
 [source, cypher]
 ----
 MATCH (p:Person {name: 'Keanu Reeves'})
 RETURN p
 ----
+// end::clauses_return_node[]
 
 .Result
 [role="queryresult",options="header,footer",cols="1*<m"]
@@ -53,11 +55,13 @@ d|Rows: 1
 To return a relationship type, list it in the `RETURN` clause:
 
 .Query
+// tag::clauses_return_relationship_type[]
 [source, cypher]
 ----
 MATCH (p:Person {name: 'Keanu Reeves'})-[r:ACTED_IN]->(m)
 RETURN type(r)
 ----
+// end::clauses_return_relationship_type[]
 
 .Result
 [role="queryresult",options="header,footer",cols="1*<m"]
@@ -74,11 +78,13 @@ d|Rows: 1
 To return a specific property, use the dot separator:
 
 .Query
+// tag::clauses_return_property[]
 [source, cypher]
 ----
 MATCH (p:Person {name: 'Keanu Reeves'})
 RETURN p.bornIn
 ----
+// end::clauses_return_property[]
 
 .Result
 [role="queryresult",options="header,footer",cols="1*<m"]
@@ -101,11 +107,13 @@ This will improve performance.
 To return all nodes, relationships and paths found in a query, use the `*` symbol:
 
 .Query
+// tag::clauses_return_all_elements[]
 [source, cypher]
 ----
 MATCH p = (keanu:Person {name: 'Keanu Reeves'})-[r]->(m)
 RETURN *
 ----
+// end::clauses_return_all_elements[]
 
 This returns the two nodes, and the two possible paths between them.
 
@@ -149,11 +157,13 @@ d|Rows: 1
 Names of returned columns can be renamed using the `AS` operator:
 
 .Query
+// tag::clauses_return_with_column_alias[]
 [source, cypher]
 ----
 MATCH (p:Person {name: 'Keanu Reeves'})
 RETURN p.nationality AS citizenship
 ----
+// end::clauses_return_with_column_alias[]
 
 Returns the `nationality` property of `'Keanu Reeves'`, but the column is renamed to `citizenship`.
 
@@ -220,11 +230,13 @@ Returns a predicate, a literal and function call with a pattern expression param
 `DISTINCT` retrieves only unique rows for the columns that have been selected for output.
 
 .Query
+// tag::clauses_return_distinct[]
 [source, cypher]
 ----
 MATCH (p:Person {name: 'Keanu Reeves'})-->(m)
 RETURN DISTINCT m
 ----
+// end::clauses_return_distinct[]
 
 The `Movie` node `'Man of Tai Chi'` is returned by the query, but only once (without the `DISTINCT` operator it would have been returned twice because there are two relationships going to it from `'Keanu Reeves'`):
 
diff --git a/modules/ROOT/pages/clauses/union.adoc b/modules/ROOT/pages/clauses/union.adoc
index 2df4687aa..89c9746a8 100644
--- a/modules/ROOT/pages/clauses/union.adoc
+++ b/modules/ROOT/pages/clauses/union.adoc
@@ -45,6 +45,7 @@ CREATE (johnny:Actor {name: 'Johnny Depp'}),
 Combining the results from two queries is done using `UNION ALL`.
 
 .Query
+// tag::clauses_union_all[]
 [source, cypher]
 ----
 MATCH (n:Actor)
@@ -53,6 +54,7 @@ UNION ALL
 MATCH (n:Movie)
 RETURN n.title AS name
 ----
+// end::clauses_union_all[]
 
 The combined result is returned, including duplicates.
 
@@ -74,6 +76,7 @@ The combined result is returned, including duplicates.
 By not including `ALL` in the `UNION`, duplicates are removed from the combined result set.
 
 .Query
+// tag::clauses_union[]
 [source, cypher]
 ----
 MATCH (n:Actor)
@@ -82,6 +85,7 @@ UNION
 MATCH (n:Movie)
 RETURN n.title AS name
 ----
+// end::clauses_union[]
 
 The combined result is returned, without duplicates.
 
diff --git a/modules/ROOT/pages/clauses/where.adoc b/modules/ROOT/pages/clauses/where.adoc
index f57792c60..c0487cb30 100644
--- a/modules/ROOT/pages/clauses/where.adoc
+++ b/modules/ROOT/pages/clauses/where.adoc
@@ -46,12 +46,14 @@ CREATE
 `WHERE` can appear inside a node pattern in a `MATCH` clause or a pattern comprehension:
 
 .Query
+// tag::clauses_where_in_match_clause[]
 [source, cypher]
 ----
 WITH 30 AS minAge
 MATCH (a:Person WHERE a.name = 'Andy')-[:KNOWS]->(b:Person WHERE b.age > minAge)
 RETURN b.name
 ----
+// end::clauses_where_in_match_clause[]
 
 .Result
 [role="queryresult",options="header,footer",cols="1*<m"]
@@ -66,11 +68,13 @@ When used this way, predicates in `WHERE` can reference the node variable that t
 The same rule applies to pattern comprehensions:
 
 .Query
+// tag::clauses_where_pattern_comprehension[]
 [source, cypher]
 ----
 MATCH (a:Person {name: 'Andy'})
 RETURN [(a)-->(b WHERE b:Person) | b.name] AS friends
 ----
+// end::clauses_where_pattern_comprehension[]
 
 .Result
 [role="queryresult",options="header,footer",cols="1*<m"]
@@ -87,6 +91,7 @@ The following boolean operators can be used with the `WHERE` clause: `AND`, `OR`
 For more information on how operators work with `null`, see the chapter on xref::values-and-types/working-with-null.adoc[Working with null].
 
 .Query
+// tag::clauses_where_boolean_operations[]
 [source, cypher]
 ----
 MATCH (n:Person)
@@ -96,6 +101,7 @@ RETURN
   n.age AS age
 ORDER BY name
 ----
+// end::clauses_where_boolean_operations[]
 
 .Result
 [role="queryresult",options="header,footer",cols="2*<m"]
@@ -114,12 +120,14 @@ ORDER BY name
 To filter nodes by label, write a label predicate after the `WHERE` keyword using `WHERE n:foo`:
 
 .Query
+// tag::clauses_where_node_label[]
 [source, cypher]
 ----
 MATCH (n)
 WHERE n:Swedish
 RETURN n.name, n.age
 ----
+// end::clauses_where_node_label[]
 
 The `name` and `age` values for `Andy` are returned:
 
@@ -138,12 +146,14 @@ The `name` and `age` values for `Andy` are returned:
 To filter on a node property, write your clause after the `WHERE` keyword:
 
 .Query
+// tag::clauses_where_node_property[]
 [source, cypher]
 ----
 MATCH (n:Person)
 WHERE n.age < 30
 RETURN n.name, n.age
 ----
+// end::clauses_where_node_property[]
 
 The `name` and `age` values for `Timothy` are returned because he is less than 30 years of age:
 
@@ -162,12 +172,14 @@ The `name` and `age` values for `Timothy` are returned because he is less than 3
 To filter on a relationship property, write your clause after the `WHERE` keyword:
 
 .Query
+// tag::clauses_where_relationship_property[]
 [source, cypher]
 ----
 MATCH (n:Person)-[k:KNOWS]->(f)
 WHERE k.since < 2000
 RETURN f.name, f.age, f.email
 ----
+// end::clauses_where_relationship_property[]
 
 The `name`, `age` and `email` values for `Peter` are returned because `Andy` has known him since before 2000:
 
@@ -218,12 +230,14 @@ The `name` and `age` values for `Timothy` are returned because he is less than 3
 Use the `IS NOT NULL` predicate to only include nodes or relationships in which a property exists:
 
 .Query
+// tag::clauses_where_property_existence[]
 [source, cypher]
 ----
 MATCH (n:Person)
 WHERE n.belt IS NOT NULL
 RETURN n.name, n.belt
 ----
+// end::clauses_where_property_existence[]
 
 The `name` and `belt` values for `Andy` are returned because he is the only one with a `belt` property:
 
@@ -242,6 +256,7 @@ The `name` and `belt` values for `Andy` are returned because he is the only one
 As `WHERE` is not considered a clause in its own right, its scope is not limited by a `WITH` directly before it.
 
 .Query
+// tag::clauses_where_with[]
 [source, cypher]
 ----
 MATCH (n:Person)
@@ -249,6 +264,7 @@ WITH n.name as name
 WHERE n.age = 25
 RETURN name
 ----
+// end::clauses_where_with[]
 
 .Result
 [role="queryresult",options="header,footer",cols="1*<m"]
@@ -538,6 +554,7 @@ The following sections will demonstrate how to use path pattern expressions in a
 === Filter on patterns
 
 .Query
+// tag::clauses_where_patterns[]
 [source, cypher]
 ----
 MATCH
@@ -546,6 +563,7 @@ MATCH
 WHERE (other)-->(timothy)
 RETURN other.name, other.age
 ----
+// end::clauses_where_patterns[]
 
 The `name` and `age` values for nodes that have an outgoing relationship to `Timothy` are returned:
 
@@ -618,12 +636,14 @@ To check if an element exists in a list, use the `IN` operator.
 The below query checks whether a property exists in a literal list:
 
 .Query
+// tag::clauses_where_lists[]
 [source, cypher]
 ----
 MATCH (a:Person)
 WHERE a.name IN ['Peter', 'Timothy']
 RETURN a.name, a.age
 ----
+// end::clauses_where_lists[]
 
 .Result
 [role="queryresult",options="header,footer",cols="2*<m"]
diff --git a/modules/ROOT/pages/clauses/with.adoc b/modules/ROOT/pages/clauses/with.adoc
index 0aa2b0952..c2939fa21 100644
--- a/modules/ROOT/pages/clauses/with.adoc
+++ b/modules/ROOT/pages/clauses/with.adoc
@@ -56,6 +56,7 @@ CREATE
 You can introduce new variables for the result of evaluating expressions.
 
 .Query
+// tag::clauses_with_variables[]
 [source, cypher, indent=0]
 ----
 MATCH (george {name: 'George'})<--(otherPerson)
@@ -63,6 +64,7 @@ WITH otherPerson, toUpper(otherPerson.name) AS upperCaseName
 WHERE upperCaseName STARTS WITH 'C'
 RETURN otherPerson.name
 ----
+// end::clauses_with_variables[]
 
 This query returns the name of persons connected to *'George'* whose name starts with a `C`, regardless of capitalization.
 
@@ -81,12 +83,14 @@ This query returns the name of persons connected to *'George'* whose name starts
 You can use the wildcard `*` to carry over all variables that are in scope, in addition to introducing new variables.
 
 .Query
+// tag::clauses_with_wildcard[]
 [source, cypher, indent=0]
 ----
 MATCH (person)-[r]->(otherPerson)
 WITH *, type(r) AS connectionType
 RETURN person.name, otherPerson.name, connectionType
 ----
+// end::clauses_with_wildcard[]
 
 This query returns the names of all related persons and the type of relationship between them.