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.
TigerGraph's RESTful APIs communicate with either the REST++ server on port 9000 or the GSQL server on port 14240. Each server uses different methods of authentication.
By default, TigerGraph REST++ endpoints are public: anyone with access to the HTTP ports of the TigerGraph server can run your endpoints. When REST++ authentication is enabled, 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 generate authorization tokens (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.
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:
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 .netrc file or a config file. 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.
TigerGraph's REST API endpoints exist on the REST++ and the GSQL server. REST++ (or RESTPP) is the TigerGraph customized REST server. Our API accepts URL-encoded query string parameters, JSON-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. By default, the REST++ server listens for requests at port 9000 and the GSQL server listens on port 14240. A request needs to specify five things:
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:
Data of primitive types, including INT, UINT, FLOAT, DOUBLE, STRING, BOOL
, and DATETIME
, as well as arrays and objects, follow the standard JSON Data Interchange Syntax. This subsection describes how to format complex data types.
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.
"results"
- this field contains the resulting data from the request. Details about the result of each built-in endpoint are described in the Built-in Endpoints section.
To make the JSON output more human-readable in the terminal, use the jq
command or Python json library built into most Linux installations:
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
optionsRequest examples in this guide are made using curl
. Below is a list of curl
options used in our code examples:
-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.
TigerGraph APIs use headers to specify size and time limits, as well as to provide RESTPP authentication tokens.
-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.
GET /echo
and POST /echo
These endpoints provide simple diagnostic utilities, which respond with the following message if the RESTPP server is up and running. Neither GET /echo
or POST /echo
require authentication, even when RESTPP authentication is enabled.
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
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.
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
Their username and password in their request header as well as specifying the graph
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
Their username and password in their request header as well as specifying the graph
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.
PUT /requesttoken
This endpoint takes a token and its associated secret and refreshes the lifetime of the token. The token itself remains unchanged.
Parameters:
DELETE /requesttoken
This endpoint takes a token and its associated secret, and deletes the token.
POST /ddl/{graph_name}
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.
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.
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.
By default, the POST /graph/{graph_name}
endpoint is not atomic. If something goes wrong during the process of the request, the request data can be partially consumed by the database.
You can append a query string parameter atomic_post
to the URL of the request and set its value to true to make the request an atomic transaction, which means that updates to the database contained in the request are all-or-nothing. Either all changes are successful, or none is successful.
For example, suppose we have the following request to upsert two vertices:
And the content of vertices.json
is:
With the request above, if the vertex Kelly
fails to be upserted due to a machine failure, it is still possible that the vertex Velma
is upserted to the database.
If you add the atomic_post
parameter to the request URL and set its value to true, the request becomes atomic and if any part of the request body fails to be upserted, nothing will be upserted:
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
.
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
.
If we set the value of vertex_must_exist
parameter to true
, the endpoint will only insert edges whose endpoint vertices both exist. This includes the vertices being inserted in the same request. Therefore, inserting the content of add_id6.json
to an empty graph would cause the edges to be rejected:
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.
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.
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.
If you have a TigerGraph HA cluster, you can specify a query to run on a particular replica with the HTTP header GSQL-REPLICA
. The value of the header needs to be an integer within the range one to the replication factor of the cluster. If you supply a invalid value for the header, the request will return an error.
When running a query through RESTPP, you can specify a limit on the number of threads that the query is allowed to use on each node through the HTTP header GSQL-THREAD-LIMIT
. The number of threads used by a query means the number of vCPUs used by the query. By default, a query will use all threads that are available on a machine.
For example, if you have a cluster of three nodes, each with 8 vCPUs, then a query will use all 8 threads available on a node in the cluster by default. By providing a thread limit in the request header, you can limit the query to only use a number of threads under the limit.
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.
If you have a TigerGraph HA cluster, you can specify a query to run on a particular replica with the HTTP header GSQL-REPLICA
. The value of the header needs to be an integer within the range one to the replication factor of the cluster. If you supply an invalid value for the header, the request will return an error.
When running a query through RESTPP, you can specify a limit on the number of threads that the query is allowed to use on each node through the HTTP header GSQL-THREAD-LIMIT
. The number of threads used by a query means the number of vCPUs used by the query. By default, a query will use all threads that are available on a machine.
For example, if you have a cluster of three nodes, each with 8 vCPUs, then a query will use all 8 threads available on a node in the cluster by default. By providing a thread limit in the request header, you can limit the query to only use a number of threads under the limit.
The query in this sample request takes a parameter of type VERTEX<person>
:
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.
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
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
Name | Required | Description |
---|
Name | Required | Description |
---|
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 - .
Name | Required | Description |
---|
Name | Required | Description |
---|
Name | Required | Description |
---|
Name | Required | Description |
---|
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 on RESTPP endpoints.
A secret, which is a random string generated in GSQL (see)
You may also use a POST
request to generate your token, see .
Name | Required | Description |
---|
A secret, which is a random string generated in GSQL (see)
You may also use a GET
request to generate your token, see .
Name | Required | Description |
---|
Name | Required | Description |
---|
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.
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 to identify the filepath string you are providing data for in the filename
parameter.
Name | Required | Description |
---|
If there are special characters in your parameter values, the special characters should use . 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 configuration parameter (default is 200 MB).
Name | Required | Description |
---|
Name | Required | Description |
---|
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 ****section). The JSON format for describing a vertex set or edge set is summarized below.
Follow the instructions in the Introduction section to . 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
:
Type | op | Meaning |
---|
To insert vertices or edges, use the endpoint.
Name | Required | Description |
---|
Name | Required | Description |
---|
Name | Required | Description |
---|
Name | Required | Description |
---|
Name | Required | Description |
---|
To insert vertices or edges, use the endpoint.
Name | Required | Description |
---|
Name | Required | Description |
---|
Name | Required | Description |
---|
Name | Required | Description |
---|
Name | Required | Description |
---|
Name | Required | Description |
---|
Name | Required | Description |
---|
When using a GET
request to run an installed query, the query parameters are .
Parameter type | Query string format | Example |
---|
Name | Required | Description |
---|
When using a POST
request to run an installed query, the query parameters are passed in through the request body and . The formatting rules for the JSON payload is the same as .
Parameter type | Syntax | Example |
---|
Installed queries can run in . To do this, use the GSQL-ASYNC
header and set its value to true
. The and 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.
When running an interpreted query through this endpoint, the query parameters should be .
Name | Required | Description |
---|
This endpoint allows you to check the status of a query run in .
Name | Required | Description |
---|
Key | Type | Description |
---|
Key | Required | Description |
---|
Key | Type | Description |
---|
Name | Required | Description |
---|
Other versions of pathfinding algorithms are available in the .
Parameter type
Description
Example
SET
or BAG
of primitives
Assign multiple values to the same parameter name.
A SET<INT>
parameter named p1
is assigned 3 integers:
p1=1&p1=5&p1=10
VERTEX
with a defined type
Use the primary key of the vertex.
A VERTEX<person>
parameter namedvp
is assigned a vertex whose ID is "person2"
:
vp=person2
VERTEX
without a defined type
Use <parameter_name>.<parameter_type>
to specify the type of the parameter, and also provide the primary key of the vertex.
A VERTEX
parameter named va
is assigned a person
type vertex whose ID is"person1"
va=person1&va.type=person
SET
or BAG
of vertices with a defined type
Same as a SET
or BAG
of primitives, where the value for each element is the primary key of the vertex.
A SET<VERTEX<person>>
parameter named vp
is assigned two vertices with IDs person3
and person4
:
vp=person3&vp=person4
SET
or BAG
of vertices without a defined type
The SET
or BAG
must be treated as an array, specifying the order of the elements with indices [0]
, [1]
, etc.
A SET<VERTEX>
parameter named vp
is assigned a person
type vertex with an ID of person1
and a post
type vertex with an ID of 11
:
vp[0]=person1&vp[0].type=person&vp[1]=11&vp[1].type=post
Data type
Description
Example
SET
, LIST
or BAG
of primitives
Use a JSON array of primitive values.
A set of primitive values:
[0.5, 0,6, 0.7]
VERTEX
Use a JSON object that has anid
field
whose value is the primary key of the
vertex and a"type"
field whose value
is the type of the vertex.
A person
vertex with an ID of "Tom"
:
{"id": "Tom", "type": "person"}
MAP
Use a JSON object that has two JSON
arrays with keys keyList
and
valueList
, each containing the
keys and the values of the map respectively.
The order of items in the valueList should correspond to the order of items in the keyList.
A map of nations and their capitals:
{
"keyList": ["England", "Germany"],
"valueList": ["London", "Berlin"]
}
User-Defined Type (UDT)
Use a JSON object that has two JSON
arrays with keys keyList
and
valueList
. The keyList
array contains the field names of the tuple, and the valueList
array contains the values of the fields.
The order of items in the valueList should correspond to the order of items in the keyList.
Tuple schema definition:
TYPEDEF TUPLE <name STRING, age INT> person
A person
tuple written in JSON:
{"keyList: ["name", "age"], "valueList": ["Sam", 24]}
| No | Integer that indicates the number of seconds for which the response will be delayed. |
| No | Takes a boolean value. Returns built-in endpoints if true. |
| No | Takes a boolean value. Returns dynamic endpoints if true. |
| No | Takes a boolean value. Returns user-installed endpoints if true. |
| 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. |
| 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. |
| No | Number of latest data points to return. If provided, the endpoint will return the latest data points that satisfy the |
| No | Name of the metric to filter for. Possible values are:
|
| No | Name of the component that reported the datapoint |
| No | Name of the node that the datapoint is reported for |
| Yes | Positive integer less than 60 that indicates how many seconds back from the current time the statistics report will cover. |
| No | Integer that indicates the number of segments that |
| No | Number of threads used to execute the rebuild. If not specified, the number specified in line 185 of the 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 |
| No | Vertex type to perform the rebuild for. If not provided, the rebuild will be run for all the vertex types. |
| 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. |
| No | Path to save the summary of the rebuild to. If not provided, the default path is |
| 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 |
| 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 |
| No | IDs of segments to perform the deleted vertex check for. If none is provided, the check will be performed on all segments. |
| No | Vertex types to perform the deleted vertex check for. If none is provided, the check will be performed on all vertex types. |
| 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:
|
| 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
|
| Yes if | User's secret to generate the token. |
| No | Period of time for which the token is valid measured in seconds. The default value is about 2.6 million (about a month). |
| Yes if | Name of the graph that the token will be valid for. |
| No | Period of time for which the token is valid in seconds. The default value is about 2.6 million (about a month). |
| Yes if using username-password pair | The graph for which to generate token. |
Name | Required | Description |
| Yes | Token to refresh. |
| Yes | User's secret used to generate the token. |
| Yes | Period of time for which the token is valid measured in seconds. |
| Yes | Token to delete. |
| Yes | User's secret used to generate the token. |
| Yes | Loading job name defined in your DDL loading job |
| Yes | File variable name or file path for the file containing the data |
| No | Separator of CSV data. If your data is JSON, you do not need to specify this parameter. The default separator is a comma |
| No | End-of-line character. Only one or two characters are allowed, except for the special case "\r\n". The default value is |
| No |
|
| No | Timeout in seconds. If set to 0, use system-wide endpoint timeout setting. |
| 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. |
| Yes | The name of the graph whose schema to retrieve. |
| 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. |
| No | The value of this parameter can either be
|
| 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. |
| No | Boolean value that indicates whether or not to insert new edges when the |
| No | Boolean value that indicates whether or not this request is an atomic transaction. Default value is false. |
1 |
| 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 the payload value to the existing value. |
3 |
| Update to the logical AND of the payload value and the existing value. |
4 |
| "` |
5 |
| Update to the higher value between the payload value and the existing value. |
6 |
| Update to the lower value between the payload value and the existing value. |
| No | Takes a boolean value. If the value is true, the |
| 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. |
| 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: |
| No | Integer value that specifies the total number of vertices to return |
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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: |
| No | Integer value that specifies the total number of vertices to delete. |
| No | Attributes to sort the vertices by. In delete operations, |
| 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. |
| 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. |
| 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. |
| 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. |
| No | Takes a boolean value. If the value is true, the |
| No | Attributes of the selected edges to return. The parameter takes a list, which is a string of comma-separated values. If |
| 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: |
| No | Integer value that specifies the maximum limit of the total number of edges to return. |
| 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 |
| No | Integer that specifies the number of seconds after which the query will time out. If the parameter is set to |
| No | Takes a boolean value. If the value is true, the |
| No | Attributes of the selected edges to return. The parameter takes a list, which is a string of comma-separated values. If |
| 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: |
| No | Integer value that specifies the maximum limit of the total number of edges to return. |
| 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 |
| No | Integer that specifies the number of seconds after which the query will time out. If the parameter is set to |
| No | Takes a boolean value. If the value is true, the |
| No | Boolean value that indicates whether or not |
| No | Attributes of the selected edges to return. The parameter takes a list, which is a string of comma-separated values. If |
| 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: |
| No | Integer value that specifies the maximum limit of the total number of edges to return. |
| 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 |
| No | Integer that specifies the number of seconds after which the query will time out. If the parameter is set to |
| No | Attributes of the selected edges to return. The parameter takes a list, which is a string of comma-separated values. If |
| No | Integer that specifies the number of seconds after which the query will time out. If the parameter is set to |
| 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. |
| Yes | Name of the graph |
| Yes | Name of the query |
Set or bag of primitives | Assign multiple values to the same parameter name. | A set |
| Use the ID of the vertex:
| A vertex with parameter name |
(type not pre-specified) | Use two query string parameters:
| A vertex with parameter name
|
Set or bag of | Assign multiple vertex IDs to the same | A set parameter named
|
Set or bag of (type not pre-specified) | The | A set parameter named
|
| Use a string formatted as |
|
Set or bag of primitives | Use a JSON array containing the primitive values |
|
| Use a JSON object containing a field |
|
| Use a JSON object containing a field |
|
Set or bag of | Use a JSON array containing a list of JSON |
|
Set or bag of vertices of unspecified types | Use a JSON array containing a list of JSON |
|
| No | The ID of the query to abort. It can take a single query ID or the string |
| 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 |
Name | Required | Description |
| Yes | Name of the graph the query belongs to. Required parameter. |
| No | String ID of the query. It also accepts the value The output will contain one JSON object for each query. |
| Yes | String ID of the query. |
| vertex object | Each path must start from this vertex. Mutually exclusive with |
| vertex array | Each path must start from one of these vertices. Mutually exclusive with |
| vertex object | Each path must end at this vertex. Mutually exclusive with |
| vertex array | Each path must end at one of these vertices. Mutually exclusive with |
| filter array | (OPTIONAL) Restrict the paths to those whose vertices satisfy any of the given filters. |
| filter array | (OPTIONAL) Restrict the paths to those whose edges satisfy any of the given filters. See details of filters above. |
| No | Integer that specified the maximum length of a shortest path. The default value is 6. |
| 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. |
| vertex object | Each path must start from this vertex. Mutually exclusive with |
| vertex array | Each path must start from one of these vertices. Mutually exclusive with |
| vertex object | Each path must end at this vertex. Mutually exclusive with |
| vertex array | Each path must end at one of these vertices. Mutually exclusive with |
| filter array | (OPTIONAL) Restrict the paths to those whose vertices satisfy any of the given filters. |
| filter array | (OPTIONAL) Restrict the paths to those whose edges satisfy any of the given filters. See details of filters above. |
| Yes | Maximum path length. |
| No |
| No |
Field | Description |
| URL of the given query. |
| The status of the given query. Possible values are |
| The timestamp for the start time of the given query. |
| The query ID associated with the given query status JSON object. |
|
| 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. |
Boolean value that indicates whether to use 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.
Boolean value that indicates whether to use 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.
The timestamp for when the given query times out. The default timeout limit is 16 seconds and can be set using the header.