Data Types

Search…
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:
EBNF for Data Types
1
lowercase          := [a-z]
2
uppercase          := [A-Z]
3
letter             := lowercase | uppercase
4
digit              := [0-9]
5
integer            := ["-"]digit+
6
real               := ["-"]("."digit+) | ["-"](digit+"."digit*)
7
numeric            := integer | real
8
stringLiteral      := '"' [~["] | '\\' ('"' | '\\')]* '"'
9
​
10
name := (letter | "_") [letter | digit | "_"]*   // Can be a single "_" or start with "_"
11
graphName := name
12
queryName := name
13
paramName := name
14
vertexType := name
15
edgeType := name
16
accumName := name
17
vertexSetName := name
18
attrName := name
19
varName := name
20
tupleType := name
21
fieldName :=name
22
funcName := name
23
​
24
type := baseType | tupleType | accumType | STRING COMPRESS
25
​
26
baseType := INT
27
          | UINT
28
          | FLOAT
29
          | DOUBLE
30
          | STRING
31
          | BOOL
32
          | VERTEX ["<" vertexType ">"]
33
          | EDGE
34
          | JSONOBJECT
35
          | JSONARRAY
36
          | DATETIME
37
​
38
filePath := paramName | stringLiteral
39
​
40
typedef := TYPEDEF TUPLE "<" tupleFields ">" tupleType
41
​
42
tupleFields := (baseType fieldName) | (fieldName baseType)
43
           ["," (baseType fieldName) | (fieldName baseType)]*
44
​
45
parameterType := baseType
46
               | [ SET | BAG ] "<" baseType ">"
47
               | FILE
Copied!
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 (identifier)
1
name := (letter | "_") [letter | digit | "_"]* 
Copied!
Overview of Types
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 types are FILE and STRING COMPRESS. 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
baseType
INT, UINT, FLOAT, DOUBLE, STRING, BOOL, DATETIME, VERTEX, EDGE,
JSONOBJECT, or JSONARRAY
Global variable
Query return value
tupleType
Sequence of base types
User-defined tuple
accumType
Family of specialized data objects which support accumulation operations
Accumulate and aggregate data, when traversing a set of vertices or edges
(Details are in the Query Lang Spec - Accumulators chapter.)
FILE
FILE object
Global sequential data object, linked to a text file
parameterType
baseType (except EDGE or JSONOBJECT), a set or bag of baseType, or FILE object
Query parameter
STRING COMPRESS
(⚠
suitable only in limited circumstances)
STRING COMPRESS
more compact storage of STRING, if there is a limited number of different values and the value is rarely accessed. Otherwise, it may use more memory.
elementType
baseType, STRING COMPRESS, or identifier
Element for most types of container accumulators: SetAccum, BagAccum, GroupByAccum, key of a MapAccum element
type
baseType, STRING COMPRESS, identifier, or accumType
Element of a ListAccum, value of a MapAccum element
Local variable
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.
EBNF
1
baseType := INT
2
          | UINT
3
          | FLOAT
4
          | DOUBLE
5
          | STRING
6
          | BOOL
7
          | VERTEX ["<" vertexType ">"]
8
          | EDGE
9
          | JSONOBJECT
10
          | JSONARRAY
11
          | DATETIME
Copied!
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 (see Section "Operators, Functions, and Expressions" for more details).
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
INT
0
A signed integer: -3
UINT
0
An unsigned integer: 5
FLOAT
0
A decimal: 3.14159
DOUBLE
0
A decimal with greater precision than FLOAT
BOOL
false
TRUE or FALSE
STRING
""
Characters enclosed by double quotes: "Hello"
DATETIME
1970-01-01 00:00:00
No literal. Can be converted from a correctly formatted string with to_datetime().
VERTEX
"Unknown"
No literal.
EDGE
No edge: {}
No literal.
JSONOBJECT
An empty object: {}
No literal. Can be converted from a correctly formatted string with parse_json_object().
JSONARRAY
An empty array: []
No literal. Can be converted from a correctly formatted string with parse_json_array().
FLOAT and DOUBLE input values must be in fixed point d.dddd** **format, where d is a digit. Output values will be printed in either fixed point for exponential notation, whichever is more compact.
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.
1
VERTEX anyVertex; 
2
VERTEX<person> owner;
Copied!
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".
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.
1
EDGE anyEdge;
2
EDGE<friendship> friendEdge;
Copied!
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
INT
INT
UINT
UINT
FLOAT
FLOAT
DOUBLE
DOUBLE
BOOL
BOOL
STRING
STRING
STRING COMPRESS
STRING
SET< type >
SetAccum< type >
LIST< type >
ListAccum< type >
MAP <key_type, value_type>
MapAccum <key_type, value_type>
DATETIME
DATETIME
SET and LIST literals
In the GSQL query language, one cannot declare a variable of SET (vertex sets are an exception), LIST , or MAP types. However, one can still use SET and LIST literals to update the value of a vertex attribute of type SET or LIST, insert a vertex or edge with attributes of type SET or LIST , and initialize an accumulator.
1
// Elements within a set or a list need to be of the same type
2
set_literal := "(" expr ("," expr)* ")" 
3
list_literal := "[" expr ("," expr)* "]" 
4
expr := INT | UINT | FLOAT | DOUBLE | BOOL | STRING | UDT | DATETIME
Copied!
Currently, GSQL query language syntax does not support MAP literals.
JSONOBJECT and JSONARRAY
These two base types allow users to pass a complex data object or to write output in a customized format. These types follow the industry-standard definition of JSON. 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. A JSONARRAY is represented as a string, starting and ending with square brackets ([])which enclose an ordered list of values. Since a _value **_can be an object or an array, JSON supports hierarchical, nested data structures.
More details are introduced in the Section JSONOBJECT and JSONARRAY Functions.
A JSONOBJECT or JSONARRAY value is immutable. No operator is allowed to modify its value.
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.
ENBF for tuples
1
typedef := TYPEDEF TUPLE "<" tupleFields ">" tupleType
2
​
3
tupleFields := (baseType fieldName) | (fieldName baseType)
4
           ["," (baseType fieldName) | (fieldName baseType)]*
Copied!
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 type SECRET_INFO, which a user-defined tuple
portfolio of type MAP<STRING, DOUBLE>
investmentNet schema
1
TYPEDEF TUPLE <age UINT (4), mothersName STRING(20) > SECRET_INFO
2
CREATE VERTEX person(PRIMARY_ID personId STRING, portfolio MAP<STRING, DOUBLE>, secretInfo SECRET_INFO)
3
CREATE VERTEX stockOrder(PRIMARY_ID orderId STRING, ticker STRING, orderSize UINT, price FLOAT)
4
CREATE UNDIRECTED EDGE makeOrder(FROM person, TO stockOrder, orderTime DATETIME)
5
CREATE GRAPH investmentNet (*)
Copied!
The query below reads both the SECRET_INFO tuple and the portfolio MAP. The tuple type does not need to redefine SECRET_INFO. 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.
tupleEx query
1
CREATE QUERY tupleEx(VERTEX<person> p) FOR GRAPH investmentNet{
2
  #TYPEDEF TUPLE <UINT age, STRING mothersName> SECRET_INFO;       # already defined in schema
3
  TYPEDEF TUPLE <STRING ticker, FLOAT price, DATETIME orderTime> ORDER_RECORD; # new for query
4
​
5
  SetAccum<SECRET_INFO> @@info;
6
  ListAccum<ORDER_RECORD> @@orderRecords;
7
  MapAccum<STRING, DOUBLE> @@portf;       # corresponds to MAP<STRING, DOUBLE> attribute
8
​
9
  INIT = {p};
10
​
11
  # Get person p's secret_info and portfolio
12
  X = SELECT v FROM INIT:v
13
      ACCUM @@portf += v.portfolio, @@info += v.secretInfo;
14
​
15
  # Search person p's orders to record ticker, price, and order time.
16
  # Note that the tuple gathers info from both edges and vertices.
17
  orders = SELECT t
18
      FROM INIT:s -(makeOrder:e)->stockOrder:t
19
      ACCUM @@orderRecords += ORDER_RECORD(t.ticker, t.price, e.orderTime);
20
​
21
  PRINT @@portf, @@info;
22
  PRINT @@orderRecords;
23
}
Copied!
tupleEx.json
1
GSQL > RUN QUERY tupleEx("person1")
2
{
3
  "error": false,
4
  "message": "",
5
  "version": {
6
    "edition": "developer",
7
    "schema": 0,
8
    "api": "v2"
9
  },
10
  "results": [
11
    {
12
      "@@info": [{
13
        "mothersName": "JAMES",
14
        "age": 25
15
      }],
16
      "@@portf": {
17
        "AAPL": 3142.24,
18
        "MS": 5000,
19
        "G": 6112.23
20
      }
21
    },
22
    {"@@orderRecords": [
23
      {
24
        "ticker": "AAPL",
25
        "orderTime": "2017-03-03 18:42:28",
26
        "price": 34.42
27
      },
28
      {
29
        "ticker": "B",
30
        "orderTime": "2017-03-03 18:42:30",
31
        "price": 202.32001
32
      },
33
      {
34
        "ticker": "A",
35
        "orderTime": "2017-03-03 18:42:29",
36
        "price": 50.55
37
      }
38
    ]}
39
  ]
40
}
Copied!
STRING COMPRESS
STRING COMPRESS is an integer type encoded by the system to represent string values. STRING COMPRESS uses less memory than STRING. The STRING COMPRESS type is designed to act like STRING: data are loaded and printed just as string data, and most functions and operators which take STRING input can also take STRING COMPRESS input. The difference is in how the data are stored internally. A STRING COMPRESS value can be obtained from a STRING_SET COMPRESS or STRING_LIST COMPRESS attribute or from converting a STRING value.
Using STRING COMPRESS instead of STRING is a trade-off: smaller storage vs. slower access times. The storage space will only be smaller if (1) the original strings are long, and (2) there are only a small number of different strings. Performance will always be slower; the slowdown is greater if the STRING COMPRESS attributes are accessed more often.

We recommend performing comparison tests for both performance and memory usage before settling on STRING COMPRESS.
STRING COMPRESS type is beneficial for sets of string values when the same values are used multiple times. In practice, STRING COMPRESS are most useful for container accumulators like ListAccum<STRING COMPRESS> or SetAccum<STRING COMPRESS>.
An accumulator containing STRING COMPRESS stores the dictionary when it is assigned an attribute value or from another accumulator containing STRING COMPRESS. An accumulator containing STRING COMPRESS can store multiple dictionaries. A STRING value can be converted to a STRING COMPRESS value only if the value is in the dictionaries. If the STRING value is not in the dictionaries, the original string value is saved. A STRING COMPRESS value can be automatically converted to a STRING value.
When a STRING COMPRESS value is output (e.g. by a PRINT statement), it is shown as a STRING.
STRING COMPRESS is not a base type.
STRING COMPRESS example
1
CREATE QUERY stringCompressEx(VERTEX<person> m1) FOR GRAPH workNet {
2
  ListAccum<STRING COMPRESS> @@strCompressList, @@strCompressList2;
3
  SetAccum<STRING COMPRESS> @@strCompressSet, @@strCompressSet2;
4
  ListAccum<STRING> @@strList, @@strList2;
5
  SetAccum<STRING> @@strSet, @@strSet2;
6
​
7
  S = {m1};
8
​
9
  S = SELECT s 
10
      FROM S:s
11
      ACCUM @@strSet += s.interestSet,    
12
            @@strList += s.interestList,   
13
            @@strCompressSet += s.interestSet,   # use the dictionary from person.interestSet
14
            @@strCompressList += s.interestList; # use the dictionary from person.interestList
15
​
16
  @@strCompressList2 += @@strCompressList;  # @@strCompressList2 gets the dictionary from @@strCompressList, which is from person.interestList
17
  @@strCompressList2 += "xyz";   # "xyz" is not in the dictionary, so store the actual string value
18
​
19
  @@strCompressSet2 += @@strCompressSet; 
20
  @@strCompressSet2 += @@strSet; 
21
​
22
  @@strList2 += @@strCompressList;  # string compress integer values are decoded to strings
23
  @@strSet2 += @@strCompressSet;  
24
​
25
  PRINT @@strSet, @@strList, @@strCompressSet, @@strCompressList;
26
  PRINT @@strSet2, @@strList2, @@strCompressSet2, @@strCompressList2;
27
}
Copied!
stringCompressEx.json Results
1
GSQL > RUN QUERY stringCompressEx("person12")
2
{
3
  "error": false,
4
  "message": "",
5
  "version": {
6
    "edition": "developer",
7
    "schema": 0,
8
    "api": "v2"
9
  },
10
  "results": [
11
    {
12
      "@@strCompressList": [
13
        "music",
14
        "engineering",
15
        "teaching",
16
        "teaching",
17
        "teaching"
18
      ],
19
      "@@strSet": [ "teaching", "engineering", "music" ],
20
      "@@strCompressSet": [ "music", "engineering", "teaching" ],
21
      "@@strList": [
22
        "music",
23
        "engineering",
24
        "teaching",
25
        "teaching",
26
        "teaching"
27
      ]
28
    },
29
    {
30
      "@@strSet2": [ "music", "engineering", "teaching" ],
31
      "@@strCompressList2": [
32
        "music",
33
        "engineering",
34
        "teaching",
35
        "teaching",
36
        "teaching",
37
        "xyz"
38
      ],
39
      "@@strList2": [
40
        "music",
41
        "engineering",
42
        "teaching",
43
        "teaching",
44
        "teaching"
45
      ],
46
      "@@strCompressSet2": [ "teaching", "engineering", "music" ]
47
    }
48
  ]
49
}
Copied!
FILE Object
A FILE object is a sequential data 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 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.
A FILE object can be passed as a parameter to another query. When a query receives a FILE object as a parameter, it can append data to that FILE, as can every other query which receives this FILE object as a parameter.
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 FILE object is a special case. It is passed by reference, meaning that the receiving query gets a link to the original FILE object. The receiving query can write to the FILE object.
EBNF
1
parameterType := INT
2
               | UINT
3
               | FLOAT
4
               | DOUBLE
5
               | STRING
6
               | BOOL
7
               | VERTEX ["<" vertexType ">"]
8
               | DATETIME
9
               | [ SET | BAG ] "<" baseType ">"
10
               | FILE
Copied!
Examples of collection type parameters
1
(SET<VERTEX<person> p1, BAG<INT> ids, FILE f1)
Copied!