Built-in Endpoints

System Utilities

GET /echo and POST /echo

These endpoints are simple diagnostic utilities which respond with the following message.

POST /echo has the same response as GET /echo.

GET /endpoints

This endpoint returns a list of the installed endpoints and their parameters. There are three types of endpoints, described in the table below.

To include one more more of the endpoint types in the output, include TypeName =true in the parameter query string for each type. For example, "builtin=true&static=true" will include builtin and static endpoints. 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 from the builtin=true option is over 300 lines long. It is listed in full in Appendix A. To illustrate the format, we show a small excerpt: the output for the GET /echo and GET /endpoints endpoint.

GET /statistics

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 REST++ server maintains a truncated log of requests from the current time and backward for a system-configured log_interval . Only those endpoints which have completed or timed out during the requested number of seconds and are within the log_interval will be included in the statistics report. For example:

The statistics data are returned in JSON format. For each endpoint which has statistics data, we return the following items:

  • 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. By default, segments 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].

Note: If there is no query sent in the past given seconds, a empty json will be returned.

GET /version

This endpoint returns the git versions of all components of the system. This can be useful information when requesting help from TigerGraph's support team.

There are over a dozen built-in endpoints, and some have several parameters, so the formatted JSON output from the builtin=true option is over 300 lines long. It is listed in full in Appendix A. To illustrate the format, we show a small excerpt: the output for the GET /echo and GET /endpoints endpoint.

GET /statistics

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 REST++ server maintains a truncated log of requests from the current time and backward for a system-configured log_interval . Only those endpoints which have completed or timed out during the requested number of seconds and are within the log_interval will be included in the statistics report. For example:

The statistics data are returned in JSON format. For each endpoint which has statistics data, we return the following items:

  • 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. By default, segments 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].

Note: If there is no query sent in the past given seconds, a empty json will be returned.

GET /version

This endpoint returns the git versions of all components of the system. This can be useful information when requesting help from TigerGraph's support team.

Accessing and Modifying the Graph Data

GET /graph/{graph_name}/vertices

This endpoint returns all vertices having the type vertex_type in the graph called graph_name . graph_name is optional if the database has only one graph but required for a database with multiple graphs. Optionally, the user can instead chose a particular vertex by including its primary_id at the vertex_id field . For example:

/graph/{graph_name}/vertices has an optional parameter "count_only". The default value is false. If it is true, the results field contains only the number of vertices selected.

GET /graph/{graph_name}/edges

This endpoint returns all edges which connect to a given vertex ID in the graph called graph_name . graph_name is optional if the database has only one graph but required for a database with multiple graphs.A source vertex ID must be given. The user may optionally specify the edge type, the target vertex type, and the target vertex ID. The URL format is as follows:

  • edge_type - type name of the edges. Use "_" to permit any edge type. Omitting the edge_type field from the URL also permits any edge type. However, skipping edge_type also means that target_vertex_type and target_vertex_id must be skipped.

  • target_vertex_type - type name of the target vertices.

  • target_vertex_id - ID of the target vertex.

Here is a simple example:

/graph/{graph_name}/edges has two optional parameters "count_only" and "not_wildcard":

  • count_only : If it is true, the results contains only the number of edges selected. The default value is false.

  • not_wildcard : This determines how the edge type name "_" is interpreted. If false (which is the default), "_" means all edge types are included. If not_wildcard is true, "_" is interpreted literally to select only edges with edge type name equal to underscore.

DELETE /graph/{graph_name}/vertices

This endpoint deletes the given vertex(vertices) in the graph called graph_name . graph_name is optional if the database has only one graph but required for a database with multiple graphs. The URL structure and semantics are analogous to those in GET /graph/{graph_name}/vertices. This endpoint has an additional parameter "permanent", whose default value is false. If "permanent" is true, the deleted vertex ids can never be inserted back, unless the graph is dropped or the graph store is cleared.

DELETE /graph/{/graph_name}/edges

This endpoint deletes the given edge(s). graph_name is optional if the database has only one graph but required for a database with multiple graphs. The URL structure and semantics are analogous to thos in GET /graph/{graph_name}/edges.

Advanced Parameters for /graph/{graph_name}/vertices and /graph/{graph_name}/edges

The above four endpoints, GET /graph/{graph_name}/vertices, GET /graph/{graph_name}/edges, DELETE /graph/{graph_name}/vertices, and DELETE /graph/{graph_name}/edges, have optional URL parameters for further operations:

  1. Select : Specify which attributes to be returned (GET only).

  2. Filter : Apply a filter on the vertices or edges, based on their attribute values.

  3. Limit : Limit the total number of vertices or edges.

  4. Sort : Sort the data. (For DELETE, sort should be used with limit together.)

  5. Timeout : Timeout in seconds. If set to 0, use system wide endpoint timeout setting.

Select

By default the GET /graph/{graph_name}/vertices and /graph/{graph_name}/edges endpoints return all the attributes of the selected vertices or edges. The select parameter can be used to specify either the desired or the undesired attributes. The format is select=attribute_list, where attribute_list is a list of comma-separated attributes. Listing an attribute name means that this attribute should be included, while an attribute name preceded by a minus sign means that this attribute should be excluded. An underscore means all attributes.

  • http://server_ip:9000/graph/{graph_name}/vertices?select=attr1,attr2 returns only attributes attr1 and attr2

  • http://server_ip:9000/graph/{graph_name}/vertices?select=-attr1,-attr2 returns all attributes except attributes attr1 andattr2

  • http://server_ip:9000/graph/{graph_name}/vertices?select=-_ returns no attribute at all

Example Query: Return the date_time attribute of all product vertices on socialNet.

Filter

The filter parameter is a set of conditions analogous to the WHERE clause in industry-standard SQL language. The format is filter=filter_list, where filter_list is a list of comma-separated filters, and each filter is the concatenation of an attribute, an operator, and a value (with no white spaces separating the parts). The following six comparison operators are supported:

  1. = equal to

  2. != not equal to

  3. > greater than

  4. >= greater than or equal to

  5. > less than

  6. <= less than or equal to

Here is an example request: It returns all User vertices with age greater than or equal to 30.

Limit

The Limit parameter is used to set a limit on the number of vertices or edges returned from a query request. Note that there is also a system limit of 10240 on the number of vertices or edges returned. The user-defined limit cannot exceed this system limit.

The following example returns up to 3 User vertices on graph "socialNet".

Sort

The Sort parameter returns results sorted by given attributes. The format is sort=list_of_index_attributes. The results are sorted by the first attribute first, and so on. Groups of the sorted results which have identical values on the first attribute are then sorted by the second attribute, and so on. Below are some examples:

  • http://server_ip:9000/graph/{graph_name}/vertices?sort=attr1 sort by attribute attr1 in ascending order

  • http://server_ip:9000/graph/{graph_name}/vertices?sort=-attr1 sort by attribute attr1 in descending order

  • http://server_ip:9000/graph/{graph_name}/vertices?sort=attr1,-attr2 first sort by attr1 in ascending order, then sort by attr2 in descending order

DELETE /graph/{graph_name}/delete_by_type/vertices

This endpoint deletes all vertices of the given vertex type in the graph called graph_name . graph_name is optional if the database has only one graph but required for a database with multiple graphs. This endpoint has two additional parameters "permanent" and "ack". The "permanent" parameter is the same as the "permanent" parameter for endpoint DELETE /graph/{graph_name}/vertices. "ack" specifies whether RESTPP needs to get acknowledgement from GPEs. If "ack" is set to "none", it doesn't need to get acknowledgement from any GPE. If "ack" is set to "all" (default), it needs to get acknowledgement from all GPEs.

POST /builtins/{graph_name}

This endpoint provides statistics for the graph called graph_name . graph_name is optional if the database has only one graph but required for a database with multiple graphs. A JSON object must be given as a data payload in order to specify the function and parameters. In the JSON object, the keyword "function" is used to specify the function. Below are the descriptions of each function:

stat_vertex_attr

This function 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 bool attribute. There is one parameter:

  • type: The vertex type name, or "*", which indicates all vertex types.

Below is an example request on socialNet and its output. The vertex type "Person" has a uint attribute "age".

stat_edge_attr

Similar to stat_vertex_attr, this function returns the statistics of the minimum, maximum, and average of the given edge type's int, uint, float and double attributes, and the count of true and false of a bool attribute. Note each undirected edge is counted twice. There are three parameters:

  • type: The edge type name, or "*", which indicates all edge types.

  • from_type: Given a vertex type, the function only includes edges whose source vertex type is the given type. "*" indicates all types. Default is all types. If a specific edge type is given, giving a correct from_type can speed up the process.

  • to_type: Given a vertex type, the function only includes edges whose destination vertex type is the given type. "*" indicates all types. Default is all types.

Below is an example request and its output. The edge type "Liked" has a float attribute "strength".

stat_vertex_number

This function returns the number of vertices of the given vertex type. There is one parameter.

  • type: The vertex type name, or "*", which indicates all vertex types.

Below is an example request and its output.

stat_edge_number

This function returns the number of edges of the given type. There are three parameters.

  • type: The edge type name, or "*", which indicates all edge types.

  • from_type: Given a vertex type, the function only those edges whose source vertex type is the given type. "*" indicates all types. Default is all types. If a specific edge type is given, giving a correct from_type can speed up the process.

  • to_type: Given a vertex type, the function counts only those edges whose destination vertex type is the given type. "*" indicates all types. Default is all types.

POST /ddl/{graph_name}

This endpoint is for loading data the the graph called graph_name . graph_name is optional if the database has only one graph but required for a database with multiple graphs. For more details, please see GSQL Language Reference Part 1 - Defining Graphs and Loading Data

This endpoint 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. This endpoint accepts five parameters:

Note that if you have special characters in your parameter values, the special characters should use URL encoding. For example, if your eol is '\n', it should be encoded as %0A. Reference guides for URL encoding of special characters can found on the web, such ashttps://www.w3schools.com/tags/ref_urlencode.asp . To avoid confusion about whether you should you one or two backslashes, we do not support backslash escape for this eol or sep parameter.

POST /graph/{graph_name}

This endpoint can upsert vertices and/or edges into the graph called graph_name . graph_name is optional if the database has only one graph but required for a database with multiple graphs. Due to the cost of checking for the existence of an edge or a vertex, the standard API does not support separate update and create (insert) operations. Instead, an upsert operation, a combination of update and insert, is provided. If the target vertex or edge already exists, it is updated with the values specified in the request. If the vertex or edge does not yet exist, the action depends on the operator chosen by the user. Some operators will direct the endpoint to create a new vertex or edge using the attribute values in the request.

The response is the number of vertices and edges that were accepted. The API uses JSON format to describe the vertices and edges to be upserted. The JSON code can be stored in a text file or specified directly in a command line. There is a maximum size for a POST data payload (see the Size Limits section). The JSON format for describing a vertex set or edge set is summarized below. The identifiers in bold are keywords. The italicized terms should be replaced with user-specified values. Moreover, multiple instances may be included at the italicized levels. See the example below for clarification.

For each attribute , we need to specify its value and op . The operator controls how the value and a possible existing value in the vertex / edge are aggregated. We support the following operators:

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 assigne d default values . The default value is 0 for int/uint, 0.0 for float/double, and "" 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:

  1. Invalid vertex type.

  2. Invalid attribute data type.

  • For edge upsert:

  1. Invalid source vertex type.

  2. Invalid edge type.

  3. Invalid target vertex type.

  4. Invalid attribute data type.

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

The following example file add_id6 . json 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.

POST /gsqlserver/interpreted_query

This endpoint is used to run GSQL queries in Interpreted Mode via a REST request. The query body should be supplied at the data payload, and the query's parameters are supplied as the URL's query string. The port should be 14240, however, not 9000.

For example, assuming you are using curl to send your HTTP request:

Path-Finding Algorithms

The TigerGraph platform comes with a family of built-in endpoints which return one or more unweighted paths connecting a set of source vertices to a set of target vertices. The user can also specify filtering conditions to specify which edges may be included or the maximum number of hops in a path.

Path finding is more efficient if the algorithm can do a bidirectional search: travel forward from the source vertices while traveling backward from target vertices, and then see where the two paths meet. To do bidirectional search, however, either the edges must be undirected or directed edge types need to be defined with a companion REVERSE_EDGE type.

The first table below summarizes the available path-finding endpoints.

Each endpoint reads a JSON object payload which describes the input parameters. The next table describes the key-value pairs in the JSON payload. The two required keys are source_vertices and target_vertices. Each of these contains an array of vertex objects. The format for a vertex object is as follows: {"type" : "<vertex_type_name>", "id" : "<vertex_id>"}

All filter conditions in the JSON array are combined with the "OR" relationship, i.e., if any one of the filter conditions is fulfilled, then the filter is satisfied. If "deny_filter" is "true", then if one filter is condition is satisfied, then the edge is NOT filtered.

Below, we show an example of each of the path endpoints.

POST /allpaths/{graphname} (Bi-directional search)

The following query returns all paths connecting vertex set {S, 6} with vertex set {T, 3, c2} on the graph. It has filter conditions on both directional edge. For positive directions, use "connected" type edge. For reverse directions, use "rev_connected" type edge. Both have the attribute filter "nameA != "S" or nameB !="T" ", where nameA and nameB are attributes for both type of edges.

POST /singledirectionallpaths/{graphname} (single direction search)

The following query returns all paths connecting vertex set {S, 6} with vertex set {T, 3, c2} on the graph. It has filter conditions on positive direction using the "connected" type edge, because it is a single direction search algorithm. It has the attribute filter that "nameA != "S" or nameB !="T" ", where nameA and nameB are attributes of the searching edge.

POST /shortestpath/{graphname} (Bi-directional search)

The following query returns all shortest paths between vertex set {S, 6} with vertex set {T, 3, c2}. It has filter conditions on both directional edge. For positive directions, use "connected" type edge. For reverse directions use, "rev_connected" type edge. Both have the attribute filter "nameA != "S" or nameB !="T" ", where nameA and nameB are attributes for both type of edges.

POST /singledirectionshortestpath (single direction search)

The following query returns a single path connecting vertex set {S, 6} with vertex set {T, 3, c2} on the graph.

POST /undirectedshortestsinglepath/{graphname} (Bi-directional search)

The following query returns one shortest path for each pair of vertex set {S, 6} with vertex set {T, 3, c2}. It differs from the above query in that only one path for each pair is returned, even if there are many shortest paths with the same length. The rule to select which shortest path is fixed if the data is loaded. However, if the graph is reloaded, the selected path might be different. It has filter conditions on both directional edge types. For positive directions, use "connected" type edge. For reverse directions, use "rev_connected" type edge. Both have the attribute filter "nameA != "S" or nameB !="T" ", where nameA and nameB are attributes for both type of edges.

POST /shortestsinglepath (single direction search)

The following query returns a single path connecting vertex set {S, 6} with vertex set {T, 3, c2} on the graph.

For further detail on the graph algorithm queries, take a look at our GSQL Graph Algorithm Library.

Dynamically Generated Endpoints

Each time a new TigerGraph query is installed, a dynamic endpoint is generated and stored at installation_directory/config/endpoints_dynamic. This new endpoint enables the user to run the new TigerGraph query by using curl commands and giving the parameters in URL or in a data payload. See the document "GSQL Language Specification, Part 2: Queries" Section "Running a Query" for more details. For example, the following TigerGraph query can generate a corresponding endpoint in <installation_directory>/config/endpoints_dynamic:

The "payload" object enables the query being executed by giving a data payload. The "parameter" object includes the query parameters.

To execute this query, with parameter p=0, the following curl command can be used:

Log Files

The REST servers log files are located in <installation_directory>/logs.