×

☰ Table of Contents

TigerGraph Docs : RESTPP API User Guide v1.0

Version 1.0
Document updated:

Copyright © 2015-2017 TigerGraph. All Rights Reserved.
For technical support on this topic, contact support@tigergraph.com with a subject line starting with "REST++"


Introduction – What is REST++?

The TigerGraph TM system uses the well-known REpresentational State Transfer (REST) architecture to manage communication with the TigerGraph core components, the Graph Processing Engine (GPE) and Graph Storage Engine (GSE). REST++ (or RESTPP) is the TigerGraph customized REST server. (See Figure 1 below) When an upper layer component, such as the Platform Web UI or GSQL, wishes to access the graph engine, it sends a request to the REST++ server. Users can also communicate directly with the REST++ server, either by using one of the standard REST APIs included with the system, or by authoring and then employing a custom endpoint API.  This document describes the APIs for the built-in endpoints, which provides methods for basic querying and manipulation of the graph data.


Figure 1 : TigerGraph System Block Diagram

Like most RESTful systems, REST++ employs the HTTP protocol (specifically HTTP/1.1 without request pipelining). Accordingly, REST APIs feature request methods and URLs, response status codes, and data responses. This guide describes the request methods and URLs used to query, update, and delete from the graph data. It also describes the format of the data responses.

The TigerGraph REST APIs employ three HTTP request methods:

  • GET is used to request data.

  • POST is used to send data.

  • DELETE is used to delete data.

If the user submits an unsupported HTTP method, the API will return an error message: "endpoint not found".

Submitting a REST++ Request

To submit a request, an HTTP request is sent to the REST++ server. By default, the REST++ server listens for requests at port 9000. A request needs to specify three things:

  1. the request method (GET, POST, or DELETE),

  2. the endpoint address, and

  3. any required or optionally request parameters.

The endpoint address is the the form of a HTTP URL.

Request parameters are appended to the end using standard HTTP query string format.

In a test or development environment, the requester may be on the same server as REST++. In this case, the server_ip is localhost .

The Linux curl command is the most convenient way to submit the HTTP request to the REST++ server.

REST Request Format
curl -X method "http://server_ip:9000/path_to_endpoint?request_parameters"

Example:

Assume the REST++ server is on the local machine (typical configuration). To get all the User vertices from the current graph:

Example: Get all User vertices
curl -X GET "http://localhost:9000/graph/vertices/User"

To list only the first three vertices, we can set limit = 3:

Example: Get up to 3 User vertices
curl -X GET "http://localhost:9000/graph/vertices/User?limit=3"

The HTTP request methods GET, POST, and DELETE are case sensitive. Also, curl option flags are case sensitive.

Input Data for POST

Input data for POST requests should be in JSON format. There are two ways to supply the data: inline or in a separate file.

Inline Data

The data should be formatted as a single string without linebreaks. Use the curl - d option, followed by the JSON string.

Syntax for a POST request with Inline Data Payload
curl -X POST -d 'json_string' "http://server_ip:9000/path_to_endpoint?request_parameters"

The following example uses the POST /graph endpoint to insert one User type vertex whose id value is "id6" into the graph.

Example using inline input data
curl -X POST -d '{"vertices":{"User":{"id6":{"id":{"value":"id6"}}}}}' "http://localhost:9000/graph"

Data File

Often it will be more convenient for the input data to be in a separate file, especially if it is large.

Use the curl option --data-binary @path_to_file as in the example below:

Syntax for a POST request with Payload Data File
curl -X POST --data-binary @json_file "http://server_ip:9000/path_to_endpoint?request_parameters"

If we now store the data string in a file (say, my_input.json), then the example above becomes the following:

Example using inline input data
curl -X POST --data-binary @my_input.json "http://localhost:9000/graph"

REST++ Output

All TigerGraph REST responses are in JSON format. The format details for each built-in endpoint are described below in the Built-in Endpoints section. By default, the output is designed for machine reading, with no extra spaces or linefeeds. The output JSON object can have three fields: error, message, and result.

To make the output more human readable, use the jq command or Python json library built into most Linux installations. Specifically,

curl -X method "http://server_ip:9000/path_to_endpoint?request_parameters" | jq . curl -X method "http://server_ip:9000/path_to_endpoint?request_parameters" | python -m json.tool

Example:

In the Collaborative Filter example in the GSQL Tutorial and Demo Examples document, the request

curl -X GET "http://localhost:9000/graph/vertices/User?limit=3"

without postprocess formatting returns the following:

{"results":[{"id":"0","vtype":"User","attributes":{}},{"id":"id2","vtype":"User","attributes":{}},{"id":"id1","vtype":"User","attributes":{}}],"error":false,"message":""}

On the other hand,

curl -X GET http://localhost:9000/graph/vertices/User?limit=3 | jq .

returns this much more readable output:

{ "error":false, "message":"", "results":[ { "attributes":{ }, "id":"0", "vtype":"User" }, { "attributes":{ }, "id":"id2", "vtype":"User" }, { "attributes":{ }, "id":"id1", "vtype":"User" } ] }


Size limits

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.client_max_body_size. The default value is 128 (in MB). To increase this limit to xxx MB, use the following gadmin command:

gadmin --set nginx.client_max_body_size xxx -f

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.


back to top


Built-in Endpoints

System Utilities

GET /echo and POST /echo

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

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

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

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.

Type

Description

builtin

preinstalled in the TigerGraph system

dynamic

generated when compiling GSQL queries

static

user-installed endpoints

To request one of the endpoint types be included in the output, include TypeName =true in the parameter query string. For example, "builtin=true". Each type must be explicitly requested to be included. To see all endpoints, include all three TypeName =true strings. If no type parameters are provided, the output will be empty.

Example: Report on all three types of endpoints
curl -X GET "http://localhost:9000/endpoints?builtin=true&dynamic=true&static=true"


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

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.

Subset of GET endpoints/ output
"GET /echo": null, "GET /endpoints": { "parameters": { "builtin": { "default": "false", "max_count": 1, "min_count": 0, "type": "BOOL" }, "dynamic": { "default": "false", "max_count": 1, "min_count": 0, "type": "BOOL" }, "static": { "default": "false", "max_count": 1, "min_count": 0, "type": "BOOL" } } }

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

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.

curl -X GET "http://server_ip:9000/version" {"error":"false", "message":"TigerGraph RESTPP: --- Version --- product poc4.4_base 7dd9c25dac6be25107aeb1d8c40411383d062dec 2017-02-15 16:52:22 -0800 olgp 4.4 8eaa1b27724df53af8bb1536a132e53c382bffa1 2017-02-15 00:48:30 -0800 topology 4.4 334a1a354b87c80dabd0b05b4b7b46472a5a75e3 2017-02-16 08:58:01 -0800 gpe 4.4 fd45a03bde22aa08a0c6ff9bb8cab33a21c15495 2017-01-31 12:57:34 -0600 gse 4.4 771e133b719eb037b7b990566f451939d77c4b22 2017-02-10 02:21:41 -0500 third_party 4.4 4bc14a5f4f89bbddcd54f242a29175a2a16291fd 2017-01-21 03:48:53 -0500 utility 4.4 0ba01f7d2668bf5cdff8c0fd6a7faef3f42d9c18 2017-02-17 09:49:00 -0800 realtime 4.4 e86c9ee9df81b201777915ba5028e34221fc60b3 2018-02-15 18:41:41 -0500 er 4.4 1c80659bee6f6bf1fb1b1559c03ce7eafda9f54c 2017-02-15 18:04:15 -0500 tut 4.4 2ebb709b95c7bc1404085a8b3e50477972a65f80 2017-02-15 18:19:09 -0800 glelib 4.4 823d806167e84f0494bdcf117763df8bbc1ef04a 2017-02-21 11:23:58 -0800 bigtest prod_master 9700dbfb596b3602ed772e2c9755ec0da0d3ed10 2016-10-07 14:23:26 -0400 pta prod_master 82ceadbb246c2e5b36783cd029577ede678a6921 2016-10-13 17:56:25 +0800 glive prod_master 70e69c4339d981d802065ff2b669554589fb66c7 2016-11-14 15:29:15 -0800 gui 4.4 2d886ca4ac5d9bad6a83bb75de92839f7726de06 2017-02-17 16:54:13 -0800 gvis prod_master 7f947364db0dac10decad21df70187fea7f9bd70 2017-02-21 11:04:39 -0800 blue_features 4.4 8a4f587ec3b58f0974bb067e4c8d2aadab1a849e 2016-11-04 13:12:59 -0500 blue_commons 4.4 7158570b7fc76da4b50c05a7469f14b25899d90d 2017-02-17 11:33:57 -0800 "}

back to top


Accessing and Modifying the Graph Data

GET /graph/vertices

Syntax for GET /graph/vertices
curl -X GET "http://server_ip:9000/graph/vertices/{vertex_type}[/{vertex_id}/]

This endpoint returns all vertices having the type vertex_type . Optionally, the user can instead chose a particular vertex by including its primary_id at the vertex_id field . For example:

curl -X GET "http://localhost:9000/graph/vertices/User/id1" { "results":[ { "id":"id1", "vtype":"User", "attributes":{ "age":30, "name":"Aaron" } } ], "error":false, "message":"" }

/graph/vertices has an optional parameter "count_only". The default value is false. If it is true, the results field contains only the count of the result vertices.

GET /graph/edges

Syntax for GET /graph/edges
curl -X GET "http://localhost:9000/graph/edges/{source_vertex_type}/{source_vertex_id}/[{edge_type}/[{target_vertex_type}/[{target_vertex_id}]]]

This endpoint returns all edges which connect to a given vertex ID. 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.

For example,

curl -X GET "http://localhost:9000/graph/edges/User/id3/Liked/User" { "results":[ { "etype":"Liked", "to_id":"id1", "to_v_type":"User", "attributes":{ "weight":3.00000 } }, { "etype":"Liked", "to_id":"id4", "to_v_type":"User", "attributes":{ "weight":3.50000 } } ], "error":false, "message":"" }

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

  • count_only: If it is true, the results contains only the count of the result edges. 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/vertices

curl -X DELETE "http://server_ip:9000/graph/vertices/{vertex_type}[/{vertex_id}/]

This endpoint deletes the given vertex(vertices). The URL is exactly the same as GET /graph/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/edges

curl -X DELETE "http://localhost:9000/graph/edges/{source_vertex_type}/{source_vertex_id}/[{edge_type}/[{target_vertex_type}/[{target_vertex_id}]]]

This endpoint deletes the given edge(s). The URL is exactly the same as GET /graph/edges.

Advanced Parameters for /graph/vertices and /graph/edges

The above four endpoints, GET /graph/vertices, GET /graph/edges, DELETE /graph/vertices, and DELETE /graph/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.

The parameter 'Limit' can reduce the search space and leads to quick reponse of queries. However if Limit and Sort are both provided, the query still needs to traverse all potential vertices/edges and it might lead to slow query response on large graph.

Select

By default the GET /graph/vertices and /graph/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.

It is illegal to specify both desired and undesired attributes in the same request.

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

curl -X GET "http://localhost:9000/graph/vertices/product?select=date_time"

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.

curl -X GET "http://localhost:9000/graph/vertices/User?filter=age>=30"


Literal strings should be enclosed in double quotation marks. For example, filter=name="GSQL" . However, if the URL is itself enclosed in quotes, as is the case when a REST request is submitted using the curl command,  then the quotation marks around a string should be URL-encoded by replacing each mark with substring %22 .

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.

curl -X GET "http://localhost:9000/graph/vertices/User?limit=3"

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:

DELETE /graph/delete_by_type/vertices

Syntax for GET /graph/delete_by_type/vertices
curl -X DELETE "http://server_ip:9000/graph/delete_by_type/vertices/{vertex_type}

This endpoint deletes all vertices of the given vertex type. This endpoint has two additional parameters "permanent" and "ack". The "permanent" parameter is the same as the "permanent" parameter for endpoint DELETE /graph/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

This endpoint provides statistics. 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 and its output. The vertex type "Person" has a uint attribute "age".

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

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

curl -X POST 'http://localhost:9000/builtins' -d '{"function":"stat_edge_attr","type":"Liked", "from_type":"*", "to_type":"*"}' | jq . { "results": [ { "edgeName": "Liked", "attributeStat": [ { "eattrName": "strength", "MAX": 0.8, "MIN": 0.2, "AVG": 0.4875 } ] } ], "error": false, "message": "" }

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.

curl -X POST 'http://localhost:9000/builtins' -d '{"function":"stat_vertex_number","type":"*"}' | jq . { "results": { "Person": 9 }, "error": false, "message": "" }

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.
curl -X POST 'http://localhost:9000/builtins' -d '{"function":"stat_edge_number","type":"*"}' | jq . { "results": [ { "edgeName": "Liked", "number": 16 } ], "error": false, "message": "" }

POST /ddl

This endpoint is for data loading. For more detai ls, please see GSQL Language Reference Part 1 - Defining Graphs and Loading Data v1.0

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:

name data type default description
tag string N.A. loading job name defined in your DDL loading job
sep one character string , separator of CSV data. If your data is JSON, you do not need to specify this parameter.
eol one or two character string \n end-of-line character. Only one character is allowed, except for the special case "\r\n"
ack string, can only be "all" or "none" "all" "all": request will return after all GPE instances have acknowledged the POST
"none": request will return immediately after RESTPP processed the POST.
timeout UINT32 0 Timeout in seconds. If set to 0, use system-wide endpoint timeout setting.

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 as https://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

This endpoint can upsert vertices and/or edges into the graph. 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.

POST /graph JSON format

" vertices " : " vertex_type " : " vertex_id " : " attribute " : "valu e", "op"

" edges " : " source_vertex_type " : " source_vertex_id " : " edge_type " : " target_vertex_type " : " target_vertex_id " : " attribute " : "value" , "op"

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:

Type op Meaning
1 "overwrite" or "=" Create a new vertex/edge with these values, or overwrite the existing value. This is the default operation if op is not given.
2 "ignore_if_exists`" or "~" If the vertex/edge does not exist, use the payload value to initialize the attribute; but if the vertex/edge already exists (which means the values of all attributes exist), do not change this attribute.a
3 "add" or "+" Add the payload value to the existing valu e.
4 "and" or "&" Update to the logical AND of the payload value and the existing value.
5 "or" or "|" Update to the logical OR of the payload value and the existing value.
6 "max" or ">" Update to maximum of the payload value and the existing value.
7 "min" or "<" Update to minimum of the payload value and the existing value.


Types 3 through 7 should only be used if the selected vertices or edges exist.  If any of these operators is requested for an non-existing vertices or edges, the entire request is rejected.

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

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

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

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

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:

parameterIsNULL.gsql
CREATE QUERY parameterIsNULL (INT p) FOR GRAPH anyGraph { IF p IS NULL THEN PRINT "p is null"; ELSE PRINT "p is not null"; END; }
parameterIsNULL.end
{ "query":{ "parameterIsNULL":{ "GET":{ "function":"queryDispatcher", "action":"query", "target":"GPE", "payload":[ { "rule":"AS_QUERY_STRING" } ], "parameters":{ "query":{ "type":"STRING", "default":"parameterIsNULL" }, "p":{ "type":"INT64", "min_count":0 } }, "summary":"This is query entrance" } } } }

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:

curl -X GET "http://localhost:9000/query/parameterIsNULL?p=0"

Log Files

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


Appendix A - JSON Catalog of Built-in Endpoints

The request

curl -X GET "http://server_ip:9000/endpoints?builtin=true"

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.

{ "DELETE /graph/delete_by_type/vertices/{vertex_type}":{ "parameters":{ "ack":{ "default":"all", "max_count":1, "min_count":1, "options":[ "all", "none" ], "type":"STRING" }, "permanent":{ "default":"false", "max_count":1, "min_count":1, "type":"BOOL" }, "vertex_type":{ "type":"TYPENAME" } } }, "DELETE /graph/edges/{source_vertex_type}/{source_vertex_id}/{edge_type}/{target_vertex_type}/{target_vertex_id}":{ "parameters":{ "edge_type":{ "max_count":1, "min_count":0, "type":"STRING" }, "filter":{ "max_count":1, "max_length":2560, "min_count":0, "type":"STRING" }, "limit":{ "max_count":1, "min_count":0, "type":"UINT64" }, "not_wildcard":{ "max_count":1, "min_count":0, "type":"BOOL" }, "permanent":{ "default":"false", "max_count":1, "min_count":1, "type":"BOOL" }, "select":{ "max_count":1, "max_length":2560, "min_count":0, "type":"STRING" }, "sort":{ "max_count":1, "max_length":2560, "min_count":0, "type":"STRING" }, "source_vertex_id":{ "id_type":"$source_vertex_type", "is_id":true, "max_count":1, "max_length":256, "min_count":1, "type":"STRING" }, "source_vertex_type":{ "max_count":1, "min_count":1, "type":"TYPENAME" }, "target_vertex_id":{ "id_type":"$target_vertex_type", "is_id":true, "max_count":1, "max_length":256, "min_count":0, "type":"STRING" }, "target_vertex_type":{ "max_count":1, "min_count":0, "type":"TYPENAME" }, "timeout":{ "default":"0", "max_count":1, "min_count":0, "type":"UINT32" } } }, "DELETE /graph/vertices/{vertex_type}/{vertex_id}":{ "parameters":{ "filter":{ "max_count":1, "max_length":2560, "min_count":0, "type":"STRING" }, "limit":{ "max_count":1, "min_count":0, "type":"UINT64" }, "permanent":{ "default":"false", "max_count":1, "min_count":1, "type":"BOOL" }, "sort":{ "max_count":1, "max_length":2560, "min_count":0, "type":"STRING" }, "timeout":{ "default":"0", "max_count":1, "min_count":0, "type":"UINT32" }, "vertex_id":{ "id_type":"$vertex_type", "is_id":true, "max_count":1, "max_length":2560, "min_count":0, "type":"STRING" }, "vertex_type":{ "type":"TYPENAME" } } }, "GET /echo":{ "parameters":{ "sleep":{ "default":"0", "type":"INT32" } } }, "GET /endpoints":{ "parameters":{ "builtin":{ "default":"false", "max_count":1, "min_count":0, "type":"BOOL" }, "dynamic":{ "default":"false", "max_count":1, "min_count":0, "type":"BOOL" }, "static":{ "default":"false", "max_count":1, "min_count":0, "type":"BOOL" } } }, "GET /graph/edges/{source_vertex_type}/{source_vertex_id}/{edge_type}/{target_vertex_type}/{target_vertex_id}":{ "parameters":{ "count_only":{ "default":"false", "max_count":1, "min_count":0, "type":"BOOL" }, "edge_type":{ "max_count":1, "min_count":0, "type":"STRING" }, "filter":{ "max_count":1, "max_length":2560, "min_count":0, "type":"STRING" }, "limit":{ "max_count":1, "min_count":0, "type":"UINT64" }, "not_wildcard":{ "max_count":1, "min_count":0, "type":"BOOL" }, "select":{ "max_count":1, "max_length":2560, "min_count":0, "type":"STRING" }, "sort":{ "max_count":1, "max_length":2560, "min_count":0, "type":"STRING" }, "source_vertex_id":{ "id_type":"$source_vertex_type", "is_id":true, "max_count":1, "max_length":256, "min_count":1, "type":"STRING" }, "source_vertex_type":{ "max_count":1, "min_count":1, "type":"TYPENAME" }, "target_vertex_id":{ "id_type":"$target_vertex_type", "is_id":true, "max_count":1, "max_length":256, "min_count":0, "type":"STRING" }, "target_vertex_type":{ "max_count":1, "min_count":0, "type":"TYPENAME" }, "timeout":{ "default":"0", "max_count":1, "min_count":0, "type":"UINT32" } } }, "GET /graph/schema":null, "GET /graph/vertices/{vertex_type}/{vertex_id}":{ "parameters":{ "count_only":{ "default":"false", "max_count":1, "min_count":0, "type":"BOOL" }, "filter":{ "max_count":1, "max_length":2560, "min_count":0, "type":"STRING" }, "limit":{ "max_count":1, "min_count":0, "type":"UINT64" }, "select":{ "max_count":1, "max_length":2560, "min_count":0, "type":"STRING" }, "sort":{ "max_count":1, "max_length":2560, "min_count":0, "type":"STRING" }, "timeout":{ "default":"0", "max_count":1, "min_count":0, "type":"UINT32" }, "vertex_id":{ "id_type":"$vertex_type", "is_id":true, "max_count":1, "max_length":2560, "min_count":0, "type":"STRING" }, "vertex_type":{ "type":"TYPENAME" } } }, "GET /statistics":{ "parameters":{ "seconds":{ "default":"10", "type":"UINT32" }, "segments":{ "default":"10", "max":"100", "min":"1", "type":"UINT32" } } }, "GET /version":null, "POST /echo":{ "parameters":{ "sleep":{ "default":"0", "type":"INT32" } } }, "POST /graph":{ "parameters":{ "ack":{ "default":"all", "max_count":1, "min_count":1, "options":[ "all", "none" ], "type":"STRING" } } }, "POST /builtins":null, "POST /ddl":{ "parameters":{ "ack":{ "default":"all", "max_count":1, "min_count":1, "options":[ "all", "none" ], "type":"STRING" }, "concise":{ "default":"false", "max_count":1, "min_count":1, "type":"BOOL" }, "eol":{ "default":"\n", "max_count":1, "max_length":4, "min_count":1, "min_length":1, "type":"STRING" }, "sep":{ "default":",", "max_count":1, "max_length":4, "min_count":0, "min_length":1, "type":"STRING" }, "tag":{ "max_count":1, "min_count":1, "type":"STRING" }, "timeout":{ "default":"0", "max_count":1, "min_count":0, "type":"UINT32" } } } }