Built-in Endpoints

System Utilities

Echo

GET /echo and POST /echo

These endpoints are simple diagnostic utilities, which respond with the following message if the RESTPP server is up and running.

Sample request:

GET echo/ Request and Response
GET echo/ Request and Response
curl -X GET "http://localhost:9000/echo"
{
"error": false,
"message": "Hello GSQL"
}

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:

$ curl 'http://localhost:14240/api/ping'
{
"error": "false",
"message": "pong",
"results": {}
}

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
Example: Report on all built-in endpoints
curl -X GET "http://localhost:9000/endpoints?builtin=true" | jq .

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
Subset of GET /endpoints output
"GET /echo": null,
"GET /endpoints": {
"parameters": {
"builtin": {
"default": "false",
"max_count": 1,
"min_count": 0,
"type": "BOOL"
},
"dynamic": {
"default": "false",
"max_count": 1,
"min_count": 0,
"type": "BOOL"
},
"static": {
"default": "false",
"max_count": 1,
"min_count": 0,
"type": "BOOL"
}
}
}

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:

curl -X GET "http://localhost:9000/version"
{"error":"false", "message":"TigerGraph RESTPP:
--- Version ---
product release_2.6.0_05-09-2020 ab1e3d0da6237c27468d6cabb90900119d63759d 2020-04-15 15:46:29 -0700
olgp release_2.6.0_05-09-2020 046c745088106b69920b9bdb3bd15969de409e92 2020-05-01 19:10:27 -0700
topology release_2.6.0_05-09-2020 c028af100117f2051b619436c3aa4febc810bf36 2020-04-22 08:44:07 -0700
gpe release_2.6.0_05-09-2020 34b9e86ef7b5fdaa106637e7db1d8a9e080a0aa2 2020-04-19 09:42:59 -0700
gse release_2.6.0_05-09-2020 ed2c2351357aa9077fa4dee7ea7a01f8ad2f7585 2020-05-11 01:18:54 -0700
third_party release_2.6.0_05-09-2020 4bce6990bae5be2b91e9201693ceb66341d3f204 2020-04-19 09:42:56 -0700
utility release_2.6.0_05-09-2020 2ce197d3edb3557bdd66ed1a4194309908d6197e 2020-04-20 21:19:34 -0700
realtime release_2.6.0_05-09-2020 52a82b454437c73b47d846acd5803ab0d9f54a45 2020-04-22 08:44:11 -0700
er release_2.6.0_05-09-2020 a3e6cb7606fb74984c75cae9bbd4d2112fdbf73a 2020-05-01 19:10:33 -0700
gle release_2.6.0_05-09-2020 d8bdbd1cf346e181aa9a317c704dd7b3b11b4658 2020-05-06 00:51:04 -0700
bigtest release_2.6.0_05-09-2020 2f64c47b7a5ac1834ead9a22eef8d42241117853 2019-12-12 01:31:35 -0800
document release_2.6.0_05-09-2020 6327094bd76b2dbc8f4625108d547827344b5091 2019-12-13 16:30:13 -0800
glive release_2.6.0_05-09-2020 93f61ea06fe42759c808fc58ff6245c9954d5447 2020-02-05 22:40:24 -0800
gap release_2.6.0_05-09-2020 e798efb595545bf91c449034566857c41f52449a 2020-04-29 22:47:26 -0700
gst release_2.6.0_05-09-2020 1b695c02f277efad0ddfb2deab710ae0158409da 2020-04-29 22:47:32 -0700
gus release_2.6.0_05-09-2020 eee784502b5387844e462305bae419954784da6f 2020-04-29 22:47:20 -0700
blue_features release_2.6.0_05-09-2020 5d7a4e8d806519f529274b331496d3bc78f01990 2020-04-15 15:46:38 -0700
blue_commons release_2.6.0_05-09-2020 432763afc49bf986aed4731e50254243d3665bc3 2019-07-30 03:34:46 -0700
"}

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:

$ curl -X GET
"https://crunch.i.tgcloud.io:14240/ts3/api/datapoints?from=1618957536&to=1619023346&what=cpu"
# Three data points returned
[
{
"detail": 0, # GPE is using 0 percent CPU
"when": 1619023346,
"where": "m1",
"who": "GPE_1#1",
"what": "cpu"
},
{
"detail": 0,
"when": 1619023346,
"where": "m1",
"who": "GSE_1#1",
"what": "cpu"
},
{
"detail": 0,
"when": 1619023346,
"where": "m1",
"who": "RESTPP#1",
"what": "cpu"
}
]

In the below example, the request asks for the 10 latest data points regarding memory usage:

$ curl -X GET
"https://crunch.i.tgcloud.io:14240/ts3/api/datapoints?what=mem&latest=10"
[
{
"detail": 159,
"when": 1620076473,
"where": "m1",
"who": "RESTPP#1",
"what": "mem"
},
{
"detail": 211,
"when": 1620076533,
"where": "m1",
"who": "GPE_1#1",
"what": "mem"
},
{
"detail": 436,
"when": 1620076533,
"where": "m1",
"who": "GSE_1#1",
"what": "mem"
},
{
"detail": 159,
"when": 1620076533,
"where": "m1",
"who": "RESTPP#1",
"what": "mem"
},
{
"detail": 211,
"when": 1620076593,
"where": "m1",
"who": "GPE_1#1",
"what": "mem"
},
{
"detail": 436,
"when": 1620076593,
"where": "m1",
"who": "GSE_1#1",
"what": "mem"
},
{
"detail": 159,
"when": 1620076593,
"where": "m1",
"who": "RESTPP#1",
"what": "mem"
},
{
"detail": 210,
"when": 1620076653,
"where": "m1",
"who": "GPE_1#1",
"what": "mem"
},
{
"detail": 436,
"when": 1620076653,
"where": "m1",
"who": "GSE_1#1",
"what": "mem"
},
{
"detail": 159,
"when": 1620076653,
"where": "m1",
"who": "RESTPP#1",
"what": "mem"
}
]

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:

# The example shows two endpoints (/graph/vertex and
# /statistics) called during the past 60 seconds.
curl -X GET "http://localhost:9000/statistics/poc_graph?seconds=60" | jq '.'
{
"GET /graph/vertices/{vertex_type}/{vertex_id}": {
"CompletedRequests": 8,
"QPS": 0.08,
"TimeoutRequests": 0,
"AverageLatency": 130,
"MaxLatency": 133,
"MinLatency": 128,
"LatencyPercentile": [
200,
200,
200,
200,
200,
200,
200,
200,
200,
200
]
},
"GET /statistics": {
"CompletedRequests": 4226,
"QPS": 42.26,
"TimeoutRequests": 0,
"AverageLatency": 2,
"MaxLatency": 125,
"MinLatency": 0,
"LatencyPercentile": [
10,
10,
10,
10,
10,
10,
10,
10,
10,
200
]
}
}

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:

$ curl -X GET 'http://localhost:9000/rebuildnow/social'
# JSON response
{
"version": {
"edition": "enterprise",
"api": "v2",
"schema": 0
},
"error": false,
"message": "RebuildNow finished, please check details in the folder: /tmp/rebuildnow",
"results": [],
"code": "REST-0000"
}
# Example summary file
$ cat finished.summary.txt
[SELECTED] Segment id: 106, vertextype: 0, vertexsubtypeid: 0, vertexcount: 187732, edgecount: 563196, deletevertexcount: 0, postqueue_pos: 16344, transaction id: 16344, rebuild ts: 1573106412990
[SKIPPED] Segment id: 6, vertextype: 0, vertexsubtypeid: 0, vertexcount: 85732, edgecount: 3106, deletevertexcount: 0, postqueue_pos: 16344, transaction id: 16344, rebuild ts: 1573106412900

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:

# Passing check performed on a single-node database
$ curl -X GET "http://localhost:9000/deleted_vertex_check?threadnum=10&verbose=0" |jq .
{
"version": {
"edition": "enterprise",
"api": "v2",
"schema": 0
},
"error": false,
"message": "check passed",
"results": [
{
"GPE": "GPE_1_1",
"PassCheck": true,
"UnSyncList": []
}
],
"code": "REST-0000"
}
# Failed check performed on a distributed cluster
$ curl -X GET 'http://localhost:9000/deleted_vertex_check?threadnum=10&verbose=0&vertextype=region' |jq .
{
"version": {
"edition": "enterprise",
"api": "v2",
"schema": 0
},
"error": false,
"message": "check failed",
"results": [
{
"GPE": "GPE_2_1",
"PassCheck": false,
"UnSyncList": [
{
"Segid": 193,
"IsRemote": false,
"VertexType": "region",
"GPEDelHash": 7013042118817697000,
"IDSDelHash": 202375168
}
]
},
{
"GPE": "GPE_3_1",
"PassCheck": false,
"UnSyncList": [
{
"Segid": 193,
"IsRemote": true,
"VertexType": "region",
"GPEDelHash": 7013042118817697000,
"IDSDelHash": 202375168
}
]
},
{
"GPE": "GPE_1_1",
"PassCheck": false,
"UnSyncList": [
{
"Segid": 193,
"IsRemote": true,
"VertexType": "region",
"GPEDelHash": 7013042118817697000,
"IDSDelHash": 202375168
}
]
}
],
"code": "REST-0000"
}

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 (Available only in V3.1.4 and later.

You can also use a POST request to request a token, see Request a token (POST).

Sample request:

curl -X GET "http://localhost:9000/requesttoken?secret=jiokmfqqfu2f95qs6ug85o89rpkneib3&lifetime=1000000"
{
"code": "REST-0000",
"expiration": 1616042814,
"error": false,
"message": "Generate new token successfully.",
"token": "tohvf6khjqju8jf0r0l1cohhlm8gi5fq"
}
curl --user example_user:example_password -X GET "localhost:9000/requesttoken?graph=example_graph"

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.

For TigerGraph versions before 3.1.4, the parameter secret is required and is the only way to generate a token to use with RESTPP. After TigerGraph 3.1.4, 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 (Available only in V3.1.4 and later.

You can also use a GET request to request a token, see Request a token (GET).

Sample requests

Request
Response
Request
curl -d <path_to_secret> -X POST \
"http://localhost:9000/requesttoken?lifetime=1000000"
Response
{
"code": "REST-0000",
"expiration": 0,
"error": false,
"message": "Refresh token successfully.",
"token": "tohvf6khjqju8jf0r0l1cohhlm8gi5fq"
}

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
Request
curl --user tigergraph:tigergraph \
-X POST '127.0.0.1:9000/requesttoken?graph=gsql_demo'
Response
{
"error":false,
"message":"Request token successfully.",
"results":{"token":"o5pn931drmppjasi2vjidrlf6rp4n4po"}
}

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. This feature is only available in TigerGraph v3.1.4 or later.

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 using username-password pair

Name of the graph that the token will be valid for.

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

curl -X PUT "http://localhost:9000/requesttoken?lifetime=15&secret=ksdoilrvpl0r0tef3d4abbpgu0t2u5la&token=0mq98l9pderkaivndf820gudg923p3l0"|jq .
{
"code": "REST-0000",
"expiration": 15,
"error": false,
"message": "Refresh token successfully.",
"token": "0mq98l9pderkaivndf820gudg923p3l0"
}

Known bug: The output shows the lifetime instead of the expiration time.

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.

# Loading job
CREATE LOADING JOB load_data for GRAPH poc_graph {
DEFINE FILENAME f1;
DEFINE FILENAME f3;
LOAD f1 to VERTEX person VALUES ($0, $0);
LOAD "/home/data/company.csv" to VERTEX company VALUES ($0, $0);
LOAD f3 to EDGE work_at VALUES ($0, $1, $3, $4, $5);
}
# Provide data for for the second LOAD statement
curl -X POST --data-binary @./another_company.csv \
"http://localhost:9000/ddl/poc_graph?tag=load_data&filename=__GSQL_FILENAME_0__" | jq
{
"version": {
"edition": "enterprise",
"api": "v2",
"schema": 0
},
"error": false,
"message": "",
"results": [
{
"sourceFileName": "Online_POST",
"statistics": {
"validLine": 7927,
"rejectLine": 0,
"failedConditionLine": 0,
"notEnoughToken": 0,
"invalidJson": 0,
"oversizeToken": 0,
"vertex": [
{
"typeName": "company",
"validObject": 7,
"noIdFound": 0,
"invalidAttribute": 0,
"invalidPrimaryId": 0,
"invalidSecondaryId": 0,
"incorrectFixedBinaryLength": 0
}
],
"edge": [],
"deleteVertex": [],
"deleteEdge": []
}
}
],
"code": "REST-0000"
}
# Provide data for filename f1 for the first LOAD statement
curl -X POST --data-binary @./person.csv \
"http://localhost:9000/ddl/poc_graph?tag=load_data&filename=f1"
# Provide data for filename f3 for the third LOAD statement
curl -X POST --data-binary @./work_at.csv \
"http://localhost:9000/ddl/poc_graph?tag=load_data&filename=f3"

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

curl -X POST "http://localhost:9000/builtins/socialNet" \
-d '{"function":"stat_vertex_attr","type":"Person"}' | jq .
{
"version": {
"api": "v2",
"schema": 0
},
"error": false,
"message": "",
"results": [
{
"vertexName": "Person",
"attributeStat": [
{
"vattrName": "age",
"MAX": 64,
"MIN": 15,
"AVG": 36.5
}
]
}
]
}

Here is an example request running stat_edge_attr on socialNet and its output. The edge type "Liked" has a float attribute "strength".

curl -X POST "http://localhost:9000/builtins/socialNet" \
-d '{"function":"stat_edge_attr","type":"Liked", "from_type":"*", "to_type":"*"}' | jq .
{
"version": {
"api": "v2",
"schema": 0
},
"error": false,
"message": "",
"results": [
{
"e_type": "Liked",
"attributes": {
"weight": {
"MAX": 2.5,
"MIN": 1,
"AVG": 1.375
}
}
}
]
}

Here is an example request running stat_vertex_number and its output.

curl -X POST "http://localhost:9000/builtins/socialNet" \
-d '{"function":"stat_vertex_number","type":"*"}' | jq .
{
"version": {
"api": "v2",
"schema": 0
},
"error": false,
"message": "",
"results": [
{
"v_type": "User",
"count": 4
},
{
"v_type": "Page",
"count": 4
},
{
"v_type": "Product",
"count": 7
},
{
"v_type": "DescWord",
"count": 7
},
{
"v_type": "NameUser",
"count": 9
},
{
"v_type": "VidUser",
"count": 4
},
{
"v_type": "Video",
"count": 5
},
{
"v_type": "AttributeTag",
"count": 4
}
]
}

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:

$ curl -u tigergraph:tigergraph \
"localhost:14240/gsqlserver/gsql/schema?graph=workNet&type=company"
{
"error": false,
"message": "",
"results": {
"Config": {
"STATS": "OUTDEGREE_BY_EDGETYPE",
"PRIMARY_ID_AS_ATTRIBUTE": false
},
"Attributes": [
{
"AttributeType": {
"Name": "STRING"
},
"IsPartOfCompositeKey": false,
"PrimaryIdAsAttribute": false,
"AttributeName": "id",
"HasIndex": false,
"IsPrimaryKey": false
},
{
"AttributeType": {
"Name": "STRING"
},
"IsPartOfCompositeKey": false,
"PrimaryIdAsAttribute": false,
"AttributeName": "country",
"HasIndex": false,
"IsPrimaryKey": false
}
],
"PrimaryId": {
"AttributeType": {
"Name": "STRING"
},
"IsPartOfCompositeKey": false,
"PrimaryIdAsAttribute": false,
"AttributeName": "clientId",
"HasIndex": false,
"IsPrimaryKey": false
},
"Name": "company"
}
}

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.

{
"error": false,
"message": "",
"results": {
"GraphName": "workNet",
"VertexTypes": [
{
"Config": {...},
"Attributes": [...],
"PrimaryId": {...},
"Name": "person"},
{
"Config": {...},
"Attributes": [...],
"PrimaryId": {...},
"Name": "company"}
],
"EdgeTypes": [
{
"IsDirected": false,
"ToVertexTypeName": "company",
"Config": {},
"Attributes": [...],
"FromVertexTypeName": "person",
"Name": "worksFor"
}
]
}
}

Parameters:

Name

Required

Description

graph

Yes

The name of the graph whose schema to retrieve.

type

No

The vertex or edge type whose details to retrieve. If not provided, the endpoint will provide a graph schema object containing the schema details of the entire graph.

Upsert data to graph

POST /graph/{graph_name}

This endpoint upserts vertices and/or edges into a graph. To upsert means that if a vertex or edge does not exist, it is inserted, and if it does exist, it is updated.

Parameters:

Name

Required

Description

ack

No

The value of this parameter can either be "all" or "none".

"all": request will return after all GPE instances have acknowledged the POST "none": request will return immediately after RESTPP processed the POST.

new_vertex_only

No

Boolean value that indicates whether or not to update existing vertices. If the value is true, it will only insert new vertices and not update existing ones.

vertex_must_exist

No

Boolean value that indicates whether or not to insert new edges when the FROM or TO vertices don't exist. If the value is true, the request will only insert edge if both the FROM and TO vertices of the edge already exist. If the value is false, the request will always insert new edges, and create the necessary vertices with default values for their attributes.

The response is the number of vertices and edges that were accepted. The API uses JSON format to describe the vertices and edges to be upserted. The JSON code can be stored in a text file or specified directly in a command line. There is a maximum size for a POST data payload (see the Size Limits section). The JSON format for describing a vertex set or edge set is summarized below.

Request body:

The payload data should be in JSON according to the schema shown below:

Request body schema
Request body schema
"vertices": {
"<vertex_type>": {
"<vertex_id>": {
"<attribute>": {
"value": <value>,
"op": <opcode>
}
}
}
},
"edges": {
"<source_vertex_type>": {
"<source_vertex_id>": {
"<edge_type>": {
"<target_vertex_type>": {
"<target_vertex_id>": {
"<attribute>": {
"value": <value>,
"op": <opcode>
}
}
}
}
}
}
}

The fields in angle brackets (<>) are placeholder names or values, to be replaced with actual values. The keys in angle brackets, such as <vertex_type>, can be repeated to form a list of items. The keys which are not in angle brackets are exact texts that must be used as they are. The nested hierarchy means that vertices are grouped by type. Edges, on the other hand, are first grouped by source vertex type, then vertex ID, then edge type.

The first example below shows two User vertices having an attribute called age:

Upsert Example Data 1: Two User vertices
Upsert Example Data 1: Two User vertices
{
"vertices": {
"User": {
"id6": {
"age": {
"value": 30
}
},
"id1": {
"age": {
"value": 22
}
}
}
}
}

The second example starts with one User vertex. If id6 already exists, it is not changed. If it doesn't yet exist, it is created with default attribute values. Then two edges are created: a Liked edge from id1 to id6, and then a Liked_By edge from id6 to id1.

Upsert Example Data 2: add_id6.json
Upsert Example Data 2: add_id6.json
{
"vertices": {
"User": {
"id6": {
}
}
},
"edges": {
"User":{
"id1": {
"Liked": {
"User": {
"id6" : {
"weight" : {
"value": 5.0
}
}
}
}
},
"id6": {
"Liked_By": {
"User": {
"id1" : {
"weight" : {
"value": 1.0
}
}
}
}
}
}
}
}

Follow the instructions in the Introduction section to format advanced data types. For example, the following payload is used to upsert two User vertices with an attribute coordinates of type LIST and an attribute measurements of type MAP:

{
"vertices": {
"User": {
"id4": {
"coordinates": {
"value": [51.3345, -7.2233]
},
"measurements": {
"value": {
"keyList": ["chest", "waist", "hip"]
"valueList": [35, 30, 35]
}
}
},
"id5": {
"coordinates": {
"value": [31.3245, -17.3292]
},
"measurements": {
"value": {
"keyList": ["chest", "waist", "hip"]
"valueList": [39, 35, 41]
}
}
}
}
}
}

Operation codes

Each attribute value may be accompanied by an operation (op) code, which provides very sophisticated schemes for data update or insertion:

Type

op

Meaning

1

"ignore_if_exists" or "~"

If the vertex/edge does not exist, use the payload value to initialize the attribute; but if the vertex/edge already exists, do not change this attribute.

2

"add" or "+"

Add the payload value to the existing value.

3

"and" or "&"

Update to the logical AND of the payload value and the existing value.

4

"or" or "|"

Update to the logical OR of the payload value and the existing value.

5

"max" or ">"

Update to the higher value between the payload value and the existing value.

6

"min" or "<"

Update to the lower value between the payload value and the existing value.

If an attribute is not given in the payload, the attribute stays unchanged if the vertex/edge already exists, or if the vertex/edge does not exist, a new vertex/edge is created and assigned the default value for that data type. The default value is 0 for int/uint, 0.0 for float/double, and ""(empty string) for string.

Invalid data types cause the request to be rejected

The RESTPP server validates the request before updating the values. The following schema violations will cause the entire request to fail and no change will be made to a graph:

  • For vertex upsert:

  1. Invalid vertex type.

  2. Invalid attribute data type.

  • For edge upsert:

  1. Invalid source vertex type.

  2. Invalid edge type.

  3. Invalid target vertex type.

  4. Invalid attribute data type.

If an invalid attribute name is given, it is ignored.

Output response

The response is the number of vertices and edges that were accepted. Additionally, if new_vertex_only is true, the response will include two more fields:

  • skipped_vertices: the number of vertices in the input data which already existed in the graph

  • vertices_already_exist: the id and type of the input vertices which were skipped

If vertex_must_exist is true, the response will include two more fields:

  • skipped_edges: the number of edges in the input data rejected because of missing endpoint vertices

  • miss_vertices: the id and type of the endpoint vertices which were missing

The example file add_id6.json (shown in the Request Body section) upserts one User vertex with id = "id6", one Liked edge, and one Liked_By edge. The Liked edge is from "id1 " to "id6"; the Liked_By edge is from "id6" to "id1".

The following example submits an upsert request by using the payload data stored in add_id6.json.

$ curl -X POST --data-binary @add_id6.json \
"http://localhost:9000/graph"
{"accepted_vertices":1,"accepted_edges":2}

Vertices

To support multiple graphs within one system, the graph data REST endpoint URLs include an optional graph name.

List vertices

GET /graph/{graph_name}/vertices/{vertex_type}

This endpoint returns all vertices having the type vertex_type in a graph.

Sample request:

curl -X GET "http://localhost:9000/graph/socialNet/vertices/User"
{
"version": {
"api": "v2",
"schema": 0
},
"error": false,
"message": "",
"results": [
{
"v_id": "id1",
"v_type": "User",
"attributes": {}
},
{
"v_id": "id2",
"v_type": "User",
"attributes": {}
}
// ... all vertices in graph socialNet of type User
]
}

Parameters

Name

Required

Description

count_only

No

Takes a boolean value. If the value is true, the results field will only contain the count of how many vertices were selected. Default is false.

select

No

Attributes of the selected vertices to return. The parameter takes a list, which is a string of comma-separated values, and will only return the attributes that are provided.

filter

No

Conditions used to filter the returned vertices. The parameter takes a list of conditions, which is a string of comma-separated values. If any filter conditions are provided, the endpoint will only return the vertices that satisfy the conditions. Six comparison operators are supported for this parameter: =, !=, >, >=, < and <=. If the value on the right side of an operator is a string literal, it should be enclosed in double-quotes.

limit

No

Integer value that specifies the total number of vertices to return

sort

No

Attributes to sort the results by. The parameter takes a list, which is a string of comma-separated values, and will sort the returned vertices based on the attributes provided in the list in order. Add "-" in front of the attribute to sort in descending order.

timeout

No

Integer that specifies the number of seconds after which the query will time out. If the parameter is set to 0 or isn't provided, the system-wide endpoint timeout setting is applied.

Retrieve a vertex

GET /graph/{graph_name}/vertices/{vertex_type}/{vertex_id}

This endpoint will return a single vertice by its vertex ID.

Sample request:

curl -X GET "http://localhost:9000/graph/socialNet/vertices/User/id1"
{
"version": {
"api": "v2",
"schema": 0
},
"error": false,
"message": "",
"results": [
{
"v_id": "id1",
"v_type": "User",
"attributes": {}
}
]
}

Parameters:

Name

Required

Description

select

No

Attributes of the selected vertices to return. The parameter takes a list, which is a string of comma-separated values, and will only return the attributes that are provided.

timeout

No

Integer that specifies the number of seconds after which the query will time out. If the parameter is set to 0 or isn't provided, the system-wide endpoint timeout setting is applied.

Insert vertices

To insert vertices or edges, use the Upsert data to graph endpoint.

Delete vertices

DELETE /graph/{graph_name}/vertices/{vertex_type}

This endpoint deletes vertices by their vertex type. The delete operation is a cascading deletion. If a vertex is deleted, then all of the edges connected to it are automatically deleted as well.

Sample request:

The response object will contain a "deleted_vertices" field that indicates the number of vertices that were deleted

curl -X DELETE "http://localhost:9000/graph/socialNet/vertices/User"
{
"version": {
"edition": "enterprise",
"api": "v2",
"schema": 0
},
"error": false,
"message": "",
"results": {
"v_type": "person",
"deleted_vertices": 3
}
}

Parameters:

Name

Required

Description

permanent

No

Takes a boolean value. If the value is true, the deleted vertex IDs can never be inserted back, unless the graph is dropped or the graph store is cleared.

filter

No

Conditions used to filter the vertices to delete. The parameter takes a list of conditions, which is a string of comma-separated values. If any filter conditions are provided, the endpoint will only delete the vertices that satisfy the conditions. Six comparison operators are supported for this parameter: =, !=, >, >=, < and <=. If the value on the right side of an operator is a string literal, it should be enclosed in double-quotes.

limit

No

Integer value that specifies the total number of vertices to delete.

sort

No

Attributes to sort the vertices by. In delete operations,sort should always be used together with limit. The endpoint will delete the number of vertices under the limit specified in the order specified. The parameter takes a list of attributes, and the endpoint will sort all vertices based on the attributes provided in the list in order. Add "-" in front of the attribute to sort by that attribute in descending order.

timeout

No

Integer that specifies the number of seconds after which the query will time out. If the parameter is set to 0 or isn't provided, the system-wide endpoint timeout setting is applied.

Delete vertices by type

DELETE /graph/{graph_name}/delete_by_type/vertices/{vertex_type}

This endpoint deletes all vertices of the given vertex type in a graph.

Sample request:

curl -X DELETE "http://localhost:9000/graph/poc_graph/delete_by_type/vertices/person"

Parameters:

Name

Required

Description

permanent

No

Takes a boolean value. If the value is true, the deleted vertex IDs can never be inserted back, unless the graph is dropped or the graph store is cleared.

ack

No

If the parameter is set to "none", the delete operation doesn't need to get acknowledgment from any GPE. If it is set to "all" (default), the operation needs to get acknowledgment from all GPEs.

Delete a vertex

DELETE /graph/{graph_name}/vertices/{vertex_type}/{vertex_id}

Sample request:

curl -X DELETE "http://localhost:9000/graph/socialNet/vertices/User/id1"
{
"version": {
"edition": "enterprise",
"api": "v2",
"schema": 0
},
"error": false,
"message": "",
"results": {
"v_type": "User",
"deleted_vertices": 1
}
}

Parameters:

Name

Required

Description

timeout

no

Integer that specifies the number of seconds after which the query will time out. If the parameter is set to 0 or isn't provided, the system-wide endpoint timeout setting is applied.

Edges

List edges of a vertex

GET /graph/{graph_name}/edges/{source_vertex_type}/{source_vertex_id}

This endpoint returns all edges which are connected to a given vertex ID in the graph

Sample request:

curl -X GET "http://localhost:9000/graph/socialNet/edges/VidUser/0?limit=2
{
"version": {
"api": "v2",
"schema": 0
},
"error": false,
"message": "",
"results": [
{
"e_type": "User_Video",
"directed": false,
"from_id": "0",
"from_type": "VidUser",
"to_id": "2",
"to_type": "Video",
"attributes": {
"rating": 5.2,
"date_time": 0
}
},
{
"e_type": "User_Video",
"directed": false,
"from_id": "0",
"from_type": "VidUser",
"to_id": "0",
"to_type": "Video",
"attributes": {
"rating": 6.8,
"date_time": 0
}
}
]
}

Parameters:

Name

Required

Description

count_only

No

Takes a boolean value. If the value is true, the results field will only contain the count of how many edges were selected. Default is false.

select

No

Attributes of the selected edges to return. The parameter takes a list, which is a string of comma-separated values. If select is provided, the edges returned will only show the attributes provided.

filter

No

Conditions used to filter the edges to return. The parameter takes a list of conditions, which is a string of comma-separated values. If any filter conditions are provided, the endpoint will only return the edges that satisfy the conditions. Six comparison operators are supported for this parameter: =, !=, >, >=, < and <=. If the value on the right side of an operator is a string literal, it should be enclosed in double-quotes.

limit

No

Integer value that specifies the maximum limit of the total number of edges to return.

sort

No

Attributes to sort the results by. The parameter takes a list, which is a string of comma-separated values, and will sort all the edges based on the attributes provided in the list in order. Add "-" in front of the attribute to sort in descending order.

timeout

No

Integer that specifies the number of seconds after which the query will time out. If the parameter is set to 0 or isn't provided, system-wide endpoint timeout setting is applied.

List edges of a vertex by edge type

GET /graph/{graph_name}/edges/{source_vertex_type}/{source_vertex_id}/{edge_type}

This endpoint lists all the edges of a specified type connected to a given vertex ID in the graph

Sample request:

curl -X GET "http://localhost:9000/graph/socialNet/edges/VidUser/0/User_Video?limit=2
{
"version": {
"api": "v2",
"schema": 0
},
"error": false,
"message": "",
"results": [
{
"e_type": "User_Video",
"directed": false,
"from_id": "0",
"from_type": "VidUser",
"to_id": "2",
"to_type": "Video",
"attributes": {
"rating": 5.2,
"date_time": 0
}
},
{
"e_type": "User_Video",
"directed": false,
"from_id": "0",
"from_type": "VidUser",
"to_id": "0",
"to_type": "Video",
"attributes": {
"rating": 6.8,
"date_time": 0
}
}
]
}

Parameters:

Name

Required

Description

count_only

No

Takes a boolean value. If the value is true, the results field will only contain the count of how many edges were selected. Default is false.

select

No

Attributes of the selected edges to return. The parameter takes a list, which is a string of comma-separated values. If select is provided, the edges returned will only show the attributes provided.

filter

No

Conditions used to filter the edges to return. The parameter takes a list of conditions, which is a string of comma-separated values. If any filter conditions are provided, the endpoint will only return the edges that satisfy the conditions. Six comparison operators are supported for this parameter: =, !=, >, >=, < and <=. If the value on the right side of an operator is a string literal, it should be enclosed in double quotes.

limit

No

Integer value that specifies the maximum limit of the total number of edges to return.

sort

No

Attributes to sort the results by. The parameter takes a list, which is a string of comma-separated values, and will sort all the edges based on the attributes provided in the list in order. Add "-" in front of the attribute to sort in descending order.

timeout

No

Integer that specifies the number of seconds after which the query will time out. If the parameter is set to 0 or isn't provided, system-wide endpoint timeout setting is applied.

List edges of a vertex by edge type and target type

GET /graph/{graph_name}/edges/{source_vertex_type}/{source_vertex_id}/{edge_type}/{target_vertex_type}

This endpoint lists edges connected to a given vertex by edge type and target vertex type

Use "_" for edge_type in the URL to permit any edge type.

Sample request:

curl -X GET "http://localhost:9000/graph/socialNet/edges/VidUser/0/User_Video/Video?limit=2
{
"version": {
"api": "v2",
"schema": 0
},
"error": false,
"message": "",
"results": [
{
"e_type": "User_Video",
"directed": false,
"from_id": "0",
"from_type": "VidUser",
"to_id": "2",
"to_type": "Video",
"attributes": {
"rating": 5.2,
"date_time": 0
}
},
{
"e_type": "User_Video",
"directed": false,
"from_id": "0",
"from_type": "VidUser",
"to_id": "0",
"to_type": "Video",
"attributes": {
"rating": 6.8,
"date_time": 0
}
}
]
}

Parameters:

Name

Required

Description

count_only

No

Takes a boolean value. If the value is true, the results field will only contain the count of how many edges were selected. Default is false.

not_wildcard

No

Boolean value that indicates whether or not "_" supplied in the endpoint URL is a wildcard. If the parameter is true, "_" is interpreted literally to select only edges with edge type name equal to underscore.

select

No

Attributes of the selected edges to return. The parameter takes a list, which is a string of comma-separated values. If select is provided, the edges returned will only show the attributes provided.

filter

No

Conditions used to filter the edges to return. The parameter takes a list of conditions, which is a string of comma-separated values. If any filter conditions are provided, the endpoint will only return the edges that satisfy the conditions. Six comparison operators are supported for this parameter: =, !=, >, >=, < and <=. If the value on the right side of an operator is a string literal, it should be enclosed in double-quotes.

limit

No

Integer value that specifies the maximum limit of the total number of edges to return.

sort

No

Attributes to sort the results by. The parameter takes a list, which is a string of comma-separated values, and will sort all the edges based on the attributes provided in the list in order. Add "-" in front of the attribute to sort in descending order.

timeout

No

Integer that specifies the number of seconds after which the query will time out. If the parameter is set to 0 or isn't provided, the system-wide endpoint timeout setting is applied.

Retrieve edge by source, target, and edge type

GET /graph/{graph_name}/edges/{source_vertex_type}/{source_vertex_id}/{edge_type}/{target_vertex_type}/{target_vertex_id}

This endpoint returns the edge of a specified type between a source vertex and a target vertex.

Sample request: