Query Language Syntax Versions

GSQL has three syntax versions: V3, V2, and V1 (legacy version). In TigerGraph 3.5, the default syntax version was changed to V2. Currently, V2 remains the default syntax version. In a future release, V3 will become the default syntax version. This page provides a summary of the differences between V2 and V3, as well as V1 and V2. It also includes guidance on how to change your V1 query into a V2 query.

Differences between V2 and V3

The table below highlights the differences between V2 and V3, focusing on the FROM clause. Note that V3 still supports V2 style syntax, for backward compatibility.

Feature V2 Style V3 Style

Vertex-Edge-Vertex Markers

Use source_vset -(edge_set)- target_vset notation. Vertices and edges are separated without additional symbols for vertices, for example, Person -(FRIENDS)- Colleague.

Use (source_vset) -[edge_set]- (target_vset) notation, where vertices are enclosed in parentheses () and edges are enclosed in square brackets [] . For example: (Person) -[FRIENDS]- (Colleague).

Alias Ordering

Object sets precede aliases: source_vset:Alias -(edge_set:EdgeAlias)- target_set:Alias.

Aliases precede object sets: (Alias:source_vset) -[EdgeAlias:edge_set]- (Alias:target_set), reversing the order of V2.

Symbols for Edge Direction

Directionality is applied at the edge-set level. Supports < (left), > (right), and _ (undirected).

Directionality applies to the entire edge pattern. Symbols include <- (left), -> (right), ~ (undirected).

Edge Direction Syntax

Supports granular directionality at the individual edge set level, allowing each edge sets in a pattern to have its own direction.

Directionality is applied globally at the edge pattern level.

Quantified Multi-Hop Patterns

V2 uses *j..k to express a range of j to k repeated edges: -(FRIENDS*1..3)->

V3 uses [j,k] to express a range of j to k repeated edges: [FRIENDS]->{1,3}

Filters in Edge Patterns

Filters are applied outside the FROM clause, e.g., SELECT Person FROM Person -(FRIENDS)- Colleague WHERE FRIENDS.length > 2

Filters can also be placed within an edge pattern for more local scope , e.g., SELECT Person FROM (Person) -[FRIENDS WHERE FRIENDS.length > 2]-> (Colleague)

V2 vs. V3 Syntax: Examples and Explanations

  1. Vertex-Edge-Vertex Markers:

    • V2 Syntax: Person -(FRIENDS)- Colleague

    • V3 Syntax: (Person) -[FRIENDS]- (Colleague)

    • In V3, uses more punctuation in order to be more explicit about vertex and edge patterns.

  2. Alias Ordering:

    • V2 Syntax: Person:p -(FRIENDS:f)- Colleague:c

    • V3 Syntax: (p:Person) -[f:FRIENDS]- (c:Colleague)

  3. Symbols for Edge Direction:

    • V2 Syntax: -(FRIENDS>:f)-

    • V3 Syntax: <-[f:FRIENDS]->

    • V3 directionality is applied globally to the entire edge pattern. V2 directionality applies to each individual edge type, for greater flexibility.

  4. Filters in Edge Patterns:

    • V2 Syntax: Filtering is applied outside the FROM clause using a WHERE condition: SELECT Person FROM Person -(FRIENDS)- Colleague WHERE FRIENDS.length > 2

    • V3 Syntax: Filters can also be placed within an edge pattern for more local scope: SELECT Person FROM (Person) -[FRIENDS WHERE FRIENDS.length > 2]-> (Colleague)

  5. Quantified Multi-Hop Patterns:

    • V2 Syntax: -(FRIENDS*1..3)->

    • V3 Syntax: [FRIENDS]->{1,3}

Comparing V2 and V3 Edge Directions

In the following table,

  1. E1 and E2: These represent directed edge types. A directed edge has a defined direction, such as Person -> Company.

  2. U1 and U2: These represent undirected edge types. An undirected edge does not have a direction and connects vertices symmetrically, such as Person - Person.

  3. Alias (A): The alias is a short name or label given to an edge or vertex for use in queries.

  4. Edge Direction:

    • Left (<): Represents edges directed towards the starting vertex.

    • Right (>): Represents edges directed away from the starting vertex.

    • Undirected (~): Represents edges with no directionality.

    • Combination (<~, ~>, etc.): Represents edges with a combination of directionality (e.g., left or undirected, right or undirected).

Orientation V2 Syntax V3 Syntax

Pointing Left

-(<E1:A)-

<-[A:E1]-

Pointing Right

-(E1>:A)-

-[A:E1]->

Undirected

-(U1:A)-

~[A:U1]~

Left or Undirected

-((<E1|U1):A)-

<~[A:E1|U1|..]~

Right or Undirected

-((E1>|U1):A)-

~[A:E1|U1|..]~>

Any direction or undirected

-(<_||>):A)-

or

-(:A)-

-[A:U1|E1|..]-

or

-[A:]-

Differences between V1 and V2

The two tables below summarize the differences between V1 and V2.

Most of the syntactical differences between V1 and V2 lie in the FROM clause of the SELECT statement. Therefore, Table 1 specifically lays out the differences in the FROM clause. Other differences are summarized in Table 2.

Table 1. Differences in the FROM clause
Feature V1 V2

Step vs path pattern

The keyword FROM is followed by a 1-hop step. Supports 1-hop only.

For more information, see FROM clause (V1).

The keyword FROM is followed by a path pattern. The path pattern may consist of multiple hops and allows for powerful pattern matching.

Edge notation

Edges in a step can optionally have a right arrowhead outside the parentheses. For example: Start:s -( Edges:e )-> Target:t or Start:s -( Edges:e )- Target:t

No arrowheads are allowed outside the parentheses. If an edge type is directed, the edge notation must have arrowheads inside the parentheses to indicate direction. For example: Person:s-(STUDY_AT>:e)-University:t

Traversal direction

The traversal action is from left to right, and the notation uses either a rightward facing arrowhead or no arrowhead to depict a connection.

The traversal direction is under the control of the query writer, with arrowheads on each edge set to show the direction.

Source vertex set

The source vertex set in a step in the FROM clause must be a vertex set (seed set) declared earlier in the query.

The source vertex set path pattern in FROM clause can be a vertex set, a vertex type, or use or ANY to indicate any vertex.
Table 2. Other differences
Feature V1 V2

POST-ACCUM clause

  • Each SELECT statement can only have 1 POST-ACCUM clause.

  • A POST-ACCUM clause may have statements that reference both source and target vertex aliases.

  • Each SELECT statement can have multiple POST-ACCUM clauses.

  • Each POST-ACCUM clause must bind itself with one vertex alias. This can be done explicitly or implicitly.

SQL-like SELECT statement

Not supported.

Supported.

Data modification statements

FROM clause can only perform one hop, which is the same as in the SELECT statement in V1.

FROM clause can only perform one hop, even though it may perform multiple hops in the SELECT statement.

Changing a query from V1 to V2

This section provides you with instructions to convert a V1 query into a V2 query.

GSQL can detect the syntax version of the query automatically, so there is no need to modify your queries from V1 to V2.

  1. Delete, move, or add arrowheads in the FROM clause.

    • If the edge is undirected, delete the arrowhead outside parentheses in the FROM clause.

      • For example Source:s -(Friend:e)-> :t becomes Source:s -(Friend:e)- :t

    • If the edge is directed, move the arrowheads into the parentheses after the edge type. If there is no arrowhead, you must add one after the edge type.

      • For example, Source:s -(Is_Located_In:e)-> :t becomes Source:s -(Is_Located_In>:e)- :t

    This is the most common incompatibility issue between a query written in V1 and V2. Most V1 queries can run smoothly in V2 after the arrowheads are deleted.

  2. Check for POST-ACCUM clauses that aren’t bound to one vertex alias or are bound to more than one vertex alias.

    • In V2, every POST-ACCUM clause must reference one vertex alias. If your V1 query has a POST-ACCUM clause that reference multiple vertex aliases, you need to break the POST-ACCUM clause into multiple POST-ACCUM clauses, with each clause referencing one vertex alias only.

Since a SELECT statement can only perform one hop in V1, you may have had to write multiple SELECT statements in order to write a multi-hop query. With pattern matching in V2, you may choose to rewrite the query to use a single SELECT statement to perform multiple hops.