This is an automated email from the ASF dual-hosted git repository.
jgemignani pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/age-website.git
The following commit(s) were added to refs/heads/master by this push:
new e92f91da Revise Clauses Section of Documentation (#240)
e92f91da is described below
commit e92f91dad67020df12c7353d6a945fb67ad33440
Author: Dehowe Feng <[email protected]>
AuthorDate: Fri Dec 22 00:00:21 2023 +0800
Revise Clauses Section of Documentation (#240)
Edits the clauses section of the documentation for content,
spelling, grammar, and other improvements.
---
docs/clauses/create.md | 16 ++++++++--------
docs/clauses/delete.md | 6 +++---
docs/clauses/limit.md | 6 +++---
docs/clauses/match.md | 34 +++++++++++++++++-----------------
docs/clauses/order_by.md | 6 +++---
docs/clauses/remove.md | 4 ++--
docs/clauses/return.md | 8 ++++----
docs/clauses/set.md | 10 +++++-----
docs/clauses/skip.md | 2 +-
docs/clauses/with.md | 4 ++--
10 files changed, 48 insertions(+), 48 deletions(-)
diff --git a/docs/clauses/create.md b/docs/clauses/create.md
index 6f073122..597758aa 100644
--- a/docs/clauses/create.md
+++ b/docs/clauses/create.md
@@ -94,7 +94,7 @@ Result
## Create a vertex with a label
-To add a label when creating a vertex, use the syntax below.
+To add a label when creating a vertex, use the following syntax:
Query
@@ -125,9 +125,9 @@ Result
-## Create vertex and add labels and properties
+## Create a vertex with labels and properties
-When creating a new vertex with labels, you can add properties at the same
time.
+You can create a vertex with labels and properties at the same time.
Query
@@ -160,7 +160,7 @@ Result
## Return created node
-Creating a single node is done by issuing the following query.
+You can create and return a node within the same query as follows:
Query
@@ -196,7 +196,7 @@ Result
## Create an edge between two nodes
-To create an edge between two vertices, we first get the two vertices. Once
the nodes are loaded, we simply create an edge between them.
+To create an edge between two vertices, we first `MATCH` the two vertices.
Once the nodes are matched, we create an edge between them.
Query
@@ -236,7 +236,7 @@ Result
## Create an edge and set properties
-Setting properties on edges is done in a similar manner to how it’s done when
creating vertices. Note that the values can be any expression.
+Setting properties on edges is done in a similar manner to setting properties
when creating vertices. Note that the values can be any expression.
Query
@@ -275,7 +275,7 @@ Result
## Create a full path
-When you use `CREATE` and a pattern, all parts of the pattern that are not
already in scope at this time will be created.
+When you use `CREATE` and a pattern, all parts of the patterns that are not
already in scope at this time will be created.
Query
@@ -289,7 +289,7 @@ $$) as (p agtype);
```
-This query creates three nodes and two relationships in one go, assigns it to
a path variable, and returns it.
+This query creates three nodes and two relationships simultaneously, assigns
the pattern to a path variable, and returns said pattern.
Result
<table>
diff --git a/docs/clauses/delete.md b/docs/clauses/delete.md
index ba475edd..d5a0a98c 100644
--- a/docs/clauses/delete.md
+++ b/docs/clauses/delete.md
@@ -46,7 +46,7 @@ This will delete the vertices (with label Useless) that have
no edges. Nothing i
## Delete all vertices and edges associated with them
-Running a Match clause will collect all nodes, use the `DETACH` option to
first delete a vertice's edges then delete the vertex itself.
+Running a `MATCH` clause will collect all nodes— use the `DETACH` option to
first delete a vertice's edges, then delete the vertex itself.
Query
@@ -76,7 +76,7 @@ Nothing is returned from this query.
## Delete edges only
-To delete an edge, use the match clause to find your edges, then add the
variable to the `DELETE`.
+To delete an edge, use the `MATCH` clause to find your edges, then add the
variable to the `DELETE` clause.
Query
```postgresql
@@ -104,7 +104,7 @@ Nothing is returned from this query.
## Return a deleted vertex
-In AGE, you can return vertices that have been deleted.
+You can return vertices that have been deleted with a `RETURN` clause.
Query
```postgresql
diff --git a/docs/clauses/limit.md b/docs/clauses/limit.md
index b7d16c60..dea73cd9 100644
--- a/docs/clauses/limit.md
+++ b/docs/clauses/limit.md
@@ -9,7 +9,7 @@
## Return a subset of the rows
-To return a subset of the result, starting from the top, use this syntax:
+To return a subset of the result, starting from the top, use the following
syntax:
Query
@@ -17,14 +17,14 @@ Query
```postgresql
SELECT *
FROM cypher('graph_name', $$
- MATCH (n)RETURN n.name
+ MATCH (n) RETURN n.name
ORDER BY n.name
LIMIT 3
$$) as (names agtype);
```
-The node is returned, and no property age exists on it.
+The name property of the matched node `n` is returned, with a limit of 3.
Result
diff --git a/docs/clauses/match.md b/docs/clauses/match.md
index c9e4d3fe..b46d6134 100644
--- a/docs/clauses/match.md
+++ b/docs/clauses/match.md
@@ -1,12 +1,12 @@
# MATCH
-The `MATCH` clause allows you to specify the patterns Cypher will search for
in the database. This is the primary way of getting data into the current set
of bindings. It is worth reading up more on the specification of the patterns
themselves in Patterns.
+The `MATCH` clause allows you to specify the patterns a query will search for
in the database. This is the primary way of retrieving data for use in a query.
-`MATCH` is often coupled to a `WHERE` part which adds restrictions, or
predicates, to the `MATCH` patterns, making them more specific. The predicates
are part of the pattern description, and should not be considered a filter
applied only after the matching is done. This means that `WHERE` should always
be put together with the `MATCH` clause it belongs to.
+ A `WHERE` clause often follows a `MATCH` clause to add user-defined
restrictions to the matched patterns to manipulate the set of data returned.
The predicates are part of the pattern description, and should not be
considered a filter applied only after the matching is done. This means that
`WHERE` should always be put together with the `MATCH` clause it belongs to.
-MATCH can occur at the beginning of the query or later, possibly after a
`WITH`. If it is the first clause, nothing will have been bound yet, and Cypher
will design a search to find the results matching the clause and any associated
predicates specified in any `WHERE` part. Vertices and edges found by this
search are available as bound pattern elements, and can be used for pattern
matching of sub-graphs. They can also be used in any future clauses, where
Cypher will use the known element [...]
+MATCH can occur at the beginning of the query or later, possibly after a
`WITH`. If it is the first clause, nothing will have been bound yet, and Cypher
will design a search to find the results matching the clause and any associated
predicates specified in any `WHERE` clause. Vertices and edges found by this
search are available as bound pattern elements, and can be used for pattern
matching of sub-graphs. They can also be used in any future clauses, where
Cypher will use the known eleme [...]
-Cypher is declarative, and so usually the query itself does not specify the
algorithm to use to perform the search. Predicates in `WHERE` parts can be
evaluated before pattern matching, during pattern matching, or after finding
matches.
+Cypher is a declarative language, and so typically the query itself does not
specify the algorithm to use to perform the search. Predicates in `WHERE` parts
can be evaluated before pattern matching, during pattern matching, or after the
match is found.
## Basic vertex finding
@@ -14,7 +14,7 @@ Cypher is declarative, and so usually the query itself does
not specify the algo
### Get all Vertices
-By just specifying a pattern with a single vertex and no labels, all vertices
in the graph will be returned.
+By specifying a pattern with a single vertex and no labels, all vertices in
the graph will be returned.
Query
@@ -26,7 +26,7 @@ $$) as (v agtype);
```
-Returns all the vertices in the database.
+Returns all vertices in the database.
<table>
@@ -72,7 +72,7 @@ Returns all the vertices in the database.
### Get all vertices with a label
-Getting all vertices with a label on them is done with a single node pattern
where the vertex has a label on it.
+Getting all vertices with a label is done with a single node pattern where the
vertex has the label specified as follows:
Query
@@ -111,7 +111,7 @@ Returns all the movies in the database.
### Related Vertices
-The symbol `-[]-` means related to, without regard to type or direction of the
edge.
+The symbol `-[]-` specifies an edge, without specifying the type or direction
of the edge.
Query
@@ -146,7 +146,7 @@ Returns all the movies directed by 'Oliver Stone'.
### Match with labels
-To constrain your pattern with labels on vertices, you add it to your vertex
in the pattern, using the label syntax.
+To constrain your pattern with labels on vertices, add it to the vertex in the
pattern, using the label syntax.
Query
@@ -184,7 +184,7 @@ Returns any vertices connected with the `Person` 'Oliver'
that are labeled `Movi
### Outgoing Edges
-When the direction of an edge is of interest, it is shown by using `->` or
`<-`.
+To return directed edges, you may use `->` or `<-` to specify the direction of
which the edge points.
Query
@@ -218,8 +218,8 @@ Returns any vertices connected with the `Person` 'Oliver'
by an outgoing edge.
### Directed Edges and variable
-
-If a variable is required, either for filtering on properties of the edge, or
to return the edge, this is how you introduce the variable.
+
+If a variable is required, either for filtering on properties of the edge, or
to return the edge, specify the variable within the edge or vertex you wish to
use.
Query
@@ -252,9 +252,9 @@ Returns the type of each outgoing edge from 'Oliver'.
-### Match on edge type
+### Match on edge label
-When you know the edge type you want to match on, you can specify it by using
a colon together with the edge type.
+When you know the edge label you want to match on, you can specify it by using
a colon together with the edge label.
Query
@@ -295,9 +295,9 @@ Returns all actors that `ACTED_IN` 'Wall Street'.
-### Match on edge type and use a variable
+### Match on edge label with a variable
-If you both want to introduce a variable to hold the edge, and specify the
edge type you want, just add them both.
+If you want to use a variable to hold the edge, and specify the edge label you
want, you can do so by specifying them both.
Query
@@ -340,7 +340,7 @@ Returns `ACTED_IN` roles for 'Wall Street'.
### Multiple Edges
-Edges can be expressed by using multiple statements in the form of `()-[]-()`,
or they can be strung together.
+Edges can be strung together to match an infinite number of edges. As long as
the base pattern `()-[]-()` is followed, users can chain together edges and
vertices to match specific patterns.
Query
diff --git a/docs/clauses/order_by.md b/docs/clauses/order_by.md
index df462f2f..abfa26ef 100644
--- a/docs/clauses/order_by.md
+++ b/docs/clauses/order_by.md
@@ -1,10 +1,10 @@
# ORDER BY
-`ORDER BY` is a sub-clause following `WITH`, and it specifies that the output
should be sorted and how.
+`ORDER BY` is a sub-clause following `WITH`. ORDER BY specifies that the
output should be sorted and how it will be sorted.
## Introduction
-Note that you cannot sort on nodes or relationships, just on properties on
these. `ORDER BY` relies on comparisons to sort the output, see Ordering and
comparison of values.
+Note that you cannot sort on nodes or relationships, sorting must be done on
properties. `ORDER BY` relies on comparisons to sort the output. See Ordering
and comparison of values.
In terms of scope of variables, `ORDER BY` follows special rules, depending on
if the projecting `RETURN` or `WITH` clause is either aggregating or
`DISTINCT`. If it is an aggregating or `DISTINCT` projection, only the
variables available in the projection are available. If the projection does not
alter the output cardinality (which aggregation and `DISTINCT` do), variables
available from before the projecting clause are also available. When the
projection clause shadows already existing [...]
@@ -181,7 +181,7 @@ Result
## Ordering null
-When sorting the result set, `null` will always come at the end of the result
set for ascending sorting, and first when doing descending sort.
+When sorting the result set, `null` will always come at the end of the result
set for ascending sorting, and first for descending sorting.
Query
diff --git a/docs/clauses/remove.md b/docs/clauses/remove.md
index 97e2981d..a8c485cd 100644
--- a/docs/clauses/remove.md
+++ b/docs/clauses/remove.md
@@ -5,12 +5,12 @@ The `REMOVE` clause is used to remove properties from vertex
and edges.
## Terminal REMOVE clauses
-A `REMOVE` clause that is not followed by another clause is called a terminal
clause. When a cypher query ends with a terminal clause, no results will be
returned from the cypher function call. However, the cypher function call still
requires a column list definition. When cypher ends with a terminal node,
define a single value in the column list definition: no data will be returned
in this variable.
+A `REMOVE` clause that is not followed by another clause is a terminal clause.
When a cypher query ends with a terminal clause, no results will be returned
from the cypher function call. However, the cypher function call still requires
a column list definition. When cypher ends with a terminal node, define a
single value in the column list definition: no data will be returned in this
variable.
## Remove a property
-Cypher doesn’t allow storing `null` in properties. Instead, if no value
exists, the property is just not there. So, removing a property value on a node
or a relationship is also done with `REMOVE`.
+Cypher does not allow storing `null` in properties. Instead, if no value
exists, the property is just not there. So, removing a property value on a node
or a relationship is also done with `REMOVE`.
Query
diff --git a/docs/clauses/return.md b/docs/clauses/return.md
index 27cdb6ea..4499ffda 100644
--- a/docs/clauses/return.md
+++ b/docs/clauses/return.md
@@ -1,6 +1,6 @@
# RETURN
-In the `RETURN` part of your query, you define which parts of the pattern you
are interested in. It can be nodes, relationships, or properties on these.
+In the `RETURN` part of your query, you define which parts of the pattern you
want to output. Output can include agtype values, nodes, relationships, or
properties.
## Return nodes
@@ -80,7 +80,7 @@ The relationship is returned by the example.
## Return property
-To return a property, use the dot separator, like this:
+To return a property, use the dot separator, as follows:
Query
@@ -247,7 +247,7 @@ Result
## Optional properties
-If a property might or might not be there, you can still select it as usual.
It will be treated as null if it is missing.
+If a property might or might not be there, it will be treated as null if it is
missing.
Query
@@ -261,7 +261,7 @@ $$) as (age agtype);
```
-This example returns the age when the node has that property, or null if the
property is not there.
+This query returns the property if it exists, or null if the property does not
exist.
Result
diff --git a/docs/clauses/set.md b/docs/clauses/set.md
index 93cd8079..371a0977 100644
--- a/docs/clauses/set.md
+++ b/docs/clauses/set.md
@@ -1,11 +1,11 @@
# SET
-The `SET` clause is used to update labels on nodes and properties on vertices
and edges
+The `SET` clause is used to update labels and properties on vertices and edges
## Terminal SET clauses
-A `SET` clause that is not followed by another clause is called a terminal
clause. When a cypher query ends with a terminal clause, no results will be
returned from the cypher function call. However, the cypher function call still
requires a column list definition. When cypher ends with a terminal node,
define a single value in the column list definition: no data will be returned
in this variable.
+A `SET` clause that is not followed by another clause is a terminal clause.
When a cypher query ends with a terminal clause, no results will be returned
from the cypher function call. However, the cypher function call still requires
a column list definition. When cypher ends with a terminal node, define a
single value in the column list definition: no data will be returned in this
variable.
## Set a property
@@ -44,7 +44,7 @@ Result
## Return created vertex
-Creating a single vertex is done by issuing the following query.
+Creating a single vertex is done with the following query:
Query
@@ -83,7 +83,7 @@ Result
## Remove a property
-Normally you remove a property by using `REMOVE`, but it’s sometimes handy to
do it using the `SET` command. One example is if the property comes from a
parameter.
+Normally a property can be removed by using `REMOVE`, but users can also
remove properties using the `SET` command. One example is if the property comes
from a parameter.
Query
@@ -121,7 +121,7 @@ Result
## Set multiple properties using one SET clause
-If you want to set multiple properties in one go, simply separate them with a
comma.
+If you want to set multiple properties in one query, you can separate them
with a comma.
Query
diff --git a/docs/clauses/skip.md b/docs/clauses/skip.md
index a43f6cf6..15911141 100644
--- a/docs/clauses/skip.md
+++ b/docs/clauses/skip.md
@@ -4,7 +4,7 @@
## Introduction
-By using `SKIP`, the result set will get trimmed from the top. Please note
that no guarantees are made on the order of the result unless the query
specifies the `ORDER BY` clause. `SKIP` accepts any expression that evaluates
to a positive integer.
+By using `SKIP`, the result set will get trimmed from the top. Please note
that no guarantees are made on the order of the returned results unless
specified by the `ORDER BY` clause. `SKIP` accepts any expression that
evaluates to a positive integer.
## Skip first three rows
diff --git a/docs/clauses/with.md b/docs/clauses/with.md
index 29cfa8d7..630f81c9 100644
--- a/docs/clauses/with.md
+++ b/docs/clauses/with.md
@@ -6,7 +6,7 @@ Using `WITH`, you can manipulate the output before it is passed
on to the follow
`WITH` can also, like `RETURN`, alias expressions that are introduced into the
results using the aliases as the binding name.
-`WITH` is also used to separate the reading of the graph from updating of the
graph. Every part of a query must be either read-only or write-only. When going
from a writing part to a reading part, the switch can be done with an optional
`WITH` clause.
+`WITH` is also used to separate the reading of the graph from updating of the
graph. Every part of a query must be either read-only or write-only. When going
from a writing clause to a reading clause, an optional `WITH` can be used to do
so.
## Filter on aggregate function results
@@ -51,7 +51,7 @@ Result
## Sort results before using collect on them
-You can sort your results before passing them to collect, thus sorting the
resulting list.
+You can sort results before passing them to collect, thus sorting the
resulting list.
Query
```postgresql
