Loading a PGQL Property Graph Using the readGraphByName API

You can load a PGQL property graph by name into the graph server (PGX).

You can use the PgxSession#readGraphByName API to load a PGQL property graph:

readGraphByName(String schemaName, String graphName, GraphSource source, ReadGraphOption options)

The arguments used in the method are described in the following table:

Table: Parameters for the readGraphByName method

Parameter	Description	Optional
`schemaName`	Schema owner	Yes
`graphName`	Name of the PGQL property graph	No
`source`	Source format for the graph: `GraphSource.PG_PGQL`: This applies for PGQL property graphs. `GraphSource.PG_SQL`: This applies for SQL Property Graphs (refer to Loading a SQL Property Graph Using the readGraphByName API).	No
`options`	Represents the graph optimization options	Yes

The readGraphByName() method reads the PGQL property graph metadata tables and internally generates the graph configuration to load the graph. You must have PGX_SESSION_NEW_GRAPH permission to use this API.

opg4j> var graph = session.readGraphByName("BANKDATA", GraphSource.PG_PGQL)
$12 ==> PgxGraph[name=bankdata,N=1000,E=5001,created=1625730942294]

PgxGraph graph = session.readGraphByName("BANKDATA", GraphSource.PG_PGQL);
Graph: PgxGraph[name=bankdata,N=1000,E=5001,created=1625732149262]

>>> graph = session.read_graph_by_name('BANKDATA', 'pg_pgql')
>>> graph
PgxGraph(name: bankdata, v: 1000, e: 5001, directed: True, memory(Mb): 0)

The readGraphByName() method also allows loading of a PGQL property graph from database tables with CLOB data type columns.

Specifying Options for the readGraphByName API
You can specify graph optimization options, OnMissingVertexOption or both when using the readGraphByName API for loading a PGQL property graph.
Specifying the Schema Name for the readGraphByName API
You can specify the schema name when using the readGraphByName API for loading a PGQL property graph.
Specifying PropertyLoadingMode Options for the readGraphByName API
You can specify the PropertyLoadingMode options to include or exclude selected properties when loading a PGQL property graph using the readGraphByName API.

See Also: Mapping Oracle Data Types to PGX Types for more information on the supported types in the graph server (PGX)

Specifying Options for the readGraphByName API

You can specify graph optimization options, OnMissingVertexOption or both when using the readGraphByName API for loading a PGQL property graph.

The ReadGraphOption interface supports an additional options parameter when loading a PGQL property graph by name.

The following sections explain the various options supported by the ReadGraphOption interface.

Using the Graph Optimization Options

The optimization strategy determines whether the graph is optimized for read-intensive scenarios or for faster updates. It impacts the performance characteristics of graph operations such as querying and updating.

The supported graph optimization options are:

ReadGraphOption.optimizeFor(GraphOptimizedFor.READ): You can choose this option when the primary operations on the graph are read-based, and updates are infrequent or non-existent.

When this strategy is selected, the graph's data structures are replicated whenever a new graph or graph snapshot is created. This results in faster and more efficient read operations, such as traversals and queries. However, creating snapshots can be expensive and it can also lead to performance overhead and increased memory usage during updates.
ReadGraphOption.optimizeFor(GraphOptimizedFor.UPDATES): You can choose this option when the graph is expected to undergo frequent updates, such as adding or removing nodes and edges, or modifying properties of existing elements.

When this strategy is selected, delta logs are used to manage updates. This approach makes updates more memory-efficient and faster. However, there may be some time overhead when querying the graph due to the need to apply these delta updates.
ReadGraphOption.synchronizable(): You can choose this option when the graph is expected to be synchronized.

It is important to note the following:

synchronizable() option can be used in combination with UPDATE and READ. However, the UPDATE and READ options cannot be used at the same time.
If you are loading a PGQL property graph for SYNCHRONIZABLE option, then ensure that the vertex and edge keys are non-composite, edge keys are numeric, and vertex keys are numeric or of a character data type.

The following example loads a PGQL property graph for READ and SYNCHRONIZABLE options:

opg4j> var graph = session.readGraphByName("BANK_GRAPH", GraphSource.PG_PGQL,
...>                            ReadGraphOption.optimizeFor(GraphOptimizedFor.READ),
...>                            ReadGraphOption.synchronizable())
graph ==> PgxGraph[name=BANK_GRAPH_2,N=1000,E=5001,created=1648457198462]

PgxGraph graph = session.readGraphByName("BANK_GRAPH", GraphSource.PG_PGQL,
                                                  ReadGraphOption.optimizeFor(GraphOptimizedFor.READ),
                                                  ReadGraphOption.synchronizable());

>>> graph = session.read_graph_by_name('BANK_GRAPH',
...      'pg_pgql', options=['optimized_for_read', 'synchronizable'])

Using the OnMissingVertex Options

If either the source or destination vertex or both are missing for an edge, then you can use the OnMissingVertexOption which specifies the behavior for handling the edge with the missing vertex. The following values are supported for this option:

ReadGraphOption.onMissingVertex(OnMissingVertex.ERROR): This is the default option and this specifies that an error must be thrown for edges with missing vertices.
ReadGraphOption.onMissingVertex(OnMissingVertex.IGNORE_EDGE): Specifies that the edge for a missing vertex must be ignored.
ReadGraphOption.onMissingVertex(OnMissingVertex.IGNORE_EDGE_LOG): Specifies that the edge for a missing vertex must be ignored and all ignored edges must be logged.
ReadGraphOption.onMissingVertex(OnMissingVertex.IGNORE_EDGE_LOG_ONCE): Specifies that the edge for a missing vertex must be ignored and only the first ignored edge must be logged.

The following example loads the PGQL property graph by ignoring the edges with missing vertices and logging only the first ignored edge. Note, to view the logs, you must update the default Logback configuration file in /etc/oracle/graph/logback.xml and the graph server (PGX) logger configuration file in /etc/oracle/graph/logback-server.xml to log the DEBUG logs. You can then view the ignored edges in /var/log/oracle/graph/pgx-server.log file.

opg4j> session.readGraphByName("REGIONS", GraphSource.PG_PGQL,
...>                             ReadGraphOption.onMissingVertex(OnMissingVertex.IGNORE_EDGE_LOG_ONCE))
$7 ==> PgxGraph[name=REGIONVIEW_3,N=27,E=18,created=1655903219910]

PgxGraph graph = session.readGraphByName("REGIONS", GraphSource.PG_PGQL, ReadGraphOption.onMissingVertex(OnMissingVertex.IGNORE_EDGE_LOG_ONCE));

>>> graph = session.read_graph_by_name('REGIONS',
...      'pg_pgql', options=['on_missing_vertex_ignore_edge_log_once'])

Specifying the Schema Name for the readGraphByName API

You can specify the schema name when using the readGraphByName API for loading a PGQL property graph.

This feature allows you to load a PGQL property graph from another user schema into the graph server (PGX). However, ensure that you have READ permission on all the underlying metadata and data tables when loading a PGQL property graph from another schema.

The following example loads a PGQL property graph from the GRAPHUSER schema:

JShell
Java

opg4j> var graph = session.readGraphByName("GRAPHUSER", "FRIENDS", GraphSource.PG_PGQL)
graph ==> PgxGraph[name=FRIENDS,N=6,E=4,created=1672743474212]

PgxGraph graph = session.readGraphByName("GRAPHUSER", "FRIENDS", GraphSource.PG_PGQL);

Specifying PropertyLoadingMode Options for the readGraphByName API

You can specify the PropertyLoadingMode options to include or exclude selected properties when loading a PGQL property graph using the readGraphByName API.

By default, the readGraphByName API loads a PGQL property graph into the graph server (PGX) with the complete set of properties. However, you can specify one of the following supported PropertyLoadingMode options to include or exclude specified properties:

ReadGraphOption.includeProperties(): You can provide a list of properties to be loaded for each provider while loading the graph.
ReadGraphOption.excludeProperties(): You can provide a list of properties to be skipped for each provider while loading the graph.
ReadGraphOption.topologyOnly(): You can choose this mode if you wish to load only the graph topology and skip all the properties.

The following example shows loading a PGQL property graph with the ReadGraphOption.includeProperties() option.

opg4j> var propertyFilterBuilder = new PropertyFilterBuilder()
propertyFilterBuilder ==> oracle.pgx.config.PropertyFilterBuilder@6b44121e
opg4j> propertyFilterBuilder.addProperty("ACCOUNTS", "NAME")
$8 ==> oracle.pgx.config.PropertyFilterBuilder@6b44121e
opg4j> propertyFilterBuilder.addProperty("TRANSFERS", "AMOUNT")
$9 ==> oracle.pgx.config.PropertyFilterBuilder@6b44121e
opg4j> var graph = session.readGraphByName("BANK_GRAPH_PGQL", GraphSource.PG_PGQL, ReadGraphOption.includeProperties(propertyFilterBuilder.build()))
graph ==> PgxGraph[name=BANK_GRAPH_PGQL,N=1000,E=5001,created=1751872689499]

PropertyFilterBuilder propertyFilterBuilder = new PropertyFilterBuilder();
propertyFilterBuilder.addProperty("ACCOUNTS", "NAME");
propertyFilterBuilder.addProperties("TRANSFERS", "AMOUNT");
PgxGraph graph = session.readGraphByName("BANK_GRAPH_PGQL", GraphSource.PG_PGQL, ReadGraphOption.includeProperties(propertyFilterBuilder.build()));

>>> from pypgx._utils.pgx_types import include_properties
>>> graph = session.read_graph_by_name("BANK_GRAPH_PGQL", "pg_pgql", options=(include_properties({"ACCOUNTS": ["NAME"], "TRANSFERS" : ["AMOUNT"] }),))

The following example shows loading a PGQL property graph with the ReadGraphOption.excludeProperties() option

opg4j> var propertyFilterBuilder = new PropertyFilterBuilder()
propertyFilterBuilder ==> oracle.pgx.config.PropertyFilterBuilder@464d5365
opg4j> propertyFilterBuilder.addProperty("ACCOUNTS", "NAME")
$2 ==> oracle.pgx.config.PropertyFilterBuilder@464d5365
opg4j> propertyFilterBuilder.addProperties("TRANSFERS", "DESCRIPTION")
$3 ==> oracle.pgx.config.PropertyFilterBuilder@464d5365
opg4j> var graph = session.readGraphByName("BANK_GRAPH_PGQL", GraphSource.PG_PGQL, ReadGraphOption.excludeProperties(propertyFilterBuilder.build()))
graph ==> PgxGraph[name=BANK_GRAPH_PGQL,N=1000,E=5001,created=1751873930712]

PropertyFilterBuilder propertyFilterBuilder = new PropertyFilterBuilder();
propertyFilterBuilder.addProperty("ACCOUNTS", "NAME");
propertyFilterBuilder.addProperties("TRANSFERS", "DESCRIPTION");
PgxGraph graph = session.readGraphByName("BANK_GRAPH_PGQL", GraphSource.PG_PGQL, ReadGraphOption.excludeProperties(propertyFilterBuilder.build()));

>>> from pypgx._utils.pgx_types import exclude_properties
>>> graph = session.read_graph_by_name("BANK_GRAPH_PGQL", "pg_pgql", options=(exclude_properties({"ACCOUNTS": ["NAME"], "TRANSFERS" : ["DESCRIPTION"] }), ))

The following example shows loading a SQL property graph with the ReadGraphOption.topologyOnly() option

opg4j> var graph = session.readGraphByName("BANK_GRAPH_PGQL", GraphSource.PG_PGQL, ReadGraphOption.topologyOnly())
graph ==> PgxGraph[name=STUDENT_NETWORK_2,N=4,E=4,created=1751204695863]

PgxGraph graph = session.readGraphByName("BANK_GRAPH_PGQL", GraphSource.PG_PGQL, ReadGraphOption.topologyOnly());

>>> from pypgx._utils.pgx_types import topology_only
>>> graph = session.read_graph_by_name("BANK_GRAPH_PGQL", "pg_pgql", options=(topology_only(),))