Exception Statements
This section describes how the GSQL language responds to exceptions and supports user-defined exception handling . An exception is a run-time error. The GSQL language supports both built-in system exceptions and user-defined exceptions. Built-in exceptions include GSQL language exceptions (such as out-of-range value, wrong data type, and illegal operation), and errors arising in other TigerGraph components or from the operation system.
The GSQL query language also supports user-defined exception responses, also known as exception handling. This section covers the following syntax for user-defined exception behavior:
1
#########################################################
2
## Exception Statements ##
3
4
declExceptStmt := EXCEPTION exceptVarName "(" errorCode ")"
5
exceptVarName := name
6
errorCode := integer
7
8
raiseStmt := RAISE exceptVarName [errorMsg]
9
errorMsg := "(" expr ")"
10
11
tryStmt := TRY queryBodyStmts EXCEPTION caseExceptBlock+
12
[elseExceptBlock] END ";"
13
caseExceptBlock := WHEN exceptVarName THEN queryBodyStmts
14
elseExceptBlock := ELSE queryBodyStmts
Copied!
Default Exception Response
When an exception occurs during the execution of a query, the default response is the following:
- The query will not execute any more statements; it will exit.
- If the query was run using the RUN QUERY command, then an error message will be displayed.
- If the query was run by invoking the GET /query REST++ endpoint, then the output will be a simple JSON object. Some errors have a error "code" field; others do no t:
Output of Unhandled Exception (query run as REST Endpoint)
1
{
2
"error": true,
3
"message": "<errorMsg>"
4
"code": "<errType><errorCode>"
5
}
Copied!
The example below show two common errors: wrong data type and divide-by-zero. First we define a simple query that divides 100.0 by the query's input parameter.
Example: query excpBuiltin
1
CREATE QUERY excpBuiltin(INT n1) FOR GRAPH minimalNet {
2
PRINT 100.0/n1;
3
}
Copied!
We then test three cases:
- 1.A valid input (such as n1 = 7)
- 2.Wrong data type (n1 = "A")
- 3.Divide by zero (n1 = 0)
First we test using the GSQL interface. When the query runs without error, the output is in JSON format. Where there is a built-in exception, however, only an error message is displayed.
Exception response for RUN QUERY
1
GSQL > RUN QUERY excpBuiltin(7)
2
{
3
"error": false,
4
"message": "",
5
"version": {
6
"edition": "developer",
7
"schema": 0,
8
"api": "v2"
9
},
10
"results": [{"100.0/n1": 14.28571}]
11
}
12
​
13
GSQL > RUN QUERY excpBuiltin("a")
14
Values of parameter n1 must be INT64 type, invalid value [a] provided.
15
​
16
GSQL > RUN QUERY excpBuiltin(0)
17
Runtime Error: divider is zero.
Copied!
The situation is a little different when running the query as a REST++ endpoint. The output is always in JSON format.
As of TigerGraph v1.2, the format for the GET /query endpoint has changed. The graph name must now be specified after /query:
/query/{graph_name}/{query_name}Exception response for GET /query request
1
$ curl -X GET "http://localhost:9000/query/minimalNet/excpBuiltin?n1=7"
2
{
3
"error": false,
4
"message": "",
5
"results": [
6
{
7
"100.0/n1": 14.28571
8
}
9
],
10
"version": {
11
"edition": "developer",
12
"api": "v2",
13
"schema": 0
14
}
15
}
16
​
17
$ curl -X GET "http://localhost:9000/query/minimalNet/excpBuiltin?n1=a"
18
{
19
"code": "REST-30000",
20
"error": true,
21
"message": "Values of parameter n1 must be INT64 type, invalid value [a] provided.",
22
"version": {
23
"edition": "developer",
24
"api": "v2",
25
"schema": 0
26
}
27
}
28
​
29
$ curl -X GET "http://localhost:9000/query/minimalNet/excpBuiltin?n1=0"
30
{
31
"error": true,
32
"message": "Runtime Error: divider is zero.",
33
"version": {
34
"edition": "developer",
35
"api": "v2",
36
"schema": 0
37
}
38
}
Copied!
User-Defined Exception Behavior
A query author can specify what should be the response if a particular type of exception occurs within a particular specified block of statements.
The following statement types are available to specify a user-defined exception condition or a user-defined exception response.
- The EXCEPTION Declaration Statement names a user-defined exception.
- The RAISE Statement indicates that one of the user-defined exceptions has occurred.
- The TRY…EXCEPTION Statement is used to define and apply user-defined exception handling to a block of query-body statements. This can be used with or without preceding user-defined EXCEPTION and RAISE statements.
Built-in exceptions always take precedence over user-defined exceptions. Therefore, user-defined exceptions can only be used to catch conditions that would not be caught by a built-in exception. This means that built–in exceptions are best used to capture situations which are legal according to the general syntax and semantics of the GSQL query language, but which are illegal or undesirable for a particular user application.
EXCEPTION Declaration Statement
1
declExceptStmt := EXCEPTION exceptVarName "(" errorCode ")"
2
exceptVarName := name
3
errorCode := integer
Copied!
To use a user-defined exception, it must first be declared. An exception declaration statement declares a user-defined exception type, assigning a name and identification number. The id number errorCode must be greater than 40,000. Numbers 40,000 and lower are reserved for system exceptions. Exception statements must be placed before any query-body statements, after accumulator declaration statements . A query can declare multiple exception types.
RAISE Statement
1
raiseStmt := RAISE exceptVarName [errorMsg]
2
errorMsg := "(" expr ")"
Copied!
The RAISE statement announces that a user-defined exception has just occurred. The exceptVarName must match one of the exceptions that was previously declared. An optional error message can be specified. Once the RAISE statement is executed, the flow of execution changes. If the RAISE statement is not within a TRY clause, then the query ends with the default exception response, using the error code and error message defined by the exception type and RAISE statements. If the RAISE is within a TRY statement, then execution jumps to the EXCEPTION handling clause of the TRY statement.
A RAISE statement itself does not include the conditions that define the exception. Typically, the user will use an IF…THEN statement and place the RAISE statement within the THEN clause.
In the current version, a RAISE statement can only be used as a query-body-statement. It cannot be used as a DML-sub-statement. In particular, you cannot RAISE an exception inside a SELECT statement.
The example below defines and checks for two types of exceptions: an empty input set (40001) and no matching edges (40002). Remember that the minimum allowed code number is 40001.
Example: Unhandled User-Defined Exceptions
1
CREATE QUERY excpCountActivity(SET<VERTEX<person>> vSet, STRING eType) FOR GRAPH socialNet {
2
# Count how many edges there are from each member of the input person set to posts,
3
# along the specified edge type.
4
​
5
MapAccum<STRING,INT> @@allCount;
6
EXCEPTION emptyList (40001);
7
EXCEPTION noEdges (40002);
8
​
9
IF ISEMPTY(vSet) THEN ## Raise 40001
10
RAISE emptyList ("Error: Input parameter 'vSet' (type SET<VERTEX<person>>) is empty");
11
END;
12
13
Start = vSet;
14
Results = SELECT s
15
FROM Start:s -(:e)-> post:t
16
WHERE e.type == eType
17
ACCUM @@allCount += (t.subject -> 1);
18
19
IF Results.size() == 0 THEN ## Raise 40002
20
RAISE noEdges ("Error: No '" + eType + "' edges from the vertex set");
21
END;
22
PRINT @@allCount;
23
}
Copied!
Results
1
// Valid input: no exceptions
2
$ curl -X GET "http://localhost:9000/query/socialNet/excpCountActivity?vSet=person2&vSet=person6&eType=posted"
3
{
4
"error": false,
5
"message": "",
6
"version": {
7
"edition": "developer",
8
"schema": 0,
9
"api": "v2"
10
},
11
"results": [{
12
"@@allCount": {
13
"cats": 1,
14
"tigergraph": 2
15
}
16
}]
17
}
18
​
19
// empty input set (due to spelling error in parameter name)
20
$ curl -X GET "http://localhost:9000/query/socialNet/excpCountActivity?vset=person2&vset=person6&eType=posted"
21
{
22
"code": "40001",
23
"error": true,
24
"version": {
25
"edition": "developer",
26
"schema": 0,
27
"api": "v2"
28
},
29
"message": "Error: Input parameter 'vSet' (type SET<VERTEX<person>>) is empty"
30
}
31
​
32
​
33
// no edges (due to unknown edge type)
34
$ curl -X GET "http://localhost:9000/query/socialNet/excpCountActivity?vSet=person2&vSet=person6&eType=commented"
35
{
36
"code": "40002",
37
"error": true,
38
"version": {
39
"edition": "developer",
40
"schema": 0,
41
"api": "v2"
42
},
43
"message": "Error: No 'commented' edges from the vertex set"
44
}
Copied!
TRY...EXCEPTION Statement for Custom Error Handling
1
tryStmt := TRY queryBodyStmts EXCEPTION caseExceptBlock [elseExceptBlock] END ";"
2
caseExceptBlock := WHEN exceptVarName THEN queryBodyStmts+
3
elseExceptBlock := ELSE queryBodyStmts
Copied!
The TRY…EXCEPTION Statement is used to define and apply user-defined exception handling to a block of query-body statements. A TRY...EXCEPTION statement can be nested within a TRY block or EXCEPTION block.
The current version of GSQL does not support custom handling of built-in exceptions. Therefore, if a built-in exception occurs, it ignores the TRY..EXCEPTION blocks and simply applies the default handling, and the query aborts. In future updates, we plan to support custom handling of both custom exceptions (RAISE) and built-in exception with the TRY...EXCEPTION block.
The TRY…EXCEPTION Statement is a compound statement containing two blocks. The first block (TRY) consists of the query-body statements for which custom error handling should be applied. The second block (EXCEPTION) contains a series of WHEN…THEN exception handling clauses. Each exception handling clause names an exception type and specifies what actions to take in the event of the exception. An optional ELSE clause contains handling statements for all other exceptions. The following text and visual flowchart details how the TRY... EXCEPTION block handles an exception.
When an exception occurs within a TRY block, the flow of execution skips the remainder of the TRY block and jumps to the EXCEPTION block. The GSQL flow now seeks to match the exception type with a handler. After executing the handling statements in the THEN or ELSE clause, the flow skips the remainder of the EXCEPTION block and continues with the statement following the END statement. However, if there is no matching WHEN or ELSE handler, then the exception is propagated. That is, the RAISE state is maintained after exiting the EXCEPTION block. If the TRY...EXCEPTION block is nested inside another TRY block, then the handling process is repeated at this upper level. This repeats until either the exception is handled or there are no more TRY...EXCEPTION blocks.
Finally, if the unhandled exception is not within a TRY block, then the the query is aborted, and the default exception response is the output.
Case 1: If cond1 is true in the outer TRY block,
- RAISE A and jump to the output EXCEPTION block.
Handled by ELSE HandStmtsZ.
Case 2: If cond2 is true in the inner TRY block,
- RAISE A and jump to the inner EXCEPTION block.
Handled by handStmtsX;
Case 3: If cond3 is true in the inner TRY block,
- RAISE B and jump to the inner EXCEPTION block. There is no matching handler here, so propagate the exception. Jump to the outer EXCEPTION block. Handled by handStmtsY.
Custom Handling Example:
The following example is a modified shortest path query. It looks for all paths from a source to a target in a computer network. It uses breadth-first search and stops at depth N when it has found at least one path at depth N, or it has searched the entire graph. There are three conditions which will cause it to RAISE an exception and abort the search:
- 1.Seeing an edge with a negative connection speed (because the graph has bad data).
- 2.Seeing an edge with a very slow connection speed (again because the graph has bad data).
- 3.If no path was found in the graph (the search is already over, but we skip printing results).
Note that cases 1 and 2 do NOT mean that a negative or slow speed edge is actually on a shortest path, only that the query noticed a bad edge during its search. Also, because we cannot RAISE within the SELECT block, we use a workaround: set an integer variable with an error code. Immediately after the SELECT block, test the integer variable and RAISE exceptions as needed.
Example: Path Search with Exceptions
1
CREATE QUERY compPathValid (vertex<computer> src, vertex<computer> tgt, BOOL enExcp)
2
FOR GRAPH computerNet {
3
# Find valid paths in a computer network from a source to a target.
4
# Stop search once you have found some paths.
5
# 3 Exceptions: (1) Negative connection speed, (2) Slow connection speed, (3) No path.
6
# Set enExcp=true to raise exceptions. enExcp=false will find paths, good or bad.
7
​
8
OrAccum @@reached, @visited;
9
ListAccum<STRING> @paths;
10
DOUBLE minSpeed = 0.4;
11
INT err;
12
​
13
EXCEPTION negSpeed (40001);
14
EXCEPTION slowSpeed (40002);
15
EXCEPTION notReached (40003);
16
​
17
TRY
18
Start = {src};
19
# Initialize: path to src is itself.
20
Start = SELECT s
21
FROM Start:s
22
ACCUM s.@paths = s.id;
23
​
24
WHILE Start.size() != 0 AND NOT @@reached DO
25
Start = SELECT t
26
FROM Start:s -(:e)-> :t
27
WHERE t.@visited == false
28
ACCUM CASE
29
WHEN e.connectionSpeed < 0 THEN err = 1
30
WHEN e.connectionSpeed < minSpeed THEN err = 2
31
WHEN t == tgt THEN @@reached += true
32
END,
33
# List1 * List2 -> List(each elem of List1 concat w/each elem of List2)
34
t.@paths += (s.@paths * ["~"]) * [t.id]
35
POST-ACCUM t.@visited = true;
36
IF err == 1 AND enExcp THEN
37
RAISE negSpeed ("Negative Speed");
38
ELSE IF err == 2 AND enExcp THEN
39
RAISE slowSpeed ("Slow Speed");
40
END;
41
END; # WHILE
42
​
43
IF NOT @@reached AND enExcp THEN
44
RAISE notReached ("No path to target");
45
ELSE
46
Result = {tgt};
47
PRINT Result[Result.@paths]; // api v2
48
END;
49
EXCEPTION
50
WHEN negSpeed THEN PRINT "bad path: negative speed";
51
WHEN slowSpeed THEN PRINT "bad path: slow speed";
52
WHEN notReached THEN PRINT "no path from source to target";
53
END;
54
}
Copied!
As the data in Appendix D show:
- Any search passing through c1 will see negative edges.
- Any search passing through c12 will see negative and slow edges.
- Any search passing through c14 will see negative edges.
The results for 5 cases are shown: 1 valid search plus each of the 3 exception conditions. The 5th case is the same as the 4th, but exception handling is not enabled.
compPathValid.json
1
GSQL > RUN QUERY compPathValid("c10","c12",true)
2
{
3
"error": false,
4
"message": "",
5
"version": {
6
"edition": "developer",
7
"schema": 0,
8
"api": "v2"
9
},
10
"results": [{"Result": [{
11
"v_id": "c12",
12
"attributes": {"[email protected]": ["c10~c11~c12"]},
13
"v_type": "computer"
14
}]}]
15
}
16
GSQL > RUN QUERY compPathValid("c1","c12",true)
17
{
18
"error": false,
19
"message": "",
20
"version": {
21
"edition": "developer",
22
"schema": 0,
23
"api": "v2"
24
},
25
"results": [{"bad path: negative speed": "bad path: negative speed"}]
26
}
27
GSQL > RUN QUERY compPathValid("c10","c13",true)
28
{
29
"error": false,
30
"message": "",
31
"version": {
32
"edition": "developer",
33
"schema": 0,
34
"api": "v2"
35
},
36
"results": [{"bad path: slow speed": "bad path: slow speed"}]
37
}
38
GSQL > RUN QUERY compPathValid("c24","c25",true)
39
{
40
"error": false,
41
"message": "",
42
"version": {
43
"edition": "developer",
44
"schema": 0,
45
"api": "v2"
46
},
47
"results": [{"no path from source to target": "no path from source to target"}]
48
}
49
GSQL > RUN QUERY compPathValid("c24","c25",false)
50
{
51
"error": false,
52
"message": "",
53
"version": {
54
"edition": "developer",
55
"schema": 0,
56
"api": "v2"
57
},
58
"results": [{"Result": [{
59
"v_id": "c25",
60
"attributes": {"[email protected]": []},
61
"v_type": "computer"
62
}]}]
63
}
Copied!
Exception Handling Flowchart
The flowchart below summarizes all the cases for triggering and handling exceptions, both user-defined and built-in.
​
Last modified 2yr ago