GSQL Style Guide

This page details TigerGraph’s style guide for writing GSQL. The purpose of the style guide is to make code easy to read and achieve lower cost of maintenance.

General

Naming

Identifiers are categorized into two broad classes:

  • Schema object types (graph, vertex, edge, and tuple type).

  • Instances.

Schema types are analogous to classes in an object-oriented language. Schema object types names have their initial letter capitalized, connected by underscore; instances use snake case, with additional specifications for accumulators.

Detailed identifier naming conventions are described in the following table:

Identifier type Style Example

Instances (This includes any variable one can declare in a loading job or query not otherwise specified in the table)

Use snake case: lowercase, letters connected by underscore

  • batch_number

  • v_type

Non-collection accumulators (SumAccum, MinAccum, MaxAccum etc.)

  • Use snake case

  • Start with the aggregation type such as sum unless there is an excellent semantic alternative

@num_fraudsters[1]

Collection accumulator

  • Use snake case

  • End with container type

  • @top_result_list

  • @@property_map

  • @neighbor_set

Vertex type name

Capitalize initial letters and connect words with underscores.

  • Person

  • Medical_Condition

Edge type name

Capitalize initial letters and connect words with underscores.

  • Diagnosed_By

Vertex and edge attribute name

Use snake case.

CREATE VERTEX Genre (PRIMARY_ID genre_id STRING, genre_name STRING)

Graph name

Capitalize initial letters and connect words with underscores.

  • Social_Net

Tuple type name

Capitalize initial letters and connect words with underscores.

  • Vertex_Score

  • Key_Pair

Query and loading job name

Use snake case.

  • match_users

  • suggest_products

  • tg_degree_cent

Spacing

Block indentation

Indent the body of a block by 4 spaces. A block is a syntactic structure which may contain multiple statements. This includes queries, SELECT, IF/ELSE, CASE WHEN/THEN, FOREACH, and WHILE. If the body of ACCUM or POST-ACCUM contains multiple clauses, then use indentation also. Use spaces instead of tabs, because tab size can vary.

Recommended

 
CREATE QUERY hello(VERTEX<Person> p) {
    Start = {p};
    Result = SELECT tgt
        FROM Start:s -(Friendship:e)- Person:tgt;
        PRINT Result;
}

Not recommended

 
CREATE QUERY hello(VERTEX<Person> p) {
Start = {p};
Result = SELECT tgt
         FROM Start:s -(Friendship:e)- Person:tgt;
PRINT Result;
}

Line length

Lines should be short enough so that they display without scrolling and can be printed without anything being cut off. If a line is more than 80 characters, it should be split into multiple lines. The additional lines should be indented, but by 2 spaces only, to show that they are a continuation of the previous line.

Recommended

CREATE QUERY hello(VERTEX<Person> p) {
    start = {p};
    result = SELECT tgt
        FROM start:s -(Friendship:e)- Person:tgt; /* This is a long
          comment and it is split into multiple lines. */
        PRINT Result;
}

Not recommended

CREATE QUERY hello(VERTEX<Person> p) {
    Start = {p};
    Result = SELECT tgt
        FROM Start:s -(Friendship:e)- Person:tgt; // This is a long comment that spans over a hundred characters. It really should be split into multiple lines instead of crowding one line
    PRINT Result;
}

Keyword justification

In a SELECT block, line up the keywords FROM, SAMPLE, WHERE, ACCUM, POST-ACCUM, HAVING, GROUP BY, ORDER BY, and LIMIT.

Recommended

 
CREATE QUERY active_members (INT activity_threshold) FOR GRAPH Social_Net {
    SumAccum<INT> @activity_amount;
    start = {Person.*};
    result = SELECT v FROM start:v -(:e)- Post:tgt
        ACCUM v.@activity_amount +=1
        HAVING v.@activity_amount >= activity_threshold; (1)
    PRINT result;
}
1 ACCUM and HAVING are lined up in the SELECT block.
2 It is acceptable to combine SELECT and FROM on the same line, if the combined line meets the line length requirement. Avoid such combination for any other two query keywords.

Not recommended

 
CREATE QUERY active_members(INT activity_threshold) FOR GRAPH Social_Net
{
    SumAccum<INT> @activity_amount;
    start = {Person.*};
    result = SELECT v FROM start:v -(_>:e)- Post:tgt
      ACCUM v.@activity_amount +=1
        HAVING v.@activity_amount >= activity_threshold; (1)
    PRINT result;
}
1 ACCUM and HAVING are not lined up in this example.

This is not recommended.

In GSQL, SELECT statements begin with a vertex set variable. This means SELECT is not in the leftmost column. If you prefer, you can break the first clause (<vertex set variable> = SELECT <vertex alias>) into two lines, putting an indented SELECT on the second line:

CREATE QUERY activity_align (INT activity_threshold) FOR GRAPH Social_Net {
    SumAccum<INT> @activity_amount;
    start = {Person.*};
    result =
        SELECT v
        FROM start:v -(:e)- Post:tgt
        ACCUM v.@activity_amount +=1;
    PRINT result;
}

Comments

  • Use // for single line and inline comments.

  • Use /* at the start and */ at the end of multiline comments, with the interior comment lines indented.

  • Do not use #.

Recommended

 
CREATE QUERY active_male_members() FOR GRAPH Social_Net
{
    /* Compute the total post activity for each male person.
    Because the gender of the vertex does not change, evaluating whether the person vertex is male before (WHERE) the ACCUM clause or after (HAVING) the ACCUM clause does not change the result.
However, if the condition in the HAVING clause could change within the ACCUM clause, these statements would produce different results. */ (1)

    SumAccum<INT> @activity_amount;
    start = {Person.*};

    // The following statements produce equivalent results (2)
    result1 = SELECT v FROM start:v -(Posted>:e)- Post:tgt
        WHERE v.gender == "Male"
        ACCUM v.@activity_amount +=1;

    result2 = SELECT v FROM start:v -(Posted>:e)- Post:tgt
        ACCUM v.@activity_amount +=1
        HAVING v.gender == "Male";

    PRINT result1;
    PRINT result2;
}
1 Multi-line comments are put in /* */.
2 Single-line comments are put after //.

Not recommended

 
CREATE QUERY active_male_members() FOR GRAPH Social_Net
{

    // Compute the total post activity for each male person.
    // Because the gender of the vertex does not change, evaluating whether the person vertex is male before (WHERE) the ACCUM clause or after (HAVING) the ACCUM clause does not change the result.
    // However, if the condition in the HAVING clause could change within the ACCUM clause, these statements would produce different results. (1)

    SumAccum<INT> @activity_amount;
    start = {Person.*};

    # The following statements produce equivalent results (2)
    result1 = SELECT v FROM start:v -(Posted>:e)- Post:tgt
        WHERE v.gender == "Male"
        ACCUM v.@activity_amount +=1;

    result2 = SELECT v FROM start:v -(Posted>:e)- Post:tgt
        ACCUM v.@activity_amount +=1
        HAVING v.gender == "Male";

    PRINT result1;
    PRINT result2;
}
1 Multi-line comments are put in multiple double forward slashes //. This is not recommended.
2 Single-line comments are put after the hashtag symbol #. This is not recommended and will not be supported by the upcoming GQL standard.
1. If you want to use num to refer to a quantity, always put it at the beginning. For example, use num_students to refer to the number of students instead of students_num