TuGraph RESTful API Legacy

This document describes how to call the Rest API of TuGrpah.

1.Introduction

TuGraph provides HTTP RESTful APIs, which allow users to access TuGraph servers through HTTP requests remotely.

This document specifiers the TuGraph HTTP RESTful API.

:warning: All the other RESTful APIs excluding the three below will be deprived after 4/30/2023.

  • Login

  • Query

  • Store Procedures

2.Protocols And Data Format

2.1.Protocols

Both HTTP and HTTPS protocols are supported by TuGraph. The system uses HTTP protocol by default. To use HTTPS, the ssl_auth option should be set to true in the DB configuration.

2.2.Request

TuGraph supports HTTP GET/POST/PUT/DELETE requests, in which:

  • GET requests are used for read-only requests, such as getting vertex properties, edge properties, etc.

  • POST requests are used to create entities, submit Cypher, and to manage and call stored procedures;

  • PUT requests are used to modify existing entities, for example, to modify vertex properties, edge properties, etc.

  • DELETE requests are used to delete existing entities, such as vertices, edges, etc.

In high-availability mode, users can set ServerVersion in the request header to make sure the request is never served with an outdated version. The current ServerVersion can be obtained from the header returned by the server.

2.3.Response

TuGraph returns the following HTTP status codes:

  • 200 OK: operation is successful.

  • 307 Temporary Redirect: the operation is redirected, typically in high-availability mode, to the master.

  • 400 Bad Request: incorrect input, such as URI error, or invalid parameters.

  • 500 Internal Server Error: server error.

When the operation is successful, the JSON response contains the return value of the operation. When the operation is redirected, the location field in the returned HTTP header contains the redirect destination address. When an input error or server error occurs, the JSON response contains a error_message field that describes the error.

In high-availability mode, the server will set server_version field in the header to inform the client of the data version of the current server. When clients switch between several different servers, this version number guarantees that the client will not read from an outdated server.

2.4.Data Format

The server and clients exchange data in JSON format. When sending a request, the header of the HTTP request should be set with Accept:application/json, Content-Type:app/json. For example, to create a new vertex, the request header should look like the following:

    Accept: application/json; charset=UTF-8
    Content-Type: application/json
    server_version: 12

2.5.URI Format

TuGraph REST API provides access to: web visualization, login, db info, label, index, node, relationship, cypher, task, cpp_plugin, and python_plugin. The URI format used for each function is as follows:

URI

Description

/web

web visualization

/cypher

cypher request

/acl

access control

/user

user management

/login

user login

/info

database status and information

/task

task management

/db

subgraph management

For each subgraph, the following interfaces are provided:

URI

Description

/db

create, modify, and delete subgraph

/db/{graph_name}/node

vertex operations

/db/{graph_name}/relationship

edge operations

/db/{graph_name}/label

label-related operations

/db/{graph_name}/index

index-related operations

/db/{graph_name}/cypher

subgraph-specific cypher operation

/db/{graph_name}/cpp_plugin

C++ plugin(stored procedure)

/db/{graph_name}/python_plugin

Python plugin(stored procedure)

/db/{graph_name}/import

online import

/db/{graph_name}/misc

other operations

3.Login

The system creates an administrator by default, whose username is admin and password is 73@TuGraph. For security reasons, please remember to change your password after first starting the server.

3.1.User Login

TuGraph provides JWT-based user authentication. To log in to the server, the REST client should send a login request containing a username and password. Upon success, the client will receive a signed token in the form of a Json Web Token (JWT) and a Boolean variable (default_password) to determine whether it is the default password. The jwt token should be stored by the client and used for each subsequent request.

  • URI: /login

  • METHOD: POST

  • REQUEST:

Field

Description

Type

user

username

String

password

password

String

  • RESPONSE:

Field

Description

Type

jwt

token

String

default_password

whether it is the default password

Bool

Example Request:

    • POST http://localhost:7070/login
    • Accept: application/json; charset=UTF-8
    • Content-Type: application/json; charset=UTF-8
    Input:
    {
      "user":"admin",
      "password":"73@TuGraph"
    }

Example Response:

    • 200: OK
    Output:
    {
        "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhZG1pbiI6dHJ1ZSwiaXNzIjoiZm1hLmFpIiwidXNlcl9pZCI6ImFkbWluIn0.SHaqrjKLaI4byjbEYVAH4D88dOTD_zYQ_uAvdizTMek",
        "default_password": true
    }

3.2.Token Refresh

After the token expires, the front-end initiates a refresh token interface, and the back-end verifies the validity of the token. If the verification passes, a new token is generated; if the verification fails, status code 401 is returned.

  • URI: /refresh

  • METHOD: POST

  • REQUEST:

Field

Description

Type

Authorization

token

String

  • RESPONSE:

Field

Description

Type

jwt

token

String

Example Request:

    • POST http://localhost:7070/refresh
    • Accept: application/json; charset=UTF-8
    • Content-Type: application/json; charset=UTF-8
    Input:
    {
        "Authorization": "Bearer eyJhbGciOiJIUz32NiIsInR5cCI6IkpXVDJ9.eyJhZG1pbiI6dHJ1ZSwiaXNzIjoiZm1hLmFpIiwidXNlcl9pZCI6ImFkbWluIn0.SHaqrjKLaI4byj3fYVAH4D88dfTD_zYQ_uAvdizTMek"
    }

Example Response:

    • 200: OK
    Output:
    {
        "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhZG1pbiI6dHJ1ZSwiaXNzIjoiZm1hLmFpIiwidXNlcl9pZCI6ImFkbWluIn0.SHaqrjKLaI4byjbEYVAH4D88dOTD_zYQ_uAvdizTMek"
    }

3.3.Modify Token Validity Period

To modify the validity period of Token, three parameters need to be transmitted: jwt, refresh_time and expire_time, among which jwt is used to verify the user’s identity. When refresh_time and expire_time are equal to 0, the validity period is indefinite. When refresh_time exceeds, you need to call the refresh interface to obtain a new Token; When expire_time expires, you need to log in again. (This interface call needs to confirm the security by itself, do not call unless necessary)

  • URI: /update_token_time

  • METHOD: POST

  • REQUEST:

Field

Description

Type

Authorization

token

String

refresh_time

Valid time (deafult set to 0)

Int64

expire_time

Expire time (deafult set to 0)

Int64

  • RESPONSE: if successful, return status code 200.

Example request.

    • POST http://localhost:7070/update_token_time
    • Accept: application/json; charset=UTF-8
    • Content-Type: application/json; charset=UTF-8
    Input:
    {
        "Authorization" : "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJmbWEuYWkiLCJwYXNzd29yZCI6IjczQFR1R3JhcGgiLCJ1c2VyIjoiYWRtaW4ifQ.o_yb5veSJkuy-ieBp4MqTk-tC1grcKotgVbgNJ0TyTU",
        "refresh_time":0
        "expire_time":0
    }

Example response.

    • 200: OK

3.4.Query Token validity period

To query the validity period of the Token, you need to transmit jwt to verify the user’s identity, and return, refresh_time and expire_time, where refresh_time indicates the refresh time, and you need to call the refresh interface to obtain a new Token when it exceeds; expire_time indicates the expiration time, and you need to log in again when it exceeds.

  • URI: /get_token_time

  • METHOD: POST

  • REQUEST:

Field

Description

Type

Authorization

token

String

  • RESPONSE: if successful, return “refresh_time” and “expire_time”.

Example request.

    • POST http://localhost:7070/get_token_time
    • Accept: application/json; charset=UTF-8
    • Content-Type: application/json; charset=UTF-8
    Input:
    {
        "Authorization" : "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJmbWEuYWkiLCJwYXNzd29yZCI6IjczQFR1R3JhcGgiLCJ1c2VyIjoiYWRtaW4ifQ.o_yb5veSJkuy-ieBp4MqTk-tC1grcKotgVbgNJ0TyTU",
    }

Example response.

    • 200: OK
    Output:
    {
        "refresh_time":600,
        "expire_time":3600
    }

3.5.Logout

The user logs out and deletes the token at the same time.

  • URI: /logout

  • METHOD: POST

  • REQUEST:

Field

Description

Type

Authorization

token

String

  • RESPONSE: if successful, return status code 200.

Example Request:

    • POST http://localhost:7070/refresh
    • Accept: application/json; charset=UTF-8
    • Content-Type: application/json; charset=UTF-8
    Input:
    {
        "Authorization" : "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJmbWEuYWkiLCJwYXNzd29yZCI6IjczQFR1R3JhcGgiLCJ1c2VyIjoiYWRtaW4ifQ.o_yb5veSJkuy-ieBp4MqTk-tC1grcKotgVbgNJ0TyTU"
    }

Example Response:

    • 200: OK

4.Query

URI format is:

    http://{host}:{port}/cypher

4.1.Call Cypher

  • URI: /cypher

  • METHOD: POST

  • REQUEST:

Field

Description

Type

graph

subgraph name

String

cypher

Cypher query

String

  • RESPONSE:

Field

Description

Type

result

running results

List

elapsed

running time in seconds

Float

header

header of the results

List

size

number of results

Integer

in which header is a list with each element in the form of:

Field

Description

Type

name

the name of column

String

type

column data type, 0 is scalar, 1 is vertex id, 2 is vector

Example Request:

    • POST http://localhost:7070/cypher
    • Accept: application/json; charset=UTF-8
    • Content-Type: application/json; charset=UTF-8
    Input:
    {
        "graph": "default",
        "script": "MATCH (n) RETURN n,n.name LIMIT 10"
    }

Example Response:

    • 200: OK
    Output:
    {
        "elapsed": 0.001224517822265625,
        "header": [
            {
                "name": "n",
                "type": 1
            },
            {
                "name": "n.name",
                "type": 0
            }
        ]
        "result": [
            [
                0,
                "Rachel Kempson"
            ],
            [
                1,
                "Michael Redgrave"
            ],
            [
                2,
                "Vanessa Redgrave"
            ]
        ],
        "size": 3
    }

4.2.Call Cypher with Parameters

Cypher supports querying with parameters. When a Cypher query with parameters is called, TuGraph caches the execution plan for that query to speed up the following queries of the same kind.

  • URI: /cypher

  • METHOD: POST

  • REQUEST:

Field

Description

Type

graph

subgraph name

String

cypher

Cypher query

String

parameters

parameters

List

  • RESPONSE:

Same as Call Cypher.

Example Request:

    • POST http://localhost:7070/db/graph1/cypher
    • Accept: application/json; charset=UTF-8
    • Content-Type: application/json; charset=UTF-8
    Input:
    {
      "graph": "default",
      "script": "MATCH (n:Person {name:$param1}) RETURN n.birthyear",
      "parameters": {
        "$param1": "Lindsay Lohan"
      }
    }

Example Response:

    • 200: OK
    Output:
    {
        "elapsed": 0.005886077880859375,
        "header": [
            {
                "name": "n.birthyear",
                "type": 0
            }
        ],
        "result": [
            [
                1986
            ]
        ],
        "size": 1
    }

5.Stored Procedures

URI format is:

    http://{host}:{port}/db/{graph_name}/cpp_plugin|python_plugin

5.1.Create Stored Procedure

  • URI: /db/{graph_name}/cpp_plugin|python_plugin

  • METHOD: POST

  • REQUEST:

Field

Description

Type

name

name of the plugin

String

description

description of the plugin

String

code_base64

code of plugin encoded in base64

String

read_only

whether it is a read-only stored procedure

Bool

code_type

type of plugin code, can be zip/cpp/so for cpp_plugin, while py for python_plugin

String

Note: read-only plugins are more efficient than write plugins. Always specify read-only=true for read-only transactions.

  • RESPONSE: if successful, return status code 200.

Example Request:

    • POST http://localhost:7070/db/graph1/cpp_plugin
    • Accept: application/json; charset=UTF-8
    • Content-Type: application/json; charset=UTF-8
    Input:
    {
        "name" : "echo",
        "description" : "A test plugin that returns the input",
        "code_base64" : "{base64 encoded echo.so}",
        "read_only" : true,
        "code_type" : "zip"
    }

Example Response:

    • 200: OK

5.2.List Stored Procedures

  • URI: /db/{graph_name}/cpp_plugin|python_plugin

  • METHOD: GET

  • RESPONSE: A list in which each element is a plugin description, in the format of:

Field

Description

Type

name

name of the stored procedure

String

description

description of the stored procedure

String

read_only

whether the stored procedure is read-only

Bool

Example Request:

    • GET http://localhost:7070/db/graph1/cpp_plugin
    • Accept: application/json; charset=UTF-8

Example Response:

    • 200: OK
    Output:
    {
        [
            {
                "description":"adds a vertex label to the db",
                "name":"add_label",
                "read_only":false
            },
            {
                "description": "scans graph and get number of edges",
                "name": "scan_graph",
                "read_only": true
            }
        ]
    }

5.3.Retrieve Stored Procedure Detail

  • URI: /db/{graph_name}/cpp_plugin|python_plugin/{plugin_name}

  • METHOD: GET

  • RESPONSE: Procedure detail, including code, in the format of:

Field

Description

Type

name

Procedure name

String

description

Procedure descrition

String

read_only

Read only or not

Bool

code_base64

存储过程的代码

String, Base64 encoded

code_type

Type of procedue code, can be zip/cpp/so for cpp_plugin, while py for python_plugin

String

Example request.

    • GET http://localhost:7070/db/graph1/cpp_plugin/echo
    • Accept: application/json; charset=UTF-8

Example response.

    • 200: OK
    Output:
    {
        "name" : "echo",
        "description" : "A test plugin that returns the input",
        "code_base64" : "{base64 encoded echo.zip}",
        "read_only" : true,
        "code_type" : "zip"
    }

5.4.Call Stored Procedure

  • URI: /db/{graph_name}/cpp_plugin|python_plugin/{plugin_name}

  • METHOD: POST

  • REQUEST: String input.

Field

Description

Type

data

input data

String

timeout

timeout in seconds, defaults to 0, which means no timeout

Float

  • RESPONSE:

Field

Description

Type

result

running results

String

Example Request:

    • POST http://localhost:7070/db/graph1/python_plugin/echo
    • Accept: application/json; charset=UTF-8
    • Content-Type: application/json; charset=UTF-8
    Input:
    {
        data : "Hello!\n你好!\nKonichiwa!",
        timeout : 0,
        in_process : true
    }

Example Response:

    • 200: OK
    Output:
    {
      "result": "Hello!\n你好!\nKonichiwa!"
    }

5.5.Delete Stored Procedure

  • URI: /db/{graph_name}/cpp_plugin|python_plugin/{plugin_name}

  • METHOD: DELETE

  • RESPONSE: if successful, return status code 200.

Example Request:

    • DELETE http://localhost:7070/db/graph1/cpp_plugin/example_plugin
    • Accept: application/json; charset=UTF-8

Example Response:

    • 200: OK

6.Deprecated

The APIs below will be removed after 4/30/2023.

6.1.User Management

6.1.1.Add User

Add a new user and set the initial password for the user. Only administrators have permission to add new users. The username can only have letters, numbers, and underscores, and should not begin with a number. The password can contain any character. The username and password have a maximum length of 64 bytes.

  • URI: /user

  • METHOD: POST

  • REQUEST:

Field

Description

Type

user

username

String

password

password

String

is_admin

whether the user is an administrator or not

Bool

  • RESPONSE: if successful, return status code 200.

Example Request:

    • POST http://localhost:7070/user
    • Accept: application/json; charset=UTF-8
    • Content-Type: application/json; charset=UTF-8
    • Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhZG1pbiI6dHJ1ZSwiaXNzIjoiZm1hLmFpIiwidXNlcl9pZCI6ImFkbWluIn0.SHaqrjKLaI4byjbEYVAH4D88dOTD_zYQ_uAvdizTMek
    Input:
    {
        "user": "USER1",
        "password": "AN_INITIAL_PASSWORD",
        "is_admin": false
    }

Example Response:

    • 200: OK

6.1.2.Change Password

Users can change their own passwords, in which case the original password needs to be verified.

Administrators can change the passwords of any user and promote non-admin users to administrators, or demote administrator users to regular users. When modifying another user’s password, the original password of the user is not needed.

  • URI: /user/{user_name}

  • METHOD: PUT

  • REQUEST:

Field

Description

Type

current_password

user’s current password, if modifying its own password

String

new_password

user’s new password

String

is_admin

should this user be administrator or not, used when promoting or demoting users

Bool

  • RESPONSE: if successful, return status code 200.

Example Request:

    • POST http://localhost:7070/user/user1
    • Accept: application/json; charset=UTF-8
    • Content-Type: application/json; charset=UTF-8
    • Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhZG1pbiI6dHJ1ZSwiaXNzIjoiZm1hLmFpIiwidXNlcl9pZCI6ImFkbWluIn0.SHaqrjKLaI4byjbEYVAH4D88dOTD_zYQ_uAvdizTMek
    Input:
    {
        "current_password": "THE_CURRENT_PASSWORD"
        "new_password": "A_NEW_PASSWORD"
        "is_admin": true
    }

Example Response:

    • 200: OK

6.1.3.List All Users

List all users of the database. Only administrators are allowed to perform this operation.

  • URI: /user/

  • METHOD: GET

  • RESPONSE: a dictionary of {user_name:is_admin}

Example Request:

    • GET http://localhost:7070/user
    • Accept: application/json; charset=UTF-8
    • Content-Type: application/json; charset=UTF-8
    • Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhZG1pbiI6dHJ1ZSwiaXNzIjoiZm1hLmFpIiwidXNlcl9pZCI6ImFkbWluIn0.SHaqrjKLaI4byjbEYVAH4D88dOTD_zYQ_uAvdizTMek

Example Response:

• 200: OK
Output:
{
    "admin": true,
    "guest1": false
}

6.1.4.Delete User

Delete a user from the DB. Only administrators have permission to do so.

  • URI: /user/{user_name}

  • METHOD: DELETE

  • RESPONSE: if successful, return status code 200.

Example Request:

    • DELETE http://localhost:7070/user/guest1
    • Accept: application/json; charset=UTF-8
    • Content-Type: application/json; charset=UTF-8
    • Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhZG1pbiI6dHJ1ZSwiaXNzIjoiZm1hLmFpIiwidXNlcl9pZCI6ImFkbWluIn0.SHaqrjKLaI4byjbEYVAH4D88dOTD_zYQ_uAvdizTMek

Example Response:

    • 200: OK

6.2.Access Control

TuGraph has four access levels. Different users can have different permissions for each subgraph. The four access levels are as follows:

Access Level

Description

NONE

no access

READ

read-only

WRITE

can read and write vertexes and edges of the subgraph

FULL

full access, including changing metadata (label, index), managing stored procedures and deleting all data in the subgraph

Administrators have full access on all subgraphs, and a newly created non-admin user does not have access for any subgraph. Users who have full access on a subgraph can set the access level for other users on that subgraph.

6.2.1.Query User’s Access Level

  • URI: /acl/?user={user_name}&graph={graph_name}

  • METHOD: GET

  • RESPONSE:

When both user and graph are specified, the user’s access level for the subgraph is returned, such as READ.

When only user is specified, all subgraphs that the user can access (access level not NONE) are returned, as well as the user’s access level on the subgraph.

When only graph is specified, all users who have access level on this graph (excluding administrators, who have implicit FULL access) and their access levels are returned. This operation requires administrator permission.

Example Request:

    • GET http://localhost:7070/acl/?user=user1
    • Accept: application/json; charset=UTF-8
    • Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhZG1pbiI6dHJ1ZSwiaXNzIjoiZm1hLmFpIiwidXNlcl9pZCI6ImFkbWluIn0.SHaqrjKLaI4byjbEYVAH4D88dOTD_zYQ_uAvdizTMek

Example Response:

    • 200: OK
    • Content-Type: application/json; charset=UTF-8
    Output:
    {
      "graph1": "READ",
      "graph2": "WRITE",
      "graph3": "FULL"
    }

6.2.2.Change User’s Access Level

  • URI: /acl

  • METHOD: PUT

  • REQUEST:

Field

Description

Type

user

username

String

graph

subgraph’s name

String

acl

access level

String

  • RESPONSE: if successful, return status code 200.

Example Request:

    • PUT http://localhost:7070/acl
    • Accept: application/json; charset=UTF-8
    • Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhZG1pbiI6dHJ1ZSwiaXNzIjoiZm1hLmFpIiwidXNlcl9pZCI6ImFkbWluIn0.SHaqrjKLaI4byjbEYVAH4D88dOTD_zYQ_uAvdizTMek
    Input:
    {
        "user": "user1",
        "graph": "graph1",
        "acl": "FULL"
    }

Example Response:

    • 200: OK

6.2.3.Remove User’s Access Right

This is equivalent to setting access level to NONE.

  • URI: /acl/?user={user_name}&graph={graph_name}

  • METHOD: DELETE

  • RESPONSE: if successful, return status code 200.

Example Request:

    • DELETE http://localhost:7070/acl/?user=user1&graph=graph1
    • Accept: application/json; charset=UTF-8
    • Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhZG1pbiI6dHJ1ZSwiaXNzIjoiZm1hLmFpIiwidXNlcl9pZCI6ImFkbWluIn0.SHaqrjKLaI4byjbEYVAH4D88dOTD_zYQ_uAvdizTMek

Example Response:

    • 200: OK

6.3.Server Status

6.3.1.Modify Server Configuration

Modifying the server configuration will take effect immediately after the configuration modification and will affect all servers. These configurations take precedence over configuration files and command line arguments.

  • URI: /config

  • METHOD: PUT

  • REQUEST:

    Field

    Description

    Type

    db_async

    Whether to enable asynchronous mode

    Bool

    optimistic_txn

    Whether to use optimistic transaction lock by default

    Bool

    enable_audit_log

    Whether to enable audit logging

    Bool

  • RESPONSE: If successful, return status code 200.

Example request.

    • PUT http://localhost:7070/config
    • Accept: application/json; charset=UTF-8
    • Content-Type: application/json
    Input:
    {
        "db_async": true,
        "enable_audit_log": false
    }

Example response.

    • 200: OK

6.3.2.Current Server Status

  • URI: /info

  • METHOD: GET

  • RESPONSE:

Field

Description

Type

lgraph_version

TuGraph version

String

git_branch

server’s git branch

String

git_commit

server’s git commit version

String

web_commit

web client commit version

String

cpp_id

cpp compiler id

String

cpp_version

cpp compiler version

String

python_version

python lib version

String

cpu

cpu information

Dictionary, format refers CPU Status

disk

disk IO information

Dictionary, format refers Disk Status

memory

memory information

Dictionary, format refers Memory Status

db_space

graph database storage

Dictionary, format refers Graph Database Storage

db_config

graph database configuration

Dictionary, format refers Graph Database Configuration

up_time

database’s online running time

Integer

Example Request:

    • GET http://localhost:7070/info
    • Accept: application/json; charset=UTF-8

Example Response:

    • 200: OK
    • Content-Type: application/json; charset=UTF-8
    Output:
    {
      "lgraph_version": "1.2.0",
      "git_branch": "master",
      "git_commit": "9e2977d",
      "web_commit": "1e2823d",
      "cpu_id": "GUN",
      "cpu_version": "4.8.5",
      "python_version": "3.2",
      "node": "/node",
      "relationship": "/relationship",
      "cpu": {
        "self": 25,
        "server": 35,
        "unit": "%"
      },
      "disk": {
        "read": 2000,
        "write": 2000,
        "unit": "B/s"
      },
      "memory": {
        "self": 25016,
        "server_avail": 46865636,
        "server_total": 65860552,
        "unit": "KB"
      },
      "db_space": {
        "space": 57344,
        "unit": "B"
      },
      "db_config": {
        "db_async": false,
        "disable_auth": false,
        "enable_ha": false,
        ...
      },
      "up_time": 3235
    }

6.3.3.CPU Status

  • URI: /info/cpu

  • METHOD: GET

  • RESPONSE:

Field

Description

Type

self

TuGraph CPU usage

Integer

server

server’s CPU usage

Integer

unit

metric unit

String

Example Request:

    • GET http://localhost:7070/info/cpu
    • Accept: application/json; charset=UTF-8

Example Response:

    • 200: OK
    • Content-Type: application/json; charset=UTF-8
    Output:
    {
      "self": 25,
      "server": 35,
      "unit": "%"
    }

6.3.4.Disk Status

  • URI: /info/disk

  • METHOD: GET

  • RESPONSE:

Field

Description

Type

read

server’s disk read rate

Integer

write

server’s disk wrtie rate

Integer

unit

metric unit

String

Example request.

    • GET http://localhost:7070/info/disk
    • Accept: application/json; charset=UTF-8

Example response.

    • 200: OK
    • Content-Type: application/json; charset=UTF-8
    Output:
    {
      "read": 2000,
      "write": 2000,
      "unit": "B/s"
    }

6.3.5.Memory Status

  • URI: /info/memory

  • METHOD: GET

  • RESPONSE:

Field

Description

Type

self

TuGraph memory usage

Integer

server_avail

server’s available memory

Integer

server_total

server’s total memory

Integer

unit

metric unit

String

Example Request:

    • GET http://localhost:7070/info/memory
    • Accept: application/json; charset=UTF-8

Example Response:

    • 200: OK
    • Content-Type: application/json; charset=UTF-8
    Output:
    {
      "self": 25016,
      "server_avail": 46865636,
      "server_total": 65860552,
      "unit": "KB"
    }

6.3.6.Database Size

  • URI: /info/db_space

  • METHOD: GET

  • RESPONSE:

Field

Description

Type

space

total size of the database

Integer

unit

metric unit

String

Example Request:

    • GET http://localhost:7070/info/db_space
    • Accept: application/json; charset=UTF-8

Example Response:

    • 200: OK
    • Content-Type: application/json; charset=UTF-8
    Output:
    {
      "space": 57344,
      "unit": "B"
    }

6.3.7.DB Configuration

  • URI: /info/db_config

  • METHOD: GET

  • RESPONSE:

Field

Description

Type

async

asynchronous mode

Bool

disable_auth

whether to disable authentication

Bool

enable_ha

whether to enable high-availability mode

Bool

enable_rpc

whether to enable RPC server

Bool

host

bound host address

String

port

port of REST server

Integer

rpc_port

port of RPC server

Integer

thread_limit

limit of available threads for the graph database

Integer

use_ssl

whether to use SSL for authentication

Bool

verbose

verbose level of the output

Integer

Example Request:

    • GET http://localhost:7070/info/db_config
    • Accept: application/json; charset=UTF-8

Example Response:

    • 200: OK
    • Content-Type: application/json; charset=UTF-8
    Output:
    {
      "async":false,
      "disable_auth":false,
      "enable_ha":false,
      "enable_rpc":false,
      "host":"127.0.0.1",
      "port":7070,
      "rpc_port":9091,
      "thread_limit":0,
      "use_ssl":false,
      "verbose":2
    }

6.3.7.High Availability Server List

Get a list of replication servers. Valid only in high-availability mode.

  • URI: /info/peers

  • METHOD: GET

  • RESPONSE: if successful, return status code 200 and a list of server information, each of server information is formatted as:

Field

Description

Type

rpc_address

server’s RPC address

String

rest_address

server’s REST address

String

state

server state

String

The server state can be MASTER, SLAVE, or OFFLINE.

Example Request:

    • GET http://localhost:7070/info/peers
    • Accept: application/json; charset=UTF-8

Example Response:

    • 200: OK
    • Content-Type: application/json; charset=UTF-8
    Output:
    {
      [
          {
              "rest_address":"192.168.1.22:17071",
              "rpc_address":"192.168.1.22:19091",
              "state":"MASTER"
          },
          {
              "rest_address":"192.168.1.22:17072",
              "rpc_address":"192.168.1.22:19092",
              "state":"SLAVE"
          }
      ]
    }

6.3.8.Current Leader Information

Get information of current leader. Valid only in HA mode.

  • URI: /info/leader

  • METHOD: GET

  • RESPONSE: if successful, return status code 200 and the current leader server information, which is formatted as:

Field

Description

Type

rpc_address

server’s RPC address

String

rest_address

server’s REST address

String

Example Request:

    • GET http://localhost:7070/info/leader
    • Accept: application/json; charset=UTF-8

Example Response:

    • 200: OK
    • Content-Type: application/json; charset=UTF-8
    Output:
    {
      "rest_address":"192.168.1.22:17071",
      "rpc_address":"192.168.1.22:19091"
    }

6.3.9.Server Statistics

  • URI: /info/statistics

  • METHOD: GET

  • RESPONSE: if successful, return status code 200 and the current server statistics, which is formatted as:

Field

Description

Type

requests/second

number of requests processed per second

Float

writes/second

number of write requests processed per second

Float

running_tasks

number of requests in progress

Integer

failure_rate

request failure rate

Float

Example Request:

    • GET http://localhost:7070/info/statistics
    • Accept: application/json; charset=UTF-8

Example Response:

    • 200: OK
    • Content-Type: application/json; charset=UTF-8
    Output:
    {
        "failure_rate": 0.023,
        "requests/second": 122.3,
        "running_tasks": 10,
        "writes/second": 12.4
    }

6.3.10.Get Audit Logs

  • URI: /info/log/?begin_time={begin_time}&end_time={end_time}&user={user}&num_log={num_log}&descending_order={descending_order}

Field

Description

Type

begin_time

start time of the queried log (required, format YYYY-mm-dd HH:MM:SS)

Timestamp

end_time

end time of the queried log (default is current time, format YYYY-mm-dd HH:MM:SS)

Timestamp

user

the operator of the queried log (administrator can query all users’ logs, ordinary users can only query their own logs)

String

num_log

maximum number of logs to return (default 100)

Integer

descending_order

whether to sort the result in descending order(default is true)

Bool

  • METHOD: GET

  • RESPONSE: if successful, return status code 200 and a list of audit logs, each of which is an action log in the format of:

Field

Description

Type

index

the index of the operation

Integer

begin_time

the start time of the operation

String

end_time

the end time of the operation

String

user

the user of the operation

String

graph

the graph of the operation

String

type

the type of the operation

String

read_write

the operation is read operation or write operation

String

success

whether the operation is successful

Bool

content

the content of the operation

String

Example Request:

    • GET http://localhost:7070/info/log/?begin_time=2020-02-17%2015:00:00&end_time=2020-02-20%2012:00:00&user=admin&num_log=100&descending_order=false
    • Accept: application/json; charset=UTF-8

Example Response:

    • 200: OK
    • Content-Type: application/json; charset=UTF-8
    Output:
    {
        [
            {
                "begin_time": "2020-02-17 15:27:15",
                "content": "post /login    Successful",
                "end_time": "2020-02-17 15:27:15",
                "graph": "",
                "index": 1,
                "read_write": "read",
                "success": true,
                "type": "Security",
                "user":"admin"
            },
            {
                "begin_time": "2020-02-17 15:27:15",
                "content": "Load plugin : `echo`    Successful",
                "end_time": "2020-02-17 15:27:15",
                "graph": "default",
                "index": 2,
                "read_write": "write",
                "success": true,
                "type": "Plugin",
                "user": "admin"
            },
            ...
        ]
    }

6.4.Task Management

TuGraph tracks long-running tasks such as complex Cypher queries and plugins. Administrators can query currently running tasks through the REST API and choose to abort the queries if necessary.

The URI format for task management is :

    http://{host}:{port}/task/{task_id}

6.4.1.List Running Tasks

  • URI: /task

  • METHOD: GET

  • RESPONSE:

The returned JSON is an array, each of which is formatted as follows:

Field

Description

Type

description

the description of the task

String

time_elapsed

time the task has been executing for, in seconds

Float

task_id

the ID of the task

String

Example Request:

    • GET http://localhost:7070/task
    • Accept: application/json; charset=UTF-8

Example Response:

    • 200: OK
    • Content-Type: application/json; charset=UTF-8
    Output:
    {
        [
            {
                "description" : "[CPP_PLUGIN] scan_graph",
                "time_elapsed" : 13.987,
                "task_id" : "3_10"
            },
            {
                "description" : "[CYPHER] MATCH(n) return n",
                "time_elapsed" : 30.887,
                "task_id" : "2_6"
            }
        ]
    }

6.4.2.Abort Task

  • URI: /task/{task_id}

Where task_id is the task_id returned by GET /task .

  • METHOD: DELETE

  • RESPONSE: if successful, return status code 200.

Example Request:

    • DELETE http://localhost:7070/task/3_10
    • Accept: application/json; charset=UTF-8

Example Response:

    • 200: OK

6.5.Subgraph Management

TuGraph supports multiple subgraphs and all subgraphs are completely independent from others. Different subgraphs can have different permissions to different users. Administrators can add, modify and delete subgraphs.

6.5.1.Create New Subgraph

  • URI: /db

  • METHOD: POST

  • REQUEST:

Field

Description

Type

name

the name of subgraph

String

config

the configuration of subgraph

Dictionary, in the format of {{column name 1}:{column value 1},…}

  • RESPONSE: if successful, return status code 200.

Example Request:

    • POST http://localhost:7070/db
    • Accept: application/json; charset=UTF-8
    • Content-Type: application/json
    Input:
    {
        "name":"graph1"
        "config" : {
            "max_size_GB":2048,
            "async":True
        }
    }

Example Response:

    • 200: OK

6.5.2.Delete Subgraph

  • URI: /db/{graph_name}

  • METHOD: DELETE

  • RESPONSE: if successful, return status code 200.

Example Request:

    • DELETE http://localhost:7070/db/graph1

Example Response:

    • 200: OK

6.5.3.List All Subgraphs

  • URI: /db

  • METHOD: GET

  • RESPONSE: The list of all subgraphs.

Example Request:

    • GET http://localhost:7070/db

Example Response:

    • 200: OK
    • Content-Type: application/json; charset=UTF-8
    Output:
    {
        "graph1": {
            "max_size_gb":1024,
            "async":false
        }
    }

6.6.Label

TuGraph is a strong-schema database. In each subgraph, each vertex and edge need to have a predefined data format. The data format is determined by Label. Users can use the REST API to add, delete, and query labels and their corresponding data format.

The URI format of the Label operation is

    http://{host}:{port}/db/{graph_name}/label/{type}/{label_name}

Where the {type} can be node or relationship.

6.6.1.Create Label

A label is created with a fixed data format. A label must be defined before any node or relationship can be created with that label.

  • URI: /db/{graph_name}/label

  • METHOD: POST

  • REQUEST:

Field

Description

Type

name

the name of label

String

fields

data column definition

List

is_vertex

whether it is a vertex Label

Bool

primary

vertex primary property

String

edge_constraints

edge constraints

List

primary should be set when is_vertex is true. This field is only available for Vertex, and must be set when creating Vertex.

edge_constraints could be set when is_vertex is false, This field is only available for Edge. This field limits the combination of starting and ending vertex of the edge, for example: [["vertex_label1","vertex_label2"],["vertex_label3","vertex_label4"]], which limits the edge direction can only be from vertex_label1 to vertex_label2 or from vertex_label3 to vertex_label4. If you don’t want to have any constraints, just leave this field unset.

In which fields is an array, in which each element defines a column of data, as follows:

Field

Description

Type

name

the name of the column

String

type

the data type of the column

String, with following types: int8, int16, int32, int64, float, double, string, date, datetime, binary, blob

optional

whether the data can be empty (optional, default is false)

Bool

  • RESPONSE: if successful, return status code 200.

Example Request:

    • POST http://localhost:7070/db/{graph_name}/label
    • Accept: application/json; charset=UTF-8
    • Content-Type: application/json
    Input:
    {
        "name":"Actor",
        "fields": [
                {"name":"uid", "type":"int64", "optional":false},
                {"name":"name", "type":"string", "optional":true}
        ],
        "is_vertex":true,
        "primary" : "uid"
    }

Example Response:

    • 200: OK

6.6.2.List All Labels

  • URI: /db/{graph_name}/label

  • METHOD: GET

  • RESPONSE:

Field

Description

Type

edge

the list of edge labels

List

vertex

the list of vertex labels

List

Example Request:

    • GET http://localhost:7070/db/{graph_name}/label
    • Accept: application/json; charset=UTF-8

Example Response:

    • 200: OK
    • Content-Type: application/json; charset=UTF-8
    Output:
    {
        "edge": [
            "HAS_CHILD",
            "MARRIED",
            "BORN_IN",
            "DIRECTED",
            "WROTE_MUSIC_FOR",
            "ACTED_IN"
        ],
        "vertex": [
            "Person",
            "City",
            "Film"
        ]
    }

6.6.3.Get Label Data Format

  • URI: /db/{graph_name}/label/{[node|relationship]}/{label_name}

  • METHOD: GET

  • RESPONSE: Data column definition table as a dictionary, in which each key is the column name, and corresponding value is the column definition defined as follows:

  • Field

    Description

    Type

    optional

    whether the column value can be empty

    Bool

    type

    the type of the column value

    String

Example Request:

    • GET http://localhost:7070/db/{graph_name}/label/node/person
    • Accept: application/json; charset=UTF-8

Example Response:

    • 200: OK
    • Content-Type: application/json; charset=UTF-8
    Output:
    {
        "age":{
            "optional":false,
            "type":"int16"
        },
        "id":{
            "optional":false,
            "type":"int8"
        },
        "name":{
            "optional":false,
            "type":"string"
        }
    }

6.6.4.Schema Import

  • URI: /db/{graph_name}/schema/text

  • METHOD: POST

  • REQUEST:

Field

Description

Type

description

Graph labels description

String

The detail description can refer to TuGraph Manual.

  • RESPONSE:

Schema import will check the new schema and original schema in database if compatible or not. If yes, this request will add the label only in new schema. If no, will return an error code.

Example request.

    • POST http://localhost:7070/db/graph1/schema/text
    • Accept: application/json; charset=UTF-8
    • Content-Type: application/json; charset=UTF-8
    Input:
    {
      "description": "{\\"schema\\":[{\\"label\\":\\"actor\\",\\"primary\\":\\"aid\\",\\"properties\\":[{\\"name\\":\\"aid\\",\\"type\\":\\"STRING\\"}],\\"type\\":\\"VERTEX\\"}]}"
    }

The value of the above description is the following json serialized string :

{
  "schema": [
    {
      "label": "actor",
      "type": "VERTEX",
      "properties": [{ "name": "aid", "type": "STRING" }],
      "primary": "aid"
    }
  ]
}

Example response.

    • 200: OK
    Output:
    {
        "log": ""
    }

6.7.Vertex Operation

URI format is:

    http://{host}:{port}/db/{graph_name}/node/{vid}

in which vid is a unique integer identifying the vertex, which can be obtained when creating new vertexes or by looking up index.

6.7.1.List Vertex and Label Number

  • URI: /db/{graph_name}/node

  • METHOD: GET

  • RESPONSE:

Field

Description

Type

num_label

the number of vertex label

Integer

num_vertex

the number of vertex

Integer

Note: num_vertex returns an estimate of the number of vertexes, not the exact number. To get the exact number, please use Cypher queries.

6.7.2.Create New Vertex

Insert a vertex into the database.

  • URI: /db/{graph_name}/node

  • METHOD: POST

  • REQUEST:

Field

Description

Type

label

the name of label

String

property

the properties of the vertex

Dictionary

in which property is a dictionary of {column_name:column_value}.

  • RESPONSE: if successful, return status code 200 and the new vertex’s vid, which can be used in later vertex operations.

Example Request:

    • POST http://localhost:7070/db/{graph_name}/node
    • Accept: application/json; charset=UTF-8
    • Content-Type: application/json
    Input:
    {
        "label" : "Person",
        "property" : {
            "name" : "Passerby A",
            "birthyear" : 1989
        }
    }

Example Response:

    • 200: OK
    • Content-Type: application/json; charset=UTF-8
    Output:
    {
        21
    }

6.7.3.Batch Create Vertexes

TuGraph allows multiple vertices to be inserted as one batch to reduce network overhead.

  • URI: /db/{graph_name}/node

  • METHOD: POST

  • REQUEST:

Field

Description

Type

label

the name of Label

String

fields

the column names

List

values

the values of each vertex

List

in which fields is a list of strings specifying column names, and values is a list in which each element is a list of column_values corresponding to the column names as specified in fields.

  • RESPONSE: if successful, return status code 200, and return the vid list of newly added vertices in the JSON content, where each vid corresponds to each vertex in the request.

Example Request:

    • POST http://localhost:7070/db/{graph_name}/node
    • Accept: application/json; charset=UTF-8
    • Content-Type: application/json
    Input:
    {
        "label" : "Person",
        "fields" : ["name", "birthyear"],
        "values" : [["alex", 2000],
                    ["bob", 1999]]
    }

Example Response:

    • 200: OK
    • Content-Type: application/json; charset=UTF-8
    Output:
    {
        [
            22,
            23
        ]
    }

6.7.4.Get Vertex

  • URI: /db/{graph_name}/node/{vertex_id}

  • METHOD: GET

  • RESPONSE:

Field

Description

Type

label

the name of Label

String

property

property

Dictionary, in the format of {column_name_1:column_value_1, …}

Example Request:

    • GET http://localhost:7070/db/{graph_name}/node/5
    • Accept: application/json; charset=UTF-8

Example Response:

    • 200: OK
    • Content-Type: application/json; charset=UTF-8
    Output:
    {
        "property": {
            "birthyear": 1963,
            "name": "Natasha Richardson"
        },
        "label": "Person"
    }

6.7.5.Delete Vertex

  • URI: /db/{graph_name}/node/{vertex_id}

  • METHOD: DELETE

  • RESPONSE: if successful, return status code 200, and also the following content in JSON:

Field

Description

Type

in

number of incoming edges of the deleted vertex

Integer

out

number of outgoing edges of the deleted vertex

Integer

Example Request:

    • DELETE http://localhost:7070/db/{graph_name}/node/4
    • Accept: application/json; charset=UTF-8

Example Response:

    • 200: OK
    • Content-Type: application/json; charset=UTF-8
    Output:
    {
        "in": 0,
        "out": 0
    }

6.7.6.Get Vertex Property

  • URI: /db/{graph_name}/node/{vertex_id}/property

  • METHOD: GET

  • RESPONSE: Vertex properties as a dictionary of {column_name:column_value}

Example Request:

    • GET http://localhost:7070/db/{graph_name}/node/5/property
    • Accept: application/json; charset=UTF-8

Example Response:

    • 200: OK
    • Content-Type: application/json; charset=UTF-8
    Output:
    {
        "birthyear": 1963,
        "name": "Natasha Richardson"
    }

6.7.7.Get Vertex Field

  • URI: /db/{graph_name}/node/{vertex_id}/property/{field}

  • METHOD: GET

  • RESPONSE: Value corresponding to the specified field.

Example Request:

    • GET http://localhost:7070/db/{graph_name}/node/5/property/name
    • Accept: application/json; charset=UTF-8

Example Response:

    • 200: OK
    • Content-Type: application/json; charset=UTF-8
    Output:
    {
        "Natasha Richardson"
    }

6.7.8.Update Vertex Property

  • URI: /db/{graph_name}/node/{vertex_id}

  • METHOD: PUT

  • REQUEST:

Field

Description

Type

property

properties to update

Dictionary

  • RESPONSE: if successful, return status code 200.

Example Request:

    • PUT http://localhost:7070/db/{graph_name}/node/5
    • Accept: application/json; charset=UTF-8
    • Content-Type: application/json
    Input:
    {
      "property" : {
        "birthyear" : 1964,
        "mobile" : "13737299333"
      }
    }

Example Response:

    • 200: OK

6.8.Edge Operation

URI format is:

    http://{host}:{port}/db/{graph_name}/relationship/{euid}

in which euid is a string uniquely identifying the edge, which can be obtained when creating edges or by iterating through the edges of a vertex.

6.8.1.Create Edge

  • URI: /db/{graph_name}/node/{src_vid}/relationship

  • METHOD: POST

  • REQUEST:

Field

Description

Type

label

the label of edge

String

destination

the vid of destination vertex

Integer

property

the property of edge

Dictionary

  • RESPONSE: if successful, return status code 200 and the euid of new created edge (type is String).

Example Request:

    • POST http://localhost:7070/db/{graph_name}/node/{src}/relationship
    • Accept: application/json; charset=UTF-8
    • Content-Type: application/json
    Input:
    {
      "destination" : 14,
      "label" : "BORN_IN",
      "property" : {}
    }

Example Response:

    • 200: OK
    • Content-Type: application/json; charset=UTF-8
    Output:
    {
        "1_14_1_0"
    }

6.8.2.Batch Create Edges

  • URI: /db/{graph_name}/relationship

  • METHOD: POST

  • REQUEST:

Field

Description

Type

label

the label of edge

String

fields

the data column name

List

edge

the data of edge

List

where the edge is a list of data, each of which specifies and edge, defined as follows:

Field

Description

Type

source

source vertex id

Integer

destination

destination vertex id

Integer

values

the data list

List

in which values is a list of column values, each of which correspond to the a column name specified in fields.

  • RESPONSE: if successful, return status code 200 and the list of euids of the newly created edges.

Example Request:

    • POST http://localhost:7070/db/{graph_name}/relationship
    • Accept: application/json; charset=UTF-8
    • Content-Type: application/json
    Input:
    {
      "label" : "knows",
      "fields" : ["from_year", "weight"],
      "edge" : [
          {"source":0, "destination":1, "values":[2011, 0.8]},
          {"source":1, "destination":2, "values":[2008, 0.9]}
      ]
    }

Example Response:

    • 200: OK
    • Content-Type: application/json; charset=UTF-8
    Output:
    {
        [
            "0_1_0_0",
            "1_2_0_0"
        ]
    }

6.8.3.List Out-going Edges

  • URI: /db/{graph_name}/node/{src}/relationship/out

  • METHOD: GET

  • RESPONSE: The list of euids of source vertex’s out-going edges.

Example Request:

    • GET http://localhost:7070/db/{graph_name}/node/4/relationship/out
    • Accept: application/json; charset=UTF-8

Example Response:

    • 200: OK
    • Content-Type: application/json; charset=UTF-8
    Output:
    {
        [
            "4_5_0_0",
            "4_7_1_2"
        ]
    }

6.8.4.List Incoming Edges

  • URI: /db/{graph_name}/node/{dst}/relationship/in

  • METHOD: GET

  • RESPONSE: The list of euids of destination vertex’s incoming edges.

Example Request:

    • GET http://localhost:7070/db/{graph_name}/node/4/relationship/in
    • Accept: application/json; charset=UTF-8

Example Response:

    • 200: OK
    • Content-Type: application/json; charset=UTF-8
    Output:
    {
        [
            "0_4_0_0",
            "3_4_3_1"
        ]
    }

6.8.5.List All Edges

  • URI: /db/{graph_name}/node/{src}/relationship/all

  • METHOD: GET

  • RESPONSE:

Field

Description

Type

in

list of incoming edges’ euids

List

out

list of outgoing edges’ euids

List

Example Request:

    • GET http://localhost:7070/db/{graph_name}/node/4/relationship/all
    • Accept: application/json; charset=UTF-8

Example Response:

    • 200: OK
    • Content-Type: application/json; charset=UTF-8
    Output:
    {
        "out": [
            "4_5_0_0",
            "4_7_1_2"
        ],
        "in": [
            "0_4_0_0",
            "3_4_3_1"
        ]
    }

6.8.6.Get Edge Information

  • URI: /db/{graph_name}/relationship/{euid}

  • METHOD: GET

  • RESPONSE:

Field

Description

Type

label

the label of the edge

String

property

the properties of the edge

Dictionary

Example Request:

    • GET http://localhost:7070/db/graph1/relationship/0_4_0_0
    • Accept: application/json; charset=UTF-8

Example Response:

    • 200: OK
    • Content-Type: application/json; charset=UTF-8
    Output:
    {
        "property": {
        },
        "label": "MARRIED"
    }

6.8.7.Delete Edge

  • URI: /db/{graph_name}/relationship/{euid}

  • METHOD: DELETE

  • RESPONSE: if successful, return status code 200.

Example Request:

    • DELETE http://localhost:7070/db/graph1/relationship/14_0_1_0
    • Accept: application/json; charset=UTF-8

Example Response:

    • 200: OK

6.8.8.Get Edge Properties

  • URI: /db/{graph_name}/relationship/{euid}/property

  • METHOD: GET

  • RESPONSE: The dictionary of edge’s properties.

Example Request:

    • GET http://localhost:7070/db/graph1/relationship/14_0_2_0/property
    • Accept: application/json; charset=UTF-8

Example Response:

    • 200: OK
    • Content-Type: application/json; charset=UTF-8
    Output:
    {
        {
            "weight": 0.8,
            "begin": 20180922
        }
    }

6.8.9.Get Edge Field

  • URI: /db/{graph_name}/relationship/{euid}/property/{field}

  • METHOD: GET

  • RESPONSE: if successful, return status code 200 and the value corresponding to given field.

Example Request:

    • GET http://localhost:7070/db/graph1/relationship/17_0_2_2/property/charactername
    • Accept: application/json; charset=UTF-8

Example Response:

    • 200: OK
    • Content-Type: application/json; charset=UTF-8
    Output:
    {
        "Henri Ducard"
    }

6.8.10.Update Edge Property

  • URI: /db/{graph_name}/relationship/{euid}

  • METHOD: PUT

  • REQUEST:

Field

Description

Type

property

properties to be updated

Dictionary

  • RESPONSE: if successful, return status code 200.

Example Request:

    • PUT http://localhost:7070/db/graph1/relationship/17_0_2_2
    • Accept: application/json; charset=UTF-8
    • Content-Type: application/json
    Input:
    {
      "property" : {
        "charactername" : "Henri Ducard/passer a"
      }
    }

Example Response:

    • 200: OK

6.9.Index

URI format is:

    http://{host}:{port}/db/{graph_name}/index/{label}/{field}

6.9.1.Create Index

Create an index on a (label, field) pair. Blocks until the index is successfully built.

  • URI: /db/{graph_name}/index

  • METHOD: POST

  • REQUEST:

Field

Description

Type

label

the name of label

String

field

field to be indexed

String

type

the type of index, 0 means nonunique index, 1 means unique index, 2 means pair_unique index

int

  • RESPONSE: if successful, return status code 200.

Example Request:

    • POST http://localhost:7070/db/graph1/index
    • Accept: application/json; charset=UTF-8
    • Content-Type: application/json
    Input:
    {
      "label": "Person",
      "field": "birthyear",
      "is_unique" : false
    }

Example Response:

    • 200: OK

6.9.2.List All Indexes

  • URI: /db/{graph_name}/index

  • METHOD: GET

  • RESPONSE: A list of index specifications, each of which has the same format as use in Create Index.

Example Request:

    • GET http://localhost:7070/db/graph1/index
    • Accept: application/json; charset=UTF-8

Example Response:

    • 200: OK
    • Content-Type: application/json; charset=UTF-8
    Output:
    {
        [
            {
                "field": "name",
                "label": "City",
                "is_unique": false
            },
            {
                "field": "title",
                "label": "Film",
                "is_unique": false
            },
            {
                "field": "name",
                "label": "Person",
                "is_unique": true
            },
            {
                "label": "Person",
                "field": "age",
                "is_unique": false
            }
        ]
    }

6.9.4.Delete Index

  • URI: /db/{graph_name}/index/{label}/{field}

  • METHOD: DELETE

  • RESPONSE: if successful, return status code 200.

Example Request:

    • DELETE http://localhost:7070/db/graph1/index/Person/name
    • Accept: application/json; charset=UTF-8

Example Response:

    • 200: OK

6.9.5.Get Vertex by Index

  • URI: /db/{graph_name}/index/{label}/?field={field}&value={value}

  • METHOD: GET

  • RESPONSE: A list of vids.

Example Request:

    • GET http://localhost:7070/db/graph1/index/Person/?field=birthyear&value=1986
    • Accept: application/json; charset=UTF-8

Example Response:

    • 200: OK
    Output:
    {
        [
            1,
            8
        ]
    }

6.10.Data Import

  • URI: /db/{graph_name}/import/text

  • METHOD: POST

  • REQUEST:

Field

Description

Type

description

description of the file content

String

data

contents of the file to be imported (recommended to have a size of 16MB, has a hard limit of 17MB)

Strings / Arrays / Objects

continue_on_error

whether to continue import when an error occurred (optional, default is false)

Bool

delimiter

delimiter used in the data file (optional, default is “,”)

String

The details of the description field can be found in TuGraph Import Tool.

delimiter can be a single character or multi-character string, but must not contain \r or \n.

data can be one of the following:

  • String, such as "1,2\n3,4\n"

  • Array of ASCII codes, such as [49,44,50,10,51,44,52,10]

  • Dictionary shaped like the above array, such as {"0":49,"1":44,"2":50,"3":10,"4":51,"5":44,"6":52,"7":10}

  • RESPONSE:

The system will not automatically perform actions such as creating a new label, adding an index, and so on. Before you do this, please make sure that the label involved already exists and has an appropriate index.

If the import is successful, return code 200 and return log information (possibly empty) in the log field. Otherwise, returns status code 400. None of the data is imported on failure, and error message is set in error_message.

Example Request:

    • POST http://localhost:7070/db/graph1/import/text
    • Accept: application/json; charset=UTF-8
    • Content-Type: application/json; charset=UTF-8
    Input:
    {
      "description": "{\\"files\\":[{\\"columns\\":[\\"SRC_ID\\",\\"role\\",\\"DST_ID\\"],\\"format\\":\\"CSV\\",\\"label\\":\\"role\\",\\"SRC_ID\\":\\"actor\\",\\"DST_ID\\":\\"movie\\"}]}"}",
      "data": "1,Role1,2\n3,Role2,4\n",
      "continue_on_error": true
    }

The value of the above description is the following json serialized string :

{
  "files": [
    {
      "format": "CSV",
      "label": "role",
      "SRC_ID": "actor",
      "DST_ID": "movie",
      "columns": ["SRC_ID", "role", "DST_ID"]
    }
  ]
}

Example Response:

    • 200: OK
    Output:
    {
        "log": "Missing src uid 1\n"
    }

Because the request specifies continue_on_error: true, the returned log indicates that the first edge cannot be inserted because there is no vertex with uid==1, while the second edge was imported successfully.

6.11.Miscellany

URI format is:

    http://{host}:{port}/db/{graph_name}/misc

6.11.1.Extract Subgraph

Give a set of vids and return the minimum subgraph which contains the vertex set and the edges between them.

  • URI: /db/{graph_name}/misc/sub_graph

  • METHOD: POST

  • REQUEST:

Field

Description

Type

vertex_ids

vertex id set

List

  • RESPONSE:

Field

description

Type

nodes

vertex information

List, each element contains vid, label, and properties.

relationships

edge information

List, each element contains src, dst, euid, label, and properties.

Example Request:

    • POST http://localhost:7070/db/graph1/misc/sub_graph
    • Accept: application/json; charset=UTF-8
    • Content-Type: application/json; charset=UTF-8
    Input:
    {
      "vertex_ids": [2, 5, 14, 20]
    }

Example Response:

    • 200: OK
    Output:
    {
        "nodes": [
            {
                "label": "Person",
                "properties": {
                    "birthyear": 1937,
                    "name": "Vanessa Redgrave"
                },
                "vid": 2
            },
            {
                "label": "Person",
                "properties": {
                    "birthyear": 1963,
                    "name": "Natasha Richardson"
                },
                "vid": 5
            },
            {
                "label": "City",
                "properties": {
                    "name": "London"
                },
                "vid": 14
            },
            {
                "label": "Film",
                "properties": {
                    "title": "Camelot"
                },
                "vid": 20
            }
        ],
        "relationships": [
            {
                "destination": 5,
                "label": "HAS_CHILD",
                "properties": {
                    "birthyear": 1937,
                    "name": "Vanessa Redgrave"
                },
                "source": 2
            },
            {
                "destination": 14,
                "label": "BORN_IN",
                "properties": {
                    "birthyear": 1937,
                    "name": "Vanessa Redgrave"
                },
                "source": 2
            },
            {
                "destination": 20,
                "label": "ACTED_IN",
                "properties": {
                    "birthyear": 1937,
                    "charactername": "Guenevere",
                    "name": "Vanessa Redgrave"
                },
                "source": 2
            },
            {
                "destination": 14,
                "label": "BORN_IN",
                "properties": {
                    "birthyear": 1963,
                    "name": "Natasha Richardson"
                },
                "source": 5
            }
        ]
    }