1. Graph Developer's Guide for Property Graph
  2. Installing Oracle Graph Server (PGX) and Client
  3. Getting Started with the Graph Server (PGX)
  4. Connecting to the Graph Server (PGX)

15.2 Connecting to the Graph Server (PGX)

This section explains how to connect to the graph server (PGX) running in remote mode or when deployed as a web application on Apache Tomcat or Oracle WebLogic Server.

The prerequisite requirement to connect to the graph server is to have the graph server (PGX) up and running. See Starting and Stopping the Graph Server (PGX) Using the Command Line for more information on the commands to start the graph server.

Note:

If you are using the graph server (PGX) as a library, see Using Graph Server (PGX) as a Library for more information.

Parent topic: Getting Started with the Graph Server (PGX)

15.2.1 Connecting with the Graph Client CLIs

The simplest way to connect to a remote graph server (PGX) instance is to specify the base URL of the server along with the database user name required for the graph server (PGX) authentication as shown:

cd /opt/oracle/graph
./bin/opg4j --base_url https://<host>:<port> --username <graphuser>
cd /opt/oracle/graph
./bin/opg4py --base_url https://<host>:<port> --username <graphuser>
where :
  • <host>: is the server host name
  • <port>: is the server port
  • <graphuser>: is the database user

    You will be prompted for the database password.

See Also:

About Logging HTTP Requests

The graph shell suppresses all debugging messages by default. To see which HTTP requests are executed, set the log level for oracle.pgx to DEBUG, as shown in this example:

Note:

Enabling these logs can lead to sensitive information like passwords getting printed on the screen. 
opg4j> loglevel("oracle.pgx","DEBUG")
===> Log level of oracle.pgx logger set to DEBUG
opg4j> var g = session.readGraphByName("BANK_GRAPH_VIEW", GraphSource.PG_PGQL)
09:19:51,859+0000 DEBUG o.p.c.RemoteUtils - create session cookie (session ID = 82f5cc30-358a-4002-a0bc-80a4ad690a94)
09:19:51,862+0000 DEBUG o.p.c.RemoteUtils - no value for the sticky cookie given
09:19:51,862+0000 DEBUG o.p.c.RemoteUtils - create csrf token cookie (token = d43a5de8-c81c-4361-ae15-81a1867cb2d6)
09:19:51,881+0000 DEBUG o.p.c.HttpRequestExecutor - Requesting POST https://localhost:7007/core/v2/describe
09:19:51,902+0000 DEBUG o.p.c.HttpRequestExecutor - received HTTP status 202
09:19:51,904+0000 DEBUG o.p.c.HttpRequestExecutor - {"futureId":"457025d4-3945-400a-95ed-a1897e6df9ac"}
09:19:51,911+0000 DEBUG o.p.c.PgxRemoteFuture - Requesting GET https://localhost:7007/core/v1/futures/x-future-id/status
09:19:52,322+0000 DEBUG o.p.c.PgxRemoteFuture - Requesting GET https://localhost:7007/core/v1/futures/x-future-id/value
09:19:52,337+0000 DEBUG o.p.c.RemoteUtils - received HTTP status 201
09:19:52,337+0000 DEBUG o.p.c.RemoteUtils - {"source_name":"BANK_GRAPH_VIEW","optimized_for":"UPDATES","attributes":{},"vertex_id_type":"string","edge_id_strategy":"PARTITIONED_IDS","vertex_id_strategy":"PARTITIONED_IDS","error_handling":{"on_missing_vertex":"ERROR"},"source_type":"PG_PGQL","vertex_providers":[{"error_handling":{},"format":"rdbms","key_column":"ID","props":[{"column":"ID","type":"long","name":"ID","dimension":0},{"column":"NAME","type":"string","name":"NAME","dimension":0}],"name":"ACCOUNTS","parallel_hint_degree":-1,"loading":{"create_key_mapping":true},"database_table_name":"BANK_ACCOUNTS","schema":"GRAPHUSER","key_type":"long","label":"ACCOUNTS","attributes":{}}],"edge_id_type":"string","loading":{"snapshots_source":"CHANGE_SET"},"name":"BANK_GRAPH_VIEW","edge_providers":[{"error_handling":{},"format":"rdbms","source_column":"FROM_ACCT_ID","destination_vertex_provider":"ACCOUNTS","props":[{"column":"FROM_ACCT_ID","type":"long","name":"FROM_ACCT_ID","dimension":0},{"column":"TO_ACCT_ID","type":"long","name":"TO_ACCT_ID","dimension":0},{"column":"AMOUNT","type":"long","name":"AMOUNT","dimension":0},{"column":"DESCRIPTION","type":"string","name":"DESCRIPTION","dimension":0}],"name":"TRANSFERS","parallel_hint_degree":-1,"source_vertex_provider":"ACCOUNTS","loading":{"create_key_mapping":false},"database_table_name":"BANK_TXNS","schema":"GRAPHUSER","destination_column":"TO_ACCT_ID","key_type":"long","label":"TRANSFERS","attributes":{}}]}
09:19:52,545+0000 DEBUG o.p.c.RemoteUtils - create session cookie (session ID = 82f5cc30-358a-4002-a0bc-80a4ad690a94)
09:19:52,547+0000 DEBUG o.p.c.RemoteUtils - no value for the sticky cookie given
09:19:52,547+0000 DEBUG o.p.c.RemoteUtils - create csrf token cookie (token = d43a5de8-c81c-4361-ae15-81a1867cb2d6)
09:19:52,673+0000 DEBUG o.p.c.HttpRequestExecutor - Requesting POST https://localhost:7007/core/v1/loadGraph
09:19:52,692+0000 DEBUG o.p.c.HttpRequestExecutor - received HTTP status 202
09:19:52,695+0000 DEBUG o.p.c.HttpRequestExecutor - {"futureId":"854bd093-8b80-437b-82ff-97f691436131"}
09:19:52,695+0000 DEBUG o.p.c.PgxRemoteFuture - Requesting GET https://localhost:7007/core/v1/futures/x-future-id/status
09:19:53,313+0000 DEBUG o.p.c.PgxRemoteFuture - Requesting GET https://localhost:7007/core/v1/futures/x-future-id/value
09:19:53,331+0000 DEBUG o.p.c.RemoteUtils - received HTTP status 201
09:19:53,332+0000 DEBUG o.p.c.RemoteUtils - {"id":"803F9E73-87BD-461E-A11A-A54853E8A4A0","links":[{"href":"core/v1/graphs/x-graph-id","rel":"self","method":"GET","interaction":["async-polling"]},{"href":"core/v1/graphs/x-graph-id","rel":"canonical","method":"GET","interaction":["async-polling"]}],"graphName":"BANK_GRAPH_VIEW","vertexTables":{"ACCOUNTS":{"name":"ACCOUNTS","metaData":{"name":"ACCOUNTS","idType":"long","labels":["ACCOUNTS"],"properties":[{"name":"ID","id":null,"propertyType":"long","dimension":0,"transient":true,"links":null,"propertyId":"6997E486-C525-4C5B-8A1B-8044386CF379"},{"name":"NAME","id":null,"propertyType":"string","dimension":0,"transient":true,"links":null,"propertyId":"F5473583-61AE-4EB8-B397-EF2E4E93DD8F"}],"edgeProviderNamesWhereSource":["TRANSFERS"],"edgeProviderNamesWhereDestination":["TRANSFERS"],"id":null,"links":null},"providerLabels":["ACCOUNTS"],"keyPropertyName":"ID","entityKeyType":"long","isIdentityKeyMapping":false,"vertexProperties":{"05E515A7-CCF7-4A21-BC31-D4444D3B1CF0":{"id":"05E515A7-CCF7-4A21-BC31-D4444D3B1CF0","links":[{"href":"core/v1/graphs/x-graph-id/properties/x-property-name","rel":"self","method":"GET","interaction":["async-polling"]},{"href":"core/v1/graphs/x-graph-id/properties/x-property-name","rel":"canonical","method":"GET","interaction":["async-polling"]}],"dimension":0,"propertyId":"05E515A7-CCF7-4A21-BC31-D4444D3B1CF0","name":"ID","entityType":"vertex","type":"long","namespace":"2C17C639-3771-3E30-88AE-34D6B380C5EC","transient":false},"0DCCD46B-ED5A-4511-865E-65CDCE6C3DFC":{"id":"0DCCD46B-ED5A-4511-865E-65CDCE6C3DFC","links":[{"href":"core/v1/graphs/x-graph-id/properties/x-property-name","rel":"self","method":"GET","interaction":["async-polling"]},{"href":"core/v1/graphs/x-graph-id/properties/x-property-name","rel":"canonical","method":"GET","interaction":["async-polling"]}],"dimension":0,"propertyId":"0DCCD46B-ED5A-4511-865E-65CDCE6C3DFC","name":"NAME","entityType":"vertex","type":"string","namespace":"2C17C639-3771-3E30-88AE-34D6B380C5EC","transient":false}},"vertexLabels":{"id":"13FE312F-18C8-4AFF-A154-AEDC3C5E86FC","links":[{"href":"core/v1/graphs/x-graph-id/properties/x-property-name","rel":"self","method":"GET","interaction":["async-polling"]},{"href":"core/v1/graphs/x-graph-id/properties/x-property-name","rel":"canonical","method":"GET","interaction":["async-polling"]}],"dimension":-1,"propertyId":"13FE312F-18C8-4AFF-A154-AEDC3C5E86FC","name":"__vertex_labels__","entityType":"vertex","type":"ro_string_set","namespace":"2C17C639-3771
09:19:53,457+0000 DEBUG o.p.a.PgxSession - ==> change sets as snapshot source. Returning graph loaded by the engine
g ==> PgxGraph[name=BANK_GRAPH_VIEW,N=1000,E=4993,created=1704705593065]
>>>setloglevel("oracle.pgx","DEBUG")
>>> graph = session.read_graph_by_name('BANK_GRAPH_VIEW', 'pg_pgql')
09:26:26,548+0000 DEBUG o.p.c.RemoteUtils - create session cookie (session ID = 279f1676-9229-4c5d-bc71-473e5ce5afb9)
09:26:26,554+0000 DEBUG o.p.c.RemoteUtils - no value for the sticky cookie given
09:26:26,555+0000 DEBUG o.p.c.RemoteUtils - create csrf token cookie (token = 354b9253-84fb-4689-8d29-79da8ec1e3cf)
09:26:26,617+0000 DEBUG o.p.c.HttpRequestExecutor - Requesting POST https://localhost:7007/core/v2/describe
09:26:26,670+0000 DEBUG o.p.c.HttpRequestExecutor - received HTTP status 202
09:26:26,671+0000 DEBUG o.p.c.HttpRequestExecutor - {"futureId":"95a4da84-ff08-4471-97ac-6a571c68a82f"}
09:26:26,675+0000 DEBUG o.p.c.PgxRemoteFuture - Requesting GET https://localhost:7007/core/v1/futures/x-future-id/status
09:26:26,708+0000 DEBUG o.p.c.PgxRemoteFuture - Requesting GET https://localhost:7007/core/v1/futures/x-future-id/value
09:26:26,716+0000 DEBUG o.p.c.RemoteUtils - received HTTP status 201
09:26:26,717+0000 DEBUG o.p.c.RemoteUtils - {"source_name":"BANK_GRAPH_VIEW","optimized_for":"UPDATES","attributes":{},"vertex_id_type":"string","edge_id_strategy":"PARTITIONED_IDS","vertex_id_strategy":"PARTITIONED_IDS","error_handling":{"on_missing_vertex":"ERROR"},"source_type":"PG_PGQL","vertex_providers":[{"error_handling":{},"format":"rdbms","key_column":"ID","props":[{"column":"ID","type":"long","name":"ID","dimension":0},{"column":"NAME","type":"string","name":"NAME","dimension":0}],"name":"ACCOUNTS","parallel_hint_degree":-1,"loading":{"create_key_mapping":true},"database_table_name":"BANK_ACCOUNTS","schema":"GRAPHUSER","key_type":"long","label":"ACCOUNTS","attributes":{}}],"edge_id_type":"string","loading":{"snapshots_source":"CHANGE_SET"},"name":"BANK_GRAPH_VIEW","edge_providers":[{"error_handling":{},"format":"rdbms","source_column":"FROM_ACCT_ID","destination_vertex_provider":"ACCOUNTS","props":[{"column":"FROM_ACCT_ID","type":"long","name":"FROM_ACCT_ID","dimension":0},{"column":"TO_ACCT_ID","type":"long","name":"TO_ACCT_ID","dimension":0},{"column":"AMOUNT","type":"long","name":"AMOUNT","dimension":0},{"column":"DESCRIPTION","type":"string","name":"DESCRIPTION","dimension":0}],"name":"TRANSFERS","parallel_hint_degree":-1,"source_vertex_provider":"ACCOUNTS","loading":{"create_key_mapping":false},"database_table_name":"BANK_TXNS","schema":"GRAPHUSER","destination_column":"TO_ACCT_ID","key_type":"long","label":"TRANSFERS","attributes":{}}]}
09:26:26,862+0000 DEBUG o.p.c.RemoteUtils - create session cookie (session ID = 279f1676-9229-4c5d-bc71-473e5ce5afb9)
09:26:26,862+0000 DEBUG o.p.c.RemoteUtils - no value for the sticky cookie given
09:26:26,862+0000 DEBUG o.p.c.RemoteUtils - create csrf token cookie (token = 354b9253-84fb-4689-8d29-79da8ec1e3cf)
09:26:26,930+0000 DEBUG o.p.c.HttpRequestExecutor - Requesting POST https://localhost:7007/core/v1/loadGraph
09:26:26,963+0000 DEBUG o.p.c.HttpRequestExecutor - received HTTP status 202
09:26:26,964+0000 DEBUG o.p.c.HttpRequestExecutor - {"futureId":"a6ec1f14-891d-470a-a20a-3e0a4a76c11d"}
09:26:26,965+0000 DEBUG o.p.c.PgxRemoteFuture - Requesting GET https://localhost:7007/core/v1/futures/x-future-id/status
09:26:27,183+0000 DEBUG o.p.c.PgxRemoteFuture - Requesting GET https://localhost:7007/core/v1/futures/x-future-id/value
09:26:27,202+0000 DEBUG o.p.c.RemoteUtils - received HTTP status 201
09:26:27,203+0000 DEBUG o.p.c.RemoteUtils - {"id":"CCA6B5D6-46DB-4DFE-AC60-2FDFBD8631AC","links":[{"href":"core/v1/graphs/x-graph-id","rel":"self","method":"GET","interaction":["async-polling"]},{"href":"core/v1/graphs/x-graph-id","rel":"canonical","method":"GET","interaction":["async-polling"]}],"graphName":"BANK_GRAPH_VIEW","vertexTables":{"ACCOUNTS":{"name":"ACCOUNTS","metaData":{"name":"ACCOUNTS","idType":"long","labels":["ACCOUNTS"],"properties":[{"name":"ID","id":null,"propertyType":"long","dimension":0,"transient":true,"links":null,"propertyId":"5A6A679C-BBD8-4CA9-886C-19D7DA3041F5"},{"name":"NAME","id":null,"propertyType":"string","dimension":0,"transient":true,"links":null,"propertyId":"3B479E88-3441-49EA-95EE-FC14EE0FD318"}],"edgeProviderNamesWhereSource":["TRANSFERS"],"edgeProviderNamesWhereDestination":["TRANSFERS"],"id":null,"links":null},"providerLabels":["ACCOUNTS"],"keyPropertyName":"ID","entityKeyType":"long","isIdentityKeyMapping":false,"vertexProperties":{"9B32DB07-AD6A-47AA-AD7E-56FE417D0423":{"id":"9B32DB07-AD6A-47AA-AD7E-56FE417D0423","links":[{"href":"core/v1/graphs/x-graph-id/properties/x-property-name","rel":"self","method":"GET","interaction":["async-polling"]},{"href":"core/v1/graphs/x-graph-id/properties/x-property-name","rel":"canonical","method":"GET","interaction":["async-polling"]}],"dimension":0,"propertyId":"9B32DB07-AD6A-47AA-AD7E-56FE417D0423","name":"ID","entityType":"vertex","type":"long","namespace":"2C17C639-3771-3E30-88AE-34D6B380C5EC","transient":false},"99C98B32-FD2F-46B5-A89A-BBB043E38F7E":{"id":"99C98B32-FD2F-46B5-A89A-BBB043E38F7E","links":[{"href":"core/v1/graphs/x-graph-id/properties/x-property-name","rel":"self","method":"GET","interaction":["async-polling"]},{"href":"core/v1/graphs/x-graph-id/properties/x-property-name","rel":"canonical","method":"GET","interaction":["async-polling"]}],"dimension":0,"propertyId":"99C98B32-FD2F-46B5-A89A-BBB043E38F7E","name":"NAME","entityType":"vertex","type":"string","namespace":"2C17C639-3771-3E30-88AE-34D6B380C5EC","transient":false}},"vertexLabels":{"id":"85CE5DC4-B2B3-4326-B970-F1A6EB5E0345","links":[{"href":"core/v1/graphs/x-graph-id/properties/x-property-name","rel":"self","method":"GET","interaction":["async-polling"]},{"href":"core/v1/graphs/x-graph-id/properties/x-property-name","rel":"canonical","method":"GET","interaction":["async-polling"]}],"dimension":-1,"propertyId":"85CE5DC4-B2B3-4326-B970-F1A6EB5E0345","name":"__vertex_labels__","entityType":"vertex","type":"ro_string_set","namespace":"2C17C639-3771
09:26:27,357+0000 DEBUG o.p.a.PgxSession - ==> change sets as snapshot source. Returning graph loaded by the engine

Parent topic: Connecting to the Graph Server (PGX)

15.2.2 Connecting with Java

You can obtain a connection to a remote graph server (PGX) instance by simply passing the base URL of the remote PGX instance to the getInstance() method. By doing this, your application automatically uses the PGX client libraries to connect to a remotely-located graph server (PGX).

You can specify the base URL when you initialize the graph server (PGX) instance using Java. An example is as follows. A URL to an graph server (PGX) is provided to the getInMemAnalyst API call. 

import oracle.pgx.api.*;
import oracle.pg.rdbms.*;
ServerInstance instance = GraphServer.getInstance("https://<hostname>:<port>","<username>","<password>".toCharArray());
PgxSession session = instance.createSession("my-session");

Note:

See Java API Reference for more information on the Java APIs.

Parent topic: Connecting to the Graph Server (PGX)

15.2.2.1 Starting and Stopping the PGX Engine

You can start the graph server (PGX ) from the application by making a call to instance.startEngine() which takes a JSON object as an argument for PGX configuration.

Note:

Stopping the PGX Engine

You can stop the PGX engine using one of the following APIs:

instance.shutdownEngineNow(); // cancels pending tasks, throws exception if engine is not running
instance.shutdownEngineNowIfRunning(); // cancels pending tasks, only tries to shut down if engine is running
if (instance.shutdownEngine(30, TimeUnit.SECONDS) == false) { 
  // doesn't accept new tasks but finishes up remaining tasks
  // pending tasks didn't finish after 30 seconds
}

Note:

Shutting down the PGX engine keeps the Apache Tomcat server alive, but new sessions cannot be created. Also, all the current sessions and tasks will be cancelled and terminated.

Parent topic: Connecting with Java

15.2.3 Connecting with Python

You can connect to a remote graph server (PGX) instance in your Python program. You must first authenticate with the remote server before you can create a session as illustrated in the following example:

import pypgx
import opg4py
import opg4py.graph_server as graph_server
pgql_conn = opg4py.pgql.get_connection("<username>","<password>", "<jdbc_url>")
pgql_statement = pgql_conn.create_statement()
pgql = """
        CREATE PROPERTY GRAPH bank_graph
        VERTEX TABLES (
          bank_accounts
            LABEL ACCOUNTS
            PROPERTIES (ID, NAME)
        )
        EDGE TABLES (
          bank_txns
            SOURCE KEY (from_acct_id) REFERENCES bank_accounts (ID)
            DESTINATION KEY (to_acct_id) REFERENCES bank_accounts (ID)
            LABEL TRANSFERS
            PROPERTIES (FROM_ACCT_ID, TO_ACCT_ID, AMOUNT, DESCRIPTION)
        ) OPTIONS(PG_PGQL)
"""
pgql_statement.execute(pgql)
instance = graph_server.get_instance("<base_url>", "<username>", "<password>")
session = instance.create_session("my_session")
graph = session.read_graph_by_name('BANK_GRAPH', 'pg_pgql')
analyst = session.create_analyst()
analyst.pagerank(graph)
rs = graph.query_pgql("SELECT id(x), x.pagerank FROM MATCH (x) LIMIT 5")
rs.print()

To execute, save the above program into a file named program.py and run the following command: 

python3 program.py

You will see the following output:

+-------------------------------------------+
| id(x)             | pagerank              |
+-------------------------------------------+
| BANK_ACCOUNTS(2)  | 9.749447313256548E-4  |
| BANK_ACCOUNTS(4)  | 0.004584001759076056  |
| BANK_ACCOUNTS(6)  | 5.358461393401424E-4  |
| BANK_ACCOUNTS(8)  | 0.0013051552434930175 |
| BANK_ACCOUNTS(10) | 0.0015040122009364232 |
+-------------------------------------------+

Converting PGQL result set into pandas dataframe

Additionally, you can also convert the PGQL result set to a pandas.DataFrame object using the to_pandas() method. This makes it easier to perform various data filtering operations on the result set and it can also be used in Lambda functions. For example,
example_query = (
    "SELECT n.name AS name, n.age AS age "
    "WHERE (n)"
)
result_set = sample_graph.query_pgql(example_query)
result_df = result_set.to_pandas()

result_df['age_bin'] = result_df['age'].apply(lambda x: int(x)/20) # create age bins based on age ranges

Note:

To view the complete set of available Python APIs, see OPG4PY Python API Reference.

Parent topic: Connecting to the Graph Server (PGX)