Declaration and Assignment Statements
Previous sections focused on the lowest level building blocks of queries: data types (Section 3), operators, functions, and expressions (Section 5), and a special section devoted to accumulators (Section 4). We now begin to look at the types of statements available in GSQL queries. This section focuses on declaration and assignment statements. Later sections will provide a closer look at the all-important SELECT statement, control flow statements and data modification statements. Furthermore, some types of statements can be nested within SELECT, UPDATE, or control flow statements.
This section covers the following subset of the EBNF syntax:
Declaration Statements
There are six types of variable declarations in a GSQL query:
Accumulator
Global baseType variable
Local baseType variable
Vertex set
File object
Vertex or Edge aliases
The first five types each have their own declaration statement syntax and are covered in this section. Aliases are declared implicitly in a SELECT statement.
Accumulators
Accumulator declaration is discussed in Section 4: "Accumulators".
Global Variables
After accumulator declarations, base type variables can be declared as global variables. The scope of a global variable is from the point of declaration until the end of the query.
A global variable can be accessed (read) anywhere in the query; however, there are restrictions on wh ere it can be updated. See the subsection below on "Assignment Statements".
Multiple global variables of the same type can be declared and initialized at the same line, as in the example below:
Local Variables
A local variable can be declared only in an ACCUM, POST-ACCUM, or UPDATE SET clause, and its scope is limited to that clause. Local variables can only be of base types (e.g. INT, FLOAT, DOUBLE, BOOL, STRING, VERTEX). A local variable must be declared and initialized together at the same statement.
Within a local variable's scope, another local variable with the same name cannot be declared at the same level. However, a new local variable with the same name can be declared at a lower level (i.e., within a nested SELECT or UPDATE statement.) . The lower declaration takes precedence at the lower level.
In a POST-ACCUM clause, each local variable may only be used in source vertex statements or target vertex statements, not both.
Vertex Set Variable Declaration and Assignment
Vertex set variables play a special role within GSQL queries. They are used for both the input and output of SELECT statements. Therefore, before the first SELECT statement in a query, a vertex set variable must be declared and initialized. This initial vertex set is called the seed set .
The query below lists all ways of assigning a vertex set variable an initial set of vertices (that is, forming a seed set).
a vertex parameter, untyped (S1) or typed (S2)
a vertex set parameter, untyped (S3) or typed (S4)
a global SetAccum<VERTEX> accumulator, untyped (S5) or typed (S6)
all vertices of any type (S7, S9) or of one type (S8)
a list of vertex ids in an external file (S10)
copy of another vertex set (S11)
a combination of individual vertices, vertex set parameters, or global variables (S12)
union of vertex set variables (S13)
When declaring a vertex set variable, a set of vertex types can be optionally specified to the vertex set variable. If the vertex set variable set type is not specified explicitly, the system determines the type implicitly by the vertex set value. The type can be ANY, _ (equivalent to ANY), or any explicit vertex type(s). See the EBNF grammar rule vertexEdgeType.
Declaration syntax difference: vertex set variable vs. base type variable
In a vertex set variable declaration, the type specifier follows the variable name and should be surrounded by parentheses: vSetName (type) This is different than a base type variable declaration, where the type specifier comes before the base variable name: type varName
After a vertex set variable is declared, the vertex type of the vertex set variable is immutable. Every assignment (e.g. SELECT statement) to this vertex set variable must match the type. The following is an example in which we must declare the vertex set variable type.
In the above example, the query returns the set of vertices after a 5-step traversal from the input "person" vertex. If we declare the vertex set variable S without explicitly giving a type, because the type of vertex parameter m1 is "person", the GSQL engine will implicitly assign S to be "person"-type. However, if S is assigned to "person"-type, the SELECT statement inside the WHILE loop causes a type checking error, because the SELECT block will generate all connected vertices, including non-"person" vertices. Therefore, S must be declared as a ANY-type vertex set variable.
FILE Object Declaration
A FILE object is a sequential text storage object, associated with a text file on the local machine.
When referring to a FILE object, we always capitalize the word FILE, to distinguish it from ordinary files.
When a FILE object is declared, associated with a particular text file, any existing content in the text file will be erased . During the execution of the query, content written to or printed to the FILE will be appended to the FILE. When the query where the FILE was declared finishes running, the FILE contents are saved to the text file.
Note that the declaration statement is invoking the FILE object constructor. The syntax for the constructor includes parentheses surrounding the filepath parameter.
Currently, the filePath must be a absolute path.
Assignment and Accumulate Statements
Assignment statements are used to set or update the value of a variable, after it has been declared. This applies to baseType variables, vertex set variables, and accumulators. Accumulators also have the special += accumulate statement, which was discussed in the Accumulator section. Assignment statements can use expressions (expr) to define the new value of the variable.
Vertex and edge (non-accumulator) attributes can use the += operator in an ACCUM or POST-ACCUM clause to perform parallel accumulation.
Restrictions on Assignment Statements
In general, assignment statements can take place anywhere after the variable has been declared. However, t here are some restrictions. These restrictions apply to "inner level" statements which are within the body of a higher-level statement:
The ACCUM or POST-ACCUM clause of a SELECT statement
The SET clause of an UPDATE statement
The body of a FOREACH statement
Global accumulator assignment "=" is not permitted within the body of SELECT or UPDATE statements
Global variable assignment is permitted in ACCUM or POST-ACCUM clauses, but the change in value will not take place until exiting the clause. Therefore, if there are multiple assignment statements for the same variable, only the final one will take effect.
Vertex attribute assignment "=" is not permitted in an ACCUM clause. However, edge attribute assignment is permitted. This is because the ACCUM clause iterates over an edge set.
There are additional restrictions within FOREACH loops for the loop variable. See the Data Modification section.
LOADACCUM Statement
LOADACCUM() can initialize a global accumulator by loading data from a file. LOADACCUM() has 3+n parameters explained in the table below: (filePath, fieldColumn_1, ...., fieldColumn_n, separator, header), where n is the number of fields in the accumulator. One assignment statement can have multiple LOADACCUM() function calls. However, every LOADACCUM() referring to the same file in the same assignment statement must use the same separator and header parameter values.
Any accumulator using generic VERTEX as an element type cannot be initialized by LOADACCUM().
parameter name | type | description |
filePath | string | The absolute file path of the input file to be read. A relative path is not supported. |
accumField1,...., accumFieldN | $ num , or $ "column_name" if header is true. | The column position(s) or column name(s) of the data file which supply data values to each field of the accumulator. |
separator | single-character string | The separator of columns. |
header | bool | Whether this file has a header. |
Below is an example with an external file
Function Call Statements
Typically, a function call returns a value and so is part of an expression (see Section 5 - Operators, Functions and Expressions). In some cases, however, the function does not return a value (i.e., returns VOID) or the return value can be ignored, so the function call can be used as an entire statement. This is a Function Call Statement.
Last updated