Built-in Endpoints
System Utilities
Echo (public)
GET /echo
and POST /echo
These endpoints provide simple diagnostic utilities, which respond with the following message if the RESTPP server is up and running. Neither GET /echo
or POST /echo
require authentication, even when RESTPP authentication is enabled.
Sample request:
POST /echo
has the same response as GET /echo
.
Parameters
Name | Required | Description |
---|---|---|
| No | Integer that indicates the number of seconds for which the response will be delayed. |
Health check (public)
This endpoint performs a simple server health check. It listens on port 14240 and does not require authentication. If you ping it and the server is running, it will respond with the message "pong".
Endpoint:
GET /api/ping
Sample request:
Parameters:
No parameters.
List all endpoints
GET /endpoints/{graph_name}
This endpoint returns a list of the installed endpoints and their parameters. There are three types of endpoints:
Built-in endpoints which are preinstalled in the TigerGraph system
Dynamic endpoints which are generated when compiling GSQL queries
Static endpoints which are user-installed endpoints
To include one or more of the endpoint types in the output, include the endpoint type in the parameter query string and set its value to true
. If no type parameters are provided, all endpoints are returned.
Response
There are over a dozen built-in endpoints, and some have several parameters, so the formatted JSON output of all built-in endpoints is over 300 lines long. It is listed in full in Appendix A. Below is a small excerpt of the output:
Parameters
Name | Required | Description |
---|---|---|
| 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. |
Show component versions
GET /version
This endpoint returns the GIT versions of all components of the system.
Sample request:
Parameters
This endpoint does not take any parameters.
Monitor system metrics
POST /ts3/api/datapoints
TigerGraph System State Service (TS3) is TigerGraph's managed monitoring service that collects system metrics and events. Many TigerGraph components will report metrics such as CPU usage, memory usage, disk usage, and network traffic to TS3 at regular intervals. You can use this endpoint to read from TS3, filtering for the data points you need by time (when
, from
, and to
), component(who
), metric(what
) and location(where
). Visualization of such metrics are available in Admin Portal - Dashboard - Cluster Monitoring.
On a TigerGraph cluster, this endpoint is only present on the m1
node.
Parameters
Name | Required | Description |
---|---|---|
| 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 |
Sample requests
In the sample request below, the filters in the query string include a timeframe starting at 1618957536
and ending at 1619023346
, and specifying that the response should only include CPU information:
In the below example, the request asks for the 10 latest data points regarding memory usage:
Show query performance
GET /statistics/{graph_name}
This endpoint returns real-time query performance statistics over the given time period, as specified by the seconds
****parameter. The seconds
parameter must be a positive integer less than or equal to 60.
Sample request:
The return object is a hash of the endpoints and their performance data:
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 thesegments
****parameter of this endpoint whose default value is 10, meaning the percentile range 0-100% will be divided into ten equal segments: 0%-10%, 11%-20%, etc.Segments
****must be [1, 100].
If there is no query sent in the past given seconds, an empty json will be returned.
Parameters
Name | Required | Description |
---|---|---|
| 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 |
Rebuild graph engine
GET /rebuildnow/{graph_name}
or POST /rebuildnow/{graph_name}
In TigerGraph, when new data is being loaded into the graph (such as new vertices or edges), data is first stored in memory before it is saved to disk permanently. TigerGraph runs a rebuild of the Graph Processing Engine (GPE) to commit the data in memory to disk every 30 seconds, but you can also call this endpoint to trigger a rebuild immediately.
Parameters:
Name | Required | Description |
---|---|---|
| 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 |
Example:
Check deleted vertices
GET /deleted_vertex_check
In certain rare cases, TigerGraph's Graph Processing Engine (GPE) and Graph Storage Engine (GSE) might be out of sync on vertex deletion information. When this happens, some vertices might exist on one of the components, but not the other. Even though these errors are exceedingly rare, TigerGraph provides an endpoint that allows you to check the deleted vertices on GSE and GPE and see if they out of sync.
The check passes if there are no discrepancies between the GSE and GPE in terms of deleted vertices. If there is a discrepancy, the check fails and the return result will contain the IDs of the deleted vertices that are not synced properly. If you are running TigerGraph on a distributed cluster, the check will be performed on each node of the cluster, and the endpoint will return a list containing the results of the check for every node.
Parameters:
Name | Required | Description |
---|---|---|
| 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
|
Example:
Authentication
The endpoints in this subsection allow users to create, refresh and delete authentication tokens for requests made to the REST++ server. These endpoints only exist when user authentication is enabled on RESTPP endpoints.
Request a token (GET
)
GET
)GET /requesttoken
If authentication is enabled on RESTPP endpoints, a token needs to be included in the request header for all requests sent to the RESTPP server. A user can generate a token using either
A secret, which is a random string generated in GSQL (see Managing User Privileges and Authentication)
Their username and password in their request header as well as specifying the graph
You may also use a POST
request to generate your token, see Request a token (POST).
Sample request:
Parameters:
Name | Required | Description |
---|---|---|
| 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. |
Users can use either secret
or their username and password to generate a token. If the user does not supply a secret and chooses to use their username and password instead, then the parameter graph
becomes required.
Request a token (POST
)
POST
)POST /requesttoken
If authentication is enabled on RESTPP endpoints, a token needs to be included in the request header for all requests sent to the RESTPP server. A user can generate a token using either
A secret, which is a random string generated in GSQL (see Managing User Privileges and Authentication)
Their username and password in their request header as well as specifying the graph
You may also use a GET
request to generate your token, see Request a token (GET).
Sample requests
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.
Parameters:
Name | Required | Description |
---|---|---|
| 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. |
Refresh a token
PUT /requesttoken
This endpoint takes a token and its associated secret and refreshes the lifetime of the token. The token itself remains unchanged.
Parameters:
Name | Required | Description |
| 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. |
Sample request
Delete a token
DELETE /requesttoken
This endpoint takes a token and its associated secret, and deletes the token.
Parameters:
Name | Required | Description |
---|---|---|
| Yes | Token to delete. |
| Yes | User's secret used to generate the token. |
Loading jobs
Run a Loading Job
POST /ddl/{graph_name}
This endpoint is for loading data into a graph. It submits data as an HTTP request payload, to be loaded into the graph by the DDL Loader. The data payload can be formatted as generic CSV or JSON. For more details, please see GSQL Language Reference Part 1 - Defining Graphs and Loading Data.
If the loading job references multiple files, multiple HTTP requests are needed to complete the loading job since you can only provide data for one filename varibale at a time. The loading job will skip the LOAD
statements referencing filename variables that the request didn't provide data for. To provide data for a filename variable, put the data in the request body and use the filename
parameter (explained in the parameter table below) to match the variable name defined in the loading job.
If a LOAD
statement is written using a filepath string instead of a file variable, even though the filepath is already provided in the loading job, you still need to provide data in the request body for the LOAD
statement to run. Since there isn't a file variable in this case, use a position-based file identifier to identify the filepath string you are providing data for in the filename
parameter.
Request body:
The request body is the data to be loaded (either in CSV or JSON format).
Curl allows you to read the data from an input file by using the @ symbol:
curl -X POST --data-binary @./company.csv "http://…"
Sample request:
In this example, the loading job is dependent on three filename variables (f1
and f3
) and one filepath string. Therefore, three HTTP requests are needed to complete the loading job.
Parameters:
Name | Required | Description |
---|---|---|
| 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. |
If there are special characters in your parameter values, the special characters should use URL encoding. To avoid confusion about whether you should you one or two backslashes, we do not support backslash escapes for the eol
or sep
parameter.
The maximum size of data you can upload via this endpoint is controlled by the Nginx.ClientMaxBodySize
configuration parameter (default is 200 MB).
Graphs
Run built-in functions on graph
POST /builtins/{graph_name}
This endpoint runs a set of built-in functions and returns relevant statistics about a graph.
Request body:
This endpoint expects a data payload in the request body that specifies which function to run on the graph. Depending on the function being run, different fields may also be expected in the request body.
Here is a list of functions supported by this endpoint and their corresponding data payload format.
stat_vertex_attr
Returns the minimum, maximum, and average values of the given vertex type's
int
,uint
,float
anddouble
attributes, and the count oftrue
andfalse
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
anddouble
attributes, and the count oftrue
andfalse
of a boolean attribute.Data payload fields:
"function": stat_edge_attr
"type"
: The edge type whose attribute values to report on. Required field. It also accepts the value*
, in which case all edge types are included."from_type"
: Optional. The source vertex type of the edges to report on."to_type"
: Optional. The target vertex type of the edges to report on.
stat_vertex_number
Returns the number of vertices of the given vertex type.
Data payload fields:
"function"
:"stat_vertex_number"
"type"
: Required field. The vertex type of the vertices to count. It also accepts the value*
(wild card), in which case, all vertex types are included.
stat_edge_number
Returns the number of edges of the given edge type
Data payload fields:
"function": "stat_edge_number"
"type"
: Required field. The edge type of the edges to count. It also accepts the value*
, in which case all edge types are included."from_type"
: Optional. The source vertex type of the edges to report on."to_type"
: Optional. The target vertex type of the edges to report on.
Sample requests:
Below is an example request running stat_vertex_attr
on socialNet
and its output. The vertex type "Person"
has a uint
attribute "age"
.
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.
Parameters:
No parameters.
Show graph schema metadata
GET /gsqlserver/gsql/schema
Returns schema details about a vertex type, an edge type, or the entire graph schema. This is a GSQL Server request sent to port 14240, and authentication credentials need to be provided.
Sample request:
Vertex schema object fields:
Name
: the vertex type name, same as the input parameter "type"PrimaryId
: details about the primary idAttributes
: details about each attribute, listed in orderConfig
: 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 nameToVertexTypeName
: target vertex type nameAttributes
: details about each attribute, listed in orderIsDirected
: whether the edge is directedConfig
: 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.
Parameters:
Name | Required | Description |
---|---|---|
| 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. |
Upsert data to graph
POST /graph/{graph_name}
This endpoint upserts vertices and/or edges into a graph. To upsert means that if a vertex or edge does not exist, it is inserted, and if it does exist, it is updated.
Atomic upsert transaction
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:
Parameters
Name | Required | Description |
---|---|---|
| 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. |
The response is the number of vertices and edges that were accepted. The API uses JSON format to describe the vertices and edges to be upserted. The JSON code can be stored in a text file or specified directly in a command line. There is a maximum size for a POST
data payload (see the Size Limits ****section). The JSON format for describing a vertex set or edge set is summarized below.
Request body
The payload data should be in JSON according to the schema shown below:
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
:
Operation codes
Each attribute value may be accompanied by an operation (op) code, which provides very sophisticated schemes for data update or insertion:
Type | op | Meaning |
---|---|---|
1 |
| 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. |
If an attribute is not given in the payload, the attribute stays unchanged if the vertex/edge already exists, or if the vertex/edge does not exist, a new vertex/edge is created and assigned the default value for that data type. The default value is 0 for int/uint
, 0.0 for float/double
, and ""
(empty string) for string.
Invalid data types cause the request to be rejected
The RESTPP server validates the request before updating the values. The following schema violations will cause the entire request to fail and no change will be made to a graph:
For vertex upsert
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.
Output response
The response is the number of vertices and edges that were accepted. Additionally, if new_vertex_only
is true, the response will include two more fields:
skipped_vertices
: the number of vertices in the input data which already existed in the graphvertices_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 verticesmiss_vertices
: the id and type of the endpoint vertices which were missing
Examples
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:
Vertices
To support multiple graphs within one system, the graph data REST endpoint URLs include an optional graph name.
Insert vertices
To insert vertices or edges, use the Upsert data to graph endpoint.
List vertices
GET /graph/{graph_name}/vertices/{vertex_type}
This endpoint returns all vertices having the type vertex_type
in a graph. __
Sample request:
Parameters
Name | Required | Description |
---|---|---|
| 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. |
Retrieve a vertex
GET /graph/{graph_name}/vertices/{vertex_type}/{vertex_id}
This endpoint will return a single vertice by its vertex ID.
Sample request:
Parameters:
Name | Required | Description |
---|---|---|
| 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. |
Delete vertices
DELETE /graph/{graph_name}/vertices/{vertex_type}
This endpoint deletes vertices by their vertex type. The delete operation is a cascading deletion. If a vertex is deleted, then all of the edges connected to it are automatically deleted as well.
Sample request:
The response object will contain a "deleted_vertices"
field that indicates the number of vertices that were deleted
Parameters:
Name | Required | Description |
---|---|---|
| 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. |
Delete vertices by type
DELETE /graph/{graph_name}/delete_by_type/vertices/{vertex_type}
This endpoint deletes all vertices of the given vertex type in a graph.
Sample request:
Parameters:
Name | Required | Description |
---|---|---|
| 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. |
Delete a vertex
DELETE /graph/{graph_name}/vertices/{vertex_type}/{vertex_id}
Sample request:
Parameters:
Name | Required | Description |
---|---|---|
| no | Integer that specifies the number of seconds after which the query will time out. If the parameter is set to 0 or isn't provided, the system-wide endpoint timeout setting is applied. |
Edges
Insert edges
To insert vertices or edges, use the Upsert data to graph endpoint.
List edges of a vertex
GET /graph/{graph_name}/edges/{source_vertex_type}/{source_vertex_id}
This endpoint returns all edges which are connected to a given vertex ID in the graph
Sample request:
Parameters:
Name | Required | Description |
---|---|---|
| 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 |
List edges of a vertex by edge type
GET /graph/{graph_name}/edges/{source_vertex_type}/{source_vertex_id}/{edge_type}
This endpoint lists all the edges of a specified type connected to a given vertex ID in the graph
Sample request:
Parameters:
Name | Required | Description |
---|---|---|
| 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 |
List edges of a vertex by edge type and target type
This endpoint lists edges connected to a given vertex by edge type and target vertex type
Use "_"
for edge_type
in the URL to permit any edge type.
Sample request:
Parameters:
Name | Required | Description |
---|---|---|
| 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 |
Retrieve edge by source, target, and edge type
This endpoint returns the edge of a specified type between a source vertex and a target vertex.
Sample request:
Parameters:
Name | Required | Description |
---|---|---|
| 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 |
Delete an edge
Deletes an edge by its source vertex type and ID, target vertex type and ID, as well as edge type.
Sample request
Parameters:
Name | Required | Description |
---|---|---|
| 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. |
Queries
Get query metadata
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.
Sample 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.
Parameters:
Name | Required | Description |
---|---|---|
| Yes | Name of the graph |
| Yes | Name of the query |
Run an installed query (GET
)
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.
Parameters
Name | Required | Description |
---|---|---|
| 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. |
Query parameter passing
When using a GET
request to run an installed query, the query parameters are passed in through the query string of the URL.
Parameter type | Query string format | Example |
---|---|---|
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
|
Specify replica
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.
Specify thread limit
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.
Sample request:
To run query hello
on a graph named social
, and the query parameter is of type VERTEX<person>
whose ID is "Tom"
Run an installed query (POST
)
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.
Parameters
Name | Required | Description |
---|---|---|
| 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. |
Query parameter Passing
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 formatting rules for the JSON payload is the same as using JSON to pass in parameters in the RUN QUERY
command.
Parameter type | Syntax | Example |
---|---|---|
| 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 |
|
Specify replica
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.
Specify thread limit
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.
Sample request
The query in this sample 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.
Run an interpreted query
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.
Request body:
The request body for this endpoint should be the entire INTERPRET QUERY
statement.
Parameter passing:
When running an interpreted query through this endpoint, the query parameters should be passed in through the URL query string.
Sample request:
List running queries
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.
Sample request:
Parameters:
No Parameters.
Abort a query
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.
Sample request:
Parameters:
Name | Required | Description |
---|---|---|
| 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 |
Check query status (Detached Mode)
GET /query_status
This endpoint allows you to check the status of a query run in detached mode.
Sample request:
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. |
| The timestamp for when the given query times out. The default timeout limit is 16 seconds and can be set using the |
| 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. |
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.
Parameters:
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. |
Check query results (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.
Sample request:
Parameters:
Name | Required | Description |
---|---|---|
| Yes | String ID of the query. |
Path-Finding Algorithms
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.
Input Parameters and Output Format for Path-Finding
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.
Source and target vertices
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.
Output
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.
Find shortest path
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.
Request body:
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.
Key | Type | Description |
---|---|---|
| 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. |
Sample request:
Parameters:
Key | Required | Description |
---|---|---|
| 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. |
Find all paths
POST /allpaths/{graph_name}
This endpoint finds all paths between a source vertex (or vertex set) and target vertex (or vertex set).
Request body:
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.
Key | Type | Description |
---|---|---|
| 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. |
Parameters:
Name | Required | Description |
---|---|---|
| Yes | Maximum path length. |
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.
Sample request:
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.
Last updated