Built-in Endpoints

Search…
Built-in Endpoints
System Utilities
Echo (Public)
GET /echo and POST /echo
These endpoints provide simple diagnostic utilities, which respond with the following message if the RESTPP server is up and running. NeitherGET /echo or POST /echo require authentication, even when RESTPP authentication is enabled.
Sample request:
GET echo/ Request and Response
1
curl -X GET "http://localhost:9000/echo"
2
{
3
    "error": false, 
4
    "message": "Hello GSQL"
5
}
Copied!
POST /echo has the same response as GET /echo.
Parameters
Name
Required
Description
sleep
No
Integer that indicates the number of seconds for which the response will be delayed.
Health check (public)
This endpoint performs a simple server health check. It listens on port 14240 and does not require authentication. If you ping it and the server is running, it will respond with the message "pong".
Endpoint:
GET /api/ping
Sample request:
1
$ curl 'http://localhost:14240/api/ping'
2
​
3
{
4
  "error": "false",
5
  "message": "pong",
6
  "results": {}
7
}
Copied!
Parameters:
No parameters.
List all endpoints
GET /endpoints/{graph_name}
This endpoint returns a list of the installed endpoints and their parameters. There are three types of endpoints:
Built-in endpoints which are preinstalled in the TigerGraph system
Dynamic endpoints which are generated when compiling GSQL queries
_Static endpoints _which are user-installed endpoints
To include one or more of the endpoint types in the output, include the endpoint type in the parameter query string and set its value to true. If no type parameters are provided, all endpoints are returned.
Example: Report on all built-in endpoints
1
curl -X GET "http://localhost:9000/endpoints?builtin=true" | jq .
Copied!
Response
There are over a dozen built-in endpoints, and some have several parameters, so the formatted JSON output of all built-in endpoints is over 300 lines long. It is listed in full in Appendix A. Below is a small excerpt of the output:
Subset of GET /endpoints output
1
    "GET /endpoints": {
2
        "parameters": {
3
            "builtin": {
4
                "default": "false", 
5
                "max_count": 1, 
6
                "min_count": 0, 
7
                "type": "BOOL"
8
            }, 
9
            "dynamic": {
10
                "default": "false", 
11
                "max_count": 1, 
12
                "min_count": 0, 
13
                "type": "BOOL"
14
            }, 
15
            "static": {
16
                "default": "false", 
17
                "max_count": 1, 
18
                "min_count": 0, 
19
                "type": "BOOL"
20
            }
21
        }
22
    }
Copied!
Parameters
Name
Required
Description
builtin
No
Takes a boolean value. Returns built-in endpoints if true.
dynamic
No
Takes a boolean value. Returns dynamic endpoints if true.
static
No
Takes a boolean value. Returns user-installed endpoints if true.
Show component versions
GET /version
This endpoint returns the GIT versions of all components of the system.
Sample request:
1
curl -X GET "http://localhost:9000/version"
2
{"error":"false", "message":"TigerGraph RESTPP: 
3
 --- Version --- 
4
product              release_2.6.0_05-09-2020 ab1e3d0da6237c27468d6cabb90900119d63759d  2020-04-15 15:46:29 -0700
5
olgp                 release_2.6.0_05-09-2020 046c745088106b69920b9bdb3bd15969de409e92  2020-05-01 19:10:27 -0700
6
topology             release_2.6.0_05-09-2020 c028af100117f2051b619436c3aa4febc810bf36  2020-04-22 08:44:07 -0700
7
gpe                  release_2.6.0_05-09-2020 34b9e86ef7b5fdaa106637e7db1d8a9e080a0aa2  2020-04-19 09:42:59 -0700
8
gse                  release_2.6.0_05-09-2020 ed2c2351357aa9077fa4dee7ea7a01f8ad2f7585  2020-05-11 01:18:54 -0700
9
third_party          release_2.6.0_05-09-2020 4bce6990bae5be2b91e9201693ceb66341d3f204  2020-04-19 09:42:56 -0700
10
utility              release_2.6.0_05-09-2020 2ce197d3edb3557bdd66ed1a4194309908d6197e  2020-04-20 21:19:34 -0700
11
realtime             release_2.6.0_05-09-2020 52a82b454437c73b47d846acd5803ab0d9f54a45  2020-04-22 08:44:11 -0700
12
er                   release_2.6.0_05-09-2020 a3e6cb7606fb74984c75cae9bbd4d2112fdbf73a  2020-05-01 19:10:33 -0700
13
gle                  release_2.6.0_05-09-2020 d8bdbd1cf346e181aa9a317c704dd7b3b11b4658  2020-05-06 00:51:04 -0700
14
bigtest              release_2.6.0_05-09-2020 2f64c47b7a5ac1834ead9a22eef8d42241117853  2019-12-12 01:31:35 -0800
15
document             release_2.6.0_05-09-2020 6327094bd76b2dbc8f4625108d547827344b5091  2019-12-13 16:30:13 -0800
16
glive                release_2.6.0_05-09-2020 93f61ea06fe42759c808fc58ff6245c9954d5447  2020-02-05 22:40:24 -0800
17
gap                  release_2.6.0_05-09-2020 e798efb595545bf91c449034566857c41f52449a  2020-04-29 22:47:26 -0700
18
gst                  release_2.6.0_05-09-2020 1b695c02f277efad0ddfb2deab710ae0158409da  2020-04-29 22:47:32 -0700
19
gus                  release_2.6.0_05-09-2020 eee784502b5387844e462305bae419954784da6f  2020-04-29 22:47:20 -0700
20
blue_features        release_2.6.0_05-09-2020 5d7a4e8d806519f529274b331496d3bc78f01990  2020-04-15 15:46:38 -0700
21
blue_commons         release_2.6.0_05-09-2020 432763afc49bf986aed4731e50254243d3665bc3  2019-07-30 03:34:46 -0700
22
"}
Copied!
Parameters
This endpoint does not take any parameters.
Monitor system metrics
POST /ts3/api/datapoints
TigerGraph System State Service (TS3) is TigerGraph's managed monitoring service that collects system metrics and events. Many TigerGraph components will report metrics such as CPU usage, memory usage, disk usage, and network traffic to TS3 at regular intervals. You can use this endpoint to read from TS3, filtering for the data points you need by time (when, from, and to), component(who), metric(what) and location(where). Visualization of such metrics are available in Admin Portal - Dashboard - Cluster Monitoring.
On a TigerGraph cluster, this endpoint is only present on the m1 node.
Parameters
Name
Required
Description
from
No
Epoch timestamp that indicates the start of the time filter. Only data points reported after the timestamp will be included in the return results.
to
No
Epoch timestamp that indicates the end of the time filter. Only data points reported before the timestamp will be included in the return results.
latest
No
Number of latest data points to return. If provided, the endpoint will return the latest data points that satisfy the what, who and where filters and ignore other time-related filters.
what
No
Name of the metric to filter for. Possible values are:
cpu: Percentage of CPU usage by component
mem: Memory usage in megabytes by component
diskspace: Disk usage in megabytes by directory
network: Network traffic in bytes since the service started
qps: Number of requests per second by endpoint
servicestate: Whether or not the service is online. A value of 0 indicates that the service is offline while a value of 1 means the service is online
connection: Number of open TCP connections
who
No
Name of the component that reported the datapoint
where
No
Name of the node that the datapoint is reported for
Sample requests
In the sample request below, the filters in the query string include a timeframe starting at 1618957536 and ending at 1619023346, and specifying that the response should only include CPU information:
1
$ curl -X GET 
2
"https://crunch.i.tgcloud.io:14240/ts3/api/datapoints?from=1618957536&to=1619023346&what=cpu"
3
​
4
# Three data points returned
5
[
6
  {
7
    "detail": 0,  # GPE is using 0 percent CPU 
8
    "when": 1619023346, 
9
    "where": "m1", 
10
    "who": "GPE_1#1",
11
    "what": "cpu"
12
  },
13
  {
14
    "detail": 0,
15
    "when": 1619023346,
16
    "where": "m1",
17
    "who": "GSE_1#1",
18
    "what": "cpu"
19
  },
20
  {
21
    "detail": 0,
22
    "when": 1619023346,
23
    "where": "m1",
24
    "who": "RESTPP#1",
25
    "what": "cpu"
26
  }
27
]
Copied!
In the below example, the request asks for the 10 latest data points regarding memory usage:
1
$ curl -X GET
2
"https://crunch.i.tgcloud.io:14240/ts3/api/datapoints?what=mem&latest=10"
3
​
4
[
5
  {
6
    "detail": 159,
7
    "when": 1620076473,
8
    "where": "m1",
9
    "who": "RESTPP#1",
10
    "what": "mem"
11
  },
12
  {
13
    "detail": 211,
14
    "when": 1620076533,
15
    "where": "m1",
16
    "who": "GPE_1#1",
17
    "what": "mem"
18
  },
19
  {
20
    "detail": 436,
21
    "when": 1620076533,
22
    "where": "m1",
23
    "who": "GSE_1#1",
24
    "what": "mem"
25
  },
26
  {
27
    "detail": 159,
28
    "when": 1620076533,
29
    "where": "m1",
30
    "who": "RESTPP#1",
31
    "what": "mem"
32
  },
33
  {
34
    "detail": 211,
35
    "when": 1620076593,
36
    "where": "m1",
37
    "who": "GPE_1#1",
38
    "what": "mem"
39
  },
40
  {
41
    "detail": 436,
42
    "when": 1620076593,
43
    "where": "m1",
44
    "who": "GSE_1#1",
45
    "what": "mem"
46
  },
47
  {
48
    "detail": 159,
49
    "when": 1620076593,
50
    "where": "m1",
51
    "who": "RESTPP#1",
52
    "what": "mem"
53
  },
54
  {
55
    "detail": 210,
56
    "when": 1620076653,
57
    "where": "m1",
58
    "who": "GPE_1#1",
59
    "what": "mem"
60
  },
61
  {
62
    "detail": 436,
63
    "when": 1620076653,
64
    "where": "m1",
65
    "who": "GSE_1#1",
66
    "what": "mem"
67
  },
68
  {
69
    "detail": 159,
70
    "when": 1620076653,
71
    "where": "m1",
72
    "who": "RESTPP#1",
73
    "what": "mem"
74
  }
75
]
Copied!
Show query performance
GET /statistics/{graph_name}
This endpoint returns real-time query performance statistics over the given time period, as specified by the seconds** **parameter. The seconds parameter must be a positive integer less than or equal to 60.
Sample request:
The return object is a hash of the endpoints and their performance data:
1
# The example shows two endpoints (/graph/vertex and
2
# /statistics) called during the past 60 seconds.
3
curl -X GET "http://localhost:9000/statistics/poc_graph?seconds=60" | jq '.'
4
​
5
{
6
  "GET /graph/vertices/{vertex_type}/{vertex_id}": {
7
    "CompletedRequests": 8,
8
    "QPS": 0.08,
9
    "TimeoutRequests": 0,
10
    "AverageLatency": 130,
11
    "MaxLatency": 133,
12
    "MinLatency": 128,
13
    "LatencyPercentile": [
14
      200,
15
      200,
16
      200,
17
      200,
18
      200,
19
      200,
20
      200,
21
      200,
22
      200,
23
      200
24
    ]
25
  },
26
  "GET /statistics": {
27
    "CompletedRequests": 4226,
28
    "QPS": 42.26,
29
    "TimeoutRequests": 0,
30
    "AverageLatency": 2,
31
    "MaxLatency": 125,
32
    "MinLatency": 0,
33
    "LatencyPercentile": [
34
      10,
35
      10,
36
      10,
37
      10,
38
      10,
39
      10,
40
      10,
41
      10,
42
      10,
43
      200
44
    ]
45
  }
46
}
Copied!
Each endpoint has the following attributes:
CompletedRequests - the number of completed requests.
QPS - query per second.
TimeoutRequests - the number of requests not returning before the system-configured timeout limit. Timeout requests are not included in the calculation of QPS.
AverageLatency - the average latency of completed requests.
MaxLatency - the maximum latency of completed requests.
MinLatency - the minimum latency of completed requests.
LatencyPercentile - The latency distribution. The number of elements in this array depends on the segments** parameter of this endpoint whose default value is 10, meaning the percentile range 0-100% will be divided into ten equal segments: 0%-10%, 11%-20%, etc.Segments **must be [1, 100].
If there is no query sent in the past given seconds, an empty json will be returned.
Parameters
Name
Required
Description
seconds
Yes
Positive integer less than 60 that indicates how many seconds back from the current time the statistics report will cover.
segments
No
Integer that indicates the number of segments that LatencyPercentile array in the response will be split into. The value for this endpoint must be between 1 and 100 and has a default value of 10.
Rebuild graph engine
GET /rebuildnow/{graph_name} or POST /rebuildnow/{graph_name}
In TigerGraph, when new data is being loaded into the graph (such as new vertices or edges), data is first stored in memory before it is saved to disk permanently. TigerGraph runs a rebuild of the Graph Processing Engine (GPE) to commit the data in memory to disk every 30 seconds, but you can also call this endpoint to trigger a rebuild immediately.
Parameters:
Name
Required
Description
threadnum
No
Number of threads used to execute the rebuild. If not specified, the number specified in line 185 of the .tg.cfg file ("RebuildThreadNumber") in the home directory of the server on which TigerGraph is running will be used; it is set to 3 by default.
The maximum value for this parameter is the number of vCPUs per node in your distributed system. If you are running a single-node server, the maximum is the number of vCPUs on that node. You can run lscpu in the command line of your Linux server and look in the CPU(s) column to view the number of vCPUs.
vertextype
No
Vertex type to perform the rebuild for. If not provided, the rebuild will be run for all the vertex types.
segid
No
Segment ID of the segments to rebuild. If not provided, all segments will be rebuilt. In general, it is recommended not to provide this parameter and rebuild all segments.
path
No
Path to save the summary of the rebuild to. If not provided, the default path is /tmp/rebuildnow
force
No
Boolean value that indicates whether to perform rebuilds for segments for which there are no records of new data. Normally, a rebuild would skip such segments, but if force is set true, the segments will not be skipped.
Example:
1
$ curl -X GET 'http://localhost:9000/rebuildnow/social' 
2
​
3
# JSON response
4
{
5
  "version": {
6
    "edition": "enterprise",
7
    "api": "v2",
8
    "schema": 0
9
  },
10
  "error": false,
11
  "message": "RebuildNow finished, please check details in the folder: /tmp/rebuildnow",
12
  "results": [],
13
  "code": "REST-0000"
14
}
15
​
16
# Example summary file
17
$ cat finished.summary.txt
18
​
19
[SELECTED]	Segment id: 106, vertextype: 0, vertexsubtypeid: 0, vertexcount: 187732, edgecount: 563196, deletevertexcount: 0, postqueue_pos: 16344, transaction id: 16344, rebuild ts: 1573106412990
20
[SKIPPED]	Segment id: 6, vertextype: 0, vertexsubtypeid: 0, vertexcount: 85732, edgecount: 3106, deletevertexcount: 0, postqueue_pos: 16344, transaction id: 16344, rebuild ts: 1573106412900
Copied!
Check deleted vertices
GET /deleted_vertex_check
In certain rare cases, TigerGraph's Graph Processing Engine (GPE) and Graph Storage Engine (GSE) might be out of sync on vertex deletion information. When this happens, some vertices might exist on one of the components, but not the other. Even though these errors are exceedingly rare, TigerGraph provides an endpoint that allows you to check the deleted vertices on GSE and GPE and see if they out of sync.
The check passes if there are no discrepancies between the GSE and GPE in terms of deleted vertices. If there is a discrepancy, the check fails and the return result will contain the IDs of the deleted vertices that are not synced properly. If you are running TigerGraph on a distributed cluster, the check will be performed on each node of the cluster, and the endpoint will return a list containing the results of the check for every node.
Parameters:
Name
Required
Description
threadnum
No
Integer that indicates the number of threads used to execute the deleted vertex check jobs. This parameter is optional and the default value is 6 if none is provided
segid
No
IDs of segments to perform the deleted vertex check for. If none is provided, the check will be performed on all segments.
vertextype
No
Vertex types to perform the deleted vertex check for. If none is provided, the check will be performed on all vertex types.
verbose
No
Integer that indicates the level of detail in the return results. Here is a list of accepted values and their corresponding level of detail:
0 (default) : Only return whether the check passed and the list of unsynced vertex IDs
1: In addition to the previous level, also return vertex count information
2: In addition to the previous level, return vertex count information for every segment
4: In addition to the previous level, also return the IDs of deleted vertices for every segment
log
No
Integer that indicates the log level of the deleted vertex check. This log is not returned in the endpoint's HTTP response, but is printed to the logs of the GPE component at /tigergraph/log/gpe/log.INFO:
0 (default): Report brief log for the check as a whole
1: Report logs for each segment
2: Report additional logs on the obtained deleted ID list
Example:
1
# Passing check performed on a single-node database
2
$ curl -X GET "http://localhost:9000/deleted_vertex_check?threadnum=10&verbose=0" |jq .
3
 
4
{
5
  "version": {
6
    "edition": "enterprise",
7
    "api": "v2",
8
    "schema": 0
9
  },
10
  "error": false,
11
  "message": "check passed",
12
  "results": [
13
    {
14
      "GPE": "GPE_1_1",
15
      "PassCheck": true,
16
      "UnSyncList": []
17
    }
18
  ],
19
  "code": "REST-0000"
20
}
21
​
22
# Failed check performed on a distributed cluster
23
​
24
$ curl -X GET 'http://localhost:9000/deleted_vertex_check?threadnum=10&verbose=0&vertextype=region' |jq .
25
{                                                                                                   
26
  "version": {                                                                                      
27
    "edition": "enterprise",                                                                        
28
    "api": "v2",                                                                                    
29
    "schema": 0                                                                                     
30
  },                                                                                                
31
  "error": false,                                                                                   
32
  "message": "check failed",                                                                        
33
  "results": [                                                                                      
34
    {                                                                                               
35
      "GPE": "GPE_2_1",                                                                             
36
      "PassCheck": false,                                                                           
37
      "UnSyncList": [                                                                               
38
        {                                                                                           
39
          "Segid": 193,                                                                             
40
          "IsRemote": false,                                                                        
41
          "VertexType": "region",                                                                   
42
          "GPEDelHash": 7013042118817697000,                                                        
43
          "IDSDelHash": 202375168                                                                   
44
        }                                                                                           
45
      ]                                                                                             
46
    },                                                                                              
47
    {                                                                                               
48
      "GPE": "GPE_3_1",                                                                             
49
      "PassCheck": false,                                                                           
50
      "UnSyncList": [                                                                               
51
        {                                                                                           
52
          "Segid": 193,                                                                             
53
          "IsRemote": true,                                                                         
54
          "VertexType": "region",                                                                   
55
          "GPEDelHash": 7013042118817697000,                                                        
56
          "IDSDelHash": 202375168                                                                   
57
        }                                                                                           
58
      ]                                                                                             
59
    },                                                                                              
60
    {                                                                                               
61
      "GPE": "GPE_1_1",                                                                             
62
      "PassCheck": false,                                                                           
63
      "UnSyncList": [                                                                               
64
        {                                                                                           
65
          "Segid": 193,                                                                             
66
          "IsRemote": true,           
67
          "VertexType": "region",                                                                   
68
          "GPEDelHash": 7013042118817697000,                                                        
69
          "IDSDelHash": 202375168                                                                   
70
        }                                                                                           
71
      ]                                                                                             
72
    }                                                                                               
73
  ],                                                                                                
74
  "code": "REST-0000"                                                                               
75
}      
Copied!
Authentication
The endpoints in this subsection allow users to create, refresh and delete authentication tokens for requests made to the REST++ server. These endpoints only exist when user authentication is enabled on RESTPP endpoints.
Request a token (GET)
GET /requesttoken
If authentication is enabled on RESTPP endpoints, a token needs to be included in the request header for all requests sent to the RESTPP server. A user can generate a token using either
A secret, which is a random string generated in GSQL (see Managing User Privileges and Authentication)
Their username and password in their request header as well as specifying the graph
You may also use a POST request to generate your token, see Request a token (POST).
Sample request:
1
curl -X GET "http://localhost:9000/requesttoken?secret=jiokmfqqfu2f95qs6ug85o89rpkneib3&lifetime=1000000"
2
{
3
  "code": "REST-0000",
4
  "expiration": 1616042814,
5
  "error": false,
6
  "message": "Generate new token successfully.",
7
  "token": "tohvf6khjqju8jf0r0l1cohhlm8gi5fq"
8
}
9
​
10
curl --user example_username:example_password -X GET "localhost:9000/requesttoken?graph=example_graph"
Copied!
Parameters:
Name
Required
Description
secret
Yes if graph is not supplied
User's secret to generate the token.
lifetime
No
Period of time for which the token is valid measured in seconds. The default value is about 2.6 million (about a month).
graph
Yes if secret is not supplied
Name of the graph that the token will be valid for.
Users can use either secret or their username and password to generate a token. If the user does not supply a secret and chooses to use their username and password instead, then the parameter graph becomes required.
Request a token (POST)
POST /requesttoken
If authentication is enabled on RESTPP endpoints, a token needs to be included in the request header for all requests sent to the RESTPP server. A user can generate a token using either
A secret, which is a random string generated in GSQL (see Managing User Privileges and Authentication)
Their username and password in their request header as well as specifying the graph
You may also use a GET request to generate your token, see Request a token (GET).
Sample requests
Request
Response
1
curl -d <path_to_secret> -X POST \
2
"http://localhost:9000/requesttoken?lifetime=1000000"
Copied!
1
{
2
  "code": "REST-0000",
3
  "expiration": 0,
4
  "error": false,
5
  "message": "Refresh token successfully.",
6
  "token": "tohvf6khjqju8jf0r0l1cohhlm8gi5fq"
7
}
Copied!
Replace path_to_secret with the path to the file containing your secret. The file should only include a single line, which is your secret.
Request
Response
1
curl --user tigergraph:tigergraph \
2
-X POST '127.0.0.1:9000/requesttoken?graph=gsql_demo'
Copied!
1
{
2
    "error":false,
3
    "message":"Request token successfully.",
4
    "results":{"token":"o5pn931drmppjasi2vjidrlf6rp4n4po"}
5
}
Copied!
You can also use a username-password pair to generate a token. In this case, you must also specify the graph you want to generate the token for.
Parameters:
Name
Required
Description
lifetime
No
Period of time for which the token is valid in seconds. The default value is about 2.6 million (about a month).
graph
Yes if using username-password pair
The graph for which to generate token.
Refresh a token
PUT /requesttoken
This endpoint takes a token and its associated secret and refreshes the lifetime of the token. The token itself remains unchanged.
Parameters:
Name
Required
Description
token
Yes
Token to refresh.
secret
Yes
User's secret used to generate the token.
lifetime
Yes
Period of time for which the token is valid measured in seconds.
Sample request
1
curl -X PUT "http://localhost:9000/requesttoken?lifetime=15&secret=ksdoilrvpl0r0tef3d4abbpgu0t2u5la&token=0mq98l9pderkaivndf820gudg923p3l0"|jq .
2
{
3
  "code": "REST-0000",
4
  "expiration": 15,
5
  "error": false,
6
  "message": "Refresh token successfully.",
7
  "token": "0mq98l9pderkaivndf820gudg923p3l0"
8
}
Copied!
Delete a token
DELETE /requesttoken
This endpoint takes a token and its associated secret, and deletes the token.
Parameters:
Name
Required
Description
token
Yes
Token to delete.
secret
Yes
User's secret used to generate the token.
Loading jobs
Run a Loading Job
POST /ddl/{graph_name}
This endpoint is for loading data into a graph. It submits data as an HTTP request payload, to be loaded into the graph by the DDL Loader. The data payload can be formatted as generic CSV or JSON. For more details, please see GSQL Language Reference Part 1 - Defining Graphs and Loading Data.
If the loading job references multiple files, multiple HTTP requests are needed to complete the loading job since you can only provide data for one filename varibale at a time. The loading job will skip the LOAD statements referencing filename variables that the request didn't provide data for. To provide data for a filename variable, put the data in the request body and use the filename parameter (explained in the parameter table below) to match the variable name defined in the loading job.
If a LOAD statement is written using a filepath string instead of a file variable, even though the filepath is already provided in the loading job, you still need to provide data in the request body for the LOAD statement to run. Since there isn't a file variable in this case, use a position-based file identifier to identify the filepath string you are providing data for in the filename parameter.
Request body:
The request body is the data to be loaded (either in CSV or JSON format).
Curl allows you to read the data from an input file by using the @ symbol:
curl -X POST --data-binary @./company.csv "http://…"
Sample request:
In this example, the loading job is dependent on three filename variables (f1 and f3) and one filepath string. Therefore, three HTTP requests are needed to complete the loading job.
1
# Loading job
2
CREATE LOADING JOB load_data for GRAPH poc_graph {
3
​
4
    DEFINE FILENAME f1;
5
    DEFINE FILENAME f3;
6
    
7
    LOAD f1 to VERTEX person VALUES ($0, $0);
8
    LOAD "/home/data/company.csv" to VERTEX company VALUES ($0, $0);
9
​
10
    LOAD f3 to EDGE work_at VALUES ($0, $1, $3, $4, $5);
11
}
12
​
13
# Provide data for for the second LOAD statement 
14
curl -X POST --data-binary @./another_company.csv \
15
"http://localhost:9000/ddl/poc_graph?tag=load_data&filename=__GSQL_FILENAME_0__" | jq 
16
​
17
{
18
  "version": {
19
    "edition": "enterprise",
20
    "api": "v2",
21
    "schema": 0
22
  },
23
  "error": false,
24
  "message": "",
25
  "results": [
26
    {
27
      "sourceFileName": "Online_POST",
28
      "statistics": {
29
        "validLine": 7927,
30
        "rejectLine": 0,
31
        "failedConditionLine": 0,
32
        "notEnoughToken": 0,
33
        "invalidJson": 0,
34
        "oversizeToken": 0,
35
        "vertex": [
36
          {
37
            "typeName": "company",
38
            "validObject": 7,
39
            "noIdFound": 0,
40
            "invalidAttribute": 0,
41
            "invalidPrimaryId": 0,
42
            "invalidSecondaryId": 0,
43
            "incorrectFixedBinaryLength": 0
44
          }
45
        ],
46
        "edge": [],
47
        "deleteVertex": [],
48
        "deleteEdge": []
49
      }
50
    }
51
  ],
52
  "code": "REST-0000"
53
}
54
​
55
# Provide data for filename f1 for the first LOAD statement
56
curl -X POST --data-binary @./person.csv \
57
"http://localhost:9000/ddl/poc_graph?tag=load_data&filename=f1"
58
​
59
# Provide data for filename f3 for the third LOAD statement
60
curl -X POST --data-binary @./work_at.csv \
61
"http://localhost:9000/ddl/poc_graph?tag=load_data&filename=f3"
Copied!
Parameters:
Name
Required
Description
tag
Yes
Loading job name defined in your DDL loading job
filename
Yes
File variable name or file path for the file containing the data
sep
No
Separator of CSV data. If your data is JSON, you do not need to specify this parameter. The default separator is a comma","
eol
No
End-of-line character. Only one or two characters are allowed, except for the special case "\r\n". The default value is "\n"
ack
No
"all": request will return after all GPE instances have acknowledged the POST request.
"none": request will return immediately after RESTPP processed the POST request.
timeout
No
Timeout in seconds. If set to 0, use system-wide endpoint timeout setting.
concise
No
Boolean value that indicates whether to return concise results of the data loading request. Concise results will only include the number of vertices and edges added or deleted, and will omit information such as the number of valid and invalid lines in the default response.
If there are special characters in your parameter values, the special characters should use URL encoding. To avoid confusion about whether you should you one or two backslashes, we do not support backslash escapes for the eol or sep parameter.
The maximum size of data you can upload via this endpoint is controlled by the Nginx.ClientMaxBodySize configuration parameter (default is 200 MB).
Graphs
Run built-in functions on graph
POST /builtins/{graph_name}
This endpoint runs a set of built-in functions and returns relevant statistics about a graph.
Request body:
This endpoint expects a data payload in the request body that specifies which function to run on the graph. Depending on the function being run, different fields may also be expected in the request body.
Here is a list of functions supported by this endpoint and their corresponding data payload format.
stat_vertex_attr
Returns the minimum, maximum, and average values of the given vertex type's int, uint, float and double attributes, and the count of true and false of a boolean attribute.
Data payload fields:
"function": "stat_vertex_attr": This specifies that the function to run isstat_vertex_attr.
"type": The vertex type whose attribute values to report on. Required field. It also accepts the value * (wild card), in which case, all vertex types are included.
stat_edge_attr
Returns the minimum, maximum, and average values of the given edge type's int, uint, float and double attributes, and the count of true and false of a boolean attribute.
Data payload fields:
"function": stat_edge_attr
"type": The edge type whose attribute values to report on. Required field. It also accepts the value * , in which case all edge types are included.
"from_type": Optional. The source vertex type of the edges to report on.
"to_type": Optional. The target vertex type of the edges to report on.
stat_vertex_number
Returns the number of vertices of the given vertex type.
Data payload fields:
"function": "stat_vertex_number"
"type": Required field. The vertex type of the vertices to count. It also accepts the value * (wild card), in which case, all vertex types are included.
stat_edge_number
Returns the number of edges of the given edge type
Data payload fields:
"function": "stat_edge_number"
"type": Required field. The edge type of the edges to count. It also accepts the value * , in which case all edge types are included.
"from_type": Optional. The source vertex type of the edges to report on.
"to_type": Optional. The target vertex type of the edges to report on.
Sample requests:
Below is an example request running stat_vertex_attr on socialNet and its output. The vertex type "Person" has a uint attribute "age".
1
curl -X POST "http://localhost:9000/builtins/socialNet" \
2
-d  '{"function":"stat_vertex_attr","type":"Person"}' | jq .
3
​
4
{
5
  "version": {
6
      "api": "v2",
7
      "schema": 0
8
   },
9
  "error": false,
10
  "message": "",
11
  "results": [
12
    {
13
      "vertexName": "Person",
14
      "attributeStat": [
15
        {
16
          "vattrName": "age",
17
          "MAX": 64,
18
          "MIN": 15,
19
          "AVG": 36.5
20
        }
21
      ]
22
    }
23
  ]
24
}
Copied!
Here is an example request running stat_edge_attr on socialNet and its output. The edge type "Liked" has a float attribute "strength".
1
curl -X POST "http://localhost:9000/builtins/socialNet" \
2
-d  '{"function":"stat_edge_attr","type":"Liked", "from_type":"*", "to_type":"*"}' | jq .
3
​
4
{
5
  "version": {
6
    "api": "v2",
7
    "schema": 0
8
  },
9
  "error": false,
10
  "message": "",
11
  "results": [
12
    {
13
      "e_type": "Liked",
14
      "attributes": {
15
        "weight": {
16
          "MAX": 2.5,
17
          "MIN": 1,
18
          "AVG": 1.375
19
        }
20
      }
21
    }
22
  ]
23
}
Copied!
Here is an example request running stat_vertex_number and its output.
1
curl -X POST "http://localhost:9000/builtins/socialNet" \
2
-d  '{"function":"stat_vertex_number","type":"*"}' | jq .
3
​
4
{
5
  "version": {
6
    "api": "v2",
7
    "schema": 0
8
  },
9
  "error": false,
10
  "message": "",
11
  "results": [
12
    {
13
      "v_type": "User",
14
      "count": 4
15
    },
16
    {
17
      "v_type": "Page",
18
      "count": 4
19
    },
20
    {
21
      "v_type": "Product",
22
      "count": 7
23
    },
24
    {
25
      "v_type": "DescWord",
26
      "count": 7
27
    },
28
    {
29
      "v_type": "NameUser",
30
      "count": 9
31
    },
32
    {
33
      "v_type": "VidUser",
34
      "count": 4
35
    },
36
    {
37
      "v_type": "Video",
38
      "count": 5
39
    },
40
    {
41
      "v_type": "AttributeTag",
42
      "count": 4
43
    }
44
  ]
45
}
Copied!
Parameters:
No parameters.
Show graph schema metadata
GET /gsqlserver/gsql/schema
Returns schema details about a vertex type, an edge type, or the entire graph schema. This is a GSQL Server request sent to port 14240, and authentication credentials need to be provided.
Sample request:
1
$ curl -u tigergraph:tigergraph \
2
"localhost:14240/gsqlserver/gsql/schema?graph=workNet&type=company"
3
​
4
{
5
  "error": false,
6
  "message": "",
7
  "results": {
8
    "Config": {
9
      "STATS": "OUTDEGREE_BY_EDGETYPE",
10
      "PRIMARY_ID_AS_ATTRIBUTE": false
11
    },
12
    "Attributes": [
13
      {
14
        "AttributeType": {
15
          "Name": "STRING"
16
        },
17
        "IsPartOfCompositeKey": false,
18
        "PrimaryIdAsAttribute": false,
19
        "AttributeName": "id",
20
        "HasIndex": false,
21
        "IsPrimaryKey": false
22
      },
23
      {
24
        "AttributeType": {
25
          "Name": "STRING"
26
        },
27
        "IsPartOfCompositeKey": false,
28
        "PrimaryIdAsAttribute": false,
29
        "AttributeName": "country",
30
        "HasIndex": false,
31
        "IsPrimaryKey": false
32
      }
33
    ],
34
    "PrimaryId": {
35
      "AttributeType": {
36
        "Name": "STRING"
37
      },
38
      "IsPartOfCompositeKey": false,
39
      "PrimaryIdAsAttribute": false,
40
      "AttributeName": "clientId",
41
      "HasIndex": false,
42
      "IsPrimaryKey": false
43
    },
44
    "Name": "company"
45
  }
46
}
Copied!
Vertex schema object** fields:**
Name: the vertex type name, same as the input parameter "type"
PrimaryId: details about the primary id
Attributes: details about each attribute, listed in order
Config: details about global properties of the vertex type
**Edge schema object **fields:
Name: the edge type name, same as the input parameter "type"
FromVertexTypeName: source vertex type name
ToVertexTypeName: target vertex type name
Attributes: details about each attribute, listed in order
IsDirected: whether the edge is directed
Config: additional details about global properties of the edge type
Graph schema object** fields:**
GraphName: the graph name, same as the input parameter "graph"
VertexTypes: an array of vertex schema objects. Each vertex schema object is exactly the JSON output if that specific vertex type had been specified.
EdgeTypes: an array of edge schema objects. Each edge schema object is exactly the JSON output if that specific edge type had been specified.
1
{
2
  "error": false,
3
  "message": "",
4
  "results": {
5
    "GraphName": "workNet",