Data Types
This section describes the data types that are native to and are supported by the GSQL Query Language. Most of the data objects used in queries come from one of three sources:
-
The query’s input parameters
-
The vertices, edges, and their attributes which are encountered when traversing the graph
-
The variables defined within the query to assist in the computational work of the query
This section covers the following subset of the EBNF language definitions:
lowercase := [a-z]
uppercase := [A-Z]
letter := lowercase | uppercase
digit := [0-9]
integer := ["-"]digit+
real := ["-"]("."digit+) | ["-"](digit+"."digit*)
numeric := integer | real
stringLiteral := '"' [~["] | '\\' ('"' | '\\')]* '"'
name := (letter | "_") [letter | digit | "_"]* // Can be a single "_" or start with "_"
graphName := name
queryName := name
paramName := name
vertexType := name
edgeType := name
accumName := name
vertexSetName := name
attrName := name
varName := name
tupleType := name
fieldName :=name
funcName := name
type := baseType | tupleType | accumType
baseType := INT
| UINT
| FLOAT
| DOUBLE
| STRING
| BOOL
| VERTEX ["<" vertexType ">"]
| EDGE
| JSONOBJECT
| JSONARRAY
| DATETIME
filePath := paramName | stringLiteral
typedef := TYPEDEF TUPLE "<" tupleFields ">" tupleType
tupleFields := (baseType fieldName) | (fieldName baseType)
["," (baseType fieldName) | (fieldName baseType)]*
createVirtualEdge := CREATE DIRECTED|UNDIRECTED VIRTUAL EDGE Virtual_Edge_Type_Name "("
FROM Vertex_Type_Name ("|" Vertex_Type_Name)* ","
TO Vertex_Type_Name ("|" Vertex_Type_Name)*
["," attribute_name type [DEFAULT default_value]]* ")"
parameterType := baseType
| [ SET | BAG ] "<" baseType ">"
| FILE
The legacy data type Existing schemas that are using |
Identifiers
An identifier is the name for an instance of a language element. In the GSQL query language, identifiers are used to name elements such as a query, a variable, or a user-defined function.
In the EBNF syntax, an identifier is referred as name
.
It can be a sequence of letters, digits, or underscores ("_"
).
Other punctuation characters are not supported. The initial character can only be a letter or an underscore.
name := (letter | "_") [letter | digit | "_"]*
Overview
Different types of data can be used in different contexts.
The EBNF syntax defines several classes of data types.
The most basic is called base type (baseType
).
The other independent type is FILE
.
The remaining types are either compound data types built from the independent data types, or supersets of other types. The table below gives an overview of their definitions and their uses.
EBNF term | Description | Use Case |
---|---|---|
|
|
|
|
|
|
|
Sequence of base types |
|
|
Family of specialized data objects which support accumulation operations |
|
|
|
|
|
|
|
|
|
|
|
|
|
Base types
The query language supports the following base types, which can be declared and assigned anywhere within their scope. Any of these base types may be used when defining a global variable, a local variable, a query return value, a parameter, part of a tuple, or an element of a container accumulator. Accumulators are described in detail in a later section.
baseType := INT
| UINT
| FLOAT
| DOUBLE
| STRING
| BOOL
| VERTEX ["<" vertexType ">"]
| EDGE
| JSONOBJECT
| JSONARRAY
| DATETIME
The default value of each base type is shown in the table below. The default value is the initial value of a base type variable (see Section "Variable Types" for more details), or the default return value for some functions.
The first seven types (INT
, UINT
, FLOAT
, DOUBLE
, BOOL
, STRING
, and DATETIME
) are the same ones mentioned in the "Attribute Data Types" section of GSQL Language Reference, Part 1.
Type | Default value | Literal |
---|---|---|
|
|
A signed integer: |
|
|
An unsigned integer: |
|
|
A decimal precise up to about 7 digits: |
|
|
A decimal precise up to about 16 digits. |
|
|
|
|
|
Characters enclosed by double quotes: |
|
|
No literal. Can be converted from a correctly formatted string with |
|
|
No literal. |
|
No edge: |
No literal. |
|
An empty object: |
No literal. Can be converted from a correctly formatted string with |
|
An empty array: |
No literal. Can be converted from a correctly formatted string with |
The FLOAT
and DOUBLE
data types have the same precision limits as in C++.
See Common Errors and Problems for more details.
The GSQL Loader can read FLOAT and DOUBLE values with exponential notation (e.g., 1.25 E-7). |
Vertex
VERTEX
is considered a base type in the GSQL query language.
Both query parameters and variables in a query body can be of type VERTEX
.
Vertex types
A graph schema defines specific vertex types.
Each vertex type has its own set of attributes.
The parameter or variable type can be restricted by giving the vertex type in angle brackets <>
after the keyword VERTEX
.
A vertex variable declared without a specifier is called a generic vertex variable.
VERTEX anyVertex; VERTEX<person> owner;
All vertices have a built-in attribute type
. The built-in attribute is of type string. You can access it with the dot (.
) operator.
For example, if you declare a vertex variable VERTEX<person> personVertex
, then personVertex.type
returns "person"
.
When you run a query with a vertex type, the syntax is different for typed vertex parameters and generic vertex parameters. See the RUN QUERY parameter list for details.
Edge
EDGE
is considered a base type in the GSQL query language.
Both query parameters and variables in a query body can be of type EDGE
.
Edge types
A graph schema defines specific edge types.
Each edge type has its own set of attributes.
The parameter or variable type can be restricted by giving the edge type in angle brackets <>
after the keyword EDGE
.
An edge variable declared without a specifier is called a generic edge variable.
EDGE anyEdge; EDGE<friendship> friendEdge;
All edges have a built-in attribute type
. The built-in attribute is of type string. You can access it with the dot (.
) operator.
For example, if you define an edge variable EDGE<friendship> friendEdge
, then friendEdge.type
returns "Friendship"
.
Vertex and Edge Attribute Types
The following table maps vertex or edge attribute types in the Data Definition Language (DDL) to GSQL query language types. If an attribute of a vertex or edge is referenced in a GSQL query, they will be automatically converted to their corresponding data type in the GSQL query language.
DDL | GSQL Query |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
JSONOBJECT
A JSONOBJECT
instance’s external representation (as input and output) is a string, starting and ending with curly braces ({}
) which enclose an unordered list of key-value pairs.
JSONOBJECT
is immutable.
No operator is allowed to alter its value.
Assign a JSONOBJECT
value to a base type variable
There is no JSONOBJECT
literal in the GSQL query language.
Therefore, to assign value to a JSONOBJECT
base type variable in GSQL, you need to use the parse_json_object()
function to convert a string representation of s JSON object to a JSONOBJECT
value.
For example, the following line declares a variable han
with a JSONOBJECT
value:
JSONOBJECT han = parse_json_object("{\"f_name\": \"Han\", \"l_name\": \"Solo\"}");
JSONARRAY
A JSONARRAY
is represented as a string, starting and ending with square brackets ([]
)which enclose an ordered list of values.
JSONARRAY
is immutable.
No operator is allowed to alter its value.
Assign a JSONARRAY
value to a base type variable
There is no JSONARRAY
literal in the GSQL query language.
Therefore, to assign value to a JSONARRAY
base type variable in GSQL, you need to use the parse_json_array()
function to convert a string representation of s JSON object to a JSONARRAY
value.
For example, the following line declares a variable fruits
with a JSONARRAY
value:
JSONARRAY fruits = parse_json_array("[\"apple\", \"banana\", \"citrus\"]");
Container types
Container types include the following data types:
-
SET
-
BAG
-
LIST
-
MAP
Type | Literal | Example | Default value |
---|---|---|---|
|
Elements enclosed by parentheses, separated by commas. |
|
Empty set. |
|
Elements enclosed by parentheses, separated by commas. |
|
Empty bag. |
|
Elements enclosed by square brackets, separated by commas. |
|
Empty list. |
|
No literal. |
N/A |
Empty map. |
To see how container type variables are declared in a GSQL query, see Local container variables.
Tuple
A tuple is a user-defined data structure consisting of a fixed sequence of base type variables.
Tuple types can be created and named using a TYPEDEF
statement.
Tuples must be defined first, before any other statements in a query.
typedef := TYPEDEF TUPLE "<" tupleFields ">" tupleType
tupleFields := (baseType fieldName) | (fieldName baseType)
["," (baseType fieldName) | (fieldName baseType)]*
A tuple can also be defined in a graph schema and then can be used as a vertex or edge attribute type. A tuple type that has been defined in the graph schema does not need to be re-defined in a query.
The vertex type person
contains two complex attributes:
-
secretInfo
of typeSECRET_INFO
, which a user-defined tuple -
portfolio
of typeMAP<STRING, DOUBLE>
Investment_Net
SchemaTYPEDEF TUPLE <age UINT (4), mothers_name STRING(20) > SECRET_INFO
CREATE VERTEX Person(PRIMARY_ID person_id STRING, portfolio MAP<STRING, DOUBLE>, secret_info SECRET_INFO)
CREATE VERTEX Stock_Order(PRIMARY_ID order_id STRING, ticker STRING, order_size UINT, price FLOAT)
CREATE UNDIRECTED EDGE make_order(FROM Person, TO Stock_Order, order_time DATETIME)
CREATE GRAPH Investment_Net (*)
The query below reads both the SECRET_INFO
tuple and the portfolio MAP.
The tuple type does not need to be redefined in the query.
To read and save the map, we define a MapAccum
with the same types for key and value as the portfolio
attribute.
In addition, the query creates a new tuple type, ORDER_RECORD
.
CREATE QUERY tuple_ex(VERTEX<Person> p) FOR GRAPH Investment_Net{
TYPEDEF TUPLE <STRING ticker, FLOAT price, DATETIME order_time> Order_Record; (1)
SetAccum<Secret_Info> @@info; (2)
ListAccum<Order_Record> @@order_records;
MapAccum<STRING, DOUBLE> @@portf;
INIT = {p};
// Get person p's secret_info and portfolio
X = SELECT v FROM INIT:v
ACCUM @@portf += v.portfolio, @@info += v.secret_info;
// Search person p's orders to record ticker, price, and order time.
// Note that the tuple gathers info from both edges and vertices.
orders = SELECT t
FROM INIT:s -(Make_Order:e)-Stock_Order:t
ACCUM @@order_records += Order_Record(t.ticker, t.price, e.order_time);
PRINT @@portf, @@info;
PRINT @@order_records;
}
1 | This statement defines a new tuple Order_Record at the top of the query. |
2 | Secret_Info has already been defined in Investment_Net Schema. |
GSQL > RUN QUERY tuple_ex("person1")
{
"error": false,
"message": "",
"version": {
"schema": 0,
"edition": "enterprise",
"api": "v2"
},
"results": [
{
"@@info": [{
"mothers_name": "JAMES",
"age": 25
}],
"@@portf": {
"AAPL": 3142.24,
"MS": 5000,
"G": 6112.23
}
},
{"@@order_records": [
{
"ticker": "B",
"price": 202.32001,
"order_time": "2017-03-03 18:42:30"
},
{
"ticker": "AAPL",
"price": 34.42,
"order_time": "2017-03-03 18:42:28"
},
{
"ticker": "A",
"price": 50.55,
"order_time": "2017-03-03 18:42:29"
}
]}
]
}
Virtual Edge
In the graph schema, while regular edges facilitate CRUD operations, traversing multiple steps between vertices can be cumbersome.
To streamline this process, we are introducing the Virtual Edge feature, which are in memory edges that can be created during query runtime, simplifying traversal and enabling predicate application across non-adjacent vertices.
createVirtualEdge := CREATE DIRECTED|UNDIRECTED VIRTUAL EDGE Virtual_Edge_Type_Name "("
FROM Vertex_Type_Name ("|" Vertex_Type_Name)* ","
TO Vertex_Type_Name ("|" Vertex_Type_Name)*
["," attribute_name type [DEFAULT default_value]]* ")"
CREATE OR REPLACE DISTRIBUTED QUERY exampleQuery(){
CREATE DIRECTED VIRTUAL EDGE virtualE1(from v1, to v2, attr1 int);
CREATE DIRECTED VIRTUAL EDGE virtualE2(from v1|v3|v5, to v2|v4|v6, attr1 int, attr2 float);
...
}
Definition scope
Virtual edges can only be defined in the global scope of a query, meaning they must be declared at the top level of the query body. They cannot be nested within local statement such as IF, ELSE, FOREACH, select-block etc. The definition of a virtual edge is visible and valid throughout the entire query.
Access, Manipulation and Traversal
In general, virtual edge is very similar to regular edge, meaning we can update, upsert, access, delete virtual edge just like regular edge.
Unresolved include directive in modules/querying/pages/data-types.adoc - include::appendix:example$virtual_edge/sample_query.gsql[]
This query creates a virtual edge type VirtualE1, insert edge, access, and delete just like regular edge
GSQL > RUN QUERY exampleQuery()
Unresolved include directive in modules/querying/pages/data-types.adoc - include::appendix:example$virtual_edge/sample_query.json[]
Limitation
-
It is only supported to create virtual edge type in the global scope of query, creating virtual edge type inside statements are not allowed, for example below is an incorrect usage
CREATE OR REPLACE DISTRIBUTED QUERY exampleQuery(Bool condition){
IF Condition THEN
// we are creating virtual edge inside if statement, which is not allowed
CREATE DIRECTED VIRTUAL EDGE VirtualE1(FROM Person, TO Post|Comment, creationDate DATETIME);
...
END;
}
-
Only GPR v2 syntax support virtual edge, while UDF does not.
-
Virtual Edge does not support multi edge, i.e. no DISCRIMINATOR attribute can be added in virtual edge
-
Virtual Edge types cannot be used together with other virtual edge or regular edges in edge traversal, for example below is an incorrect usage
R = select s from Person:s -((VirtualE1>|VirtualE2>):e)- :t
accum
case e.type
when "VirtualE1" then @@results1 += Results01(e._a, e._b, e._c, e._d)
when "VirtualE2" then @@results2 += Results02(e._a, e._b)
end
;
-
Does not support virtual edge with getAttr(), setAttr() functions
-
Cannot aggregate virtual edge into edge containers, for example below is an incorrect usage
ListAccum<edge> @@res;
R = SELECT p1 FROM person:p1 -(FOF:e)- person:p2
ACCUM
@@res += e;
-
Does not support user defined tuple as attribute type
-
Does not support update and access attributes of same Virtual Edge type in the same ACCUM clause.
-
Correct example
-
// we are reading the attribute of virtual edge in ACCUM clause, and // insert(update) virtual edge in POST-ACCUM caluse, which is allowed W = select s from Src:s - (VE:e) - Tgt:t ACCUM @@cnt +=e.attr1; POST-ACCUM INSERT INTO VE values(s, t);
-
Incorrect example
// we are reading the attribute of virtual edge and also updating it in // the same ACCUM clause, which is not allowed W = select s from Src:s - (VE:e) - Tgt:t ACCUM @@cnt +=e.attr1, e.attr1 += 1;
FILE
Object
A FILE
object is a sequential data storage object, associated with a text file on the local machine or with an S3 bucket.
When referring to a |
Local disk file
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 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.
S3 object
Define s3 file object
The path should start with s3://
, followed by the bucket name and the S3 path, e.g., s3://bucket-name/queryoutput/output.csv
. During the execution of the query, content will be uploaded to the S3 bucket. Note that the S3 object cannot be modified or appended, if an S3 object with the same path already exists, it will be overwritten.
Set S3 connection credentials
To use an S3 path, ensure that the necessary permissions and configurations are properly set up to allow read/write access to the specified S3 bucket. Configure the S3 connection credentials using gadmin config
:
gadmin config set GPE.QueryOutputS3AWSAccessKeyID YOUR_AWS_ACCESS_KEY_ID
gadmin config set GPE.QueryOutputS3AWSSecretAccessKey YOUR_AWS_SECRET_ACCESS_KEY
gadmin config apply -y
gadmin restart gpe -y
Output
Since S3 is a shared storage system, multiple nodes in a cluster can upload to the same S3 bucket. To handle potential conflicts and ensure unique output files, the S3 path can include a suffix based on the instance name, such as _GPE_{PartitionId}_{ReplicaId}
. For distributed queries, additional suffixes will be used to differentiate between the manager and worker roles on the same GPE. Specifically, suffixes like _coordinator
and _worker
will be added, where _coordinator
refers to the worker manager and _worker
refers to the worker node.
Error code
For S3 bucket connection errors, refer to error code GSQL-5301
.
A |
Query parameter types
Input parameters to a query can be base type (except EDGE
, JSONARRAY
, or JSONOBJECT
).
A parameter can also be a SET
or BAG
which uses base type (except EDGE
, JSONARRAY
, or JSONOBJECT
) as the element type. A FILE
object can also be a parameter.
Within the query, SET
and BAG
are converted to SetAccum
and BagAccum
, respectively.
A query parameter is immutable. It cannot be assigned a new value within the query. The |
parameterType := INT
| UINT
| FLOAT
| DOUBLE
| STRING
| BOOL
| VERTEX ["<" vertexType ">"]
| DATETIME
| [ SET | BAG ] "<" baseType ">"
| FILE
(SET<VERTEX<person> p1, BAG<INT> ids, FILE f1)