3.0
TigerGraph Get TigerGraph

Built-in Endpoints

System Utilities

GET /echo and POST /echo

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

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

curl -X GET "http://localhost:9000/endpoints?builtin=true&dynamic=true&static=true"
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.

    "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/{graph_name}

This endpoint returns real-time query performance statistics over the given time period, as specified by the seconds parameter. The seconds parameter must be a positive integer less than or equal to 60. The 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/poc_graph?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              release_2.6.0_05-09-2020 ab1e3d0da6237c27468d6cabb90900119d63759d  2020-04-15 15:46:29 -0700
olgp                 release_2.6.0_05-09-2020 046c745088106b69920b9bdb3bd15969de409e92  2020-05-01 19:10:27 -0700
topology             release_2.6.0_05-09-2020 c028af100117f2051b619436c3aa4febc810bf36  2020-04-22 08:44:07 -0700
gpe                  release_2.6.0_05-09-2020 34b9e86ef7b5fdaa106637e7db1d8a9e080a0aa2  2020-04-19 09:42:59 -0700
gse                  release_2.6.0_05-09-2020 ed2c2351357aa9077fa4dee7ea7a01f8ad2f7585  2020-05-11 01:18:54 -0700
third_party          release_2.6.0_05-09-2020 4bce6990bae5be2b91e9201693ceb66341d3f204  2020-04-19 09:42:56 -0700
utility              release_2.6.0_05-09-2020 2ce197d3edb3557bdd66ed1a4194309908d6197e  2020-04-20 21:19:34 -0700
realtime             release_2.6.0_05-09-2020 52a82b454437c73b47d846acd5803ab0d9f54a45  2020-04-22 08:44:11 -0700
er                   release_2.6.0_05-09-2020 a3e6cb7606fb74984c75cae9bbd4d2112fdbf73a  2020-05-01 19:10:33 -0700
gle                  release_2.6.0_05-09-2020 d8bdbd1cf346e181aa9a317c704dd7b3b11b4658  2020-05-06 00:51:04 -0700
bigtest              release_2.6.0_05-09-2020 2f64c47b7a5ac1834ead9a22eef8d42241117853  2019-12-12 01:31:35 -0800
document             release_2.6.0_05-09-2020 6327094bd76b2dbc8f4625108d547827344b5091  2019-12-13 16:30:13 -0800
glive                release_2.6.0_05-09-2020 93f61ea06fe42759c808fc58ff6245c9954d5447  2020-02-05 22:40:24 -0800
gap                  release_2.6.0_05-09-2020 e798efb595545bf91c449034566857c41f52449a  2020-04-29 22:47:26 -0700
gst                  release_2.6.0_05-09-2020 1b695c02f277efad0ddfb2deab710ae0158409da  2020-04-29 22:47:32 -0700
gus                  release_2.6.0_05-09-2020 eee784502b5387844e462305bae419954784da6f  2020-04-29 22:47:20 -0700
blue_features        release_2.6.0_05-09-2020 5d7a4e8d806519f529274b331496d3bc78f01990  2020-04-15 15:46:38 -0700
blue_commons         release_2.6.0_05-09-2020 432763afc49bf986aed4731e50254243d3665bc3  2019-07-30 03:34:46 -0700
"}

GSQL Server Endpoints

It is also possible to send certain requests to the GSQL Server. There are two key differences:

  • Requests are sent to port 14240 (HTTP hub server) instead of 9000 (dedicated RESTPP server).

  • Username and password are required.

GET /gsqlserver/gsql/schema : Get Graph Schema metadata

Returns schema details about a vertex type, an edge type, or the entire graph schema.

curl -u GET "http://server_ip:14240/gsqlserver/gsql/schema"

Parameters:

  • graph: (REQUIRED) the name of the graph

  • type: (OPTIONAL) the name of either a vertex type or an edge type

Output: The output structure depends on whether type is a vertex type, an edge type, or is omitted. These three cases are described below.

Get One Vertex Type

If a vertex type is specified, the only the description for that one vertex type is returned. The JSON results object for a vertex type contains 4 fields:

  • "Name": the vertex type name, same as the input parameter "type"

  • "PrimaryId": details about the primary id

  • "Attributes": details about each attribute, listed in order

  • "Config": details about global properties of the vertex type

For example, to see details about the company vertex type in the workNet graph (see Example Graphs in the Appendix of GSQL Language Reference Part 2):

curl -u tigergraph:tigergraph "localhost:14240/gsqlserver/gsql/schema?graph=workNet&type=company"
{
  "error": false,
  "message": "",
  "results": {
    "Config": {
      "STATS": "OUTDEGREE_BY_EDGETYPE",
      "PRIMARY_ID_AS_ATTRIBUTE": false
    },
    "Attributes": [
      {
        "AttributeType": {
          "Name": "STRING"
        },
        "IsPartOfCompositeKey": false,
        "PrimaryIdAsAttribute": false,
        "AttributeName": "id",
        "HasIndex": false,
        "IsPrimaryKey": false
      },
      {
        "AttributeType": {
          "Name": "STRING"
        },
        "IsPartOfCompositeKey": false,
        "PrimaryIdAsAttribute": false,
        "AttributeName": "country",
        "HasIndex": false,
        "IsPrimaryKey": false
      }
    ],
    "PrimaryId": {
      "AttributeType": {
        "Name": "STRING"
      },
      "IsPartOfCompositeKey": false,
      "PrimaryIdAsAttribute": false,
      "AttributeName": "clientId",
      "HasIndex": false,
      "IsPrimaryKey": false
    },
    "Name": "company"
  }
}

Get One Edge Type

If an edge type is specified, the only the description for that one edge type is returned. The JSON results for an edge type contains 6 fields:

  • "Name": the edge type name, same as the input parameter "type"

  • "FromVertexTypeName": FROM (source) vertex type name

  • "ToVertexTypeName": TO (target) vertex type name

  • "Attributes": details about each attribute, listed in order

  • "IsDirected": whether the edge is directed (true or false)

  • "Config": additional details about global properties of the edge type

For example, to see details about the worksFor vertex type in the workNet graph (see Example Graphs):

curl -u tigergraph:tigergraph "localhost:14240/gsql/schema?graph=workNet&type=worksFor"
{
  "error": false,
  "message": "",
  "results": {
    "IsDirected": false,
    "ToVertexTypeName": "company",
    "Config": {},
    "Attributes": [
      {
        "AttributeType": {
          "Name": "INT"
        },
        "IsPartOfCompositeKey": false,
        "PrimaryIdAsAttribute": false,
        "AttributeName": "startYear",
        "HasIndex": false,
        "IsPrimaryKey": false
      },
      {
        "AttributeType": {
          "Name": "INT"
        },
        "IsPartOfCompositeKey": false,
        "PrimaryIdAsAttribute": false,
        "AttributeName": "startMonth",
        "HasIndex": false,
        "IsPrimaryKey": false
      },
      {
        "AttributeType": {
          "Name": "BOOL"
        },
        "IsPartOfCompositeKey": false,
        "PrimaryIdAsAttribute": false,
        "AttributeName": "fullTime",
        "HasIndex": false,
        "IsPrimaryKey": false
      }
    ],
    "FromVertexTypeName": "person",
    "Name": "worksFor"
  }
}

Get the Entire Graph Schema

If the type parameter is omitted, then the JSON results object will contain 3 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.

For example, to see details about the entire workNet graph (see Example Graphs):

curl --user tigergraph:tigergraph -X GET "localhost:14240/gsqlserver/gsql/schema?graph=workNet"

For brevity, some details which were shown in the One Vertex Type and One Edge Type examples above have been truncated.

{
  "error": false,
  "message": "",
  "results": {
    "GraphName": "workNet",
    "VertexTypes": [
      {
        "Config": {...},
        "Attributes": [...],
        "PrimaryId": {...},
        "Name": "person"},
      {
        "Config": {...},
        "Attributes": [...],
        "PrimaryId": {...},
        "Name": "company"}
    ],
    "EdgeTypes": [
      {
        "IsDirected": false,
        "ToVertexTypeName": "company",
        "Config": {},
        "Attributes": [...],
        "FromVertexTypeName": "person",
        "Name": "worksFor"
      }
    ]
  }
}

GET /gsqlserver/gsql/queryinfo: Get Query Metadata

Returns metadata details about a query. In particular, it lists the input parameters and output PRINT statement syntax.

curl -u GET "http://server_ip:14240/gsqlserver/gsql/queryinfo"

Parameters:

  • graph: (REQUIRED) the name of the graph

  • query: (REQUIRED) the name of the query

Output: The JSON output contains three fields:

  • "queryname": The name of the query, same as the query input parameter.

  • "input": an unordered list of the input parameter names and data types.

  • "output": a JSON structure which follows the same structure of the query's output. For each key-value pair, the key is the name which will appear in the query output. Instead of the data you would expect when running a query, the values are data types.

Example: In the GSQL Language Reference, the query to_vertex_setTest is used to demonstrate the to_vertex_set() function. Its signature is to_vertex_setTest (SET<STRING> uids, STRING uid, STRING vtype). It has four PRINT statements.

curl -u tigergraph:tigergraph -X GET "http://localhost:14240/gsqlserver/gsql/queryinfo?graph=workNet&query=to_vertex_setTest"
{
  "output": [
    {
      "v": "vertex"
    },
    {
      "@@v2": "SetAccum<vertex>"
    },
    {
      "S2": [
        {
          "v_id": "int",
          "attributes": {
            "interestList": "INT_LIST",
            "skillSet": "INT_SET",
            "skillList": "INT_LIST",
            "locationId": "STRING",
            "interestSet": "INT_SET",
            "id": "STRING"
          },
          "v_type": "person"
        },
        {
          "v_id": "int",
          "attributes": {
            "country": "STRING",
            "id": "STRING"
          },
          "v_type": "company"
        }
      ]
    },
    {
      "SDIFF.size()": "int"
    }
  ],
  "input": {
    "uid": "string",
    "uids": "set<string>",
    "vtype": "string"
  },
  "queryname": "to_vertex_setTest",
  "error": false,
  "message": "",
  "version": {
    "schema": 0,
    "edition": "DEVELOPER_EDITION",
    "api": "V2"
  }
}

Accessing and Modifying the Graph Data

To support multiple graphs within one system, the graph data REST endpoint URLs include an optional graph name.

GET /graph/{graph_name}/vertices

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

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:

curl -X GET "http://localhost:9000/graph/socialNet/vertices/User/id1"

{
  "version": {
    "api": "v2",
    "schema": 0
  },
  "error": false,
  "message": "",
  "results": [
    {
      "v_id": "id1",
      "v_type": "User",
      "attributes": {}
    }
  ]
}

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

The delete operation is a cascading deletion. If a vertex is deleted, then all of the edges which connect to it are automatically deleted as well.

GET /graph/{graph_name}/edges

curl -X GET "http://localhost:9000/graph/{graph_name}/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 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.

There are several optional parameters which may be used with either the GET or DELETE requests for /graph/ endpoints. See the Advanced Parameters section below.

The GET /graph/ endpoints can return at most 10240 items.

Here is a simple example:

curl -X GET "http://localhost:9000/graph/socialNet/edges/VidUser/0/User_Video/Video"

{
  "version": {
    "api": "v2",
    "schema": 0
  },
  "error": false,
  "message": "",
  "results": [
    {
      "e_type": "User_Video",
      "directed": false,
      "from_id": "0",
      "from_type": "VidUser",
      "to_id": "2",
      "to_type": "Video",
      "attributes": {
        "rating": 5.2,
        "date_time": 0
      }
    },
    {
      "e_type": "User_Video",
      "directed": false,
      "from_id": "0",
      "from_type": "VidUser",
      "to_id": "0",
      "to_type": "Video",
      "attributes": {
        "rating": 6.8,
        "date_time": 0
      }
    },
    {
      "e_type": "User_Video",
      "directed": false,
      "from_id": "0",
      "from_type": "VidUser",
      "to_id": "3",
      "to_type": "Video",
      "attributes": {
        "rating": 10,
        "date_time": 0
      }
    }
  ]
}

/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

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

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

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

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

The parameter 'Limit' can reduce the search space and leads to quick response 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/{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

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 on socialNet.

curl -X GET "http://localhost:9000/graph/socialNet/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/{graph_name}/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 on graph "socialNet".

curl -X GET "http://localhost:9000/graph/socialNet/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:

  • 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

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

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

curl -X POST 'http://localhost:9000/builtins/socialNet' -d  '{"function":"stat_vertex_attr","type":"Person"}' | jq .

{
  "version": {
      "api": "v2",
      "schema": 0
   },
  "error": false,
  "message": "",
  "results": [
    {
      "vertexName": "Person",
      "attributeStat": [
        {
          "vattrName": "age",
          "MAX": 64,
          "MIN": 15,
          "AVG": 36.5
        }
      ]
    }
  ]
}

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/socialNet' -d  '{"function":"stat_edge_attr","type":"Liked", "from_type":"*", "to_type":"*"}' | jq .

{
  "version": {
    "api": "v2",
    "schema": 0
  },
  "error": false,
  "message": "",
  "results": [
    {
      "e_type": "Liked",
      "attributes": {
        "weight": {
          "MAX": 2.5,
          "MIN": 1,
          "AVG": 1.375
        }
      }
    }
  ]
}

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/socialNet' -d  '{"function":"stat_vertex_number","type":"*"}' | jq .

{
  "version": {
    "api": "v2",
    "schema": 0
  },
  "error": false,
  "message": "",
  "results": [
    {
      "v_type": "User",
      "count": 4
    },
    {
      "v_type": "Page",
      "count": 4
    },
    {
      "v_type": "Product",
      "count": 7
    },
    {
      "v_type": "DescWord",
      "count": 7
    },
    {
      "v_type": "NameUser",
      "count": 9
    },
    {
      "v_type": "VidUser",
      "count": 4
    },
    {
      "v_type": "Video",
      "count": 5
    },
    {
      "v_type": "AttributeTag",
      "count": 4
    }
  ]
}

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/socialNet' -d  '{"function":"stat_edge_number","type":"*"}' | jq .

{
  "version": {
    "api": "v2",
    "schema": 0
  },
  "error": false,
  "message": "",
  "results": [
    {
      "e_type": "Liked",
      "count": 4
    },
    {
      "e_type": "Liked_By",
      "count": 5
    },
    {
      "e_type": "Linkto",
      "count": 6
    },
    {
      "e_type": "Has_desc",
      "count": 40
    },
    {
      "e_type": "NameConn",
      "count": 38
    },
    {
      "e_type": "Video_AttributeTag",
      "count": 18
    },
    {
      "e_type": "User_Video",
      "count": 14
    }
  ]
}

POST /ddl/{graph_name} - Run a Loading Job

This endpoint is for loading data 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. 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:

name

data type

default

description

tag

string

N.A.

loading job name defined in your DDL loading job (REQUIRED)

filename

string

N.A.

file variable name or filepath for the file containing the data (REQUIRED)

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.

# Loading job
CREATE LOADING JOB load_data for GRAPH poc_graph {

    DEFINE FILENAME f1;
    DEFINE FILENAME f2;
    DEFINE FILENAME f3;
    
    LOAD f1 to VERTEX person VALUES ($0, $0);
    LOAD f2 to VERTEX company VALUES ($0, $0);

    LOAD f3 to EDGE work_at VALUES ($0, $1, $3, $4, $5);
}

# Executing the job via the REST API
curl -X POST --data-binary @company.csv "http://localhost:9000/ddl/poc_graph?tag=load_data&filename=f2" | jq 

{
  "version": {
    "edition": "enterprise",
    "api": "v2",
    "schema": 0
  },
  "error": false,
  "message": "",
  "results": [
    {
      "sourceFileName": "Online_POST",
      "statistics": {
        "validLine": 7927,
        "rejectLine": 0,
        "failedConditionLine": 0,
        "notEnoughToken": 0,
        "invalidJson": 0,
        "oversizeToken": 0,
        "vertex": [
          {
            "typeName": "company",
            "validObject": 7,
            "noIdFound": 0,
            "invalidAttribute": 0,
            "invalidPrimaryId": 0,
            "invalidSecondaryId": 0,
            "incorrectFixedBinaryLength": 0
          }
        ],
        "edge": [],
        "deleteVertex": [],
        "deleteEdge": []
      }
    }
  ],
  "code": "REST-0000"
}

Note that if your loading job defines multiple file sources, you will need to call the endpoint multiple times, once for each file as you can only pass one file to the endpoint at a time. LOAD statements utilising file definitions not referenced in the filename tag will be skipped.

The maximum size of data you can upload via this endpoint is controlled by the Nginx.ClientMaxBodySize configuration parameter (default is 128 MB).

POST /graph/{graph_name} - Upsert the given data

This endpoint upserts 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. "Upsert" means that if the target vertex or edge does not yet exist, it is insert; if it does exist, it is updated. The endpoint offers some parameters which can fine tune this behavior.

This endpoint accepts three parameters:

name

data type

default

description

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.

new_vertex_only

bool

false

"false": Upsert vertices "true": Treat vertices as insert-only. If the input data refers to a vertex which already exists, do not update it.

vertex_must_exist

bool

false

"false": Always insert new edges. If a new edge refers to an endpoint vertex which does not exist, create the necessary vertices, using given id and default values for other parameters. "true": Only insert or update an edge If both endpoint vertices already exist.

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.

Payload (Input) Data

The payload data should be in JSON according the schema shown below:

"vertices": {
   "<vertex_type>": {
      "<vertex_id>": {
         "<attribute>": {
            "value": <value>,
            "op": <opcode>
         }
      }
   }
},
"edges": {
   "<source_vertex_type>": {
      "<source_vertex_id>": {
         "<edge_type>": {
            "<target_vertex_type>": {
               "<target_vertex_id>": {
                  "<attribute>": {
                     "value": <value>,
                     "op": <opcode>
                  }
               }
            }
         }
      }
   }
}

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 the exact text which must be used. 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 attr1. Op codes are explained below.

{
 "vertices": {
    "User": {
      "id6": {
        "attr1": {
           "value": 1,
           "op": max
         }
      },
      "id1": {
        "attr1": {
           "value": 2
         }
      }
    }
  }
}

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 edges from id6 to id1.

{
 "vertices": {
    "User": {
      "id6": {
      }
    }
  },
  "edges": {
    "User":{
      "id1": {
        "Liked": {
          "User": {
            "id6" : {
              "weight" : {
                "value": 5.0
              }
            }
          }
        }
      },
      "id6": {
        "Liked_By": {
          "User": {
            "id1" : {
              "weight" : {
                "value": 1.0
              }
            }
          }
        }
      }
    }
  }
}

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

"ignore_if_exists`" or "~"

If the vertex/edge does not exist, use the payload value to initialize the attribute; but if the vertex/edge already exists, do not change this attribute.

2

"add" or "+"

Add the payload value to the existing value.

3

"and" or "&"

Update to the logical AND of the payload value and the existing value.

4

"or" or "|"

Update to the logical OR of the payload value and the existing value.

5

"max" or ">"

Update to maximum of the payload value and the existing value.

6

"min" or "<"

Update to minimum of the payload value and the existing va

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

  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.

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 graph

  • vertices_already_exist: the id and type of the input vertices which were skipped

If vertex_must_exist is true, the response will include two more fields:

  • skipped_edges: the number of edges in the input data rejected because of missing endpoint vertices

  • miss_vertices: the id and type of the endpoint vertices which were missing

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

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

POST /gsqlserver/interpreted_query - Run an 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 request goes directly to the GSQL server (port 14240) instead of the 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:

curl --fail -u myUsername:myPassword -X POST "http://localhost:14240/gsqlserver/interpreted_query?a=10" -d '
  INTERPRET QUERY (INT a) FOR GRAPH gsql_demo {
    PRINT a;
 }'

If you do not want the password to be included in the request, there are ways to have the username and password stored in a file and then to reference the file. The following method by Pierre D is published in https://stackoverflow.com/questions/2594880/using-curl-with-a-username-and-password:

curl --netrc-file my-password-file http://example.com

The format of the password file is (as per man curl):

machine <example.com> login <username> password <password>

Note:

  1. Machine name must not include https:// or similar! Just the hostname.

  2. The words 'machine', 'login', and 'password' are just keywords; the actual information is the stuff after those keywords.

Managing Running Queries

Once a query has been started, it is assigned a request ID. There are built-in endpoints to report on all running queries and to abort queries.

Get Running Queries /showprocesslist/{graph_name}

This endpoint reports statistics of running queries: the query's request ID, start time, expiration time, and the REST endpoint's url.

curl -X GET "http://localhost:9000/showprocesslist" | jq .
{
  "version": {
    "edition": "enterprise",
    "api": "v2",
    "schema": 0
  },
  "error": false,
  "message": "",
  "results": [
    {
      "requestid": "65538.RESTPP_1_1.1558386411523.N",
      "startTime": "2019-05-20 14:06:51.523",
      "expirationTime": "2019-05-20 14:15:11.523",
      "url": "/sleepgpe?milliseconds=100001"
    },
    {
      "requestid": "196609.RESTPP_1_1.1558386401478.N",
      "startTime": "2019-05-20 14:06:41.478",
      "expirationTime": "2019-05-20 14:15:01.478",
      "url": "/sleepgpe?milliseconds=100000"
    }
  ],
  "code": "REST-0000"
}

Abort a Query /abortquery/{graph_name}

The /abortquery endpoint safely aborts the selected query or queries. Either the GET or POST method may be used.

curl "http://server_ip:9000/abortquery/{graph_name}?{requestid=xxx}[&{url=xxx}]

The following examples show how the options are used to specify which queries to abort.

Abort Query with Given RequestID

To abort one query request, use the requestid parameter to specify its request (obtained from /showprocesslist), e.g., ?requestid=16842763.RESTPP_1_1.1561401340785.N

To abort multiple query requests, simply use the requestid parameter multiple times, e.g., ?requestid=16842763.RESTPP_1_1.1561401340785.N&requestid=16973833.RESTPP_1_1.1561401288421.N

curl -X GET "localhost:9000/abortquery/poc_graph?requestid=16842763.RESTPP_1_1.1561401340785.N&requestid=16973833.RESTPP_1_1.1561401288421.N"

{
  "version": {
    "edition": "enterprise",
    "api": "v2",
    "schema": 0
  },
  "error": false,
  "message": "",
  "results": [
    {
      "aborted_queries": [
        {
          "requestid": "16842763.RESTPP_1_1.1561401340785.N",
          "url": "/sleepgpe?milliseconds=110000"
        },
        {
          "requestid": "16973833.RESTPP_1_1.1561401288421.N",
          "url": "/sleepgpe?milliseconds=100000"
        }
      ]
    }
  ],
  "code": "REST-0000"
}

Abort All Queries

To abort all queries, instead of using specific requestids, use requestid=all.

curl -X GET "localhost:9000/abortquery/poc_graph?requestid=all"

{
  "version": {
    "edition": "enterprise",
    "api": "v2",
    "schema": 0
  },
  "error": false,
  "message": "",
  "results": [
    {
      "aborted_queries": [
        {
          "requestid": "16777232.RESTPP_1_1.1561401584866.N",
          "url": "/sleepgpe?milliseconds=110000"
        }
      ]
    }
  ],
  "code": "REST-0000"
}

Abort Queries by Endpoint

To abort all queries of a given endpoint or endpoints, there is an option to input a string for the query's REST endpoint url. You must specify the base of the endpoint's url, but then use a wildcard to allow for different parameters. For example, to abort all running queries for the endpoint /sleepgpe, use url=/sleepgpe.* 

curl -X GET "localhost:9000/abortquery/poc_graph?url=/sleepgpe.*"

{
  "version": {
    "edition": "enterprise",
    "api": "v2",
    "schema": 0
  },
  "error": false,
  "message": "",
  "results": [
    {
      "aborted_queries": [
        {
          "requestid": "16973836.RESTPP_1_1.1561401442432.N",
          "url": "/sleepgpe?milliseconds=110000"
        }
      ]
    }
  ],
  "code": "REST-0000"
}

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.

Name

Path Type

/shortestpath

shortest path between the source and target vertex sets

/allpaths

all possible paths up to a given maximum path length between the source and target vertex sets

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:

[{"type": "bought", "condition": "price < \"100\" and quality == \"good\""},
 {"type": "sold",   "condition": "price > \"100\"  or quality != \"good\""}]

key

type

value

source

vertex object

Each path must start from this vertex. Mutually exclusive with sources.

sources

vertex array

Each path must start from one of these vertices. Mutually exclusive with source.

target

vertex object

Each path must end at this vertex. Mutually exclusive with targets.

targets

vertex array

Each path must end at one of theses vertices. Mutually exclusive with target.

vertexFilters

filter array

(OPTIONAL) Restrict the paths to those whose vertices satisfy any of the given filters. See details of filters above.

edgeFilters

filter array

(OPTIONAL) Restrict the paths to those whose edges satisfy any of the given filters. See details of filters above.

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.

POST /shortestpath/{graphName} (Shortest Path Search)

The /shortestpath endpoint has the following additional parameters.

Key

Type

Description

maxLength

integer

(OPTIONAL) Maximum length of a shortest path. Default is 6.

allShortestPaths

boolean

(OPTIONAL) 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.

The example below requests a single shortest path between the source vertex set {VidUser 2} and the target vertex set {VidUsers 0 and 3}. The path contains edges of type User_Video whose attributes fulfill the predicate rating > 5 and date_time > 1000. The result is a single path consisting of 3 vertices and 2 edges: VidUser 0 -- (User_Video edge) -- Video 0 -- (User_Video edge) -- VidUser 3

curl -s -X POST 'http://localhost:9000/shortestpath' -d
'{
  "sources":[{"type":"VidUser","id":"2"}],
  "targets":[{"type":"VidUser","id":"0"}, {"type":"VidUser","id":"3"}],
  "edgeFilters":[{"type":"User_Video","condition":"rating > 5 and date_time > 1000"}],
  "maxLength":4
}'

# Result is an array of vertex json objects and edge json objects,
# describing the subgraph for all found vertices and edges.
{
  "version": { "edition": "developer", "api": "v2", "schema": 0 },
  "error": false,
  "message": "Cannot get 'vertex_filters' filters, use empty filter.",
  "results": [
    {
      "vertices": [
        { "v_id": "3","v_type": "VidUser","attributes": { "name": "Dale" }},
        { "v_id": "0","v_type": "Video","attributes": { "name": "Solo", "year", 2018 }},
        { "v_id": "0","v_type": "VidUser","attributes": { "name": "Angel" }},
      ],
      "edges": [
        {
          "e_type": "User_Video", "from_id": "0", "from_type": "Video",
          "to_id": "0", "to_type": "VidUser", "directed": false,
          "attributes": { "rating": 6.8, "date_time": 15000 }
        },
        {
          "e_type": "User_Video", "from_id": "0", "from_type": "Video",
          "to_id": "3", "to_type": "VidUser",  "directed": false,
          "attributes": { "rating": 6.6, "date_time": 16000 }
        }
      ]
    }
  ]
}

To get all shortest paths between the above source and target vertex sets, we can simply do so by specifying the allShortestPaths parameter is true. Now we get two paths. The paths partially overlap, so we get a total of 4 vertices and 3 edges: VidUser 0 -- (User_Video edge) -- Video 0 -- (User_Video edge) -- VidUser 3 VidUser 0 -- (User_Video edge) -- Video 0 -- (User_Video edge) -- VidUser 2

curl -s -X POST 'http://localhost:9000/shortestpath' -d
'{
  "sources":[{"type":"VidUser","id":"2"}],
  "targets":[{"type":"VidUser","id":"0"}, {"type":"VidUser","id":"3"}],
  "edgeFilters":[{"type":"User_Video","condition":"rating > 5 and date_time > 1000}],
  "maxLength":4
  "allShortestPaths": true
}'

# Result is an array of vertex json objects and edge json objects,
# indicating the subgraph for all found vertices and edges.
{
  "version": { "edition": "developer", "api": "v2", "schema": 0 },
  "error": false,
  "message": "Cannot get 'vertex_filters' filters, use empty filter.",
  "results": [
    {
      "vertices": [
        { "v_id": "3","v_type": "VidUser","attributes": { "name": "Dale" }},
        { "v_id": "2","v_type": "VidUser","attributes": { "name": "Chris" }},
        { "v_id": "0","v_type": "Video","attributes": { "name": "Solo", "year", 2018 }},
        { "v_id": "0","v_type": "VidUser","attributes": { "name": "Angel" }},
      ],
      "edges": [
        {
          "e_type": "User_Video", "from_id": "2", "from_type": "VidUser",
          "to_id": "0", "to_type": "Video", "directed": false,
          "attributes": { "rating": 7.4, "date_time": 17000 }
        },
        {
          "e_type": "User_Video", "from_id": "0", "from_type": "Video",
          "to_id": "0", "to_type": "VidUser", "directed": false,
          "attributes": { "rating": 6.8, "date_time": 15000 }
        },
        {
          "e_type": "User_Video", "from_id": "0", "from_type": "Video",
          "to_id": "3", "to_type": "VidUser",  "directed": false,
          "attributes": { "rating": 6.6, "date_time": 16000 }
        }
      ]
    }
  ]
}

POST /allpaths/{graphName} (All Paths Search)

The /allpaths endpoint has the following additional required parameter.

Key

Type

Description

maxLength

integer

(REQUIRED) 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.

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

curl -s -X POST 'http://localhost:9000/allpaths' -d
'{
  "sources":[{"type":"Video","id":"0"}],
  "targets":[{"type": "AttributeTag", "id":"action"}],
  "vertexFilters":[{"type":"Video", "condition":"year >= 1984"}],
  "maxLength": 3
}'

# Result is an array of vertex json objects and edge json objects,
# indicating the subgraph for all found vertices and edges.
{
  "version": { "edition": "developer", "api": "v2", "schema": 0 },
  "error": false,
  "message": "Cannot get 'edge_filters' filters, use empty filter.",
  "results": [
    {
      "vertices": [
        { "v_id": "action","v_type": "AttributeTag","attributes": {}},
        { "v_id": "3","v_type": "VidUser","attributes": { "name": "Dale" }},
        { "v_id": "0","v_type": "VidUser","attributes": { "name": "Angel" }},
        { "v_id": "0","v_type": "Video","attributes": { "name": "Solo", "year", 2018 }},
        { "v_id": "2","v_type": "Video","attributes": { "name": "Thor", "year", 2011 }},
        { "v_id": "4","v_type": "Video","attributes": { "name": "Ran", "year", 1985 }}
      ],
      "edges": [
        {
          "e_type": "Video_AttributeTag", "from_id": "0", "from_type": "Video",
          "to_id": "action", "to_type": "AttributeTag", "directed": false,
          "attributes": { "weight": 1, "date_time": 0 }
        },
        {
          "e_type": "Video_AttributeTag", "from_id": "4", "from_type": "Video",
          "to_id": "action", "to_type": "AttributeTag", "directed": false,
          "attributes": { "weight": 1, "date_time": 11000 }
        },
        {
          "e_type": "User_Video", "from_id": "3", "from_type": "VidUser",
          "to_id": "4", "to_type": "Video", "directed": false,
          "attributes": { "rating": 8.4, "date_time": 12000 }
        },
        {
          "e_type": "User_Video", "from_id": "3", "from_type": "VidUser",
          "to_id": "0", "to_type": "Video", "directed": false,
          "attributes": { "rating": 6.6, "date_time": 16000 }
        },   
        {
          "e_type": "Video_AttributeTag", "from_id": "2", "from_type": "Video",
          "to_id": "action", "to_type": "AttributeTag", "directed": false,
          "attributes": { "weight": 1, "date_time": 0 }
        },
        {
          "e_type": "User_Video", "from_id": "2", "from_type": "VidUser",
          "to_id": "0", "to_type": "Video", "directed": false,
          "attributes": { "rating": 7.4, "date_time": 17000 }
        },
        {
          "e_type": "User_Video", "from_id": "0", "from_type": "Video",
          "to_id": "0", "to_type": "VidUser", "directed": false,
          "attributes": { "rating": 6.8, "date_time": 15000 }
        }
      ]
    }
  ]
}

Other versions of path finding algorithms are available in the 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:

CREATE QUERY parameterIsNULL (INT p) FOR GRAPH anyGraph {
  IF p IS NULL THEN
    PRINT "p is null";
  ELSE
    PRINT "p is not null";
  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/anyGraph/parameterIsNULL?p=0"

Log Files

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

PreviousRESTPP RequestsNextBuilt-in Endpoints JSON Catalog

Last updated