2022.11.07

Neo4j 5.xのNeo4j 4.4からの重大な変更点 #neo4j #neo4j5

この記事は1年以上前に投稿されました。情報が古い可能性がありますので、ご注意ください。

Neo4j バージョン5への移行は、バージョン4.4からのみサポートされています。
Neo4j v5には多くの新機能と変更が導入されています。移行手順に進む前に、それらを徹底的に確認することが不可欠です。
Neo4j 4.4と、Neo4j 5.xの間の重大な変更について、まとめて共有いたします。

※本記事は、下記Neo4j社公式ドキュメントページの翻訳・まとめになります。
neo4j.com - アップグレード＆マイグレーションガイド - Breaking changes between Neo4j 4.4 and Neo4j 5.x

JDK 17 & Scala 2.13
Java API
Autonomous Cluster（Causal Clusterの廃止）
Neo4j-Admin CLI & Neo4j CLI
バックアップとリストア
neo4j.conf
Fabric（複合データベース）
Cypher ※2022/11/10 一部内容を修正しました。
APOC Library ※2022/11/08 14:00 追記しました。
Indexes ※2022/11/09 11:00 追記しました。
Logging ※2022/11/09 11:00 追記しました。
Metrics ※2022/11/11 10:00 追記しました。
削除事項まとめ ※2022/11/11 10:00 追記しました。
非推奨事項まとめ ※2022/11/11 10:00 追記しました。
外部依存関係 ※2022/11/11 10:00 追記しました。

1. JDK 17 & Scala 2.13

Neo4j 4.xでは JDK11がサポートされていましたが、Neo4j 5.xはJDK17に変更になりました。
アップグレードには、JDKの更新が必要ですが、同じマシンで他のJavaアプリケーションを実行している場合の互換性の確認や、複数のJDKを実行するように設定が必要になります。

**表1. Neo4jとJavaの対応表**
Neo4jバージョン	Javaバージョン
5.x	Java SE 17
4.x	Java SE 11
3.x	Java SE 8

また、Scalaを利用されている方は、Scala 2.13がサポート対象になります。

2. Java API

JavaのAPIも大きく更新されています。

クラス：11クラスが削除され、5クラスが追加されました。
メソッド：17パッケージで変更があり、メソッド個別レベルになると、追えないくらい多いです。
設定パラメータ：8パッケージに変更があります。
クラスタ設定：5パッケージで変更されていますね。

ここでは列挙するには多すぎるので、詳細はコチラ：neo4j.com - アップグレード＆マイグレーションガイド - Changes to Java API in Neo4j 5で確認ください。

一方、トラバーサルAPIは、大幅に見直されて性能向上しているようです。

Neo4j Traversal Framework とは？
グラフトラバースを効率良く実行するために開発されたフレームワークです。
Cypherクエリー言語よりも可読性が低く、複雑なため、Neo4j社もCypherを使用することを推奨しています。
一方で、Cypherでは表現しきれないクエリが表現できたり、潜在的にパフォーマンスが高い処理ができるため、開発・提供されています。

Neo4jのグラフトラバースの具体例：neo4j.com - Java Reference 5 - Traversal
Traversal Frameworkの詳細：neo4j.com - Java Reference 5 - Traversal Framework

3. Autonomous Cluster（Causal Clusterの廃止）

なんと、Causal Cluster は Autonomous Cluster（オートノマスクラスタ）に更新されたとのこと。
共存ではなく、インフラストラクチャから更新したとのことで、Causal Cluster を利用していた場合、移行にはかなり注意が必要ですね。
公式に Neo4j 5に移行する際は、新しいクラスタでゼロから始めることを推奨 されています。
詳しくはコチラ：neo4j.com - 運用マニュアル 5 - Clusteringを参照ください。

Autonomous Cluster については、詳細を確認して、後日ブログに個別記事を公開いたします。

3.1. 主な機能

Autonomous Clusterへの更新は、特にオーケストレーション機能を向上させることが目的のようです。つまりは、クラスター管理の自動化を強化したということです。

データベースの自動配置と水平スケーリングを提供する
データベースはクラスタ内の別のサーバにレプリケート(コピー)される。
データベースのコピーはプライマリ/セカンダリを指定できる。
各データベースのコピー数とサーバ数を指定することで、どのデータベースコピーをどのサーバに割り当てるかは、システムが自動で決める。
サーバーの追加や削除に伴い、割り当てが変更される可能性がある。

メリットとしては、例えば、5つのデータベースがある場合、それを3つにコピーし、それを8サーバに分散させるといった、より多くのサーバに分散させて、レスポンス性能を上げることができることです。

3.2. 用語の変更

Causal Cluster で使われていた用語は廃止され、Autonomous Clusterでは新たな用語になるようです。

**用語の変更**
Causal Cluster	Autonomous Cluster
コア	プライマリデータベースコピー
リードレプリカ	セカンダリデータベースコピー

つまりは、コア・リードレプリカといった役割の区別がなくなるのでしょうか？
詳しく調べて、後日別記事で公開いたします。

4. Neo4j-Admin CLI & Neo4j CLI

詳細については、neo4j.com - 運用マニュアル 5 - Neo4j Admin and Neo4j CLI を参照してください。

4.1. Neo4j-Admin CLI

neo4j-adminコマンドが新しくなりました。構文は下記になります。
neo4j-admin [category] [command] [subcommand]
[category] は下記の5つに整理されました。

dbms - DBMS全体(シングル環境もクラスタ環境も)の管理コマンド類
server - サーバー全体の管理コマンド類
database - データベースに特化した管理コマンド類
help - 本コマンドのヘルプ表示
version - 本コマンドのバージョン表示

図1. neo4j-admin カテゴリとコマンドのマップ一覧

4.2. Neo4j CLI

neo4jコマンドも更新されています。構文は下記になります。
neo4j [command]
このコマンドは、neo4j-admin serverカテゴリコマンドの中でも、最も重要なコマンドのエイリアスとして設計されています。頻出のコマンドを neo4j-admin server [command]と打つよりも、使いやすいエイリアスにしたということですね。

図2. neo4j-admin と neo4j コマンド関係 - 黄色背景のコマンドがエイリアス対象

5. バックアップとリストア

特に、大きな変更点は、ポイントインタイム・リストア（ただし、限定的）ができるようになったことです。

差分バックアップに対して、ポイントインタイムまたはトランザクションIDまでのリストアが可能
データベースバックアップチェーンの統合：フルバックアップデータと差分バックアップデータを統合し新たなフルバックアップデータを生成可能
APIを更新し、操作性を向上

注意点はこれまでのバックアップシステムとの互換性は無いとのことです。
では、Neo4j 4のバックアップをリストア出来ないのでは？と、考えましたが、
Neo4j 4のバックアップ/リストアコマンドは、後方互換性のために（名称を変更して）維持する予定とのことです。

Autonomous Cluster のバックアップ
下記マニュアルを確認したのですが、概要がわからず、後日公開とさせてください。

詳細：neo4j.com - 運用マニュアル 5 - Backup and restore

6. neo4j.conf

Neo4j 5では、すべてのConfig設定が server, dbms, db, initial, browser, client< の6カテゴリに再分類されました。
つまり、これまでの設定パラメータ名が変更されているということです。
そのため、Neo4j Adminに設定ファイル移行用のツールが追加されています。4.4の設定を5.xに移行する際、対応しているか・いないかをこのツールで判定出来ます。詳しくは、neo4j.com - 運用マニュアル 5 - Migrate the Neo4j configuration fileをご覧ください。

**configの変更例**
4.x	5.x
metrics.enabled	server.metrics.enabled
dbms.config.strict_validation=false	server.config.strict_validation.enabled=true (デフォルト値の変更)
Fabricカテゴリの設定	システムデータベースに移動：詳しく→7.fabric(複合データベース)
db.tx_state.memory_allocation = OFF_HEAP	db.tx_state.memory_allocation = ON_HEAP (デフォルト値の変更)

変更された設定の全リストは、neo4j.com - アップグレード＆マイグレーションガイド - Changes to configuration settings in Neo4j 5 を参照してください。

7. Fabric（複合データベース）

neo4j.conf の Fabricカテゴリに分類されていた構成設定は、システムデータベースに移動されたとのこと。それに伴い、CypherはFabric設定を操作できるように拡張されています。
よって、Fabricによるシャードやフェデレート設定・管理は、下記のように動的に実行できるように改善しました。

再起動せずにFabricの設定を変更
複数のFabricデータベースのサポート
ローカル、リモート、シャーディングに関わらず、データベースとして管理
オートノマスクラスタを組み合わせることで、より複雑なNeo4jデータベースインフラもより簡単に構成可能

詳しくは、neo4j.com - 運用マニュアル 5 - Composite databases をご覧ください。

8. Cypher

8.1. 構文の削除・非推奨・更新・新規

~~例えば、よく使う exists関数 が廃止され、IS NOT NULL に統一されています。~~
【2022/11/10(木) 更新】誤解を招く表現だったため訂正します。
具体的には、exists関数は、WHERE exists(a.name) AND NOT exists(b.name)のようにプロパティを引数にもつ機能は廃止され、WHERE a.name IS NOT NULL AND b.name IS NULLに統合されました。一方、WHERE EXISTS((n)-[:MARRIED]->())のようなパターンマッチングや、サブクエリを引数にもつ機能は継続して利用できます。
新規では、先述のサーバ操作周りの文法だけでなく、MATCH (n: A&(B|C)&!D) のように、ラベルマッチの条件指定機能が強化されていますね。その他、多くの変更があるため、アップグレード時には慎重なチェックが必要です。
Cypherの削除・非推奨・更新・新規それぞれのすべて変更内容については、neo4j.com - Cypherマニュアル 5 -Deprecations, additions and compatibility をご確認ください。

8.2. Error・Warning

セマンティックエラーは、Neo.ClientError.Statement.SyntaxErrorとして報告されます。そこで、そのシンタックスエラーとセマンティックエラーをより見分けやすくするため、エラー・ワーニングの情報を改善したとのこと。
また、いくつかの Warning は Info レベルに変更されました。

**Warningレベルの変更一覧**
4.x Warning	5.x Info
SubqueryVariableShadowingWarning	SubqueryVariableShadowing
NoApplicableIndexWarning	NoApplicableIndex
CartesianProductWarning	CartesianProduct
DynamicPropertyWarning	DynamicProperty
EagerOperatorWarning	EagerOperator
ExhustiveShortestPathWarning	ExhustiveShortestPath
UnboundedVariableLengthPatternWarning	UnboundedVariableLengthPattern
ExperimentalFeature	RuntimeExperimental

詳細は、neo4j.com - ステータスコード 5 をご確認ください。

9. APOC Library

9.1. サポート内容

5.0以降、APOCは2つのリポジトリに分割されます。1つはもともとはAPOC Coreと呼ばれた、メインのNeo4j 5 APOC ライブラリ、もう1つはNeo4j Communityで開発されるAPOC Extended ライブラリです。
公式にサポートは下記のように、Neo4j 5 APOC ライブラリのみに限定されます。

APOC Extended ライブラリは Neo4j 5 APOC ライブラリに含まれていないため、Neo4j Community のみでサポートされます。
APOC Extended ライブラリのコードは、他のLabsプロジェクトと同様に、APOC Core 4.xのコードと一緒に拡張リポジトリに残ります。
Neo4j は、APOC Extended のメソッドを実稼働環境で使用することを推奨・奨励しません。

現在、APOC Extendedは Neo4j 5に対応が間に合っていないようで、一部の関数（例えば、apoc.export.cypher.all）でエラーが出るという報告もあります。詳細は追って共有いたします。
APOC Core ライブラリについては、neo4j.com - APOC Documentation - APOC User Guide 5.0 を参照ください。
APOC Extendedライブラリについては、neo4j.com/lab - APOC Documentation - APOC Extended User Guide 5.0、または、github.com - Neo4j Contrib - neo4j-apoc-procedures を参照ください。

Neo4j 5 APOC ライブラリは、一部の例外を除き、Neo4j Aura で利用できます。
詳しくは、neo4j.com- Neo4j Aura - APOC support をご覧ください。

9.2. リポジトリとパッケージング

下記変更がされています。

Neo4j 5 APOC ライブラリリポジトリは、github.com - Neo4j - apoc に移動しました。
Neo4j 5 APOC ライブラリドキュメントは、Neo4j 公式ドキュメントの一部です。
Neo4j 5 APOC ライブラリは、Neo4j インストール・パッケージの一部として含まれています。
APOC Full パッケージ（APOC Core + APOC Extended）は販売終了しています。サポートされていないAPOC Extendedのメソッドを使用したい場合は、github.com - Neo4j Contrib - neo4j-apoc-proceduresリポジトリを参照する必要があります。
Neo4j Dockerコンテナは、APOC Fullパッケージではなく、Neo4j 5 APOC ライブラリパッケージをインストールするようになりました。
apoc-coreフラグは削除されました。

10. indexes

10.1. BTREE indexの削除

BTREEインデックスは削除されました。代わりに、RANGEインデックス と POINTインデックスが新しく利用できるようになったそうです。
したがって、5.xバイナリに切り替える前に、インデックスプロバイダnative-btree-1.0またはlucene+native-3.0を持つすべてのBTREEインデックスとインデックス・バック制約を置換・削除する必要があります。
最も適切な方法は、5.x に移行する前にインデックスを 4.4 で再作成する方法です。その後、移行中に 5.x は各 BTREEインデックスとインデックス・バック制約が同等のタイプのインデックスとプロバイダーを持つことをチェックし、それらを削除します。

Neo4j は次の場合に起動しません。

BTREEインデックスが存在し、かつ、同じスキーマにRANGE/POINT/TEXTインデックスが1つも存在しない場合。
native-btree-1.0 または lucene+native-3.0プロバイダを持つインデックス・バック制約が存在し、かつ、同じスキーマ上にrange-1.0プロバイダのインデックス・バック制約制約が存在しない場合。

10.2. TEXTインデックスの性能向上

範囲検索のためのTEXTインデックスのサポート、n.prop > "string" は削除されました。範囲検索を使用するクエリのパフォーマンスを向上させるには、RANGEインデックスを使用してください。

10.3. リストに対するFULLTEXTインデックス

FULLTEXTインデックスが文字列のリストをインデックスできるようになりました。4.x で作成されたインデックスは引き続き同じ方法で動作します。つまり、文字列の配列はインデックスされません。5.x で作成されたインデックスや再作成されたインデックスは、新しい動作、つまり、文字列や文字列の配列にインデックスが付けられるようになります。

//Example Cypher 
//In Neo4j 5.x
 
UNWIND range( 1, 100000, 1 ) AS id
CREATE ( n:N1 { p0: id, p1: [] } )
WITH n
     UNWIND range( 1, toInteger( rand() * 30 + 1 ), 1 ) AS p
     WITH n AS n,
     substring( randomUUID(), 9, 4 ) + " " + substring( randomUUID(), 9, 4 ) + " " + substring( randomUUID(), 9, 4 ) AS stringToAdd
     SET n.p1 = n.p1 + stringToAdd;
 
CREATE FULLTEXT INDEX ftList IF NOT EXISTS
   FOR ( n:N1 ) ON EACH [ n.p1 ];
CALL db.awaitIndex( "ftList" );
 
WITH substring( randomUUID(), 9, 4 ) AS stringToSearch
CALL db.index.fulltext.queryNodes( "ftList", stringToSearch ) YIELD node, score
RETURN stringToSearch, node.p0, node.p1, score;
+----------------------------------------------------------------------------------------------------------------------------------------------------+
| stringToSearch | node.p0 | node.p1                                                                                            | score              |
+----------------------------------------------------------------------------------------------------------------------------------------------------+
| "da58"         | 15190   | ["da58 85af 31bb", "2b0d 215a 94bc", "164a ca4f 8aaa"]                                             | 4.874580383300781  |
| "da58"         | 96778   | ["a8c2 7276 a942", "55b9 0581 fe38", "5d1c da58 ac44"]                                             | 4.874580383300781  |
| "da58"         | 93452   | ["d0c8 a916 2546", "6bda 3a33 96c4", "14cb aa4f ce36", "9d3d fe00 da58", "3f0b 5ef2 9ac4", ... ]   | 4.358154296875     |
...
+----------------------------------------------------------------------------------------------------------------------------------------------------+
75 rows
ready to start consuming query after 60 ms, results consumed after another 50 ms

11. Logging

Neo4j 5からロギングにLog4j 2を使用しているようです。使用法の詳細は、logging.apache.org - Log4j公式ドキュメントを参照してください。
デフォルトのNeo4jインストールがどのように動作するか、またLog4jを利用するための設定例については、neo4j.com - 操作マニュアル 5 - Logging をご確認ください。

11.1. 設定の変更

ファイル管理に関する設定を Log4j 設定ファイルに移行し、クエリログの内容設定の見直しと簡素化を行っているとのことです。主な変更点は以下の通りです。もちろん、他にも細かい変更はあります。

neo4j.conf ファイルにおけるコンフィギュレーション設定の簡略化
ログファイルのファイル管理、フォーマットの制御を強化
Neo4j 4.x 時に設定として提供されていた機能を、標準機能として有効化
JVMガベージコレクションのロギングに関する設定は、neo4j.confファイルに残る
Log4j の設定ファイルは、neo4j.conf とともに $NEO4J_HOME/conf フォルダに配置
Log4j の xml 設定ファイルは、conf/server-logs.xml と conf/user-log.xml の 2 つ
- user-logs.xml は、neo4j.log（ユーザログ）の設定に使用します。これはコンソールモードからの標準出力リダイレクションを管理するためのもので、サーバーログとは別ログになります。
- server-logs.xml は、デバッグログ、セキュリティログ、http ログ、クエリログに使用されます。
- すべてのログは、Log4j XML ファイルにこれらの設定を持つようになりました。
```
//Properties
SizeBasedTriggeringPolicy :
Max log file size.
Default value is 20 MBytes

DefaultRolloverStrategy :
Max number of log files retained
Default value is 7 files retained
    
```
「通常の」neo4jロギングオプションが利用可能
ファイルのローテーションとリテンションのコントロール
出力フォーマットの制御（PLAINまたはJSON形式)
お客様がロギングを拡張するために、Log4jのすべての柔軟性を提供
構成ファイルへのあらゆる変更は監視されるので、動的と見なすことができます。

11.2. neo4j.confの変更点

Neo4j 5では、新しい命名規則が導入され、設定名の一貫性が改善されました。

**表2. 新規設定:**
設定項目	概要
server.logs.config	ログ用のlog4j設定パス
server.logs.debug.enabled	デバッグログの有効/無効を追加
server.logs.user.config	ユーザーログ用のlog4j設定パス

**表3. 名称変更された設定:**
旧設定項目名	名称変更後の項目名
dbms.directories.logs	server.directories.logs
dbms.logs.gc.enabled	server.logs.gc.enabled
dbms.logs.gc.options	server.logs.gc.options
dbms.logs.gc.rotation.keep_number	server.logs.gc.rotation.keep_number
dbms.logs.gc.rotation.size	server.logs.gc.rotation.size
dbms.logs.query.early_raw_logging_enabled	db.logs.query.early_raw_logging_enabled
dbms.logs.query.enabled	db.logs.query.enabled
dbms.logs.query.max_parameter_length	db.logs.query.max_parameter_length
dbms.logs.query.obfuscate_literals	db.logs.query.obfuscate_literals
dbms.logs.query.parameter_logging_enabled	db.logs.query.parameter_logging_enabled
dbms.logs.query.plan_description_enabled	db.logs.query.plan_description_enabled
dbms.logs.query.threshold	db.logs.query.threshold
dbms.logs.query.transaction.enabled	db.logs.query.transaction.enabled
dbms.logs.query.transaction.threshold	db.logs.query.transaction.threshold

変更されていない設定:

dbms.logs.http.enabled

**表4. 削除された設定:**
設定項目	オプション
dbms.logs.query.parameter_full_entities
dbms.logs.user.stdout_enabled
metrics.neo4j.logs.enabled
dbms.logs.query.allocation_logging_enabled	: Always on
dbms.logs.query.page_logging_enabled	: Always on
dbms.logs.query.runtime_logging_enabled	: Always on
dbms.logs.query.time_logging_enabled	: Always on
dbms.logs.query.transaction_id.enabled	: Always on

下記の設定項目は log4j設定に移動しました。

dbms.logs.debug.format
dbms.logs.debug.level
dbms.logs.debug.path
dbms.logs.debug.rotation.delay
dbms.logs.debug.rotation.keep_number
dbms.logs.debug.rotation.size
dbms.logs.default_format
dbms.logs.http.rotation.size
dbms.logs.http.format
dbms.logs.http.path
dbms.logs.http.rotation.keep_number
dbms.logs.query.format
dbms.logs.query.path
dbms.logs.query.rotation.keep_number
dbms.logs.query.rotation.size
dbms.logs.security.format
dbms.logs.security.level
dbms.logs.security.path
dbms.logs.security.rotation.delay
dbms.logs.security.rotation.keep_number
dbms.logs.security.rotation.size
dbms.logs.user.format
dbms.logs.user.path
dbms.logs.user.rotation.delay
dbms.logs.user.rotation.keep_number
dbms.logs.user.rotation.size

12. Metrics

すべてのメトリクス名に dbms または database ネームスペースが含まれるようになり、metrics.namespaces.enabled 設定が削除されました。
メトリクスの種類を有効化および無効化する metrics.*.enabled 設定はすべて削除されました。有効にするメトリクスを正規表現で指定する server.metrics.filter に置き換えました。

13. 削除事項まとめ

削除事項のまとめです。一部内容は、これまでに紹介した内容の再掲になります。

レガシーHTTPトランザクションAPI - db/data/transactionのようなURIにデータベース名を含まない特定のリクエスト
結果サマリーのバージョン / version_info
Javaドライバからのセッション#リセット(長い間非推奨でしたが削除)
BTREEインデックスを廃止し、RANGEとPOINTインデックスを使用
Cypher 3.5モード
リレーション変数の繰り返しを禁止
リストのブール値への自動強制キャスト
exists()関数による、プロパティのNULL判定機能
causal_clustering.multi_dc_licenseを含むマルチデータセンター設定

廃止されたプロシージャ
プロシージャ	代替
db.indexes	SHOW INDEXES command
db.indexDetails	SHOW INDEXES YIELD * command
db.schemaStatements	SHOW INDEXES YIELD * command and SHOW CONSTRAINTS YIELD * command
db.constraints	SHOW CONSTRAINTS command
db.createIndex	CREATE INDEX command
db.createUniquePropertyConstraint	CREATE CONSTRAINT … IS UNIQUE command
db.index.fulltext.createNodeIndex	CREATE FULLTEXT INDEX command
db.index.fulltext.createRelationshipIndex	CREATE FULLTEXT INDEX command
db.index.fulltext.drop	DROP INDEX command
dbms.procedures	SHOW PROCEDURES command
dbms.functions	SHOW FUNCTIONS command
dbms.listTransactions	SHOW TRANSACTIONS command
dbms.killTransaction	TERMINATE TRANSACTIONS command
dbms.killTransactions	TERMINATE TRANSACTIONS command
dbms.listQueries	SHOW TRANSACTIONS command
dbms.killQuery	TERMINATE TRANSACTIONS command
dbms.killQueries	TERMINATE TRANSACTIONS command
dbms.scheduler.profile	-

全てのCypher削除項のリストは、neo4j.com - Cypherマニュアル 5 - Removals, deprecations, additions and extensionsをご覧ください

14. 非推奨事項まとめ

apoc.create.uuid() と apoc.create.uuids() は非推奨です。 UUID.randomUUID() に置き換えてください。
全てのCypher非推奨事項のリストは、neo4j.com - Cypherマニュアル 5 - Removals, deprecations, additions and extensionsをご覧ください。

15. 外部依存関係

外部依存関係とそのバージョンは、mvnrepository.com - Neo4j をご覧ください。

目次