This is an automated email from the ASF dual-hosted git repository.
dehowef 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 bfe39f38 docs: inline code formatting (#218)
bfe39f38 is described below
commit bfe39f38039d8f67893dff70b9679c7e7213989c
Author: Emmanuel Allison <[email protected]>
AuthorDate: Mon Oct 9 20:16:30 2023 +0100
docs: inline code formatting (#218)
---
docs/intro/aggregation.md | 30 +++++++++++++++---------------
docs/intro/comparability.md | 24 ++++++++++++------------
docs/intro/cypher.md | 4 ++--
docs/intro/graphs.md | 4 ++--
docs/intro/setup.md | 4 ++--
docs/intro/types.md | 20 ++++++++++----------
6 files changed, 43 insertions(+), 43 deletions(-)
diff --git a/docs/intro/aggregation.md b/docs/intro/aggregation.md
index d00f0099..1f100e64 100644
--- a/docs/intro/aggregation.md
+++ b/docs/intro/aggregation.md
@@ -3,9 +3,9 @@
## Introduction
-Generally an aggregation aggr(expr) processes all matching rows for each
aggregation key found in an incoming record (keys are compared using
[equivalence](../intro/comparability.md)).
+Generally an aggregation `aggr(expr)` processes all matching rows for each
aggregation key found in an incoming record (keys are compared using
[equivalence](../intro/comparability.md)).
-In a regular aggregation (i.e. of the form aggr(expr)), the list of aggregated
values is the list of candidate values with all null values removed from it.
+In a regular aggregation (i.e. of the form `aggr(expr)`), the list of
aggregated values is the list of candidate values with all null values removed
from it.
## Data Setup
@@ -25,9 +25,9 @@ $$) as (a agtype);
```
## Auto Group By
-To calculate aggregated data, Cypher offers aggregation, analogous to SQL’s
GROUP BY.
+To calculate aggregated data, Cypher offers aggregation, analogous to SQL’s
`GROUP BY`.
-Aggregating functions take a set of values and calculate An aggregated value
over them. Examples are [avg()](../functions/aggregate_functions.md#avg) that
calculates the average of multiple numeric values, or
[min()](../functions/aggregate_functions.md#min) that finds the smallest
numeric or string value in a set of values. When we say below that an
aggregating function operates on a set of values, we mean these to be the
result of the application of the inner expression(such as n.age) [...]
+Aggregating functions take a set of values and calculate An aggregated value
over them. Examples are [`avg()`](../functions/aggregate_functions.md#avg) that
calculates the average of multiple numeric values, or
[`min()`](../functions/aggregate_functions.md#min) that finds the smallest
numeric or string value in a set of values. When we say below that an
aggregating function operates on a set of values, we mean these to be the
result of the application of the inner expression(such as `n. [...]
Aggregation can be computed over all the matching subgraphs, or it can be
further divided by introducing grouping keys. These are non-aggregate
expressions, that are used to group the values going into the aggregate
functions.
@@ -66,11 +66,11 @@ $$) as (grouping_key agtype, count agtype);
</table>
-We have two return expressions: grouping_key, and count(*). The first,
grouping_key, is not an aggregate function, and so it will be the grouping
key. The latter, count(*) is an aggregate expression. The matching subgraphs
will be divided into different buckets, depending on the grouping key. The
aggregate function will then be run on these buckets, calculating an aggregate
value per bucket.
+We have two return expressions: `grouping_key`, and `count(*)`. The first,
`grouping_key`, is not an aggregate function, and so it will be the grouping
key. The latter, `count(*)` is an aggregate expression. The matching subgraphs
will be divided into different buckets, depending on the grouping key. The
aggregate function will then be run on these buckets, calculating an aggregate
value per bucket.
## Sorting on aggregate functions
-To use aggregations to sort the result set, the aggregation must be included
in the RETURN to be used in the ORDER BY.
+To use aggregations to sort the result set, the aggregation must be included
in the `RETURN` to be used in the `ORDER BY`.
```postgresql
SELECT *
@@ -82,10 +82,10 @@ $$) as (friends agtype, me agtype);
```
## Distinct aggregation
-In a distinct aggregation (i.e. of the form aggr(DISTINCT expr)), the list of
aggregated values is the list of candidate values with all null values removed
from it. Furthermore, in a distinct aggregation, only one of all equivalent
candidate values is included in the list of aggregated values, i.e. duplicates
under equivalence are removed.
+In a distinct aggregation (i.e. of the form `aggr(DISTINCT expr)`), the list
of aggregated values is the list of candidate values with all null values
removed from it. Furthermore, in a distinct aggregation, only one of all
equivalent candidate values is included in the list of aggregated values, i.e.
duplicates under equivalence are removed.
-The DISTINCT operator works in conjunction with aggregation. It is used to
make all values unique before running them through an aggregate function.
+The `DISTINCT` operator works in conjunction with aggregation. It is used to
make all values unique before running them through an aggregate function.
```postgresql
SELECT *
@@ -123,7 +123,7 @@ $$) as (a agtype);
```
### Invalid Query in AGE
-AGE's solution to this problem is to not allow a WITH or RETURN column to
combine aggregate functions with variables that are not explicitly listed in
another column of the same WITH or RETURN clause.
+AGE's solution to this problem is to not allow a `WITH` or `RETURN` column to
combine aggregate functions with variables that are not explicitly listed in
another column of the same `WITH` or `RETURN` clause.
@@ -143,7 +143,7 @@ LINE 3: RETURN x.a + count(*) + x.b + count(*) + x.c
### Valid Query in AGE
-Columns that do not include an aggregate function in AGE are considered to be
the grouping keys for that WITH or RETURN clause.
+Columns that do not include an aggregate function in AGE are considered to be
the grouping keys for that `WITH` or `RETURN` clause.
For the above query, the user could rewrite the query is several ways that
will return results
@@ -155,7 +155,7 @@ SELECT * FROM cypher('graph_name', $$
$$) as (count agtype, key agtype);
```
-x.a + x.b + x.c is the grouping key. Grouping keys created like this must
include parenthesis.
+`x.a + x.b + x.c` is the grouping key. Grouping keys created like this must
include parenthesis.
Results
<table>
@@ -182,7 +182,7 @@ SELECT * FROM cypher('graph_name', $$
$$) as (count agtype, a agtype, b agtype, c agtype);
```
-x.a, x.b, and x.c will be considered different grouping keys
+`x.a`, `x.b`, and `x.c` will be considered different grouping keys
Results:
@@ -220,7 +220,7 @@ Results:
### Vertices and edges in ambiguous grouping
-Alternatively, the grouping key can be a vertex or edge, and then any
properties of the vertex or edge can be specified without being explicitly
stated in a WITH or RETURN column.
+Alternatively, the grouping key can be a vertex or edge, and then any
properties of the vertex or edge can be specified without being explicitly
stated in a `WITH` or `RETURN` column.
```postgresql
SELECT * FROM cypher('graph_name', $$
@@ -229,7 +229,7 @@ SELECT * FROM cypher('graph_name', $$
$$) as (count agtype, key agtype);
```
-Results will be grouped on x, because it is safe to assume that properties be
considered unecessary for grouping to be unambiguous.
+Results will be grouped on `x`, because it is safe to assume that properties
be considered unecessary for grouping to be unambiguous.
Results
<table>
@@ -259,7 +259,7 @@ Results
### Hiding unwanted grouping keys
-If the grouping key is considered unecessary for the query output, the
aggregation can be done in a WITH clause then passing information to the RETURN
clause.
+If the grouping key is considered unecessary for the query output, the
aggregation can be done in a `WITH` clause then passing information to the
`RETURN` clause.
```postgresql
SELECT * FROM cypher('graph_name', $$
diff --git a/docs/intro/comparability.md b/docs/intro/comparability.md
index 430cacf2..63b14031 100644
--- a/docs/intro/comparability.md
+++ b/docs/intro/comparability.md
@@ -9,9 +9,9 @@ AGE already has good semantics for equality within the
primitive types (booleans
The underlying conceptual model is complex and sometimes inconsistent. This
leads to an unclear relationship between comparison operators, equality,
grouping, and ORDER BY:
* Comparability and orderability are aligned with each other consistently, as
all types can be ordered and compared.
-* The difference between equality and equivalence, as exposed by IN, =,
DISTINCT, and grouping, in AGE is limited to testing two instances of the value
null to each other
- * In equality, null = null is null.
- * In equivalence, used by DISTINCT and when grouping values, two null
values are always treated as being the same value.
+* The difference between equality and equivalence, as exposed by `IN`, `=`,
`DISTINCT`, and grouping, in AGE is limited to testing two instances of the
value null to each other
+ * In equality, `null = null` is `null`.
+ * In equivalence, used by `DISTINCT` and when grouping values, two null
values are always treated as being the same value.
* However, equality treats null values differently if they are an element
of a list or a map value.
## Concepts
@@ -26,17 +26,17 @@ Comparability is used by the inequality operators (>, <,
>=, <=), and defi
### Equality
-Equality is used by the equality operators (=, <>), and the list membership
operator (IN). It defines the underlying semantics to determine if two values
are the same in these contexts. Equality is also used implicitly by literal
maps in node and relationship patterns, since such literal maps are merely a
shorthand notation for equality predicates.
+Equality is used by the equality operators (=, <>), and the list membership
operator (`IN`). It defines the underlying semantics to determine if two values
are the same in these contexts. Equality is also used implicitly by literal
maps in node and relationship patterns, since such literal maps are merely a
shorthand notation for equality predicates.
### Orderability
-Orderability is used by the ORDER BY clause, and defines the underlying
semantics of how to order values.
+Orderability is used by the `ORDER BY` clause, and defines the underlying
semantics of how to order values.
### Equivalence
-Equivalence is used by the DISTINCT modifier and by grouping in projection
clauses (WITH,RETURN), and defines the underlying semantics to determine if two
values are the same in these contexts.
+Equivalence is used by the `DISTINCT` modifier and by grouping in projection
clauses (`WITH`, `RETURN`), and defines the underlying semantics to determine
if two values are the same in these contexts.
## Comparability and equality
@@ -57,8 +57,8 @@ Comparability is defined between any pair of values, as
specified below.
* Integers are compared numerically in ascending order.
* Floats
* Floats (excluding NaN values and the Infinities) are compared
numerically in ascending order.
- * Positive infinity is of type FLOAT, equal to itself and greater than
any other number, except NaN values.
- * Negative infinity is of type FLOAT, equal to itself and less than
any other number.
+ * Positive infinity is of type `FLOAT`, equal to itself and greater
than any other number, except NaN values.
+ * Negative infinity is of type `FLOAT`, equal to itself and less than
any other number.
* NaN values are comparable to each and greater than any other float
value.
* Numeric
* Numerics are compared numerically in ascending order.
@@ -66,14 +66,14 @@ Comparability is defined between any pair of values, as
specified below.
* Booleans are compared such that false is less than true.
* Comparison to any value that is not also a boolean follows the rules of
orderability.
* Strings
- * Strings are compared in dictionary order, i.e. characters are compared
pairwise in ascending order from the start of the string to the end. Characters
missing in a shorter string are considered to be less than any other character.
For example, 'a' < 'aa'.
+ * Strings are compared in dictionary order, i.e. characters are compared
pairwise in ascending order from the start of the string to the end. Characters
missing in a shorter string are considered to be less than any other character.
For example, `'a' < 'aa'`.
* Comparison to any value that is not also a string follows the rules of
orderability.
* Lists
- * Lists are compared in sequential order, i.e. list elements are compared
pairwise in ascending order from the start of the list to the end. Elements
missing in a shorter list are considered to be less than any other value
(including null values). For example, [1] < [1, 0]but also [1] < [1,
null].
+ * Lists are compared in sequential order, i.e. list elements are compared
pairwise in ascending order from the start of the list to the end. Elements
missing in a shorter list are considered to be less than any other value
(including null values). For example, `[1] < [1, 0]` but also `[1] < [1, null]`.
* Comparison to any value that is not also a list follows the rules of
orderability.
* Maps
* The comparison order for maps is unspecified and left to implementations.
- * The comparison order for maps must align with the equality semantics
outlined below. In consequence, any map that contains an entry that maps its
key to a null value is incomparable. For example, {a: 1} <= {a: 1, b: null}
evaluates to null.
+ * The comparison order for maps must align with the equality semantics
outlined below. In consequence, any map that contains an entry that maps its
key to a null value is incomparable. For example, `{a: 1} <= {a: 1, b: null}`
evaluates to null.
* Comparison to any value that is not also a regular map follows the rules
of orderability.
Entities
@@ -82,7 +82,7 @@ Entities
* Edges
* The comparison order for edges is based on the assigned graphid.
* Paths
- * Paths are compared as if they were a list of alternating nodes and
relationships of the path from the start node to the end node. For example,
given nodes n1, n2, n3, and relationships r1and r2, and given that n1 < n2
< n3 and r1 < r2, then the path p1 from n1 to n3 via r1 would be less
than the path p2 to n1 from n2 via r2.
+ * Paths are compared as if they were a list of alternating nodes and
relationships of the path from the start node to the end node. For example,
given nodes `n1`, `n2`, `n3`, and relationships `r1` and `r2`, and given that
`n1 < n2 < n3` and `r1 < r2`, then the path `p1` from `n1` to `n3` via `r1`
would be less than the path `p2` to `n1` from `n2` via `r2`.
* Expressed in terms of lists:
```
p1 < p2
diff --git a/docs/intro/cypher.md b/docs/intro/cypher.md
index b3744fc6..2af9a592 100644
--- a/docs/intro/cypher.md
+++ b/docs/intro/cypher.md
@@ -5,7 +5,7 @@ Cypher queries are constructed using a function called cypher
in ag_catalog whic
## Cypher()
-Cypher() executes the cypher query passed as an argument.
+`cypher()` executes the cypher query passed as an argument.
Syntax `cypher(graph_name, query_string, parameters)`
@@ -68,7 +68,7 @@ Cypher may not be used as part of an expression, use a
subquery instead. See [Ad
## SELECT Clause
-Calling Cypher in the SELECT clause as an independent column is not allowed.
However Cypher may be used when it belongs as a conditional.
+Calling Cypher in the `SELECT` clause as an independent column is not allowed.
However Cypher may be used when it belongs as a conditional.
Not Allowed:
diff --git a/docs/intro/graphs.md b/docs/intro/graphs.md
index 5d53081c..2d1b336d 100644
--- a/docs/intro/graphs.md
+++ b/docs/intro/graphs.md
@@ -5,7 +5,7 @@ A graph consists of a set of vertices and edges, where each
individual node and
## Create a Graph
-To create a graph, use the create_graph function, located in the ag_catalog
namespace.
+To create a graph, use the `create_graph` function, located in the
`ag_catalog` namespace.
### create_graph()
@@ -52,7 +52,7 @@ SELECT * FROM ag_catalog.create_graph('graph_name');
## Delete a Graph
-To delete a graph, use the drop_graph function, located in the ag_catalog
namespace.
+To delete a graph, use the `drop_graph` function, located in the `ag_catalog`
namespace.
### drop_graph()
diff --git a/docs/intro/setup.md b/docs/intro/setup.md
index 3b9835e6..fed68e4b 100644
--- a/docs/intro/setup.md
+++ b/docs/intro/setup.md
@@ -126,7 +126,7 @@ For every connection of AGE you start you will need to load
the AGE extension.
LOAD 'age';
```
-We recommend adding ag_catalog to your search_path to simplify your queries.
The rest of this document will assume you have done so. If you do not, remember
to add 'ag_catalog' to your cypher query function calls.
+We recommend adding `ag_catalog` to your `search_path` to simplify your
queries. The rest of this document will assume you have done so. If you do not,
remember to add 'ag_catalog' to your cypher query function calls.
```postgresql
SET search_path = ag_catalog, "$user", public;
@@ -134,7 +134,7 @@ SET search_path = ag_catalog, "$user", public;
### Allow non-superusers to use Apache AGE
-* Non-superusers can only apply LOAD to library files located in
`$libdir/plugins/` (see <https://www.postgresql.org/docs/15/sql-load.html>). A
symlink can be created to allow non-superusers to LOAD the Apache AGE library:
+* Non-superusers can only apply `LOAD` to library files located in
`$libdir/plugins/` (see <https://www.postgresql.org/docs/15/sql-load.html>). A
symlink can be created to allow non-superusers to `LOAD` the Apache AGE library:
```console
sudo ln -s /usr/lib/postgresql/15/lib/age.so
/usr/lib/postgresql/15/lib/plugins/age.so
diff --git a/docs/intro/types.md b/docs/intro/types.md
index 072e61b0..9f94d5ec 100644
--- a/docs/intro/types.md
+++ b/docs/intro/types.md
@@ -8,7 +8,7 @@ AGE uses a custom data type called agtype, which is the only
data type returned
### Null
-In Cypher, null is used to represent missing or undefined values.
Conceptually, null means 'a missing unknown value' and it is treated somewhat
differently from other values. For example getting a property from a vertex
that does not have said property produces null. Most expressions that take null
as input will produce null. This includes boolean expressions that are used as
predicates in the WHERE clause. In this case, anything that is not true is
interpreted as being false. null is no [...]
+In Cypher, `null` is used to represent missing or undefined values.
Conceptually, `null` means 'a missing unknown value' and it is treated somewhat
differently from other values. For example getting a property from a vertex
that does not have said property produces `null`. Most expressions that take
`null` as input will produce `null`. This includes boolean expressions that are
used as predicates in the `WHERE` clause. In this case, anything that is not
true is interpreted as being false [...]
Input/Output Format
@@ -48,13 +48,13 @@ Result:
#### Agtype NULL vs Postgres NULL
-The concept of NULL in Agtype and Postgres is the same as it is in Cypher.
+The concept of `NULL` in Agtype and Postgres is the same as it is in Cypher.
### Integer
The integer type stores whole numbers, i.e. numbers without fractional
components. Integer data type is a 64-bit field that stores values from
-9,223,372,036,854,775,808 to 9,223,372,036,854,775,807. Attempts to store
values outside this range will result in an error.
-The type integer is the common choice, as it offers the best balance between
range, storage size, and performance. The smallint type is generally used only
if disk space is at a premium. The bigint type is designed to be used when the
range of the integer type is insufficient.
+The type integer is the common choice, as it offers the best balance between
range, storage size, and performance. The `smallint` type is generally used
only if disk space is at a premium. The `bigint` type is designed to be used
when the range of the integer type is insufficient.
Input/Output Format
@@ -91,7 +91,7 @@ Result:
### Float
-The data type float is an inexact, variable-precision numeric type, conforming
to the IEEE-754 Standard.
+The data type `float` is an inexact, variable-precision numeric type,
conforming to the IEEE-754 Standard.
Inexact means that some values cannot be converted exactly to the internal
format and are stored as approximations, so that storing and retrieving a value
might show slight discrepancies. Managing these errors and how they propagate
through calculations is the subject of an entire branch of mathematics and
computer science and will not be discussed here, except for the following
points:
@@ -158,7 +158,7 @@ Result:
### Numeric
-The type numeric can store numbers with a very large number of digits. It is
especially recommended for storing monetary amounts and other quantities where
exactness is required. Calculations with numeric values yield exact results
where possible, e.g., addition, subtraction, multiplication. However,
calculations on numeric values are very slow compared to the integer types, or
to the floating-point type.
+The type `numeric` can store numbers with a very large number of digits. It is
especially recommended for storing monetary amounts and other quantities where
exactness is required. Calculations with numeric values yield exact results
where possible, e.g., addition, subtraction, multiplication. However,
calculations on numeric values are very slow compared to the integer types, or
to the floating-point type.
We use the following terms below: The _precision_ of a numeric is the total
count of significant digits in the whole number, that is, the number of digits
to both sides of the decimal point. The _scale_ of a numeric is the count of
decimal digits in the fractional part, to the right of the decimal point. So
the number 23.5141 has a precision of 6 and a scale of 4. Integers can be
considered to have a scale of zero.
@@ -173,7 +173,7 @@ The maximum allowed precision when explicitly specified in
the type declaration
If the scale of a value to be stored is greater than the declared scale of the
column, the system will round the value to the specified number of fractional
digits. Then, if the number of digits to the left of the decimal point exceeds
the declared precision minus the declared scale, an error is raised.
-Numeric values are physically stored without any extra leading or trailing
zeroes. Thus, the declared precision and scale of a column are maximums, not
fixed allocations. (In this sense the numeric type is more akin to varchar(_n_)
than to char(_n_).) The actual storage requirement is two bytes for each group
of four decimal digits, plus three to eight bytes overhead.
+Numeric values are physically stored without any extra leading or trailing
zeroes. Thus, the declared precision and scale of a column are maximums, not
fixed allocations. (In this sense the numeric type is more akin to `varchar(n)`
than to `char(n)`.) The actual storage requirement is two bytes for each group
of four decimal digits, plus three to eight bytes overhead.
In addition to ordinary numeric values, the numeric type allows the special
value NaN, meaning “not-a-number”. Any operation on NaN yields another NaN.
When writing this value as a constant in an SQL command, you must put quotes
around it, for example UPDATE table SET x = 'NaN'.
@@ -189,7 +189,7 @@ When rounding values, the numeric type rounds ties away
from zero, while (on mos
Input/Output Format:
-When creating a numeric data type, the ‘::numeric’ data annotation is required.
+When creating a numeric data type, the `::numeric` data annotation is required.
Query
@@ -226,7 +226,7 @@ Result:
AGE provides the standard Cypher type boolean. The boolean type can have
several states: “true”, “false”, and a third state, “unknown”, which is
represented by the Agtype null value.
-Boolean constants can be represented in Cypher queries by the keywords TRUE,
FALSE, and NULL.
+Boolean constants can be represented in Cypher queries by the keywords `TRUE`,
`FALSE`, and `NULL`.
Input/Output Format
@@ -372,7 +372,7 @@ Result:
### List
-All examples will use the [WITH](../clauses/with.md) clause and
[RETURN](../clauses/return.md) clause.
+All examples will use the [`WITH`](../clauses/with.md) clause and
[`RETURN`](../clauses/return.md) clause.
#### Lists in general
@@ -413,7 +413,7 @@ Result:
#### NULL in a List
-A list can hold the value null, unlike when a null is an independent value, it
will appear as the word ‘null’ in a list
+A list can hold the value `null`, unlike when a `null` is an independent
value, it will appear as the word ‘null’ in a list
Query
