19.1 Graph Server REST API Version 2

Learn about the graph server REST API version 2 (v2).

This API version supports a token-based authentication for the REST endpoints. Therefore, you must first obtain an access token which can be used in the subsequent REST API requests.

Parent topic: REST Endpoints for the Graph Server

19.1.1 Get an Authentication Token

POST https://localhost:7007/auth/token

Get an authentication token which can be used to authenticate the REST API requests.

Request

Request Header

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

Table 19-1 Request Body Parameters

Parameter Type Description Required
username string Name of the user Yes
password string Password for the user Yes
createSession boolean To determine if a session needs to be created Optional. Set it to true if you want to run queries against the graph server (PGX).
source string A descriptive string identifying the client Optional. Ensure to enter the source value without spaces (for example, "commandLine", "shellWithJava", and so on).
sessionId string To reuse an existing session when connecting to the graph server Optional. Set it to an existing session ID if you want to reuse that session.

Sample Request Body

{
    "username": "graphuser",
    "password": "<password_for_graphuser>",
    "createSession": true,
    "source": "<source-value-for-pgx-session>",
    "sessionId": "<session-id>"
}

Response

  • 201 Created
  • Content-Type: application/json

Sample Response Body

{
    "access_token": "<token>"
    "token_type": "bearer",
    "expires_in": 3600
}

cURL Example

curl --location 'https://localhost:7007/auth/token' \
--header 'Content-Type: application/json' \
--data '{ 
    "username": "graphuser",
    "password": "<password_for_graphuser>",
    "createSession": true,
    "source": "commandLine",
    "sessionId": "<session-id>"
}'

Parent topic: Graph Server REST API Version 2

19.1.2 Refresh an Authentication Token

PUT https://localhost:7007/auth/token

Refresh a valid access token.

Request

Request Header

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

Table 19-2 Request Body Parameters

Parameter Type Description Required
token string Access token value Yes
createSession boolean Flag to determine if a session needs to be created Optional. Set it to true if you want to run queries against the graph server (PGX).
sessionId string To reuse an existing session when connecting to the graph server Optional. Set it to an existing session ID if you want to reuse that session.

Sample Request Body

{
    "token": "<token>",
    "createSession": true,
    "sessionId": "<session-id>"
}

Response

  • 201 Created
  • Content-Type: application/json

Sample Response Body

{
    "access_token": "<token>"
    "token_type": "bearer",
    "expires_in": 3600
}

cURL Example

curl --location --request PUT 'https://localhost:7007/auth/token' \
--header 'Content-Type: application/json' \
--data '{
    "token": "<token_value>",
    "createSession": true,
    "sessionId": "<session-id>"
}'

Parent topic: Graph Server REST API Version 2

19.1.3 Get Graphs

GET https://localhost:7007/v2/graphs

Get the list of graphs for the specified driver.

Version: v2

Request

Request Header

  • Accept: application/json; charset=UTF-8
  • Header: Authorization: Bearer <token>
  • Content-Type: application/json

Request Query Parameter

  • driver (required): Specifies the PGQL driver value. This is a mandatory parameter. Supported values are as follows:
    • GRAPH_SERVER_PGX: Graphs loaded into the graph server (PGX)
    • PGQL_IN_DATABASE: PGQL property graphs in the database
    • SQL_IN_DATABASE: SQL property graphs in the database

Response

  • 200 OK
  • Content-Type: application/json

Sample Response Body

[
    {
        "schema": <value>,
        "graphName": <value>
    }
]

Note that the schema parameter will be NULL for graphs created in the graph server (PGX).

cURL Example

curl --location --request GET 'https://localhost:7007/v2/graphs?driver=<driver-value>' \
--header 'Authorization: Bearer <token>'

Parent topic: Graph Server REST API Version 2

19.1.4 Run a PGQL Query

POST https://localhost:7007/v2/runQuery

Run one or multiple statements for the specified driver.

Version: v2

Request

Request Header

  • Accept: application/json; charset=UTF-8
  • Header: Authorization: Bearer <token>
  • Content-Type: application/json

Table 19-3 Request Body Parameters

Parameter Type Description Required
statements string [ ] One or multiple statements Yes
driver string Specifies the PGQL driver. The supported values are:
  • GRAPH_SERVER_PGX: To run PGQL queries against the graph server (PGX)
  • PGQL_IN_DATABASE: To run PGQL statements or queries against the database
  • SQL_IN_DATABASE: To run graph queries against the database
Yes
formatter string The supported values are:
  • DATASTUDIO
  • GVT

Note: Starting from Graph Server and Client Release 24.4, the formatter parameter is deprecated.

Yes
parameters object
  • dynamicSampling: integer
  • parallel: integer
  • start: integer
  • size: integer
Parameters include:
  • Dynamic Sampling Value
  • Degree of Parallelism
  • Fetch size (= the number of rows) of the query result
 Parameters are all optional.
  • Default value for dynamic sampling is 2.
  • Default value for parallelism depends on the driver.
  • Default value for start is 0.
  • Default value for size is 100.
visualize boolean Flag to set visualization Optional. Default value is true.

Sample Request Body

{
  "statements": [
    "DROP PROPERTY GRAPH TEST_GRAPH",
    "CREATE PROPERTY GRAPH TEST_GRAPH VERTEX TABLES( Male KEY (id) LABEL Male PROPERTIES ARE ALL COLUMNS EXCEPT (gender), Female KEY (id) LABEL Female PROPERTIES ARE ALL COLUMNS EXCEPT (gender) ) EDGE TABLES( knowsmm KEY (id) SOURCE KEY (sid) REFERENCES Male DESTINATION KEY (did) REFERENCES Male LABEL knows PROPERTIES (mval, firstMetAt, since), knowsmf KEY (id) SOURCE KEY (sid) REFERENCES Male DESTINATION KEY (did) REFERENCES Female LABEL knows PROPERTIES (mval, firstMetAt, since), knowsfm KEY (id) SOURCE KEY (sid) REFERENCES Female DESTINATION KEY (did) REFERENCES Male LABEL knows PROPERTIES (mval, firstMetAt, since), knowsff KEY (id) SOURCE KEY (sid) REFERENCES Female DESTINATION KEY (did) REFERENCES Female LABEL knows PROPERTIES (mval, firstMetAt, since), friendOfmm KEY (id) SOURCE KEY (sid) REFERENCES Male DESTINATION KEY (did) REFERENCES Male LABEL friendOf PROPERTIES (strength), friendOfmf KEY (id) SOURCE KEY (sid) REFERENCES Male DESTINATION KEY (did) REFERENCES Female LABEL friendOf PROPERTIES (strength), friendOffm KEY (id) SOURCE KEY (sid) REFERENCES Female DESTINATION KEY (did) REFERENCES Male LABEL friendOf PROPERTIES (strength), friendOfff KEY (id) SOURCE KEY (sid) REFERENCES Female DESTINATION KEY (did) REFERENCES Female LABEL friendOf PROPERTIES (strength) ) OPTIONS ( pg_pgql )", 
    "SELECT v FROM MATCH (v) ON TEST_GRAPH LIMIT 1"
  ],
  "driver": "PGQL_IN_DATABASE",
  "formatter": "GVT",
  "parameters": {
    "dynamicSampling": 2,
    "parallel": 8,
    "start": 0,
    "size": 100
  },
  "visualize": true

Response

  • 200 OK
  • Content-Type: application/json

Sample Response Body

{
    "results": [
        {
            "pgqlStatement": "DROP PROPERTY GRAPH TEST_GRAPH",
            "result": "Graph successfully dropped",
            "success": true,
            "error": null,
            "started": 1689656429130,
            "ended": 1689656429198
        },
        {
            "pgqlStatement": "CREATE PROPERTY GRAPH TEST_GRAPH VERTEX TABLES( Male KEY (id) LABEL Male PROPERTIES ARE ALL COLUMNS EXCEPT (gender), Female KEY (id) LABEL Female PROPERTIES ARE ALL COLUMNS EXCEPT (gender) ) EDGE TABLES( knowsmm KEY (id) SOURCE KEY (sid) REFERENCES Male DESTINATION KEY (did) REFERENCES Male LABEL knows PROPERTIES (mval, firstMetAt, since), knowsmf KEY (id) SOURCE KEY (sid) REFERENCES Male DESTINATION KEY (did) REFERENCES Female LABEL knows PROPERTIES (mval, firstMetAt, since), knowsfm KEY (id) SOURCE KEY (sid) REFERENCES Female DESTINATION KEY (did) REFERENCES Male LABEL knows PROPERTIES (mval, firstMetAt, since), knowsff KEY (id) SOURCE KEY (sid) REFERENCES Female DESTINATION KEY (did) REFERENCES Female LABEL knows PROPERTIES (mval, firstMetAt, since), friendOfmm KEY (id) SOURCE KEY (sid) REFERENCES Male DESTINATION KEY (did) REFERENCES Male LABEL friendOf PROPERTIES (strength), friendOfmf KEY (id) SOURCE KEY (sid) REFERENCES Male DESTINATION KEY (did) REFERENCES Female LABEL friendOf PROPERTIES (strength), friendOffm KEY (id) SOURCE KEY (sid) REFERENCES Female DESTINATION KEY (did) REFERENCES Male LABEL friendOf PROPERTIES (strength), friendOfff KEY (id) SOURCE KEY (sid) REFERENCES Female DESTINATION KEY (did) REFERENCES Female LABEL friendOf PROPERTIES (strength) ) OPTIONS ( pg_pgql )",
            "result": "Graph successfully created",
            "success": true,
            "error": null,
            "started": 1689656429198,
            "ended": 1689656429458
        },
        {
            "pgqlStatement": "SELECT v FROM MATCH (v) ON TEST_GRAPH LIMIT 1",
            "result": "{\"schema\":\"GRAPHUSER\",\"name\":\"TEST_GRAPH\",\"resultSetId\":\"\",\"graph\":{\"vertices\":[{\"id\":\"MALE(0)\",\"properties\":{\"AGE\":\"40\",\"BVAL\":\"Y\",\"LNAME\":\"Brown\",\"FNAME\":\"Bill\",\"PREFERENCES\":\"{ \\\"color\\\": \\\"blue\\\", \\\"number\\\": \\\"5\\\" }\",\"ID\":\"0\",\"TEXT\":\"the cat sat on the mat\",\"MVAL\":\"y\"}}],\"edges\":[],\"numResults\":1},\"table\":\"V\\nMALE(0)\"}",
            "success": true,
            "error": null,
            "started": 1689656429458,
            "ended": 1689656430029
        }
    ]
}

cURL Example

curl --location --request POST 'https://localhost:7007/v2/runQuery' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{
  "statements": [
    "DROP PROPERTY GRAPH TEST_GRAPH",
    "CREATE PROPERTY GRAPH TEST_GRAPH VERTEX TABLES( Male KEY (id) LABEL Male PROPERTIES ARE ALL COLUMNS EXCEPT (gender), Female KEY (id) LABEL Female PROPERTIES ARE ALL COLUMNS EXCEPT (gender) ) EDGE TABLES( knowsmm KEY (id) SOURCE KEY (sid) REFERENCES Male DESTINATION KEY (did) REFERENCES Male LABEL knows PROPERTIES (mval, firstMetAt, since), knowsmf KEY (id) SOURCE KEY (sid) REFERENCES Male DESTINATION KEY (did) REFERENCES Female LABEL knows PROPERTIES (mval, firstMetAt, since), knowsfm KEY (id) SOURCE KEY (sid) REFERENCES Female DESTINATION KEY (did) REFERENCES Male LABEL knows PROPERTIES (mval, firstMetAt, since), knowsff KEY (id) SOURCE KEY (sid) REFERENCES Female DESTINATION KEY (did) REFERENCES Female LABEL knows PROPERTIES (mval, firstMetAt, since), friendOfmm KEY (id) SOURCE KEY (sid) REFERENCES Male DESTINATION KEY (did) REFERENCES Male LABEL friendOf PROPERTIES (strength), friendOfmf KEY (id) SOURCE KEY (sid) REFERENCES Male DESTINATION KEY (did) REFERENCES Female LABEL friendOf PROPERTIES (strength), friendOffm KEY (id) SOURCE KEY (sid) REFERENCES Female DESTINATION KEY (did) REFERENCES Male LABEL friendOf PROPERTIES (strength), friendOfff KEY (id) SOURCE KEY (sid) REFERENCES Female DESTINATION KEY (did) REFERENCES Female LABEL friendOf PROPERTIES (strength) ) OPTIONS ( pg_pgql )",
    "SELECT v FROM MATCH (v) ON TEST_GRAPH LIMIT 1"
  ],
  "driver": "PGQL_IN_DATABASE",
  "formatter": "GVT",
  "parameters": {
    "dynamicSampling": 2,
    "parallel": 8,
    "start": 0,
    "size": 100  
  },
  "visualize": true
}'

Parent topic: Graph Server REST API Version 2

19.1.5 Get the Database Version

GET https://localhost:7007/v2/dbVersion

Get the database version to which the graph server is connected.

Version: v2

Request

Request Header

  • Accept: application/json; charset=UTF-8
  • Header: Authorization: Bearer <token>
  • Content-Type: application/json

Response

  • 200 OK
  • Content-Type: application/json

Sample Response Body

{
    "dbVersion": "23.0"
}

cURL Example


curl --location --request GET 'https://localhost:7007/v2/dbVersion' \
--header 'Authorization: Bearer <token>'

Parent topic: Graph Server REST API Version 2

19.1.6 Get User

GET https://localhost:7007/v2/user

Get the username that is currently connected to the graph server (username is attached to the token).

Version: v2

Request

Request Header

  • Accept: application/json; charset=UTF-8
  • Header: Authorization: Bearer <token>
  • Content-Type: application/json

Response

  • 200 OK
  • Content-Type: application/json

Sample Response Body

{
    "username": "graphuser"
}

cURL Example

curl --location --request GET 'https://localhost:7007/v2/user' \
--header 'Authorization: Bearer <token>'

Parent topic: Graph Server REST API Version 2

19.1.7 Asynchronous REST Endpoints

The graph server REST endpoints support cancellation of queries.

In order to be able to cancel queries, you need to send the query using the following asynchronous REST endpoints:

Parent topic: Graph Server REST API Version 2

19.1.7.1 Run an Asynchronous PGQL Query

POST https://localhost:7007/v2/runQueryAsync

Run a PGQL query asynchronously on a property graph.

Version: v2

Request

Request Header

  • Accept: application/json; charset=UTF-8
  • Header: Authorization: Bearer <token>
  • Content-Type: application/json

Request Query Parameters: See Table 19-3 for details.

Sample Request Body

{
  "statements": [
    "DROP PROPERTY GRAPH TEST_GRAPH",
    "CREATE PROPERTY GRAPH TEST_GRAPH VERTEX TABLES( Male KEY (id) LABEL Male PROPERTIES ARE ALL COLUMNS EXCEPT (gender), Female KEY (id) LABEL Female PROPERTIES ARE ALL COLUMNS EXCEPT (gender) ) EDGE TABLES( knowsmm KEY (id) SOURCE KEY (sid) REFERENCES Male DESTINATION KEY (did) REFERENCES Male LABEL knows PROPERTIES (mval, firstMetAt, since), knowsmf KEY (id) SOURCE KEY (sid) REFERENCES Male DESTINATION KEY (did) REFERENCES Female LABEL knows PROPERTIES (mval, firstMetAt, since), knowsfm KEY (id) SOURCE KEY (sid) REFERENCES Female DESTINATION KEY (did) REFERENCES Male LABEL knows PROPERTIES (mval, firstMetAt, since), knowsff KEY (id) SOURCE KEY (sid) REFERENCES Female DESTINATION KEY (did) REFERENCES Female LABEL knows PROPERTIES (mval, firstMetAt, since), friendOfmm KEY (id) SOURCE KEY (sid) REFERENCES Male DESTINATION KEY (did) REFERENCES Male LABEL friendOf PROPERTIES (strength), friendOfmf KEY (id) SOURCE KEY (sid) REFERENCES Male DESTINATION KEY (did) REFERENCES Female LABEL friendOf PROPERTIES (strength), friendOffm KEY (id) SOURCE KEY (sid) REFERENCES Female DESTINATION KEY (did) REFERENCES Male LABEL friendOf PROPERTIES (strength), friendOfff KEY (id) SOURCE KEY (sid) REFERENCES Female DESTINATION KEY (did) REFERENCES Female LABEL friendOf PROPERTIES (strength) ) OPTIONS ( pg_pgql )", 
    "SELECT v FROM MATCH (v) ON TEST_GRAPH LIMIT 1"
  ],
  "driver": "PGQL_IN_DATABASE",
  "formatter": "GVT",
  "parameters": {
    "dynamicSampling": 2,
    "parallel": 8,
    "start": 0,
    "size": 100
  },
  "visualize": true

Response

  • 202 OK
  • Content-Type: application/json

Sample Response Body

{
    "message": "Query execution started.",
    "result_id": 0
}

cURL Example

curl --location --request POST 'https://localhost:7007/v2/runQueryAsync' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{
  "statements": [
    "DROP PROPERTY GRAPH TEST_GRAPH",
    "CREATE PROPERTY GRAPH TEST_GRAPH VERTEX TABLES( Male KEY (id) LABEL Male PROPERTIES ARE ALL COLUMNS EXCEPT (gender), Female KEY (id) LABEL Female PROPERTIES ARE ALL COLUMNS EXCEPT (gender) ) EDGE TABLES( knowsmm KEY (id) SOURCE KEY (sid) REFERENCES Male DESTINATION KEY (did) REFERENCES Male LABEL knows PROPERTIES (mval, firstMetAt, since), knowsmf KEY (id) SOURCE KEY (sid) REFERENCES Male DESTINATION KEY (did) REFERENCES Female LABEL knows PROPERTIES (mval, firstMetAt, since), knowsfm KEY (id) SOURCE KEY (sid) REFERENCES Female DESTINATION KEY (did) REFERENCES Male LABEL knows PROPERTIES (mval, firstMetAt, since), knowsff KEY (id) SOURCE KEY (sid) REFERENCES Female DESTINATION KEY (did) REFERENCES Female LABEL knows PROPERTIES (mval, firstMetAt, since), friendOfmm KEY (id) SOURCE KEY (sid) REFERENCES Male DESTINATION KEY (did) REFERENCES Male LABEL friendOf PROPERTIES (strength), friendOfmf KEY (id) SOURCE KEY (sid) REFERENCES Male DESTINATION KEY (did) REFERENCES Female LABEL friendOf PROPERTIES (strength), friendOffm KEY (id) SOURCE KEY (sid) REFERENCES Female DESTINATION KEY (did) REFERENCES Male LABEL friendOf PROPERTIES (strength), friendOfff KEY (id) SOURCE KEY (sid) REFERENCES Female DESTINATION KEY (did) REFERENCES Female LABEL friendOf PROPERTIES (strength) ) OPTIONS ( pg_pgql )",
    "SELECT v FROM MATCH (v) ON TEST_GRAPH LIMIT 1"
  ],
  "driver": "PGQL_IN_DATABASE",
  "formatter": "GVT",
  "parameters": {
    "dynamicSampling": 2,
    "parallel": 8,
    "start": 0,
    "size": 100  
  },
  "visualize": true
}'

Parent topic: Asynchronous REST Endpoints

19.1.7.2 Check Asynchronous Query Completion

GET https://localhost:7007/v2/isAsyncQueryExecutionComplete/<result_id>

Check if an asynchronous query execution is completed.

Version: v2

Request Header

  • Accept: application/json; charset=UTF-8
  • Header: Authorization: Bearer <token>
  • Content-Type: application/json
Request Path Parameter:
  • result_id: PGQL query execution result id.

Response

  • 200 OK
  • Content-Type: application/json

Sample Response Body

true

cURL Example

curl --location --request GET 'https://localhost:7007/v2/isAsyncQueryExecutionComplete/<result-id>' \
--header 'Authorization: Bearer <token>'

Parent topic: Asynchronous REST Endpoints

19.1.7.3 Retrieve Asynchronous Query Result

GET https://localhost:7007/v2/runQueryAsync/<result_id>

Retreive the result of an asynchronous query.

Version: v2

Request

Request Header

  • Accept: application/json; charset=UTF-8
  • Header: Authorization: Bearer <token>
  • Content-Type: application/json

Request Path Parameter:

  • result_id: PGQL query execution result id.

Response

  • 200 OK
  • Content-Type: application/json

Sample Response Body

{
    "results": [
        {
            "pgqlStatement": "DROP PROPERTY GRAPH TEST_GRAPH",
            "result": "Graph successfully dropped",
            "success": true,
            "error": null,
            "started": 1689656429130,
            "ended": 1689656429198
        },
        {
            "pgqlStatement": "CREATE PROPERTY GRAPH TEST_GRAPH VERTEX TABLES( Male KEY (id) LABEL Male PROPERTIES ARE ALL COLUMNS EXCEPT (gender), Female KEY (id) LABEL Female PROPERTIES ARE ALL COLUMNS EXCEPT (gender) ) EDGE TABLES( knowsmm KEY (id) SOURCE KEY (sid) REFERENCES Male DESTINATION KEY (did) REFERENCES Male LABEL knows PROPERTIES (mval, firstMetAt, since), knowsmf KEY (id) SOURCE KEY (sid) REFERENCES Male DESTINATION KEY (did) REFERENCES Female LABEL knows PROPERTIES (mval, firstMetAt, since), knowsfm KEY (id) SOURCE KEY (sid) REFERENCES Female DESTINATION KEY (did) REFERENCES Male LABEL knows PROPERTIES (mval, firstMetAt, since), knowsff KEY (id) SOURCE KEY (sid) REFERENCES Female DESTINATION KEY (did) REFERENCES Female LABEL knows PROPERTIES (mval, firstMetAt, since), friendOfmm KEY (id) SOURCE KEY (sid) REFERENCES Male DESTINATION KEY (did) REFERENCES Male LABEL friendOf PROPERTIES (strength), friendOfmf KEY (id) SOURCE KEY (sid) REFERENCES Male DESTINATION KEY (did) REFERENCES Female LABEL friendOf PROPERTIES (strength), friendOffm KEY (id) SOURCE KEY (sid) REFERENCES Female DESTINATION KEY (did) REFERENCES Male LABEL friendOf PROPERTIES (strength), friendOfff KEY (id) SOURCE KEY (sid) REFERENCES Female DESTINATION KEY (did) REFERENCES Female LABEL friendOf PROPERTIES (strength) ) OPTIONS ( pg_pgql )",
            "result": "Graph successfully created",
            "success": true,
            "error": null,
            "started": 1689656429198,
            "ended": 1689656429458
        },
        {
            "pgqlStatement": "SELECT v FROM MATCH (v) ON TEST_GRAPH LIMIT 1",
            "result": "{\"schema\":\"GRAPHUSER\",\"name\":\"TEST_GRAPH\",\"resultSetId\":\"\",\"graph\":{\"vertices\":[{\"id\":\"MALE(0)\",\"properties\":{\"AGE\":\"40\",\"BVAL\":\"Y\",\"LNAME\":\"Brown\",\"FNAME\":\"Bill\",\"PREFERENCES\":\"{ \\\"color\\\": \\\"blue\\\", \\\"number\\\": \\\"5\\\" }\",\"ID\":\"0\",\"TEXT\":\"the cat sat on the mat\",\"MVAL\":\"y\"}}],\"edges\":[],\"numResults\":1},\"table\":\"V\\nMALE(0)\"}",
            "success": true,
            "error": null,
            "started": 1689656429458,
            "ended": 1689656430029
        }
    ]
}

cURL Example

curl --location --request GET 'https://localhost:7007/v2/runQueryAsync/<result-id>' \
--header 'Authorization: Bearer <token>'

Parent topic: Asynchronous REST Endpoints

19.1.7.4 Cancel an Asynchronous Query Execution

DELETE https://localhost:7007/v2/runQueryAsync/<result_id>

Cancel the execution of an asynchronous query.

Version: v2

Request

Request Header

  • Accept: application/json; charset=UTF-8
  • Header: Authorization: Bearer <token>
  • Content-Type: application/json

Request Path Parameter:

  • result_id: PGQL query execution result id.

Response

  • 200 Accepted
  • Content-Type: application/json

cURL Example

curl --location --request DELETE 'https://localhost:7007/v2/runQueryAsync/<result-id>' /
--header 'Authorization: Bearer <token>'

Parent topic: Asynchronous REST Endpoints