Documentation Notations
The GSQL Language Reference uses conventional notation for software documentation. In particular, note the following:
Long lines
For more convenient display, long statements in this guide may sometimes be displayed on multiple lines. This is for display purposes only; the actual code must be entered as a single line (unless the multi-line mode is used). When necessary, the examples may show a shell prompt before the start of a statement, to clearly mark where each statement begins.
Example: A SELECT query is grammatically a single statement, so GSQL requires that it be entered as a single line.
SELECT *|attribute_name FROM vertex_type_name [WHERE conditions] [ORDER BY attribute1,attribute2,...] [LIMIT k]However, the statement is easier to read and to understand when displayed one clause per line:
SELECT *|attribute_name
FROM vertex_type_name
[WHERE conditions]
[ORDER BY attribute1,attribute2,...]
[LIMIT k]Repeated zero or more times
In template code, it is sometimes desirable to show that a term is repeated an arbitrary number of times. For example, a vertex definition contains zero or more user-defined attributes. A loading job contains one or more LOAD statements. In formal template code, if an asterisk (Kleene star) immediately follows option brackets, then the bracketed term can be repeated zero or more times.
For example:
TO VERTEX|EDGE object_name VALUES ( id_expr [, attr_expr ]*)The previous template code means that the VALUES list contains at least one attribute expression.
It may be followed by any number of additional attribute expressions.
Each additional attribute expression must be preceded by a comma.
Optional content
Square brackets are used to enclose a portion that is optional.
Options can be nested.
Square brackets themselves are rarely used as part of the GSQL language itself.
Example: In the RUN JOB statement, the -n flag is optional.
If used, -n is to be followed by a value.
RUN JOB [-n count ] job_nameSometimes, options are nested, which means that an inner option can only be used if the outer option is used:
RUN JOB [-n [ first_line_num , ] last_line_num ] job_namemeans that first_line_num may be specified if and only if last_line_num is specified first. These options provide three possible forms for this statement:
RUN JOB job_name
RUN JOB -n last_line_num job_name
RUN JOB -n first_line_num , last_line_num job_nameQuotation Marks
When quotation marks are shown, they are to be typed as shown (unless stated otherwise). A placeholder for a string value does not have quotation marks in the template code, but if a template is converted to actual code, quotation marks should be used around string values.
Choices
The vertical bar | is used to separate the choices when the syntax requires that the user choose one out of a set of values.
Example: Either the keyword VERTEX or EDGE is to be used.
Also, note the inclusion of quotation marks.
Template:
LOAD " file_path " TO VERTEX|EDGE object_type_name VALUES (id_expr, attr_expr1 , attr_expr2 ,...)Possible actual values:
LOAD "data/users.csv" TO VERTEX user VALUES ($0, $1, $2)The user-defined identifiers are edge_type_name , vertex_type_name1, vertex_type_name2, attribute_name and default_value . As explained in the Create Vertex section, type is one of the attribute data types.
Placeholder identifiers and values
In template code, any token that is not a keyword, a literal value, or punctuation is a placeholder identifier or a placeholder value. Example:
CREATE UNDIRECTED EDGE edge_type_name (FROM vertex_type_name1 , TO vertex_type_name2 ,
attribute_name type [DEFAULT default_value ],...)|
===
In a very few cases, some option keywords are case-sensitive. For example, in the command to delete all data from the graph store, clear graph store -HARD |
the option -HARD must be in all capital letters. ===