1. Graph Developer's Guide for Property Graph
  2. Getting Started with Oracle Property Graphs
  3. Property Graph Support Overview
  4. Using Oracle Graph with the Autonomous Database
  5. Using Autonomous Database Graph Client

1.10.1 Using Autonomous Database Graph Client

Using the AdbGraphClient API, you can access Graph Studio features in Autonomous Database programmatically using the Oracle Graph Client or through your Java or Python application.

This API provides the following capabilities:

  • Authenticate with Autonomous Database
  • Manage the Graph Studio environment
  • Execute graph queries and algorithms against the graph server (PGX)
  • Execute graph queries directly against Oracle Database

To use the AdbGraphClient API, you must have access to Oracle Graph Client installation. The API is provided by the Oracle Graph Client library which is a part of the Oracle Graph Server and Client distribution. See Installing Oracle Graph Client on how to install and get started with the graph client shell CLIs for Java or Python.

Also, prior to using the Autonomous Database Graph Client, ensure you meet all the prerequisite requirements explained in Prerequisites for Using Autonomous Database Graph Client.
The following example shows using the AdbGraphClient API to establish a connection to Graph Studio, start an environment with allocated memory, load a PG View graph into memory, execute PGQL queries and run algorithms against the graph.

Note:

See the Javadoc and Python API Reference for more information on AdbGraphClient API.
  1. Start the interactive graph shell CLI and connect to your Autonomous Database instance as shown: 
    cd /opt/oracle/graph
./bin/opg4j --no_connect
For an introduction type: /help intro
Oracle Graph Server Shell 22.2.0
opg4j> import oracle.pg.rdbms.*
opg4j> var config = AdbGraphClientConfiguration.builder()
config ==> AdbGraphClientConfiguration.AdbGraphClientConfigurationBuilder(endpoint=null, tenant=null, database=null, username=null, password=null, httpClient$value=null, refreshTimeBeforeTokenExpiry$value=0, refreshTimeBeforeTokenExpiryTimeUnit$value=null, executorService$value=null, jobPollInterval$value=0, jobPollIntervalTimeUnit$value=null, graphStudioApiVersion$value=null)
opg4j> config.database("<DB_name>")
$3 ==> AdbGraphClientConfiguration.AdbGraphClientConfigurationBuilder(endpoint=null, tenant=null, database=<DB_name>, username=null, password=null, httpClient$value=null, refreshTimeBeforeTokenExpiry$value=0, refreshTimeBeforeTokenExpiryTimeUnit$value=null, executorService$value=null, jobPollInterval$value=0, jobPollIntervalTimeUnit$value=null, graphStudioApiVersion$value=null)
opg4j> config.tenant("<tenant_OCID>")
$4 ==> AdbGraphClientConfiguration.AdbGraphClientConfigurationBuilder(endpoint=null, tenant=<tenant_OCID>, database=<DB_name>, username=null, password=null, httpClient$value=null, refreshTimeBeforeTokenExpiry$value=0, refreshTimeBeforeTokenExpiryTimeUnit$value=null, executorService$value=null, jobPollInterval$value=0, jobPollIntervalTimeUnit$value=null, graphStudioApiVersion$value=null)
opg4j> config.username("ADBDEV")
$5 ==> AdbGraphClientConfiguration.AdbGraphClientConfigurationBuilder(endpoint=null, tenant=<tenant_OCID>, database=<DB_name>, username=ADBDEV, password=null, httpClient$value=null, refreshTimeBeforeTokenExpiry$value=0, refreshTimeBeforeTokenExpiryTimeUnit$value=null, executorService$value=null, jobPollInterval$value=0, jobPollIntervalTimeUnit$value=null, graphStudioApiVersion$value=null)
opg4j> config.password("<password_for_ADBDEV>")
$6 ==> AdbGraphClientConfiguration.AdbGraphClientConfigurationBuilder(endpoint=null, tenant=<tenant_OCID>, database=<DB_name>, username=ADBDEV, password=<password_for_ADBDEV>, httpClient$value=null, refreshTimeBeforeTokenExpiry$value=0, refreshTimeBeforeTokenExpiryTimeUnit$value=null, executorService$value=null, jobPollInterval$value=0, jobPollIntervalTimeUnit$value=null, graphStudioApiVersion$value=null)
opg4j> config.endpoint("https://<hostname-prefix>.adb.<region>.oraclecloudapps.com/")
$7 ==> AdbGraphClientConfiguration.AdbGraphClientConfigurationBuilder(endpoint=https://<hostname-prefix>.adb.<region>.oraclecloudapps.com/, tenant=<tenant_OCID>, database=<DB_name>, username=ADBDEV, password=<password_for_ADBDEV>, httpClient$value=null, refreshTimeBeforeTokenExpiry$value=0, refreshTimeBeforeTokenExpiryTimeUnit$value=null, executorService$value=null, jobPollInterval$value=0, jobPollIntervalTimeUnit$value=null, graphStudioApiVersion$value=null)
opg4j> var client = new AdbGraphClient(config.build())
client ==> oracle.pg.rdbms.AdbGraphClient@7b8d1537
    import oracle.pg.rdbms.*;
 
var config = AdbGraphClientConfiguration.builder();
config.tenant("<tenant_OCID>");
config.database("<DB_name>");
config.username("ADBDEV");
config.password("<password_for_ADBDEV>");
config.endpoint("https://<hostname-prefix>.adb.<region>.oraclecloudapps.com/");
 
var client = new AdbGraphClient(config.build());
    cd /opt/oracle/graph 
./bin/opg4py --no_connect
Oracle Graph Server Shell 22.2.0
>>> from opg4py.adb import AdbClient
>>> config = {
...          'tenant': '<tenant_OCID>',
...          'database': '<DB_name>',
...          'username': 'ADBDEV',
...          'password': '<password_for_ADBDEV>',
...          'endpoint': 'https://<hostname-prefix>.adb.<region>.oraclecloudapps.com/'
... }
>>> client = AdbClient(config)
>>> client.__enter__()
<opg4py.adb.AdbClient object at 0x7f35a071acc0>
  2. Start the PGX server environment with the desired memory as shown in the following code.
    This submits a job in Graph Studio for environment creation. job.get() waits for the environment to get started. You can always verify if the environment has started successfully with client.isAttached(). The method returns a boolean true if the environment is running.

    However, you can skip the step of creating an environment, if client.isAttached() returns true in the first step of the code. 

    opg4j> client.isAttached()
$9 ==> false
opg4j> var job=client.startEnvironment(10)
job ==> oracle.pg.rdbms.Job@117e9a56[Not completed]
opg4j> job.get()
$11 ==> null
opg4j> job.getName()
$11 ==> "Environment Creation - 16 GBs"
opg4j> job.getType()
$12 ==> ENVIRONMENT_CREATION
opg4j> job.getCreatedBy()
$13 ==> "ADBDEV"
opg4j> client.isAttached()
$11 ==> true
     if (!client.isAttached()) {
         var job = client.startEnvironment(10);
         job.get();
         System.out.println("job details: name=" + job.getName() + "type= " + job.getType() +"created_by= " + job.getCreatedBy());
      }
job details: name=Environment Creation - 16 GBstype= ENVIRONMENT_CREATIONcreated_by= ADBDEV
    >>> client.is_attached()
False
>>> job = client.start_environment(10)
>>> job.get()
>>> job.get_name()
'Environment Creation - 16 GBs'
>>> job.get_created_by()
'ADBDEV'
>>> client.is_attached()
True
  3. Create an instance and a session object as shown: 
    opg4j> var instance = client.getPgxInstance()
instance ==> ServerInstance[embedded=false,baseUrl=https://<hostname-prefix>.adb.<region>.oraclecloudapps.com/graph/pgx]
opg4j> var session = instance.createSession("AdbGraphSession")
session ==> PgxSession[ID=c403be26-ad0c-45cf-87b7-1da2a48bda54,source=AdbGraphSession]
    ServerInstance instance = client.getPgxInstance();
PgxSession session = instance.createSession("AdbGraphSession");
    >>> instance = client.get_pgx_instance()
>>> session = instance.create_session("adb-session")
  4. Load a PGView graph from your Autonomous Database instance into memory. 
    opg4j> var graph = session.readGraphByName("BANK_GRAPH", GraphSource.PG_VIEW)
graph ==> PgxGraph[name=BANK_GRAPH,N=1000,E=5001,created=1647800790654]
    PgxGraph graph = session.readGraphByName("BANK_GRAPH", GraphSource.PG_VIEW);
    >>> graph = session.read_graph_by_name("BANK_GRAPH", "pg_view")
  5. Create an Analyst and execute a Pagerank algorithm on the graph as shown: 
    opg4j> session.createAnalyst().pagerank(graph)
$16 ==> VertexProperty[name=pagerank,type=double,graph=BANK_GRAPH]
    session.createAnalyst().pagerank(graph);
    >>> session.create_analyst().pagerank(graph)
VertexProperty(name: pagerank, type: double, graph: BANK_GRAPH)
  6. Execute a PGQL query on the graph and print the result set as shown: 
    opg4j> graph.queryPgql("SELECT a.acct_id AS source, a.pagerank, t.amount, b.acct_id AS destination FROM MATCH (a)-[t]->(b) ORDER BY a.pagerank DESC LIMIT 3").print()
    PgqlResultSet rs = graph.queryPgql("SELECT a.acct_id AS source, a.pagerank, t.amount, b.acct_id AS destination FROM MATCH (a)-[t]->(b) ORDER BY a.pagerank DESC LIMIT 3");
rs.print();
    >>> rs = graph.query_pgql("SELECT a.acct_id AS source, a.pagerank, t.amount, b.acct_id AS destination FROM MATCH (a)-[t]->(b) ORDER BY a.pagerank DESC LIMIT 3").print()
    On execution, the query produces the following output:
    +------------------------------------------------------+
| source | pagerank             | amount | destination |
+------------------------------------------------------+
| 387    | 0.007302836252205922 | 1000.0 | 188         |
| 387    | 0.007302836252205922 | 1000.0 | 374         |
| 387    | 0.007302836252205922 | 1000.0 | 577         |
+------------------------------------------------------+
  7. Optionally, you can execute a PGQL query directly against the graph in the database as shown in the following code.
    In order to establish a JDBC connection to the database, you must download the wallet and save it in a secure location. See JDBC Thin Connections with a Wallet on how to determine the JDBC URL connection string. 
    opg4j> String jdbcUrl="jdbc:oracle:thin:@<tns_alias>?TNS_ADMIN=<path_to_wallet>"
opg4j> var conn = DriverManager.getConnection(jdbcUrl,"ADBDEV","<password_for_ADBDEV>")
conn ==> oracle.jdbc.driver.T4CConnection@36ee8c7b
opg4j> var pgqlConn = PgqlConnection.getConnection(conn)
pgqlConn ==> oracle.pg.rdbms.pgql.PgqlConnection@5f27d271
opg4j> var pgqlStmt = pgqlConn.createStatement()
pgqlStmt ==> oracle.pg.rdbms.pgql.PgqlExecution@4349f52c
opg4j> pgqlStmt.executeQuery("SELECT a.acct_id AS source, t.amount, b.acct_id AS destination FROM MATCH (a)-[t]->(b) ON BANK_GRAPH LIMIT 3").print()
    import oracle.pg.rdbms.pgql.PgqlConnection;
import oracle.pg.rdbms.pgql.PgqlStatement;
import oracle.pg.rdbms.pgql.PgqlResultSet;
import oracle.pgx.api.*;
import oracle.pg.rdbms.GraphServer;
import oracle.pg.rdbms.pgql.jdbc.PgqlJdbcRdbmsDriver;
….
DriverManager.registerDriver(new PgqlJdbcRdbmsDriver());
String jdbcUrl="jdbc:oracle:thin:@<tns_alias>?TNS_ADMIN=<path_to_wallet>";
Connection conn = DriverManager.getConnection(jdbcUrl,"ADBDEV","<password_for_ADBDEV>");
PgqlConnection pgqlConn = PgqlConnection.getConnection(conn);
PgqlStatement pgqlStmt = pgqlConn.createStatement();
PgqlResultSet rs = pgqlStmt.executeQuery("SELECT a.acct_id AS source, t.amount, b.acct_id AS destination FROM MATCH (a)-[t]->(b) ON BANK_GRAPH LIMIT 3");
rs.print();
    >>> jdbcUrl = "jdbc:oracle:thin:@<tns_alias>?TNS_ADMIN=<path_to_wallet>"
>>> pgql_conn = opg4py.pgql.get_connection("ADBDEV","<password_for_ADBDEV>", jdbcUrl)
>>> pgql_statement = pgql_conn.create_statement()
>>> pgql_statement.execute_query("SELECT a.acct_id AS source, t.amount, b.acct_id AS destination FROM MATCH (a)-[t]->(b) ON BANK_GRAPH LIMIT 3").print()
    On execution, the query produces the following output:
    +-------------------------------+
| SOURCE | AMOUNT | DESTINATION |
+-------------------------------+
| 1000   | 1000   | 921         |
| 1000   | 1000   | 662         |
| 1000   | 1000   | 506         |
+-------------------------------+
  8. Close the session after executing all graph queries as shown: 
    opg4j> session.close()
    opg4j> session.close();
    >>> session.close()

Parent topic: Using Oracle Graph with the Autonomous Database