12.1 readGraphByName APIを使用したPGQLプロパティ・グラフのロード
PGQLプロパティ・グラフを名前でグラフ・サーバー(PGX)にロードできます。
PgxSession#readGraphByName APIを使用して、PGQLプロパティ・グラフをロードできます。
readGraphByName(String schemaName, String graphName, GraphSource source, ReadGraphOption options)
次の表に、メソッドで使用される引数を示します:
表12-1 readGraphByNameメソッドのパラメータ
| パラメータ | 説明 | オプション |
|---|---|---|
schemaName |
スキーマの所有者 | はい |
graphName |
PGQLプロパティ・グラフの名前 | 不可 |
source |
グラフのソース形式:
|
不可 |
options |
グラフ最適化オプションを表します | はい |
readGraphByName()メソッドは、PGQLプロパティ・グラフのメタデータ表を読み取り、グラフをロードするためのグラフ構成を内部的に生成します。このAPIを使用するには、PGX_SESSION_NEW_GRAPH権限が必要です。
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)
readGraphByName()メソッドでは、CLOBデータ型の列があるデータベース表からPGQLプロパティ・グラフをロードすることもできます。
- readGraphByName APIのオプションの指定
readGraphByNameAPIを使用してPGQLプロパティ・グラフをロードする場合は、グラフ最適化オプションまたはOnMissingVertexOption、あるいはその両方を指定できます。 - readGraphByName APIへのスキーマ名の指定
readGraphByNameAPIを使用してPGQLプロパティ・グラフをロードするときにスキーマ名を指定できます。 - readGraphByName APIのPropertyLoadingModeオプションの指定
readGraphByNameAPIを使用してPGQLプロパティ・グラフをロードするときに、PropertyLoadingModeオプションを指定して、選択したプロパティを含めたり除外できます。
関連項目:
グラフ・サーバー(PGX)でサポートされるタイプの詳細は、Oracle DatabaseタイプのPGXタイプへのマッピングを参照してください12.1.1 readGraphByName APIのオプションの指定
readGraphByName APIを使用してPGQLプロパティ・グラフをロードする場合は、グラフ最適化オプションまたはOnMissingVertexOption、あるいはその両方を指定できます。
PGQLプロパティ・グラフを名前でロードする際、ReadGraphOptionインタフェースでは追加のoptionsパラメータがサポートされます。
次の各項では、ReadGraphOptionインタフェースでサポートされている様々なオプションについて説明します。
グラフ最適化オプションの使用
最適化戦略によって、グラフが読取り集中型のシナリオに最適化されるか、高速な更新のために最適化されるかが決まります。問合せや更新などのグラフ操作のパフォーマンス特性に影響します。
サポートされているグラフ最適化optionsは次のとおりです:
ReadGraphOption.optimizeFor(GraphOptimizedFor.READ): このオプションは、グラフのプライマリ操作が読取りベースで、更新の頻度が低いか更新がない場合に選択できます。この戦略を選択すると、新しいグラフまたはグラフ・スナップショットが作成されるたびに、グラフのデータ構造がレプリケートされます。これにより、トラバーサルや問合せなどの読取り操作が迅速かつ効率的になります。ただし、スナップショットの作成にはコストがかかる可能性があり、更新時のパフォーマンス・オーバーヘッドやメモリー使用量の増加につながることもあります。
ReadGraphOption.optimizeFor(GraphOptimizedFor.UPDATES): このオプションは、ノードやエッジの追加や削除、既存の要素のプロパティの変更など、グラフが頻繁に更新されることが予想される場合に選択できます。この戦略を選択すると、更新の管理にデルタ・ログが使用されます。このアプローチにより、更新はメモリー効率が高く、高速になります。ただし、これらのデルタ更新を適用する必要があるため、グラフの問合せ時に時間のオーバーヘッドが発生する場合があります。
ReadGraphOption.synchronizable(): このオプションは、グラフが同期されることが予想される場合に選択できます。
次の点に注意してください。
-
synchronizable()オプションは、UPDATEおよびREADと組み合せて使用できます。ただし、UPDATEオプションとREADオプションは同時に使用できません。 SYNCHRONIZABLEオプションのPGQLプロパティ・グラフをロードする場合は、頂点キーとエッジ・キーが数値であり、コンポジットではないことを確認します。
次の例では、READオプションとSYNCHRONIZABLEオプションのPGQLプロパティ・グラフをロードします。
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'])OnMissingVertexオプションの使用
エッジのソース頂点または宛先頂点のいずれか、あるいはその両方が欠落している場合は、頂点が欠落しているエッジを処理するための動作を指定するOnMissingVertexOptionを使用できます。このオプションでは、次の値がサポートされています。
ReadGraphOption.onMissingVertex(OnMissingVertex.ERROR): これはデフォルト・オプションで、頂点が欠落しているエッジに対してエラーをスローする必要があることを指定します。ReadGraphOption.onMissingVertex(OnMissingVertex.IGNORE_EDGE): 欠落した頂点のエッジを無視する必要があることを指定します。ReadGraphOption.onMissingVertex(OnMissingVertex.IGNORE_EDGE_LOG): 欠落した頂点のエッジを無視し、無視されたすべてのエッジをログに記録する必要があることを指定します。ReadGraphOption.onMissingVertex(OnMissingVertex.IGNORE_EDGE_LOG_ONCE): 欠落した頂点のエッジを無視し、最初の無視されたエッジのみをログに記録する必要があることを指定します。
次の例では、頂点が欠落しているエッジを無視し、最初の無視されたエッジのみをログに記録することによって、PGQLプロパティ・グラフをロードします。ログを表示するには、/etc/oracle/graph/logback.xmlのデフォルトのLogback構成ファイルと、/etc/oracle/graph/logback-server.xmlのグラフ・サーバー(PGX)ロガー構成ファイルを更新して、DEBUGログを記録する必要があります。そのようにすると、無視されたエッジを/var/opt/log/pgx-server.logファイルで確認できます。
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'])12.1.2 readGraphByName APIへのスキーマ名の指定
readGraphByName APIを使用してPGQLプロパティ・グラフをロードするときにスキーマ名を指定できます。
この機能を使用すると、別のユーザー・スキーマからグラフ・サーバー(PGX)にPGQLプロパティ・グラフをロードできます。ただし、別のスキーマからPGQLプロパティ・グラフをロードする場合は、基礎となるすべてのメタデータおよびデータ表に対するREAD権限を持っていることを確認してください。
次の例では、GRAPHUSERスキーマからPGQLプロパティ・グラフをロードします。
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);12.1.3 readGraphByName APIのPropertyLoadingModeオプションの指定
readGraphByName APIを使用してPGQLプロパティ・グラフをロードするときに、PropertyLoadingModeオプションを指定して、選択したプロパティを含めたり除外できます。
デフォルトでは、readGraphByName APIは、プロパティの完全なセットとともに、PGQLプロパティ・グラフをグラフ・サーバー(PGX)にロードします。ただし、サポートされている次のPropertyLoadingModeオプションのいずれかを指定して、指定したプロパティを含めたり除外できます:
ReadGraphOption.includeProperties(): グラフのロード中に、各プロバイダに対してロードするプロパティのリストを指定できます。ReadGraphOption.excludeProperties(): グラフのロード中に、各プロバイダに対してスキップするプロパティのリストを指定できます。ReadGraphOption.topologyOnly(): グラフ・トポロジのみをロードし、すべてのプロパティをスキップする場合に、このモードを選択できます。
次の例は、ReadGraphOption.includeProperties()オプションを指定したPGQLプロパティ・グラフのロードを示しています。
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"] }),))次の例は、ReadGraphOption.excludeProperties()オプションを指定したPGQLプロパティ・グラフのロードを示しています。
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"] }), ))次の例は、ReadGraphOption.topologyOnly()オプションを指定したSQLプロパティ・グラフのロードを示しています
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(),))