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

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 | STRING COMPRESS

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)]*

parameterType := baseType
               | [ SET | BAG ] "<" baseType ">"
               | FILE

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)

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 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

EBNF term	Description	Use Case
`baseType`	`INT`, `UINT`, `FLOAT`, `DOUBLE`, `STRING`, `BOOL`, `DATETIME,` `VERTEX`, `EDGE`, + `JSONOBJECT`, or `JSONARRAY`	Base type variable Query return value
`containerType`	`SET`, `BAG`, `LIST`, `MAP`	Local container variable
`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` (⚠Deprecated data type. Please use `STRING` instead)	`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

baseType

INT, UINT, FLOAT, DOUBLE, STRING, BOOL, DATETIME, VERTEX, EDGE,
+ JSONOBJECT, or JSONARRAY

Base type variable
Query return value

containerType

SET, BAG, LIST, MAP

Local container variable

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

(⚠Deprecated data type. Please use STRING instead)

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

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

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()`.

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.

Generic and typed vertex variables

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".

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.

Generic and typed edge variables

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

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`

INT

UINT

FLOAT

DOUBLE

BOOL

STRING

STRING COMPRESS

STRING

SET< type >

SetAccum< type >

LIST< type >

ListAccum< type >

MAP <key_type, value_type>

MapAccum <key_type, value_type>

DATETIME

`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

Table 1. Container types
Type	Literal	Example	Default value
`SET`	Elements enclosed by parentheses, separated by commas.	`(1, 2, 3)`	Empty set.
`BAG`	Elements enclosed by parentheses, separated by commas.	`(1, 1, 2)`	Empty bag.
`LIST`	Elements enclosed by square brackets, separated by commas.	`[1, 2, 3]`	Empty list.
`MAP`	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.

EBNF for tuples

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 type SECRET_INFO, which a user-defined tuple
portfolio of type MAP<STRING, DOUBLE>

investmentNet Schema

TYPEDEF TUPLE <age UINT (4), mothersName STRING(20) > SECRET_INFO

CREATE VERTEX person(PRIMARY_ID personId STRING, portfolio MAP<STRING, DOUBLE>, secretInfo SECRET_INFO)

CREATE VERTEX stockOrder(PRIMARY_ID orderId STRING, ticker STRING, orderSize UINT, price FLOAT)

CREATE UNDIRECTED EDGE makeOrder(FROM person, TO stockOrder, orderTime DATETIME)

CREATE GRAPH investmentNet (*)

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.

Query
Result

CREATE QUERY tupleEx(VERTEX<person> p) FOR GRAPH investmentNet{

  TYPEDEF TUPLE <STRING ticker, FLOAT price, DATETIME orderTime> ORDER_RECORD;(1)

  SetAccum<SECRET_INFO> @@info; (2)
  ListAccum<ORDER_RECORD> @@orderRecords;
  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.secretInfo;

  # 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 -(makeOrder:e)-stockOrder:t
      ACCUM @@orderRecords += ORDER_RECORD(t.ticker, t.price, e.orderTime);

  PRINT @@portf, @@info;
  PRINT @@orderRecords;
}

1	This statement defines a new tuple `ORDER_RECORD` at the top of the query.
2	`SECRET_INFO` has already been defined in `investmentNet` Schema.

GSQL > RUN QUERY tupleEx("person1")
{
  "error": false,
  "message": "",
  "version": {
    "edition": "developer",
    "schema": 0,
    "api": "v2"
  },
  "results": [
    {
      "@@info": [{
        "mothersName": "JAMES",
        "age": 25
      }],
      "@@portf": {
        "AAPL": 3142.24,
        "MS": 5000,
        "G": 6112.23
      }
    },
    {"@@orderRecords": [
      {
        "ticker": "AAPL",
        "orderTime": "2017-03-03 18:42:28",
        "price": 34.42
      },
      {
        "ticker": "B",
        "orderTime": "2017-03-03 18:42:30",
        "price": 202.32001
      },
      {
        "ticker": "A",
        "orderTime": "2017-03-03 18:42:29",
        "price": 50.55
      }
    ]}
  ]
}

`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.

Below is an example query that uses the STRING COMPRESS type.

STRING COMPRESS is not a base type.

Query
Results

CREATE QUERY stringCompressEx(VERTEX<person> m1) FOR GRAPH workNet {
  ListAccum<STRING COMPRESS> @@strCompressList, @@strCompressList2;
  SetAccum<STRING COMPRESS> @@strCompressSet, @@strCompressSet2;
  ListAccum<STRING> @@strList, @@strList2;
  SetAccum<STRING> @@strSet, @@strSet2;

  S = {m1};

  S = SELECT s
      FROM S:s
      ACCUM @@strSet += s.interestSet,
            @@strList += s.interestList,
            @@strCompressSet += s.interestSet,   # use the dictionary from person.interestSet
            @@strCompressList += s.interestList; # use the dictionary from person.interestList

  @@strCompressList2 += @@strCompressList;  # @@strCompressList2 gets the dictionary from @@strCompressList, which is from person.interestList
  @@strCompressList2 += "xyz";   # "xyz" is not in the dictionary, so store the actual string value

  @@strCompressSet2 += @@strCompressSet;
  @@strCompressSet2 += @@strSet;

  @@strList2 += @@strCompressList;  # string compress integer values are decoded to strings
  @@strSet2 += @@strCompressSet;

  PRINT @@strSet, @@strList, @@strCompressSet, @@strCompressList;
  PRINT @@strSet2, @@strList2, @@strCompressSet2, @@strCompressList2;
}

GSQL > RUN QUERY stringCompressEx("person12")
{
  "error": false,
  "message": "",
  "version": {
    "edition": "developer",
    "schema": 0,
    "api": "v2"
  },
  "results": [
    {
      "@@strCompressList": [
        "music",
        "engineering",
        "teaching",
        "teaching",
        "teaching"
      ],
      "@@strSet": [ "teaching", "engineering", "music" ],
      "@@strCompressSet": [ "music", "engineering", "teaching" ],
      "@@strList": [
        "music",
        "engineering",
        "teaching",
        "teaching",
        "teaching"
      ]
    },
    {
      "@@strSet2": [ "music", "engineering", "teaching" ],
      "@@strCompressList2": [
        "music",
        "engineering",
        "teaching",
        "teaching",
        "teaching",
        "xyz"
      ],
      "@@strList2": [
        "music",
        "engineering",
        "teaching",
        "teaching",
        "teaching"
      ],
      "@@strCompressSet2": [ "teaching", "engineering", "music" ]
    }
  ]
}

`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

parameterType := INT
               | UINT
               | FLOAT
               | DOUBLE
               | STRING
               | BOOL
               | VERTEX ["<" vertexType ">"]
               | DATETIME
               | [ SET | BAG ] "<" baseType ">"
               | FILE

Examples of collection type parameters

(SET<VERTEX<person> p1, BAG<INT> ids, FILE f1)

Data Types

Identifiers

Overview

Base types

Vertex

Vertex types

Edge

Edge types

Vertex and Edge Attribute Types

JSONOBJECT

Assign a JSONOBJECT value to a base type variable

JSONARRAY

Assign a JSONARRAY value to a base type variable

Container types

Tuple

STRING COMPRESS

FILE Object

Query parameter types

`JSONOBJECT`

Assign a `JSONOBJECT` value to a base type variable

`JSONARRAY`

Assign a `JSONARRAY` value to a base type variable

`STRING COMPRESS`

`FILE` Object