この記事は、RexZhengさんが執筆した記事を日本語化したものです。
本記事はこちらから。

この記事では、Oracle Cloud Infrastructure Database Systemのインスンスに Oracle Property Graph Server and clientをインストールし、環境構築をしていきます。更に、Property Graphサーバとデータベースサーバにクライアント側から正しく接続するための設定方法も紹介していきます。

上記のセットアップ手順だけではなく、2つのサンプルも用意していますので、グラフテクノロジーを体感していきましょう。

最新版の記事をチェックしたい方はこちら

今回の環境

下記が、本記事での環境をまとめたリストになります。

Oracle Property Graph Server 20.4
Oracle Property Graph Client 20.4
Oracle Database Software Edition: Enterprise Edition High Performance
DB System Version: 19.9.0.0.0
Oracle Linux 7.8 x64
Oracle JDK 11
Browser: Firefox

PL/SQL Packages

Oracle Database 12.2以降であれば、Oracle Graph Server and ClientはOracle Databaseでちゃんと動きます。その前に、Oracle Graph Server and Clientの最新のPL/SQLパッケージを自分でインストールしなければなりません。
Oracle Graph Client for PL/SQLを、こちらからダウンロード

Download Oracle Graph Client for PL/SQLをダウンロード後、任意のディレクトリ内で解凍して下さい。
下記のSQL文でOracle Databaseにログインしましょう。

-- SYSDBAで接続
SQL> alter session set container=<YOUR_PDB_NAME>;
SQL> @opgremov.sql
SQL> @catopg.sql

注記: 未解凍のZipディレクトリには2つのディレクトリがあると思います。一つは、Oracle Database 18c以下を使っているユーザのためのもの。もう一つが、Oracle Database 19c以降を使っているユーザ用です。DBA権限を持つデータベースユーザとして、REAME.mdファイル内のインストラクションに従って下さい。インストラクションを参考にする時は、自分のデータベースのバージョンに合っているか確認してください。これは、グラフ機能が入ったPDBを使用する際に、都度必要になります。私が作ったDBCSインスタンスは19cですから、私は19c_and_aboveのスクリプトを流していきます。

Oracle Property Graph Server and Clientのインストール

このセクションでは、Oracle Graph Server and Client 20.4.の最新バージョンをインストールしていきます。
下記のページからインストールパッケージをダウンロード可能です。

Oracle Graph Server and Client Downloads

Oracle JDK 11

20.4から、Oracle Graph Server and Clientは同じJDKバージョンである11を使うようになりました。
JDK 11を先にダウンロードしていきましょう。

Java SE Development Kit 11 Downloads

sudo rpm -i jdk-11.0.9_linux-x64_bin.rpm
java --version
opc@db19h graph]$

[Figure: java version]

Oracle Property Graph Server 20.4

インストール

下記のコマンドでOracle Property graph Serverをインストールを始めます。

sudo rpm -i oracle-graph-20.4.0.x86_64.rpm

このコマンドは実行してもレスポンスは返ってきません。
下記のコマンドよりOracle Property Graph Serverをスタートさせることができます。

sudo systemctl start pgx
systemctl status pgx
sudo systemctl stop pgx

[Figure: PGX start & status]

Oracle Databaseの設定

oracleユーザに変更し、sysとしてデータベースに接続します。

sudo su - oracle
sqlplus / as sysdba

[Figure: connect to DB]

PDBのpdb1に demographというユーザを作成します。
下記のようにロールと表領域を与えていきます。
全ての表は、スキーマdemographに作成され、ロードされます。

CREATE USER demograph IDENTIFIED BY <PASSWORD>;
GRANT CONNECT, resource TO demograph;
GRANT CREATE VIEW TO demograph;

CREATE ROLE graph_developer;
CREATE ROLE graph_administrator;

GRANT graph_developer TO demograph;
GRANT graph_administrator to demograph;

ALTER USER demograph QUOTA 10G ON USERS

GRANT UNLIMITED TABLESPACE TO demograph;

[Figure: prepare DB user demograph]

Oracle Property Graph Serverの設定

graphというシステムユーザを追加

sudo useradd graph
sudo usermod -a -G oraclegraph graph
sudo passwd graph

pgx.confという設定ファイルの中にJDB connection stringを追加

sudo vim /etc/oracle/graph/pgx.conf
jdbc:oracle:thin:@//db19h.sub11160238550.graphvcntokyo.oraclevcn.com:1521/pdb1.sub11160238550.graphvcntokyo.oraclevcn.com

connection stringはDBCSウェブコンソールから手に入ります。
もしくは、lsnrctl statusコマンドからサービス名を入手しましょう。

ユーザdemographはpdb1内に作成されたので,ここで私が使うconnection stringはpdb1になります。

[Figure: JDBC in pgx.conf]

server.confという設定ファイルを編集

enable_tlsをfalseに設定。

sudo vim /etc/oracle/graph/server.conf

[Figure: enable_tls in server.conf]

PGX serviceを再起動

sudo systemctl restart pgx
sudo systemctl status pgx

[Figure: restart PGX service]

Oracle Property Graph Client 20.4

インストール

ユーザgraphに変更

sudo su - graph

ダウンロードしたクライアントパッケージを解凍

unzip oracle-graph-client-20.4.0.zip

Auth tokenを入手

Property Graph serverにクライアントから接続する場合、先ずauth tokenを入手する必要があります。

curl コマンドを使って、簡単にauth tokenを入手できます。
下記のコマンドで可能です。

curl -X POST -H 'Content-Type: application/json' -d '{"username": "<DB USER>", "password": "<PASSWORD>"}' <HOST URL>:7007/auth/token

# e.g. curl -X POST -H 'Content-Type: application/json' -d '{"username": "demograph", "password": "<PASSWORD>"}' http://db19h.sub11160238550.graphvcntokyo.oraclevcn.com:7007/auth/token

usernameとpasswordですが、ユーザネームdemographと作成したパスワードになります。
HOST URLは、connection stringからextractできます。

[Figure: get PGX token]

実は、レスポンスはJSONオブジェクトとして返ってきます。レスポンスをフォーマットしてあげると、3つの要素で構成されているのが見えてきます。その要素は、トークンの中身、トークンタイプ、そしてトークンの有効時間です。
次のステップで必要なのは、access_tokenの中身になります。
また、有効時間にも目を向けてみてください。14400 は４時間後に有効性を失うという意味です。４時間後に、このトークンで作られたセッションも無効となります。

{
  "access_token": "<ENCRYPTED CONTENT>",
  "token_type": "bearer",
  "expires_in": 14400
}

[Figure: access token content]

Property Graph Serverに接続

Oracle Property Graph ClientはPGX serverへの複数の接続方法を用意しています。今回のサンプルでは、 Oracle Property Graph Client shellを最初に使っていきます。

未解凍のクライアントパッケージが入っているbinディレクトリに移動しましょう。

cd /home/graph/oracle-graph-client-20.4.0/bin

./opg-jshell --base_url <HOST URL>:7007
# e.g. ./opg-jshell --base_url http://db19h.sub11160238550.graphvcntokyo.oraclevcn.com:7007

**注記: セキュリティの観点から、トークンのペーストした際には何も表示されません。ペーストして何も変化がなくても、安心してエンターボタンを押して下さいね。

[Figure: jshell to PGX server]

opg-jshell>という風にコマンドプロンプトが変化したのを確認できたら、サーバに接続できたということです。

Graph サンプル - HR

HRというデータベーススキーマの準備

Download the HR create script from ここからHRスキーマと作成するスクリプトをダウンロードして、pdb1のユーザdemographでHRスキーマを作成して下さい。

sqlplus demograph/<PASSWORD>@db19h.sub11160238550.graphvcntokyo.oraclevcn.com:1521/pdb1.sub11160238550.graphvcntokyo.oraclevcn.com

@HR_create_hr_objects.sql

property graph表を作成

データベースに接続するためにjshellから下記のスクリプトを実行して下さい。

var jdbcUrl = "jdbc:oracle:thin:@//db19h.sub11160238550.graphvcntokyo.oraclevcn.com:1521/pdb1.sub11160238550.graphvcntokyo.oraclevcn.com"
var user = "demograph"
var pass = "<PASSWORD>"
var conn = DriverManager.getConnection(jdbcUrl, user, pass)

conn.setAutoCommit(false)

[Figure: jshell connection]

PGQL接続のために下記のスクリプトを実行して下さい。
このPGQL接続を通じて、用意してあるcreate.pgqlスクリプトを実行していきます。
このスクリプトで、先ほど作成したHRスキーマのデータベース表も基にproperty graph表を作成することができます。

ここからcreate.pgqlを入手できます。

var pgql = PgqlConnection.getConnection(conn)
pgql.prepareStatement(Files.readString(Paths.get("/home/graph/create.pgql"))).execute()

[Figure: pgql connection]

[Figure: create.pgql]

さて、VERTEX TABLESとEDGE TABLESなど、いくつかのproperty graph表を作成して参りました。

データベースから問合せ

ラムダファンクションqueryを定義するために、jshellから下記のスクリプトを実行して下さい。
このファンクションは、後ほど問合せを実行する際に役立ちます。

Consumer < String > query = q -> {
    try (var s = pgql.prepareStatement(q)) {
        s.execute();
        s.getResultSet().print();
    } catch (Exception e) {
        throw new RuntimeException(e);
    }
}

[Figure: lambda query]

下記のスクリプトでhr graphの頂点の数を問合せる。

query.accept("select count(v) from hr match (v)")

[Figure: query vertices]

下記のスクリプトで、エッジの数を問合せる。

query.accept("select count(e) from hr match ()-[e]->()")

降順でマネージャの情報と彼らの給料について問合せる。

query.accept("select distinct m.FIRST_NAME, m.LAST_NAME,m.SALARY from hr match (v:EMPLOYEES)-[:WORKS_FOR]->(m:EMPLOYEES) order by m.SALARY desc")

[Figure: query manager info]

メモリから問い合わせ

Property graph serverにデータをロードすると、問合せのスピードだけでなく、問合せのキャパシティも改善されます。メモリにロードすることで、より応用的なアルゴリズムを使った問合せもできるようになります。つまり、データからもっと価値のある結果を手に入れることができるのです。

下記のスクリプトで、メモリ上のgraph構造を定義します。

Supplier <GraphConfig> pgxConfig = () -> {
    return
    GraphConfigBuilder.forPropertyGraphRdbms()
    .setJdbcUrl(jdbcUrl)
    .setUsername(user)
    .setPassword(pass)
    .setName("hr")
    .addVertexProperty("COUNTRY_NAME", PropertyType.STRING)
    .addVertexProperty("DEPARTMENT_NAME", PropertyType.STRING)
    .addVertexProperty("FIRST_NAME", PropertyType.STRING)
    .addVertexProperty("LAST_NAME", PropertyType.STRING)
    .addVertexProperty("EMAIL", PropertyType.STRING)
    .addVertexProperty("PHONE_NUMBER", PropertyType.STRING)
    .addVertexProperty("SALARY", PropertyType.DOUBLE)
    .addVertexProperty("MIN_SALARY", PropertyType.DOUBLE)
    .addVertexProperty("MAX_SALARY", PropertyType.DOUBLE)
    .addVertexProperty("STREET_ADDRESS", PropertyType.STRING)
    .addVertexProperty("POSTAL_CODE", PropertyType.STRING)
    .addVertexProperty("CITY", PropertyType.STRING)
    .addVertexProperty("STATE_PROVINCE", PropertyType.STRING)
    .addVertexProperty("REGION_NAME", PropertyType.STRING)
    .setPartitionWhileLoading(PartitionWhileLoading.BY_LABEL)
    .setLoadVertexLabels(true)
    .setLoadEdgeLabel(true)
    .setKeystoreAlias("alias")
    .build();
}

[Figure: define graph structure in memory]

下記のスクリプトで、メモリ上にgraphを作成します。

var graph = session.readGraphWithProperties(pgxConfig.get())

[Figure: create graph in memory]

下記のスクリプトで、pagerankアルゴリズムを使ったグラフ分析を行います。

analyst.pagerank(graph)

[Figure: analyze graph with pagerank]

下記のスクリプトで、pagerank結果の最初の１０人の従業員を問合せて、降順表示します。

session.queryPgql("select m.FIRST_NAME, m.LAST_NAME,m.pagerank from hr match (m:EMPLOYEES) order by m.pagerank desc limit 10").print().close()

[Figure: query pagerank result]

グラフサンプル - ネット通販

このセクションでは、ネット通販の情報からいくつかデータベースの表を作成していきます。
また、property graph serverにグラフも作成していきます。

サーバへの接続時にkeystoreを使っていきます。kyestoreを使うことで、平文トークンがネットワーク経由で送信されることを防ぐことができます。セキュリティ面の更なる強化を期待できます。

Online Retail表の作成

実を言うと、このセクションは、Yamanakaさんが作成したサンプルに沿っているに過ぎません。Yamanakaさんは、Oracleでspatial and graph製品のプロダクトマネジャーとしてアジアパシフィック担当されている方です。
このセクションで使用する全てのスクリプトは、Yamanakaさんのgithubリポジトリからダウンロードすることができます。

ダウンロードが必要なファイルを下記にまとめています。

create_table.sql
create_table_normalized.sql
sqlldr.ctl
config-tables-distinct.json

上記のファイルの中身を確認して、ご自身の設定に合わせてアップデートして下さい。 config-tables-distinct.jsonのJDB connection string、user name、keystore aliasには注意して下さい。また、sqlldr.ctlのinput file pathにも注意です。

データベースにロード予定のデータに関して、こちらのページのDownload Datasetセクションを参考にして下さい。

基本的に、online retail表を作成するには、下記の5つのステップを踏んで行きます。

data.csvを用意して、上記の全てのスクリプトをダウンロードする
oracleに変更し、demographユーザでpdb1にログインする
use create_table.sqlを使って、transactions表を作成する
SQL*Loaderを使ってdata.csv into transactions表にdata.csvをロードする
create_table_normalized.sqlを使って、関係するいくつかの表を作成する

必要な表を作成できれば、データベースの表の準備は完了です。

`keystore`の準備

keytoolは、keyの管理とそれらのceritificateをするためのJavaユーティリティです。このJavaユーティリティは、keystoreを生成するために今回使用します。

下記のコマンドで、keystoresディレクトリを作成し、keystoreを生成します。

cd
mkdir keystores && cd keystores
keytool -importpass -alias demograph -keystore keystore.p12

Enter keystore password:と表示されたら、keystore用のパスワードを入力して下さい。その後、Enter the password to be stored:と表示されたら、格納したいパスワードを入力して下さい。この記事では、データベースユーザのdemographのパスワードを入力していきましょう。

[Figure: generate keystore]

`keystore`で接続

To connect from jshellからデータベースに接続するためには、auth tokenが必要になります。
やっていきましょう。

curl -X POST -H 'Content-Type: application/json' -d '{"username": "<DB USER>", "password": "<PASSWORD>"}' <HOST URL>:7007/auth/token

# e.g. curl -X POST -H 'Content-Type: application/json' -d '{"username": "demograph", "password": "<PASSWORD>"}' http://db19h.sub11160238550.graphvcntokyo.oraclevcn.com:7007/auth/token

そして、下記のコマンドで、サーバにkeystoreを使った接続を行います。

cd /home/graph/oracle-graph-client-20.4.0/bin
./opg-jshell --base_url http://db19h.sub11160238550.graphvcntokyo.oraclevcn.com:7007 --secret_store /home/graph/keystores/keystore.p12

いま手に入れたauth tokenを入力して下さい。
その後、enter password for keystore /home/graph/keystores/keystore.p12:と表示されたら、keystore用のパスワードを入力して下さい。

[Figure: jshell connect with keystore ]

事前定義された設定ファイルでPGXにグラフを作成

下記のスクリプトで、事前定義された設定ファイルであるconfig-tables-distinct.jsonを使って、property graph serverにグラフを作成します。

var graph = session.readGraphWithProperties("/home/graph/config-tables-distinct.json", "Online Retail");

[Figure: load Online Retail graph]

下記のスクリプトで、カスタマーIDがcust_12353の顧客の購買履歴を問合せる

graph.queryPgql(" SELECT ID(c), ID(p), p.description FROM MATCH (c)-[has_purchased]->(p) WHERE ID(c) = 'cust_12353' ").print();

[Figure: query in online retail graph]

下記のスクリプトで、personalizedPagerankを使って、カスタマーIDがcust_12353の顧客を分析する

var vertex = graph.getVertex("cust_12353");
analyst.personalizedPagerank(graph, vertex)

[Figure: personoalizedPagerank]

下記のスクリプトで、トップ10の製品を問合せる

graph.queryPgql(
    "  SELECT ID(p), p.description, p.pagerank " +
    "  MATCH (p) " +
    "  WHERE LABEL(p) = 'Product' " +
    "    AND NOT EXISTS ( " +
    "     SELECT * " +
    "     MATCH (p)-[:purchased_by]->(a) " +
    "     WHERE ID(a) = 'cust_12353' " +
    "    ) " +
    "  ORDER BY p.pagerank DESC" +
    "  LIMIT 10"
).print();

[Figure: top10]

GraphVizの問合せ

ここまで、コマンドラインインタフェースであるjshellを使って問合せを行ってきました。
しかし、ビルドインのグラフィックインターフェースであるGraphVizを使って問合せを行うことができるんです。

GraphVizはブラウザベースのインターフェースで、<HOST URL>:7007/uiというURLでアクセスできます。

ログイン画面で、usernameはdemograph、passwordはご自身で設定されたものを入力して下さい。

下記のスクリプトで、セッションIDを取得できます。セッションが切れていない限り、そのセッションIDを入力すれば、そのセッションのグラフにアクセスすることができます。

session.getId();

[Figure: session ID]

[Figure: GraphViz Login]

ログイン後、下記のようにデフォルトページを確認できます。

[Figure: GraphViz Query default]

ここでは、複雑な問合せを実行できますし、GraphVizは問合せ結果をインタラクティブなグラフとして表示してくれます。

SELECT *
MATCH (c1)-[e1]->(p1)<-[e2]-(c2)-[e3]->(p2)
WHERE ID(c1) = 'cust_12353'
  AND ID(p2) = 'prod_23166'
  AND ID(c1) != ID(c2)
  AND ID(p1) != ID(p2)

[Figure: GraphViz Query sample]

また、カスタムセッティングをアップロードすることで、グラフチャートの表現かカスタマイズすることが可能です。例えば、下記のスクリーンショットでは、highlight.jsonと言う設定ファイルをアップロードしました。チャートがさらに直感的に理解できるように表示されています。

[Figure: GraphViz upload highlight.json]

[Figure: GraphViz highlight graph]

まとめ

この記事では、Oracle DBCSインスタンスにOracle Property Graph server and clientをセットアップする方法を紹介しました。 ※the server and clientはどんなマシーン上にもインストールすることができます。

また、グラフを体感するために、HRとOnline Retailという2つのサンプルを作成しました。

グラフの作成方法
グラフの問合せ方法
メモリ上にグラフをロードする方法
複雑な問合せを実行する方法
GraphVizの使い方

この記事を読んで頂きまして、ありがとうございました。
Oracle Property Graphのテクノロジーの基本的な理解と、Oracle Property Graph serverで遊び始められる環境を持ち帰って頂ければ、幸いです。もし、もっと知りたいと言う方がいらっしゃいましたら、下記の参考文献もご参照下さいね。

参考文献