简介 - 什么是REST ++？
TigerGraph TM 系统使用着名的REpresentational State Transfer（REST）架构来管理与TigerGraph核心组件，图形处理引擎（GPE）和图形存储引擎（GSE）的通信。REST ++（或RESTPP）是TigerGraph定制的REST服务器。（请参见下面的图1）当上层组件（如Platform Web UI或GSQL）希望访问图形引擎时，它会向REST ++服务器发送请求。用户还可以通过使用系统附带的标准REST API之一，或通过创作然后使用自定义终端API，直接与REST ++服务器通信。本文档描述了内置端点的API，该API提供了对图形数据进行基本查询和操作的方法。
图1 ：TigerGraph系统框图
像大多数RESTful系统一样，REST ++采用HTTP协议（特别是没有请求流水线的HTTP / 1.1）。因此，REST API具有请求方法和URL，响应状态代码和数据响应。本指南介绍了用于查询，更新和从图数据中删除的请求方法和URL。它还描述了数据响应的格式。
TigerGraph REST API使用三种HTTP请求方法：
-
GET 用于请求数据。
-
POST 用于发送数据。
-
DELETE 用于删除数据。
如果用户提交不支持的HTTP方法，API将返回一条错误消息：“未找到端点”。
REST Request Format
To list only the first three vertices, we can set limit = 3:
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.
The following example uses the POST /graph endpoint to insert one User type vertex whose id value is "id6" into the graph called "socialNet".
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:
If we now store the data string in a file (say, my_input.json), then the example above becomes the following:
REST++ Output
To make the output more human readable, use the jq command or Python json library built into most Linux installations. Specifically,
Example:
without postprocess formatting returns the following:
On the other hand,
returns this much more readable output:
{
"version": {
"api": "v2",
"schema": 0
},
"error": false,
"message": "",
"results": [
{
"v_id": "id2",
"v_type": "User",
"attributes": {}
},
{
"v_id": "id14",
"v_type": "User",
"attributes": {}
},
{
"v_id": "id58",
"v_type": "User",
"attributes": {}
}
]
}
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.
| Type | Description |
|---|---|
| builtin | preinstalled in the TigerGraph system |
| dynamic | generated when compiling GSQL queries |
| static | user-installed endpoints |
GET /graph/graph_name/vertices
This endpoint returns all vertices having the type vertex_type in the graph called graph_name . Optionally, the user can instead chose a particular vertex by including its primary_id at the vertex_id field . For example:
graph_name: 图分组名称
vertex_type: 点的类型名称。目前demo:User Page Product DescWord NameUser VidUser Video AttributeTag Person SocialUser
vertex_id: 点的ID类型
curl -X GET "http://172.16.0.222:9000/graph/vertices/User/id1" | jq .
{ "version": { "api": "v2", "schema": 0 }, "error": false, "message": "", "results": [ { "v_id": "id1", "v_type": "User", "attributes": {} } ] }count_only: BOOL(1/0/true/false)
curl -X GET 'http://172.16.0.222:9000/graph/vertices/SocialUser?count_only=1' | jq .
{
"version": {
"api": "v2",
"schema": 0
},
"error": false,
"message": "",
"results": [
{
"v_type": "SocialUser",
"count": 10
}
]
}
filter: 过滤attributes的属性
curl -X GET 'http://172.16.0.222:9000/graph/vertices/SocialUser?filter=name="peter"' | jq .
{
"version": {
"api": "v2",
"schema": 0
},
"error": false,
"message": "",
"results": [
{
"v_id": "6",
"v_type": "SocialUser",
"attributes": {
"name": "peter",
"isActive": true,
"registration_timestamp": 146000000
}
}
]
}
limit:限制放回个数
curl -X GET 'http://172.16.0.222:9000/graph/vertices/SocialUser?limit=2' | jq .
{
"version": {
"api": "v2",
"schema": 0
},
"error": false,
"message": "",
"results": [
{
"v_id": "6",
"v_type": "SocialUser",
"attributes": {
"name": "peter",
"isActive": true,
"registration_timestamp": 146000000
}
},
{
"v_id": "5",
"v_type": "SocialUser",
"attributes": {
"name": "steven",
"isActive": false,
"registration_timestamp": 145000000
}
}
]
}
select: 返回筛选的attributes的属性
curl -X GET 'http://172.16.0.222:9000/graph/vertices/SocialUser?select=name' | jq .
{
"version": {
"api": "v2",
"schema": 0
},
"error": false,
"message": "",
"results": [
{
"v_id": "6",
"v_type": "SocialUser",
"attributes": {
"name": "peter"
}
},
{
"v_id": "5",
"v_type": "SocialUser",
"attributes": {
"name": "steven"
}
},
{
"v_id": "8",
"v_type": "SocialUser",
"attributes": {
"name": "joseph"
}
},
{
"v_id": "7",
"v_type": "SocialUser",
"attributes": {
"name": "james"
}
},
{
"v_id": "2",
"v_type": "SocialUser",
"attributes": {
"name": "matthew"
}
},
{
"v_id": "4",
"v_type": "SocialUser",
"attributes": {
"name": "paul"
}
},
{
"v_id": "9",
"v_type": "SocialUser",
"attributes": {
"name": "thomas"
}
},
{
"v_id": "1",
"v_type": "SocialUser",
"attributes": {
"name": "john"
}
},
{
"v_id": "0",
"v_type": "SocialUser",
"attributes": {
"name": "luke"
}
},
{
"v_id": "3",
"v_type": "SocialUser",
"attributes": {
"name": "mark"
}
}
]
}
sort: 通过筛选的attributes的属性进行排序
curl -X GET 'http://172.16.0.222:9000/graph/vertices/SocialUser?sort=name' | jq .
{
"version": {
"api": "v2",
"schema": 0
},
"error": false,
"message": "",
"results": [
{
"v_id": "7",
"v_type": "SocialUser",
"attributes": {
"name": "james",
"isActive": true,
"registration_timestamp": 147000000
}
},
{
"v_id": "1",
"v_type": "SocialUser",
"attributes": {
"name": "john",
"isActive": true,
"registration_timestamp": 1410000000
}
},
{
"v_id": "8",
"v_type": "SocialUser",
"attributes": {
"name": "joseph",
"isActive": true,
"registration_timestamp": 148000000
}
},
{
"v_id": "0",
"v_type": "SocialUser",
"attributes": {
"name": "luke",
"isActive": true,
"registration_timestamp": 1400000000
}
},
{
"v_id": "3",
"v_type": "SocialUser",
"attributes": {
"name": "mark",
"isActive": true,
"registration_timestamp": 143000000
}
},
{
"v_id": "2",
"v_type": "SocialUser",
"attributes": {
"name": "matthew",
"isActive": false,
"registration_timestamp": 1420000000
}
},
{
"v_id": "4",
"v_type": "SocialUser",
"attributes": {
"name": "paul",
"isActive": true,
"registration_timestamp": 144000000
}
},
{
"v_id": "6",
"v_type": "SocialUser",
"attributes": {
"name": "peter",
"isActive": true,
"registration_timestamp": 146000000
}
},
{
"v_id": "5",
"v_type": "SocialUser",
"attributes": {
"name": "steven",
"isActive": false,
"registration_timestamp": 145000000
}
},
{
"v_id": "9",
"v_type": "SocialUser",
"attributes": {
"name": "thomas",
"isActive": true,
"registration_timestamp": 149000000
}
}
]
}
GET /graph/graph_name/edges
This endpoint returns all edges which connect to a given vertex ID in the graph called graph_name . 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.
source_vertex_type: 源点，如VidUser
source_vertex_id: 源点ID,如 0
edge_type: 边的类型，如User_Video
target_vertex_type: 目标点，如 User
target_vertex_id: 目标点ID ,如Video
sort: 通过筛选的attributes的属性进行排序
curl -X GET 'http://172.16.0.222:9000/graph/edges/VidUser/0/User_Video/Video' | jq .
{
"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
}
}
]
}
count_only、limit、select、sort、timeout 跟/graph/vertices一样
/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/vertices
graph_name: 图分组名称
vertex_type: 点的类型名称。目前demo:User Page Product DescWord NameUser VidUser Video AttributeTag Person SocialUser
vertex_id: 点的ID类型
This endpoint deletes the given vertex(vertices) in the graph called graph_name . The URL is exactly the same as 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.
Example:
curl -X DELETE "http://172.16.0.222:9000/graph/vertices/User/id64" | jq .
{
"version": {
"api": "v2",
"schema": 0
},
"error": false,
"message": "",
"results": {
"v_type": "User",
"deleted_vertices": 1
}
}
DELETE /graph/edges
source_vertex_type: 源点，如VidUser
source_vertex_id: 源点ID,如 0
edge_type: 边的类型，如User_Video
target_vertex_type: 目标点，如 User
target_vertex_id: 目标点ID ,如Video
sort: 通过筛选的attributes的属性进行排序
Example:
curl -X DELETE "http://172.16.0.222:9000/graph/edges/VidUser/0/User_Video/Video" | jq .
{
"version": {
"api": "v2",
"schema": 0
},
"error": false,
"message": "",
"results": [
{
"e_type": "User_Video",
"deleted_edges": 3
}
]
}
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/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:
- Select: Specify which attributes to be returned (GET only).
- Filter: Apply a filter on the vertices or edges, based on their attribute values.
- Limit: Limit the total number of vertices or edges.
- Sort: Sort the data. (For DELETE, sort should be used with limit together.)
- 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/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.
http://server_ip:9000/graph/graph_name/vertices?select=attr1,attr2returns only attributesattr1andattr2http://server_ip:9000/graph/graph_name/vertices?select=-attr1,-attr 2returns all attributes except attributesattr1andattr2http://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.
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:
-
=equal to -
!=not equal to -
>greater than -
>=greater than or equal to -
>less than -
<=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://172.16.0.222:9000/graph/vertices/User?filter=age>=30"
{"version":{"api":"v2","schema":0},"error":false,"message":"","results":[{"v_id":"id2","v_type":"User","attributes":{}},{"v_id":"id14","v_type":"User","attributes":{}},{"v_id":"id58","v_type":"User","attributes":{}}]}
1162
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
