Miscellaneous Functions

This page lists the functions in the GSQL query language that are not tied to any single data type.

coalesce()

Syntax

coalesce( exp [, exp ...] )

Description

Returns the first expression that isn’t NULL.

This function requires all its arguments have the same data type (BOOL, INT, FLOAT, DOUBLE, STRING, or VERTEX). The only exception is that different numeric types can be used together. In this case, all values are converted into the first argument type.

Return type

BOOL, INT, FLOAT, DOUBLE, STRING, or VERTEX

Parameters

The function takes a number of parameters and returns the first one that does not evaluate to NULL

Example

CREATE QUERY coalesceFuncEx (INT p1, DOUBLE p2) FOR GRAPH social {
  PRINT COALESCE(p1, p2, 999.5);  # p2 and the last value will be converted into first argument type, which is INT.
}
Results
GSQL > RUN QUERY coalesceFuncEx(_,_)
{
  "error": false,
  "message": "",
  "version": {
    "schema": 1,
    "edition": "enterprise",
    "api": "v2"
  },
  "results": [{"coalesce(p1,p2,999.5)": 999}]
}

GSQL > RUN QUERY coalesceFuncEx(1,2)
{
  "error": false,
  "message": "",
  "version": {
    "schema": 1,
    "edition": "enterprise",
    "api": "v2"
  },
  "results": [{"coalesce(p1,p2,999.5)": 1}]
}

evaluate()

Syntax

evaluate( expressionStr, typeStr )

Description

Takes a string argument and interprets it as an expression which is evaluated during run-time. This enables users to create a general purpose query instead of separate queries for each specific computation.

This function cannot be nested.

The following situations generate a run-time error:

  • The expression string expressionStr cannot be compiled (unless the error is due to a non-existent vertex or edge attribute).

  • The result type of the expression does not match the parameter typeStr.

Silent failure conditions

If any of the following conditions occur, the query may continue running, but the entire clause or statement in which the evaluate() function resides will fail, without producing a run-time error message. For conditional clauses (WHERE, HAVING), a failing evaluate() clause is treated as if the condition is false. An assignment statement with a failing evaluate() will not execute, and an ORDER BY clause with a failing evaluate() will not sort.

  1. The expression references a non-existent attribute of a vertex or edge alias.

  2. The expression uses an operator for non-compatible operation. For example, 123 == "xyz".

Return type

Type indicated by typeStr

Parameters

Parameter Description Data type

expressionStr

The expression to evaluate typed as a string.

  • Identifiers used in the expression can refer only to a vertex or edge aliases, vertex-attached accumulators, global accumulators, parameters, or scalar function calls involving the above variables.

  • The expression may not refer to local variables, global variables, or to FROM clause vertices or edges by type.

  • Any accumulators in the expression must be scalar accumulators (e.g., MaxAccum) for primitive-type data. Container accumulators (e.g., SetAccum) or scalar accumulators with non-primitive type (e.g. VERTEX, EDGE, DATETIME) are not supported. Container type attributes are not supported.

STRING

typeStr

The return type for the function call. It must be a string literal for a primitive data type, e.g., one of "int", "float", "double", "bool", "string" (case insensitive).

The default value is "bool".

STRING

Example

Example query
CREATE QUERY evaluateEx (STRING whereCond = "TRUE", STRING postAccumIntExpr = "1") FOR GRAPH socialNet {
  SetAccum<INT> @@timeSet;
  MaxAccum<INT> @latestLikeTime, @latestLikePostTime;

  S = {person.*};
  S2 = SELECT s
       FROM S:s - (liked>:e) - post:t
       WHERE evaluate(whereCond)
       ACCUM s.@latestLikeTime += datetime_to_epoch( e.actionTime ),
             s.@latestLikePostTime += datetime_to_epoch( t.postTime )
       POST-ACCUM @@timeSet += evaluate(postAccumIntExpr, "int")
       ;
  PRINT @@timeSet;
}
Results
GSQL > RUN QUERY evaluateEx("s.gender==\"Male\"", "s.@latestLikePostTime")
{
  "error": false,
  "message": "",
  "results": [
    {
      "@@timeSet": [1263295325,1296752752,1297054971,1296788551]
    }
  ]
}

GSQL > RUN QUERY evaluateEx("s.gender==\"Female\"", "s.@latestLikeTime + 1")
{
  "error": false,
  "message": "",
  "results": [
    {
      "@@timeSet": [1263293536,1263352566,1263330726]
    }
  ]
}