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.
POST /echo
has the same response as GET /echo
.
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".
GET /api/ping
No parameters.
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.
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:
GET /version
This endpoint returns the GIT versions of all components of the system.
This endpoint does not take any parameters.
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.
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:
In the below example, the request asks for the 10 latest data points regarding memory usage:
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.
The return object is a hash of the endpoints and their performance data:
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.
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.
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.
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.
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
).
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.
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).
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.
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.
PUT /requesttoken
This endpoint takes a token and its associated secret and refreshes the lifetime of the token. The token itself remains unchanged.
Parameters:
Known bug: For TigerGraph versions before 3.1.2, the output shows lifetime instead of the expiration time.
DELETE /requesttoken
This endpoint takes a token and its associated secret, and deletes the token.
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.
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://…"
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.
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).
POST /builtins/{graph_name}
This endpoint runs a set of built-in functions and returns relevant statistics about a graph.
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.
Below is an example request running stat_vertex_attr
on socialNet
and its output. The vertex type "Person"
has a uint
attribute "age"
.
Here is an example request running stat_edge_attr
on socialNet
and its output. The edge type "Liked"
has a float attribute "strength"
.
Here is an example request running stat_vertex_number
and its output.
No parameters.
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.
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.
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.
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.
The payload data should be in JSON according to the schema shown below:
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
:
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
.
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
:
Each attribute value may be accompanied by an operation (op) code, which provides very sophisticated schemes for data update or insertion:
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.
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:
Invalid vertex type.
Invalid attribute data type.
For edge upsert:
Invalid source vertex type.
Invalid edge type.
Invalid target vertex type.
Invalid attribute data type.
If an invalid attribute name is given, it is ignored.
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
.
To support multiple graphs within one system, the graph data REST endpoint URLs include an optional graph name.
GET /graph/{graph_name}/vertices/{vertex_type}
This endpoint returns all vertices having the type vertex_type
in a graph.
GET /graph/{graph_name}/vertices/{vertex_type}/{vertex_id}
This endpoint will return a single vertice by its vertex ID.
To insert vertices or edges, use the Upsert data to graph endpoint.
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.
The response object will contain a "deleted_vertices"
field that indicates the number of vertices that were deleted
DELETE /graph/{graph_name}/delete_by_type/vertices/{vertex_type}
This endpoint deletes all vertices of the given vertex type in a graph.
DELETE /graph/{graph_name}/vertices/{vertex_type}/{vertex_id}
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
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
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.
This endpoint returns the edge of a specified type between a source vertex and a target vertex.
To insert vertices or edges, use the Upsert data to graph endpoint.
Deletes an edge by its source vertex type and ID, target vertex type and ID, as well as edge type.
GET /gsqlserver/gsql/queryinfo
Returns metadata details about a query. In particular, it lists the input parameters and output PRINT
statement syntax. This endpoint exists on port 14240 and requests are sent to the GSQL server. Therefore, you should provide authentication credentials in the request.
The JSON response object contains three fields:
queryname
: name of the query, same as the query input parameter.
input
: unordered list of the input parameter names and data types.
output
: JSON object that follows the same structure of the query's output. For each key-value pair, the key is the name that appears in the query output, while the values are the data types of the output.
GET
)GET /query/{graph_name}/{query_name}
Each time a new TigerGraph query is installed, a dynamic endpoint is generated. This new endpoint enables the user to run the new TigerGraph query through HTTP requests and giving the parameters in URL or in a data payload. In the case of a GET
request, parameters should be passed in through the query string.
When using a GET
request to run an installed query, the query parameters are passed in through the query string of the URL.
To run query hello
on a graph named social
, and the query parameter is of type VERTEX<person>
whose ID is "Tom"
POST
)POST /query/{graph_name}/{query_name}
Users can also run queries through a POST
request, which allows them to pass query parameters in JSON. This is especially helpful when the query takes complex parameters.
When using a POST
request to run an installed query, the query parameters are passed in through the request body and encoded in JSON format.
The query in this request takes a parameter of type VERTEX<person>
:
Installed queries can run in Detached Mode. To do this, use the GSQL-ASYNC
header and set its value to true
. The results and status of the queries run in Detached Mode can be retrieved with a query ID, which is returned immediately when queries are executed in Detached Mode.
POST /gsqlserver/interpreted_query
This endpoint runs a GSQL query in Interpreted Mode. The query body should be supplied at the data payload, and the query's parameters are supplied as the URL's query string. This endpoint exists on the GSQL server on port 14240.
This request goes directly to the GSQL server (port 14240) instead of the RESTPP server (port 9000), so the username and password must be specified in the header. If you are using curl, you can use the -u
option as shown below.
The request body for this endpoint should be the entire INTERPRET QUERY
statement.
When running an interpreted query through this endpoint, the query parameters should be passed in through the URL query string.
GET /showprocesslist/{graph_name}
This endpoint reports statistics of running queries of a graph: the query's request ID, start time, expiration time, and the REST endpoint's URL.
No Parameters.
GET /abortquery/{graph_name}
This endpoint safely aborts a selected query by ID or all queries of an endpoint by endpoint URL of a graph.
GET /query_status
This endpoint allows you to check the status of a query run in detached mode.
If one or more of the provided query IDs (requestid
) are invalid, the return JSON will include anunknown_requestid
field containing all the invalid query IDs. If a query ID is marked as unknown, it means either the query does not exist or that it was not run in Detached Mode.
GET /query_result
This endpoint allows you to check the results of queries run in Detached Mode if they have finished running. If the query is still running, the endpoint will respond with an error and a message saying "Unable to retrieve result for query <requestid>"
. Ensure that the query is finished before checking its result.
The TigerGraph platform comes with two built-in endpoints, /shortestpath
and /allpaths
, which return either the shortest or all unweighted paths connecting a set of source vertices to a set of target vertices. The table below summarizes the two path-finding endpoints.
Each REST endpoint reads a JSON-formatted payload that describes the input parameters. These parameters specify which vertices and edges may be on the paths, additional conditions on the attributes of the vertices and edges, and the maximum length of a path.
Each endpoint must have either a source or sources key and either a target or targets parameter. The source and target parameters describe a single vertex. The format for a vertex object is as follows: {"type" : "<vertex_type_name>", "id" : "<vertex_id>"}.
The sources and targets parameters are JSON arrays containing a list of vertex objects.
Filters
The payload may also have an array of filter conditions, to restrict the vertices or edges in the paths. Each individual filter is a JSON object which describes a condition on one vertex type or edge type. A filter object has one or two key-value pairs: {"type": "<vertex_or_edge_type>", "condition": "<attribute_condition>"}
"type":
the vertex type or edge type to be filtered
"condition"
(optional): a boolean expression on one attribute of the given vertex type or edge type. "AND" and "OR" may be used to make compound expressions.
Example of a filter array:
Note that all filtering conditions in vertexFilters
and edgeFilters
are combined with the "OR"
relationship, i.e., if a vertex (or edge) fulfills any one of the filter conditions, then this vertex (or edge) will be included in the resulting paths.
The JSON output is a list of vertices and a list of edges. Each vertex and each edge is listed in full, with all attributes. The collections of vertices and edges are not in path order.
POST /shortestpath/{graph_name}
This endpoint takes a source vertex or a set of source vertices, a target vertex or a set of target vertices, and returns the shortest path between the source and the target. If the source is a set of vertices, the resulting path will begin with one of the vertices in the set. If the target is a set of vertices, the resulting path will end with one of the vertices in the set.
This endpoint expects a request body that describes the source and target vertex or vertex set. Below is a table of all the fields in the request body.
POST /allpaths/{graph_name}
This endpoint finds all paths between a source vertex (or vertex set) and target vertex (or vertex set).
This endpoint expects a request body that describes the source and target vertex or vertex set. Below is a table of all the fields in the request body.
The current implementation of this endpoint will include paths with loops. Since it is possible to go around a loop an infinite number of times, it is important that you select the smallest value of maxLength which you consider appropriate. Even if there are no loops in your graph, a smaller maxLength will allow your query to run faster.
The example below requests all paths between the source vertex set {Video 0} and the target vertex set {AttributeTag "action"}, up to maximum length 3. The path may only contain Video vertices where year >= 1984
. The result includes 3 paths:
AttrributeTag "action" -- Video 0
AttrributeTag "action" -- Video 3 -- VidUser 4 -- Video 0
AttrributeTag "action" -- Video 2 -- VidUser 0 -- Video 0
Other versions of pathfinding algorithms are available in the GSQL Graph Algorithm Library.
Name
Required
Description
sleep
No
Integer that indicates the number of seconds for which the response will be delayed.
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.
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
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.
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.
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
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.
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.
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.
Name
Required
Description
token
Yes
Token to delete.
secret
Yes
User's secret used to generate the token.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Name
Required
Description
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.
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.
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.
Name
Required
Description
graph
Yes
Name of the graph
query
Yes
Name of the query
Name
Required
Description
read_committed
No
Boolean value that indicates whether to use read-committed isolation level for the query. At the read committed level, it is guaranteed that any data read is committed at the moment it is read. By default, it is off.
Name
Required
Description
read_committed
No
Boolean value that indicates whether to use read-committed isolation level for the query. At the read committed level, it is guaranteed that any data read is committed at the moment it is read. By default, it is off.
Name
Required
Description
requestid
No
The ID of the query to abort. It can take a single query ID or the string "all"
. If requestid
is set to all. It will abort all running queries.
url
No
The endpoint whose running queries to abort. You must specify the base of the endpoint's URL, but then use a wildcard to allow for different parameters. For example, to abort all running queries for the endpoint /sleepgpe
, use url=/sleepgpe.*
Field
Description
url
URL of the given query.
status
The status of the given query. Possible values are “success”
, “timeout”
, “aborted”
, or “running”
.
startTime
The timestamp for the start time of the given query.
requestid
The query ID associated with the given query status JSON object.
expirationTime
The timestamp for when the given query times out. The default timeout limit is 16 seconds and can be set using theGSQL-TIMEOUT
header.
elapsedTime
Elapsed real time of the given query measured in milliseconds. For completed queries, the value shows the total runtime of the request. For ongoing queries, it shows the amount of time taken so far.
Name
Required
Description
graph_name
Yes
Name of the graph the query belongs to. Required parameter.
requestid
No
String ID of the query. It also accepts the value "all"
, in which case it will return a status report for every running query. When multiple requestid
are provided, it will return the status of all corresponding queries. If no requestid
is provided, or if the value of requestid
is "all"
, it will return the status of all queries that are currently running.
The output will contain one JSON object for each query.
Name
Required
Description
requestid
Yes
String ID of the query.
Key
Type
Description
source
vertex object
Each path must start from this vertex. Mutually exclusive with sources
.
sources
vertex array
Each path must start from one of these vertices. Mutually exclusive with source
.
target
vertex object
Each path must end at this vertex. Mutually exclusive with targets
.
targets
vertex array
Each path must end at one of these vertices. Mutually exclusive with target
.
vertexFilters
filter array
(OPTIONAL) Restrict the paths to those whose vertices satisfy any of the given filters.
edgeFilters
filter array
(OPTIONAL) Restrict the paths to those whose edges satisfy any of the given filters. See details of filters above.
Key
Required
Description
maxLength
No
Integer that specified the maximum length of a shortest path. The default value is 6.
allShortestPaths
No
If true, the endpoint will return all shortest paths between the source and target. Default is false, meaning that the endpoint will return only one path.
Key
Type
Description
source
vertex object
Each path must start from this vertex. Mutually exclusive with sources
.
sources
vertex array
Each path must start from one of these vertices. Mutually exclusive with source
.
target
vertex object
Each path must end at this vertex. Mutually exclusive with targets
.
targets
vertex array
Each path must end at one of these vertices. Mutually exclusive with target
.
vertexFilters
filter array
(OPTIONAL) Restrict the paths to those whose vertices satisfy any of the given filters.
edgeFilters
filter array
(OPTIONAL) Restrict the paths to those whose edges satisfy any of the given filters. See details of filters above.
Name
Required
Description
maxLength
Yes
Maximum path length.
The request
generates the following output, appropriately 400 lines long when formatted. In addition to listing each endpoint, the JSON output also lists all the required and optional parameters for each endpoint. In turn, each parameter is described by some or all of these attributes:
default
max_count
min_count
type
max_length
is_id
id_type
While this information alone is not sufficient for a full understanding of each endpoint, the descriptive names of parameters and the attribute values go a long way towards this goal.
The request method (GET
, POST
, PUT
, or DELETE
)
The endpoint address
Any required or optional request parameters in URL encoding
For POST
requests, a data payload (i.e., request body) in JSON encoding unless otherwise specified
In some cases, request header parameters
For requests that are sent to the GSQL server, the sender needs to provide TigerGraph user credentials for the request to be accepted. If authentication is enabled on the RESTPP server, a request token needs to be included in the request header as well.
In a test or development environment, the requester may be on the same server as REST++. In this case, the server IP is localhost.
TigerGraph's API endpoints accept parameters in URL encoding, which is straightforward in the case of string, number, and boolean values. However, some parameters are more complex and require specific formatting. The list below describes how to format the complex type parameter values when executing a query.
POST
requestsInput data for POST
requests should be in JSON format, unless the endpoint specifically accepts data in other formats. There are two ways to supply the data: inline or in a separate file.
The data should be formatted as a single string without linebreaks. If using curl, use the -d
option, followed by the JSON string.
The following example uses the POST /graph
endpoint to insert one User type vertex whose ID is "id6
" into the graph called "socialNet"
.
Often it will be more convenient for the input data to be in a separate file, especially if the data is large.
For curl, use --data-binary <path_to_file>
as in the example below:
If a vertex has a composite key composed of N attributes, then N values must be provided for the "id"
. The values can be presented either as a JSON object with N key-value pairs, or as a JSON array with a list of N values in the same order as defined in the schema.
The example below shows the two methods for a vertex v
having a composite primary key composed of the three attributes id
, name
, and label.
SET
or BAG
of Vertices To describe a SET
or BAG
of vertices in JSON, use a JSON array with vertex objects nested in the SET
or BAG
array.
All TigerGraph REST responses are in JSON format. The output JSON object has four fields: "version"
, "error"
, "message"
, and "result"
.
"version"
- this field describes the version of the running TigerGraph instance.
"error"
- a boolean value to indicate if there is an error in processing the request. If there is an error, the "error"
field will be true
.
"message"
- the error message when there is an error. If a request is successful, the field will be an empty string or a brief message conveying the result of the request.
Once REST++ authentication is enabled, a valid token should always be included in the HTTP header. If you are using curl to format and submit your REST++ requests, then use the following syntax:
Here is a sample request:
All requests made to the GSQL Server must be accompanied by your user credentials. You can use the curl -u
option to pass in the username and password of the TigerGraph user:
The maximum length for the request URL is 8K bytes, including the query string. Requests with a large parameter size should use a data payload file instead of inline data.
The maximum size for a request body, including the payload file, is set by the system parameter Nginx.ClientMaxBodySize
. The default value is 200 (in MB). To increase this limit, use the following gadmin
command:
The upper limit of this setting is 1024 MB. Raising the size limit for the data payload buffer reduces the memory available for other operations, so be cautious about increasing this limit.
By default, an HTTP request in the TigerGraph system times out after 16 seconds. to customize this timeout limit for a particular query instance, you can set the GSQL-TIMEOUT parameter in the request header. If you are using curl to submit your RESTPP request, the syntax would be the following:
You can specify the response size limit of an HTTP request with the following header:
If the response size is larger than the given limit, an error message will be returned instead of the actual query result:
curl
options-d <data>
Sends the specified data in a POST
request to the HTTP server in the same way that a browser does when a user has filled in an HTML form and presses the submit button. This will cause curl to pass the data to the server using the content-type application/x-www-form-urlencoded
.
If you start the data with the character @
, the rest should be a filepath from which to read the data. The command curl -d @foobar
will read data from a file named foobar
.
--data-binary <data>
Sends data with a POST
request exactly as specified with no extra processing.
--fail
Makes curl fail silently (no output at all) on server errors.
This is mostly done to enable scripts etc. to better deal with failed attempts. In normal cases when an HTTP server fails to deliver a document, it returns an HTML document stating so (which often also describes why and more). This flag will prevent curl from outputting that and return error 22.
-H <header>
Extra header to include in the request when sending HTTP to a server. You may specify any number of extra headers.
-s
Silent or quiet mode. Don't show a progress meter or error messages. It will still output the data you ask for, potentially even to the terminal/stdout unless you redirect it.
-u <user:password>
Submits the specified user name and password for server authentication.
-X <request_method>
Specifies a custom request method to use when communicating with the HTTP server. If this option is not used, curl will make a GET
request by default.
TigerGraph's REST API endpoints exist on the REST++ and the GSQL server. REST++ (or RESTPP) is the TigerGraph customized server. Our API accepts URL-encoded query string parameters, -encoded request bodies and returns JSON encoded responses. This user guide provides information on how to engage with our REST APIs: the introduction section explains how to send requests, pass parameters, and format request bodies, while the subsequent sections describe in detail each endpoint and its input and output.
To submit a request, send an HTTP request to the REST++ server or the GSQL server. , the REST++ server listens for requests at port 9000 and the GSQL server listens on port 14240. A request needs to specify five things:
Data of primitive types, including INT, UINT, FLOAT, DOUBLE, STRING, BOOL
, and DATETIME
, as well as arrays and objects, follow the standard . This subsection describes how to format complex data types.
"results"
- this field contains the resulting data from the request. Details about the result of each built-in endpoint are described in the section.
To make the JSON output more human-readable in the terminal, use the command or Python json library built into most Linux installations:
By default, TigerGraph REST++ endpoints are public: anyone with access to the HTTP ports of the TigerGraph server can run your endpoints. When , then a valid authorization token must be included in the header.
The REST++ server implements OAuth 2.0-style authorization as follows: Each user can create one or more secrets (unique pseudorandom strings). Each secret is associated with a particular user and the user's privileges for a particular graph. Anyone who has this secret can invoke a special REST endpoint to (other pseudorandom strings). An authorization token can then be used to perform TigerGraph database operations via other REST endpoints. Each token will expire after a certain period of time. The TigerGraph default lifetime for a token is 1 month.
To keep your credentials more secure, one way to avoid having the user name and password on the command line is to instead use a or a . If you are in interactive mode, you can also use the -u
option without specifying the password, and then curl will prompt for the password.
Request examples in this guide are made using . Below is a list of curl
options used in our code examples:
TigerGraph APIs use headers to specify , as well as to provide RESTPP tokens.
Parameter type | Description | Example |
| Assign multiple values to the same parameter name. | A |
| Use the primary key of the vertex. | A |
| Use | A |
| Same as a | A |
| The | A
|
Data type | Description | Example |
| Use a JSON array of primitive values. | A set of primitive values:
|
| Use a JSON object that has an | A
|
| Use a JSON object that has two JSON
arrays with keys | A map of nations and their capitals:
|
User-Defined Type (UDT) | Use a JSON object that has two JSON
arrays with keys | Tuple schema definition:
|