About Graph Pattern

5.1 About Graph Pattern

The GRAPH_TABLE operator in a SQL graph query contains a graph pattern.

A graph pattern is expressed between the input graph name and the COLUMNS clause inside the GRAPH_TABLE operator.

A graph pattern contains one or more comma-separated path patterns, which are composed of vertex and edge patterns. For example, the following path pattern has two vertex patterns and one edge pattern:

(v1) -[e]-> (v2)

A vertex pattern is enclosed in parentheses and specifies how to match a single vertex. An edge pattern is enclosed by a square bracket with delimiters on the left and right side of the edge pattern and specifies how to match a single edge.

Also, the available arrow tokens for edge patterns are summarized in the following table:

Table 5-1 Arrow Tokens for Edge Patterns

Directionality	Bracketed Syntax	Abbreviated Syntax^Foot 1
Directed to the right	`-[ ]->`	`->`
Directed to the left	`<-[ ]-`	`->`
Any directed edge (right or left)	`<-[ ]->` or `-[ ]-`	`-`

^Footnote 1

There are no brackets for the arrows in the “abbreviated syntax” column.
All edge labels will be considered as no edge label is specified. Hence, filtering on a specific edge is not supported.

A graph element pattern (which can either be a vertex or an edge pattern) may in turn optionally include:

An element variable.
A label expression which is that part in an element pattern that starts with the keyword IS and is followed by a list of one or more label names. If there is more than one label name, then these are separated by vertical bars.
An element pattern WHERE clause which expresses a search condition on the element variable declared by the element pattern.

5.1.1 Graph Element Variables

Vertex and edge pattern variables ranges over vertices and edges respectively.

For example, consider the following graph pattern which contains three graph element variables.

(v1)–[e]->(v2)

In the preceding graph pattern, v1 and v2 are two vertex pattern variables and e is an edge pattern variable.

Ensure that you apply the following rules for the graph pattern variables:

You cannot use the same variable name for both a vertex and an edge.
You can use the same variable name in two different vertex patterns as shown:
MATCH (a IS person) -> (a IS person)

In the preceding example, the vertex variable a is used in two vertex patterns - (a IS person) and (a IS person). This implies that the two vertex patterns that declare the same vertex variable must bind to the same vertex. Thus the vertex variable binds to a unique vertex but the vertex pattern can appear multiple times in the same graph pattern.
You can use the same variable name in two different edge patterns.
Anonymous (that is, omitted) vertex and edge variables are supported. See Example 5-8.

Parent topic: About Graph Pattern

5.1.2 Path Variables

A graph path pattern in a SQL graph query can have an optional path variable declaration.

For instance, consider the following example which shows comma-separated path patterns in a MATCH clause:

MATCH p1 = (a is Person), (b is Person)

The first path pattern (a is Person) starts with a path variable declaration named p1, whereas the second path pattern (b is Person) is unnamed.

Note the following about path variables:

Path variable declarations are optional in a path pattern.
A path variable, when used, is declared at the beginning of a path pattern.
A MATCH clause can contain both named and unamed path patterns.
All path variables have to be unique and cannot be multiply declared. This means that a path variable may not be declared with the same name as an element variable, an iterator variable, or another path variable.
Adding a path variable to SQL graph query does not impact the query output unless the query contains the ONE ROW PER STEP/VERTEX clause or PATH_NAME function.

See Example 5-21 for an example using path variables.

Parent topic: About Graph Pattern

5.1.3 Label Expressions

A label expression in a vertex or an edge element pattern is introduced by the keyword IS.

For example, in the following graph pattern, the vertex pattern associated with the graph element variable v1 has the label person. Also, the edge pattern associated with the graph element variable e contains the label friendOf:

(v1 IS person) –[e IS friendOf]-> (v2)

If the label is omitted in a graph element pattern, then depending on the type of the element variable, either all vertex properties or all edge properties in the graph can be referenced. Otherwise, if a label expression is specified, then the set of properties that can be referenced is the union of the properties of labels belonging to vertex (or edge) tables that have at least one label that satisfies the label expression.

A label expression can also include an optional in-line SQL search condition that can access any matched variable. When accessing a property, you must specify a graph pattern variable.

The supported vertex and edge label expressions are described in the following table:

Table 5-2 Supported Vertex and Edge Label Expressions

Vertex Label Expression	Edge Label Expression	Description
`(a)`	`[e]`	The vertex graph pattern variable `a` may match a vertex with any label. The edge graph pattern variable `e` may match an edge with any label.
`()`	`[]`	The vertex pattern has no label and can match any vertex. The edge pattern has no label and can match any edge. When a graph pattern variable is not specified, a unique vertex or edge variable name is internally generated by the system. Therefore, you cannot reference the vertex or edge elsewhere in the query, as it is unknown.
`(IS person)`	`[IS friend_of]`	The vertex pattern has only the `person` label. The edge pattern has only the `friend_of` label. When a graph pattern variable is not specified, a unique vertex or edge variable name is internally generated by the system. Therefore, you cannot reference the vertex or edge elsewhere in the query, as it is unknown.
`(IS person\|place\|thing)`	`[IS friend_of\|student_of]`	The vertex pattern has an alternation of three labels, `person`, `place` and `thing`. This implies that the vertex pattern can match any vertex having those labels. The edge pattern has an alternation of two labels, `friend_of` and `student_of`. This implies that the edge pattern can match any edge having those labels. As there is no explicit graph pattern variable in the vertex or edge pattern, you cannot reference this vertex or edge elsewhere in the query.
`(a IS person\|place\|thing)`	`[e IS friend_of\|student_of]`	Same as the preceding table entry. However, the vertex and edge patterns contain `a` and `e` as vertex and edge graph pattern variables respectively. Therefore, you can reference the vertex or edge using the respective graph pattern variables elsewhere in the query. See Example 5-12.
`(a IS person),` `(a IS car)`	`(a)–[e IS L1]->(b),` `(a)–[e is L2]->(b)`	The vertex pattern `a IS person` implies that `a` must match vertices having the label `person`, and the vertex pattern `a IS car` implies that `a` must match vertices having the label `car`. Therefore, this represents that `a` must match vertices having both `person` and `car` as labels, effectively an `AND` of these two conditions. Also, you can reference a vertex as `a` elsewhere in the query. The edge pattern `e IS L1` implies that `e` must match edges having the label `L1`, and the edge pattern `e IS L2` implies that `e` must match edges having the label `L2`. Therefore, this represents that `e` must match edges having both `L1` and `L2` as labels, effectively an `AND` of these two conditions. Also, you can reference an edge as `e` elsewhere in the query. See Example 5-13.
`(a IS person WHERE a.name = 'Fred')`	`[e IS student_of WHERE e.subject = 'Arts']`	The vertex pattern has a label `person` and a vertex graph pattern variable `a`, which is qualified in the element pattern `WHERE` clause. The edge pattern has a label `student_of` and an edge graph pattern variable `e`, which is qualified in the element pattern `WHERE` clause. The only graph pattern variable that is visible within an element pattern is the graph pattern variable defined locally by the element pattern. Graph pattern variables from another element patterns cannot be accessed. See Example 5-5.

Parent topic: About Graph Pattern

5.1.4 Accessing Label Properties

You can access a property inside a graph element pattern, in the out-of-line WHERE clause or in the COLUMNS clause.

Consider the following graph element pattern where a is a graph element variable and name is a property name:

(a IS person WHERE a.name='John')

You can then reference the property in the WHERE clause inside the graph element pattern as a.name. This means a.name references the property name of the graph element bound to the graph pattern variable a.

Also, the following conditions apply when accessing a property:

The property name is part of at least one table that satisfies the label expression.
A graph variable name must always be used to access a property.
At the time of query compilation, certain type checking rules apply for the vertex or edge table properties. See Type Compatibility Rules for Determining Property Types for more information.
If an element variable is not bound to a graph element, then the result is a null value. This can happen only when an element variable is optionally bound, such as when the element variable is an iterator variable declared in ONE ROW PER STEP. Specifically, the edge variable and the second vertex variable declared in ONE ROW PER STEP will not be bound to a graph element when the path pattern matches an empty path (that is, when a quantifier iterated zero times). See Using ONE ROW PER Clause in a SQL Graph Query for more information on ONE ROW PER STEP.

The following examples describe a few scenarios for determining property types when querying SQL property graphs. Note that Example 5-1 to Example 5-3 refer to the SQL property graph definition for g1 which contains height as a shared property across different labels.

Example 5-1 Determining the Property Type for a Single Label

The data type for a.height in the following query is FLOAT:

SELECT * FROM GRAPH_TABLE (g1
MATCH
(a IS person)
COLUMNS (a.height)
);

The query output is as shown:

HEIGHT
----------
       1.8
      1.65
      1.75
       1.7

Example 5-2 Determining Union Compatible Property Type for Two Different Labels

The data type for a.height in the following query is the union compatible type between FLOAT and BINARY_DOUBLE:

SELECT * FROM GRAPH_TABLE (g1
MATCH
(a IS person|t3)
COLUMNS (a.height)
);

The query output is as shown:

    HEIGHT
----------
  1.8E+000
 1.65E+000
 1.75E+000
  1.7E+000
  1.8E+000
 1.65E+000

In the SQL property graph g1, the property type for height associated with the labels person and t3 is FLOAT and BINARY_DOUBLE respectively. BINARY_DOUBLE takes precedence over FLOAT and hence the resulting output property type for a.height is BINARY_DOUBLE.

Example 5-3 No Union Compatible Property Type for Two Different Labels

Error is thrown for the following query as the data type for a.height is not union compatible across the tables, person (FLOAT) and t2 (VARCHAR):

SELECT * FROM GRAPH_TABLE (g1
  MATCH
   (a IS person|t2)
  COLUMNS (a.height)
  );

On execution. the preceding query throws the error - ORA-01790: expression must have same datatype as corresponding expression

Example 5-4 Determining Union Compatible Property Type for Shared Labels

Consider the SQL property graph definition for g3 which uses a shared label (t) that is associated with a shared property name (height).

When querying g3, the data type for a.height in the following SQL graph query is BINARY_DOUBLE:

SELECT * FROM GRAPH_TABLE (g3
MATCH
(a IS t)
COLUMNS (a.height)
);

The query output is a union of the property columns across all the graph element tables sharing the label. Also, the property type is BINARY_DOUBLE as per the Type Compatibility Rules for Determining Property Types:

    HEIGHT
----------
  1.8E+000
 1.65E+000
 1.75E+000
  1.7E+000
  1.8E+000
 1.65E+000

Parent topic: About Graph Pattern

5.1.5 Using the IS LABELED Predicate

You can use the IS [NOT] LABELED predicate to determine whether a graph element satisfies a label expression.

The function returns a BOOLEAN data type as specified in the following scenarios:

TRUE: A vertex or an edge is bound to the specified label.
FALSE: A vertex or an edge is bound, but not to the specified label.
NULL: A vertex or an edge is not bound.

The IS [NOT] LABELED predicate can be used in the COLUMNS or WHERE clause of a SQL graph query as shown:

SELECT * FROM GRAPH_TABLE ( g1
MATCH (n)
COLUMNS (n.name, n IS LABELED Person AS labeledPerson)
);

Note that you can only specify a simple label name; label disjunction is not supported.

See Example 5-14 for more information.

Parent topic: About Graph Pattern

5.1.6 Using the PROPERTY_EXISTS Predicate

You can use the PROPERTY_EXISTS predicate to determine if the graph element bound to a singleton element reference has a specific property.

The function returns a BOOLEAN data type as specified in the following scenarios:

TRUE: A vertex or an edge is bound and at least one of the labels have the specified property.
FALSE: A vertex or an edge is bound, but the specified property does not exist in any of the labels.
NULL: A vertex or an edge is not bound.

The PROPERTY_EXISTS predicate can be used in the COLUMNS or WHERE clause of a SQL graph query as shown:

SELECT * FROM GRAPH_TABLE ( g1
MATCH (n)
COLUMNS (n.name, PROPERTY_EXISTS(n, name) AS nameExists)
);

See Example 5-15 for more information.

Parent topic: About Graph Pattern