19 REST Endpoints for the Graph Server
This chapter describes the graph server REST API endpoints.
The graph server REST API supports two different versions. It is recommended that you use version 2 of the API.
- Graph Server REST API Version 2
Learn about the graph server REST API version 2 (v2). - Graph Server REST API Version 1
Learn about the graph server REST API version 1 (v1).
Parent topic: Using the Graph Server (PGX)
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.
- Get an Authentication Token
- Refresh an Authentication Token
- Get Graphs
- Run a PGQL Query
- Get the Database Version
- Get User
- Asynchronous REST Endpoints
Parent topic: REST Endpoints for the Graph Server
19.1.1 Get an Authentication Token
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).
|
Sample Request Body
{
"username": "graphuser",
"password": "<password_for_graphuser>",
"createSession": true
}
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
}'
Parent topic: Graph Server REST API Version 2
19.1.2 Refresh an Authentication Token
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).
|
Sample Request Body
{
"token": "<token>",
"createSession": true
}
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
}'
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 databaseSQL_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:
|
Yes |
formatter |
string | The supported values are:
|
Yes |
parameters |
object
|
Parameters include:
|
Parameters are all optional.
|
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_view )",
"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_view )",
"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_view )",
"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:
- Run an Asynchronous PGQL Query
- Check Asynchronous Query Completion
- Retrieve Asynchronous Query Result
- Cancel an Asynchronous Query Execution
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_view )",
"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_view )",
"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
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_view )",
"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 resultid
.
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
19.2 Graph Server REST API Version 1
Learn about the graph server REST API version 1 (v1).
Parent topic: REST Endpoints for the Graph Server
19.2.1 Login
POST https://localhost:7007/ui/v1/login/
Login to the graph server.
Version: v1
Authentication: Uses cookie-based authentication.
Table 19-4 Parameters
Parameter | Parameter Type | Value | Required |
---|---|---|---|
Content-type |
Header | application/json |
Yes |
username |
Body | <username> |
Yes |
password |
Body | <password> |
Yes |
baseUrl |
Body | <baseUrl> to point to the graph
server (PGX) or the database
|
Optional. If empty, the
pgx.base_url parameter value in the
web.xml file in
/opt/oracle/graph/pgx/server/graph-server-webapp-23.3.0.war will be
used.
|
pgqlDriver |
Body | Valid PGQL driver configuration values are:
|
Yes |
sessionId |
Body | sessionId from graph server
(PGX)
|
Optional |
Request
The following curl
command signs the user in to the graph
server:
curl --cacert /etc/oracle/graph/ca_certificate.pem -c cookie.txt -X POST -H "Content-Type: application/json" -d '{"username": "<username>", "password": "<password>", "pgqlDriver": "<pgqlDriver>","baseUrl": "<baseUrl>", "sessionId": "<sessionId>" }' https://localhost:7007/ui/v1/login/
username
used for the login. For
example:"oracle"
On successful login, the server session cookie is stored in a cookie file, cookie.txt
. Use this cookie file, in the subsequent calls to the API.
Parent topic: Graph Server REST API Version 1
19.2.2 Get Graphs
GET
https://localhost:7007/ui/v1/graphs
Get the list of all graphs that belong to a user.
Version: v1
Request
The following curl
command lists all the graphs that
belong to the user:
curl --cacert /etc/oracle/graph/ca_certificate.pem -b cookie.txt 'https://localhost:7007/ui/v1/graphs'
Response: The list of graphs available for the current user. For example:
[
{
"schema": "HR",
"graphName": "MY_GRAPH"
}
]
Also, note that the schema
parameter will be
NULL
for graphs created in the graph server (PGX).
Parent topic: Graph Server REST API Version 1
19.2.3 Run a PGQL Query
POST
https://localhost:7007/ui/v1/query
Run a PGQL Query on a property graph.
Version: v1
Table 19-5 Request Query Parameters
Parameter | Description | Values | Required |
---|---|---|---|
pgql |
PGQL query string | <PGQL_query> |
Yes |
graph |
Name of the graph | <graph_name> |
Optional, only if the pgql query parameter
contains the graph name. Otherwise, it is required.
|
parallelism |
Degree of Parallelism | <parallelism_value> |
Optional.
Default value depends on the PGQL driver
configuration:
|
size |
Fetch size (= the number of rows) of the query result | <size_value> |
Optional. Default size value is 100 .
|
formatter |
Formatter of the graph | <formatter_value> |
Optional.
Supported formatter options are:
Default value is |
Request
The following curl
command executes PGQL Query on a property
graph:
curl --cacert /etc/oracle/graph/ca_certificate.pem -b cookie.txt 'https://localhost:7007/ui/v1/query?pgql=SELECT%20e%0AMATCH%20()-%5Be%5D-%3E()%0ALIMIT%205&graph=hr&size=100'
Response: The PGQL query result in JSON format.
{
"name": "bank_graph_analytics_2",
"resultSetId": "pgql_14",
"graph": {
"idType": "number",
"vertices": [
{
"_id": "1",
"p": [],
"l": [
"Accounts"
],
"g": [
"anonymous_1"
]
},
{
"_id": "418",
"p": [],
"l": [
"Accounts"
],
"g": [
"anonymous_2"
]
},
{
"_id": "259",
"p": [],
"l": [
"Accounts"
],
"g": [
"anonymous_2"
]
}
],
"edges": [
{
"_id": "0",
"p": [
{
"n": "AMOUNT",
"v": "1000.0",
"s": false
}
],
"l": [
"Transfers"
],
"g": [
"e"
],
"s": "1",
"d": "259",
"u": false
},
{
"_id": "1",
"p": [
{
"n": "AMOUNT",
"v": "1000.0",
"s": false
}
],
"l": [
"Transfers"
],
"g": [
"e"
],
"s": "1",
"d": "418",
"u": false
}
],
"paths": [],
"totalNumResults": 2
},
"table": "e\nPgxEdge[provider=Transfers,ID=0]\nPgxEdge[provider=Transfers,ID=1]"
}
Parent topic: Graph Server REST API Version 1
19.2.4 Get User
GET https://localhost:7007/ui/v1/user
Get the name of the current user.
Version: v1
Request
The following curl
command gets the name of the current user:
curl --cacert /etc/oracle/graph/ca_certificate.pem -b cookie.txt 'https://localhost:7007/ui/v1/user'
Response: The name of the current user. For example:
"oracle"
Parent topic: Graph Server REST API Version 1
19.2.5 Logout
POST https://localhost:7007/ui/v1/logout/
Log out from the graph server.
Version: v1
Request
The following curl
command is to successfully log out from the
graph server.
curl --cacert /etc/oracle/graph/ca_certificate.pem -b cookie.txt -X POST 'https://localhost:7007/ui/v1/logout/'
Response: None
On successful logout, the server returns HTTP
status code
200
and the session token from the cookie.txt
file will no longer be valid.
Parent topic: Graph Server REST API Version 1
19.2.6 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:
- Run an Asynchronous PGQL Query
- Check Asynchronous Query Completion
- Retrieve Asynchronous Query Result
- Cancel an Asynchronous Query Execution
Parent topic: Graph Server REST API Version 1
19.2.6.1 Run an Asynchronous PGQL Query
GET https://localhost:7007/ui/v1/async-query
Run a PGQL query asynchronously on a property graph.
Version: 1
See Table 19-5 for more information on query parameters.
Request
The following curl
command executes a PGQL query asynchronously on a property graph:
curl --cacert /etc/oracle/graph/ca_certificate.pem -b cookie.txt 'https://localhost:7007/ui/v1/async-query?pgql=SELECT%20e%0AMATCH%20()-%5Be%5D-%3E()%0ALIMIT%205&graph=hr¶llelism=&size=100'
Response: None.
Note:
An error message will be returned in case the query is malformed or if the graph does not exist.Parent topic: Asynchronous REST Endpoints
19.2.6.2 Check Asynchronous Query Completion
GET https://localhost:7007/ui/v1/async-query-complete
Checks if an asynchronous query execution is completed.
Version: v1
Request
The following curl
command checks if the PGQL query
execution is completed:
curl --cacert /etc/oracle/graph/ca_certificate.pem -b cookie.txt 'https://localhost:7007/ui/v1/async-query-complete'
Response: A boolean that indicates if the query execution is completed. For example,
true
Note:
You do not have to specify any request ID
, as the
currently executing query is attached to your HTTP session. You can only have
one query executing per session. For concurrent query execution, create multiple
HTTP sessions by logging in multiple times.
Parent topic: Asynchronous REST Endpoints
19.2.6.3 Retrieve Asynchronous Query Result
GET https://localhost:7007/ui/v1/async-result
Retreive the result of an asynchronous query.
Version: v1
Note:
The endpoint,GET
https://localhost:7007/ui/v1/async-result
to retrieve a query result is
deprecated:curl --cacert /etc/oracle/graph/ca_certificate.pem -b cookie.txt 'https://localhost:7007/ui/v1/async-result?pgql=SELECT%20e%0AMATCH%20()-%5Be%5D-%3E()%0ALIMIT%205&graph=hr¶llelism=&size=100'
Request
The following curl
command retrieves the result of a successfully completed query:
curl --cacert /etc/oracle/graph/ca_certificate.pem -b cookie.txt 'https://localhost:7007/ui/v1/async-result'
Response: The PGQL query result in JSON format.
{
"name": "bank_graph_analytics_2",
"resultSetId": "pgql_14",
"graph": {
"idType": "number",
"vertices": [
{
"_id": "1",
"p": [],
"l": [
"Accounts"
],
"g": [
"anonymous_1"
]
},
{
"_id": "418",
"p": [],
"l": [
"Accounts"
],
"g": [
"anonymous_2"
]
},
{
"_id": "259",
"p": [],
"l": [
"Accounts"
],
"g": [
"anonymous_2"
]
}
],
"edges": [
{
"_id": "0",
"p": [
{
"n": "AMOUNT",
"v": "1000.0",
"s": false
}
],
"l": [
"Transfers"
],
"g": [
"e"
],
"s": "1",
"d": "259",
"u": false
},
{
"_id": "1",
"p": [
{
"n": "AMOUNT",
"v": "1000.0",
"s": false
}
],
"l": [
"Transfers"
],
"g": [
"e"
],
"s": "1",
"d": "418",
"u": false
}
],
"paths": [],
"totalNumResults": 2
},
"table": "e\nPgxEdge[provider=Transfers,ID=0]\nPgxEdge[provider=Transfers,ID=1]"
}
Parent topic: Asynchronous REST Endpoints
19.2.6.4 Cancel an Asynchronous Query Execution
DELETE https://localhost:7007/ui/v1/async-query
Cancels the execution of an asynchronous query.
Version: 1
Request
The following curl
command cancels a currently executing PGQL Query on a property graph:
curl -X DELETE --cacert /etc/oracle/graph/ca_certificate.pem -b cookie.txt 'https://localhost:7007/ui/v1/async-query'
Response: Confirmation of the cancellation or an error message if the query has already completed execution.
Parent topic: Asynchronous REST Endpoints