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>
<host>
: is the server host name<port>
: is the server port<graphuser>
: is the database userYou will be prompted for the database password.
See Also:
- Java API Reference for information on the Java APIs
- Python API Reference for information on the Python APIs
About Logging HTTP Requests
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_VIEW)
13:00:52,493+0000 DEBUG o.p.c.RemoteUtils - create session cookie (session ID = c294d8bd-18c4-426d-b380-64c9ff2e7f43)
13:00:52,498+0000 DEBUG o.p.c.RemoteUtils - no value for the sticky cookie given
13:00:52,498+0000 DEBUG o.p.c.RemoteUtils - create csrf token cookie (token = 30377abc-2223-4773-82b9-aafd34f1966d)
13:00:52,513+0000 DEBUG o.p.c.HttpRequestExecutor - Requesting POST https://localhost:7007/core/v1/describe
13:00:52,531+0000 DEBUG o.p.c.HttpRequestExecutor - received HTTP status 202
13:00:52,531+0000 DEBUG o.p.c.HttpRequestExecutor - {"futureId":"514b1214-3ca2-4220-8117-7b3b6118ae73"}
13:00:52,533+0000 DEBUG o.p.c.PgxRemoteFuture - Requesting GET https://localhost:7007/core/v1/futures/x-future-id/status
13:00:52,771+0000 DEBUG o.p.c.PgxRemoteFuture - Requesting GET https://localhost:7007/core/v1/futures/x-future-id/value
13:00:52,777+0000 DEBUG o.p.c.RemoteUtils - received HTTP status 201
13:00:52,777+0000 DEBUG o.p.c.RemoteUtils - {"vertex_id_strategy":"PARTITIONED_IDS","attributes":{},"edge_id_strategy":"PARTITIONED_IDS","source_type":"PG_VIEW","vertex_providers":[{"parallel_hint_degree":-1,"key_type":"long","loading":{"create_key_mapping":true},"attributes":{},"format":"rdbms","key_column":"ID","name":"ACCOUNTS","database_table_name":"BANK_ACCOUNTS","error_handling":{},"schema":"GRAPHUSER","props":[{"type":"long","dimension":0,"column":"ID","name":"ID"},{"type":"string","dimension":0,"column":"NAME","name":"NAME"}],"label":"ACCOUNTS"}],"edge_id_type":"string","error_handling":{"on_missing_vertex":"ERROR"},"optimized_for":"UPDATES","vertex_id_type":"string","name":"BANK_GRAPH_VIEW","loading":{"snapshots_source":"CHANGE_SET"},"edge_providers":[{"source_vertex_provider":"ACCOUNTS","parallel_hint_degree":-1,"key_type":"long","loading":{"create_key_mapping":false},"attributes":{},"format":"rdbms","destination_vertex_provider":"ACCOUNTS","name":"TRANSFERS","source_column":"FROM_ACCT_ID","database_table_name":"BANK_TXNS","error_handling":{},"destination_column":"TO_ACCT_ID","schema":"GRAPHUSER","props":[{"type":"long","dimension":0,"column":"FROM_ACCT_ID","name":"FROM_ACCT_ID"},{"type":"long","dimension":0,"column":"TO_ACCT_ID","name":"TO_ACCT_ID"},{"type":"long","dimension":0,"column":"AMOUNT","name":"AMOUNT"},{"type":"string","dimension":0,"column":"DESCRIPTION","name":"DESCRIPTION"}],"label":"TRANSFERS"}],"source_name":"BANK_GRAPH_VIEW"}
13:00:52,948+0000 DEBUG o.p.c.RemoteUtils - create session cookie (session ID = c294d8bd-18c4-426d-b380-64c9ff2e7f43)
13:00:52,948+0000 DEBUG o.p.c.RemoteUtils - no value for the sticky cookie given
13:00:52,949+0000 DEBUG o.p.c.RemoteUtils - create csrf token cookie (token = 30377abc-2223-4773-82b9-aafd34f1966d)
13:00:53,020+0000 DEBUG o.p.c.HttpRequestExecutor - Requesting POST https://localhost:7007/core/v1/loadGraph
13:00:53,073+0000 DEBUG o.p.c.HttpRequestExecutor - received HTTP status 202
13:00:53,073+0000 DEBUG o.p.c.HttpRequestExecutor - {"futureId":"7a31abff-8bd8-4c54-a79c-4cbe236b5316"}
13:00:53,076+0000 DEBUG o.p.c.PgxRemoteFuture - Requesting GET https://localhost:7007/core/v1/futures/x-future-id/status
13:00:53,738+0000 DEBUG o.p.c.PgxRemoteFuture - Requesting GET https://localhost:7007/core/v1/futures/x-future-id/value
13:00:53,751+0000 DEBUG o.p.c.RemoteUtils - received HTTP status 201
13:00:53,752+0000 DEBUG o.p.c.RemoteUtils - {"id":"737DAFE2-129C-4AA5-BE16-7CFABC72D2F5","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":"0C11F796-9ABC-4322-9D55-4828B02EED53"},{"name":"NAME","id":null,"propertyType":"string","dimension":0,"transient":true,"links":null,"propertyId":"BD86FF3A-D24C-4A44-867B-C9A7D489692F"}],"edgeProviderNamesWhereSource":["TRANSFERS"],"edgeProviderNamesWhereDestination":["TRANSFERS"],"id":null,"links":null},"providerLabels":["ACCOUNTS"],"keyPropertyName":"ID","entityKeyType":"long","isIdentityKeyMapping":false,"vertexProperties":{"E65F9F20-476A-4C77-906E-814F99395BC3":{"id":"E65F9F20-476A-4C77-906E-814F99395BC3","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":"E65F9F20-476A-4C77-906E-814F99395BC3","name":"ID","entityType":"vertex","type":"long","namespace":"2C17C639-3771-3E30-88AE-34D6B380C5EC","transient":false},"969A8DAB-33DB-425C-9BD6-814E1D5E1788":{"id":"969A8DAB-33DB-425C-9BD6-814E1D5E1788","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":"969A8DAB-33DB-425C-9BD6-814E1D5E1788","name":"NAME","entityType":"vertex","type":"string","namespace":"2C17C639-3771-3E30-88AE-34D6B380C5EC","transient":false}},"vertexLabels":{"id":"68FD284B-6803-45B3-AE09-8E6D2DE37AFB","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":"68FD284B-6803-45B3-AE09-8E6D2DE37AFB","name":"__vertex_labels__","entityType":"vertex","type":"ro_string_set","namespace":"2C17C639-3771
13:00:53,871+0000 DEBUG o.p.a.PgxSession - ==> change sets as snapshot source. Returning graph loaded by the engine
g ==> PgxGraph[name=BANK_GRAPH_VIEW,N=999,E=4993,created=1688562053517]
>>>setloglevel("oracle.pgx","DEBUG")
>>> graph = session.read_graph_by_name('BANK_GRAPH_VIEW', 'pg_view')
13:07:00,249+0000 DEBUG o.p.c.RemoteUtils - create session cookie (session ID = bf5aefbb-a99f-45da-bd80-a953e5e4f4c5)
13:07:00,256+0000 DEBUG o.p.c.RemoteUtils - no value for the sticky cookie given
13:07:00,256+0000 DEBUG o.p.c.RemoteUtils - create csrf token cookie (token = a0c08765-cda0-48f9-878c-b3f29cc99ebf)
13:07:00,321+0000 DEBUG o.p.c.HttpRequestExecutor - Requesting POST https://localhost:7007/core/v1/describe
13:07:00,371+0000 DEBUG o.p.c.HttpRequestExecutor - received HTTP status 202
13:07:00,371+0000 DEBUG o.p.c.HttpRequestExecutor - {"futureId":"97ff8992-d2b1-473c-88dd-b11ad8f4fe71"}
13:07:00,373+0000 DEBUG o.p.c.PgxRemoteFuture - Requesting GET https://localhost:7007/core/v1/futures/x-future-id/status
13:07:00,638+0000 DEBUG o.p.c.PgxRemoteFuture - Requesting GET https://localhost:7007/core/v1/futures/x-future-id/value
13:07:00,647+0000 DEBUG o.p.c.RemoteUtils - received HTTP status 201
13:07:00,648+0000 DEBUG o.p.c.RemoteUtils - {"vertex_id_strategy":"PARTITIONED_IDS","attributes":{},"edge_id_strategy":"PARTITIONED_IDS","source_type":"PG_VIEW","vertex_providers":[{"parallel_hint_degree":-1,"key_type":"long","loading":{"create_key_mapping":true},"attributes":{},"format":"rdbms","key_column":"ID","name":"ACCOUNTS","database_table_name":"BANK_ACCOUNTS","error_handling":{},"schema":"GRAPHUSER","props":[{"type":"long","dimension":0,"column":"ID","name":"ID"},{"type":"string","dimension":0,"column":"NAME","name":"NAME"}],"label":"ACCOUNTS"}],"edge_id_type":"string","error_handling":{"on_missing_vertex":"ERROR"},"optimized_for":"UPDATES","vertex_id_type":"string","name":"BANK_GRAPH_VIEW","loading":{"snapshots_source":"CHANGE_SET"},"edge_providers":[{"source_vertex_provider":"ACCOUNTS","parallel_hint_degree":-1,"key_type":"long","loading":{"create_key_mapping":false},"attributes":{},"format":"rdbms","destination_vertex_provider":"ACCOUNTS","name":"TRANSFERS","source_column":"FROM_ACCT_ID","database_table_name":"BANK_TXNS","error_handling":{},"destination_column":"TO_ACCT_ID","schema":"GRAPHUSER","props":[{"type":"long","dimension":0,"column":"FROM_ACCT_ID","name":"FROM_ACCT_ID"},{"type":"long","dimension":0,"column":"TO_ACCT_ID","name":"TO_ACCT_ID"},{"type":"long","dimension":0,"column":"AMOUNT","name":"AMOUNT"},{"type":"string","dimension":0,"column":"DESCRIPTION","name":"DESCRIPTION"}],"label":"TRANSFERS"}],"source_name":"BANK_GRAPH_VIEW"}
13:07:00,900+0000 DEBUG o.p.c.RemoteUtils - create session cookie (session ID = bf5aefbb-a99f-45da-bd80-a953e5e4f4c5)
13:07:00,903+0000 DEBUG o.p.c.RemoteUtils - no value for the sticky cookie given
13:07:00,904+0000 DEBUG o.p.c.RemoteUtils - create csrf token cookie (token = a0c08765-cda0-48f9-878c-b3f29cc99ebf)
13:07:01,072+0000 DEBUG o.p.c.HttpRequestExecutor - Requesting POST https://localhost:7007/core/v1/loadGraph
13:07:01,132+0000 DEBUG o.p.c.HttpRequestExecutor - received HTTP status 202
13:07:01,133+0000 DEBUG o.p.c.HttpRequestExecutor - {"futureId":"e35e9fc2-d5fe-45af-ae2f-392c5719d4af"}
13:07:01,135+0000 DEBUG o.p.c.PgxRemoteFuture - Requesting GET https://localhost:7007/core/v1/futures/x-future-id/status
13:07:01,864+0000 DEBUG o.p.c.PgxRemoteFuture - Requesting GET https://localhost:7007/core/v1/futures/x-future-id/value
13:07:01,898+0000 DEBUG o.p.c.RemoteUtils - received HTTP status 201
13:07:01,899+0000 DEBUG o.p.c.RemoteUtils - {"id":"52B3EDC8-A64D-4470-B4A3-D3B73D12BEE5","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":"F7E69A4D-CBDA-45CD-B8CB-14F1388AC85B"},{"name":"NAME","id":null,"propertyType":"string","dimension":0,"transient":true,"links":null,"propertyId":"56DFA353-577A-46ED-893B-8B630C201D98"}],"edgeProviderNamesWhereSource":["TRANSFERS"],"edgeProviderNamesWhereDestination":["TRANSFERS"],"id":null,"links":null},"providerLabels":["ACCOUNTS"],"keyPropertyName":"ID","entityKeyType":"long","isIdentityKeyMapping":false,"vertexProperties":{"F71D0432-B029-4311-BCD1-1B7E00679A84":{"id":"F71D0432-B029-4311-BCD1-1B7E00679A84","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":"F71D0432-B029-4311-BCD1-1B7E00679A84","name":"ID","entityType":"vertex","type":"long","namespace":"2C17C639-3771-3E30-88AE-34D6B380C5EC","transient":false},"58DF93C1-1A94-4E96-8914-F50C58C957D2":{"id":"58DF93C1-1A94-4E96-8914-F50C58C957D2","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":"58DF93C1-1A94-4E96-8914-F50C58C957D2","name":"NAME","entityType":"vertex","type":"string","namespace":"2C17C639-3771-3E30-88AE-34D6B380C5EC","transient":false}},"vertexLabels":{"id":"39856D86-C0B7-4159-BC16-E5E68E505989","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":"39856D86-C0B7-4159-BC16-E5E68E505989","name":"__vertex_labels__","entityType":"vertex","type":"ro_string_set","namespace":"2C17C639-3771
13:07:02,122+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.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:
- See Connecting with Java for more information about connecting to a graph server (PGX) instance
and obtaining a
ServerInstance
object. - See Configuration Parameters for the Graph Server (PGX) Engine for the various configuration options for the graph server (PGX).
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_view')
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
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)