Spring イニシャライザーに対して curl リクエストを発行して、基本的な Maven プロジェクトを作成できます。

これにより、新しいフォルダー Neo4jSpringBootExample が作成されます。このスターターはまだイニシャライザーにないため、次の依存関係を pom.xml に手動で追加する必要があります。

既存のプロジェクトの場合は、依存関係を手動で追加することもできます。

考え方は同じで、Gradle プロジェクトを生成するだけです。

Gradle の依存関係は次のようになり、build.gradle に追加する必要があります。

既存のプロジェクトの場合は、依存関係を手動で追加することもできます。

アプリケーションを実行する Neo4j のバージョンに応じて、Neo4j Cypher-DSL を実行するダイアレクトを設定することをお勧めします。デフォルトで使用されるダイアレクトは、Neo4j の LTS バージョンとして Neo4j 4.4 をターゲットにしています。これは、Cypher-DSL Configuration Bean を定義することで変更できます。

SDN は、Kotlin の Java クラスと data クラスの両方で、変更不可能なエンティティを完全にサポートします。ここでは不変エンティティに焦点を当てます。リスト 8 はそのようなエンティティを示します。

一般論として: SDN では、データベースによって生成された値をフィールドに設定する方法が必要であるため、内部生成された ID を使用する不変エンティティは少し矛盾しています。

適切なビジネスキーが見つからない場合、または ID のジェネレーターを使用したくない場合は、内部的に生成された ID を通常のコンストラクターと、SDN で使用されるいわゆるウィザー -Method とともに使用する同じエンティティを次に示します。

もちろん、Kotlin (英語) で SDN を使用し、Kotlin のデータクラスでドメインをモデル化することもできます。プロジェクト Lombok (英語) は、純粋に Java 内に留まりたい、またはその必要がある場合の代替手段です。

ここには基本的に 2 つのオプションがあります。SDN をストアに依存しないメソッドで作業することと、ドメイン固有の拡張を次の 1 つにすることができます。

それに応じて命令型とリアクティブ型を選択します。

もう 1 つのオプションは、ストア固有の実装に落ち着いて、サポートされているすべてのメソッドをすぐに利用できるようにすることです。このアプローチの利点は最大の欠点でもあります。一度公開されると、これらのメソッドはすべて API の一部になってしまいます。ほとんどの場合、後から何かを追加するよりも、何かを取り除く方が困難です。さらに、ストアの詳細を使用すると、ストアがドメインに漏洩します。パフォーマンスの観点からは、ペナルティはありません。

上記のムービーエンティティのいずれかに適合するリアクティブリポジトリは次のようになります。

@Node アノテーションは、マッピングコンテキストによるクラスパススキャンの対象となる、クラスをマネージドドメインクラスとしてマークするために使用されます。

オブジェクトをグラフ内のノードにマッピングしたり、その逆を行うには、マッピング先またはマッピング元のクラスを識別するラベルが必要です。

@Node には、アノテーション付きクラスのインスタンスの読み取りおよび書き込み時に使用される 1 つ以上のラベルを構成できる属性 labels があります。value 属性は labels のエイリアスです。ラベルを指定しない場合は、単純なクラス名がプライマリラベルとして使用されます。複数のラベルを指定したい場合は、次のいずれかを実行できます。

プライマリラベルは常に、ドメインクラスを反映する最も具体的なラベルである必要があります。

リポジトリまたは Neo4j テンプレートを通じて書き込まれたアノテーション付きクラスのインスタンスごとに、少なくともプライマリラベルを持つグラフ内の 1 つのノードが書き込まれます。逆に、プライマリラベルを持つすべてのノードは、アノテーションが付けられたクラスのインスタンスにマップされます。

@Node はクラスと特定のラベルを持つノード間のマッピングを作成しますが、そのクラスの個々のインスタンス (オブジェクト) とノードのインスタンス間の接続も作成する必要があります。

ここで @Id が活躍します。@Id は、クラスの属性をオブジェクトの一意の識別子としてマークします。その一意の識別子は、最適な世界では一意のビジネスキー、言い換えれば自然キーです。@Id は、サポートされている単純型のすべての属性で使用できます。

ただし、自然キーを見つけるのは非常に困難です。たとえば、人の名前は一意であることはほとんどなく、時間の経過とともに変化したり、さらに悪いことに、誰もが姓名を持っているわけではありません。

2 つの異なる種類の代理キーをサポートします。

型 String、long、または Long の属性では、@Id を @GeneratedValue とともに使用できます。Long と long は Neo4j 内部 ID にマップされます。String は Neo4j 5 以降で使用可能な elementId にマップされます。どちらもノードまたはリレーションシップのプロパティではなく、通常は属性には表示されませんが、SDN がクラスの個々のインスタンスを取得できるようにします。

@GeneratedValue は属性 generatorClass を提供します。generatorClass を使用して、IdGenerator を実装するクラスを指定できます。IdGenerator は関数インターフェースであり、その generateId はプライマリラベルとインスタンスを取得して ID を生成します。すぐに使える 1 つの実装として UUIDStringGenerator をサポートします。

generatorRef を介して @GeneratedValue のアプリケーションコンテキストから Spring Bean を指定することもできます。Bean も IdGenerator を実装する必要がありますが、データベースと対話するための Neo4j クライアントやテンプレートなど、コンテキスト内のすべてを利用できます。

Spring Data Neo4j は、Long 型付きフィールドで @Version アノテーションを使用することにより、オプティミスティックロックをサポートします。この属性は更新中に自動的に増加するため、手動で変更しないでください。

たとえば、異なるスレッドの 2 つのトランザクションがバージョン x の同じオブジェクトを変更したい場合、最初の操作はデータベースに正常に永続化されます。この時点で、バージョンフィールドはインクリメントされるため、x+1 になります。2 番目の操作は、データベースに存在しないバージョン x のオブジェクトを変更しようとしているため、OptimisticLockingFailureException で失敗します。このような場合、データベースから現在のバージョンのオブジェクトを新たにフェッチすることから始めて、操作を再試行する必要があります。

ビジネス ID を使用する場合は、@Version 属性も必須です。Spring Data Neo4j はこのフィールドをチェックして、エンティティが新しいか、以前にすでに永続化されているかを判断します。

@Node アノテーション付きクラスのすべての属性は、Neo4j ノードおよびリレーションシップのプロパティとして保持されます。さらに構成を行わなければ、Java または Kotlin クラスの属性の名前が Neo4j プロパティとして使用されます。

既存の Neo4j スキーマを使用している場合、またはマッピングをニーズに合わせて調整したい場合は、@Property を使用する必要があります。name は、データベース内のプロパティの名前を指定するために使用されます。

@Relationship アノテーションは、単純型ではないすべての属性で使用できます。これは、@Node のアノテーションが付けられた他の型の属性、またはそのコレクションおよびマップに適用できます。

type または value 属性では関連の型を構成でき、direction では方向を指定できます。SDN のデフォルトの方向は Relationship.Direction#OUTGOING です。

ダイナミックな関連をサポートします。動的関連は Map<String, AnnotatedDomainClass> または Map<Enum, AnnotatedDomainClass> として表されます。このような場合、他のドメインクラスとの関連の型はマップキーによって指定されるため、@Relationship を通じて構成する必要はありません。

これらすべてを組み合わせると、単純なドメインを作成できます。さまざまなロールを持つムービーや人物を使用します。

ここでは、人々が actors と directors という 2 つのロールにマッピングされています。ドメインクラスは同じです。

ドメインクラスに一意の識別子を与える最も簡単なメソッドは、型 String または Long のフィールドで @Id と @GeneratedValue を組み合わせることです (インスタンスが新しいかどうかを示すより適切な指標はリテラル null であるため、スカラー long ではなくオブジェクトが望ましい) ):

フィールドに setter を指定する必要はありません。SDN はリフレクションを使用してフィールドを割り当てますが、setter がある場合はそれを使用します。内部生成された ID を使用して不変のエンティティを作成したい場合は、wither を指定する必要があります。

必要な場合は、id 属性に setter を指定するか、wither のようなものを指定する必要があります。

@GeneratedValue アノテーションは、org.springframework.data.neo4j.core.schema.IdGenerator を実装するクラスをパラメーターとして受け取ることができます。SDN は、すぐに使用できる InternalIdGenerator (デフォルト) および UUIDStringGenerator を提供します。後者は、エンティティごとに新しい UUID を生成し、java.lang.String として返します。これを使用するアプリケーションエンティティは次のようになります。

利点と欠点に関しては、2 つのことを別々に議論する必要があります。割り当て自体と UUID 戦略。普遍的に一意の識別子 [Wikipedia] (英語) は、実用的な目的のために一意であることを目的としています。Wikipedia の言葉を引用すると、「したがって、誰でも UUID を作成し、それを使用して何かを識別することができます。その識別子は、他のものを識別するためにすでに作成された、または今後作成される識別子とほぼ確実に重複しません。」私たちの戦略は Java 内部 UUID メカニズムを使用し、暗号的に強力な擬似乱数ジェネレーターを採用します。ほとんどの場合、これで問題なく動作するはずですが、実際の実行距離は異なる場合があります。

これで割り当て自体は残ります。

独自の ID ジェネレーターを展開するには、いくつかのオプションがあります。1 つはジェネレーターを実装する POJO です。

別のオプションは、次のように追加の Spring Bean を提供することです。

上記のジェネレーターは、次のように Bean リファレンスとして構成されます。

完全な例の MovieEntity および PersonEntity ではビジネスキーを使用しています。個人の名前は、アプリケーションによって、および Spring Data を介してロードされる際の両方で、構築時に割り当てられます。

これは安定した一意のビジネスキーを見つけた場合にのみ可能ですが、優れた不変ドメインオブジェクトが作成されます。

ビジネスキーは、Spring Data Neo4j が処理する前に常にドメインエンティティに設定されることに注意してください。これは、@Version フィールドも提供されない限り、エンティティが新しいかどうかを判断できないことを意味します (エンティティは常に新しいと想定されます)。

Spring Data は、その型のオブジェクトの具体化に使用される永続エンティティのコンストラクターを自動的に検出しようとします。解決アルゴリズムは次のように機能します。

値の解決は、コンストラクターの引数名がエンティティのプロパティ名と一致することを前提としています。つまり、マッピングのすべてのカスタマイズ（異なるデータストア列またはフィールド名など）を含む、プロパティが設定されるかのように解決が実行されます。また、これには、クラスファイルで使用可能なパラメーター名情報、またはコンストラクターに存在する @ConstructorProperties アノテーションのいずれかが必要です。

エンティティのインスタンスが作成されると、Spring Data はそのクラスの残りのすべての永続プロパティを設定します。エンティティのコンストラクターによってすでに入力されていない場合（つまり、コンストラクターの引数リストを介して使用される場合）、ID プロパティが最初に入力され、循環オブジェクト参照の解決が可能になります。その後、コンストラクターによってまだ設定されていないすべての非一時的なプロパティがエンティティインスタンスに設定されます。そのために、次のアルゴリズムを使用します。

次のエンティティを見てみましょう。

Spring Data は、Kotlin の仕様を適合させて、オブジェクトの作成と変更を可能にします。

リポジトリインターフェースを使い始める方法にはいくつかのバリエーションがあります。

典型的なアプローチは、CrudRepository を継承することです。これにより、CRUD 機能のメソッドが提供されます。CRUD は、Create、Read、Update、Delete の略です。バージョン 3.0 では、CrudRepository と非常によく似た ListCrudRepository も導入されましたが、複数のエンティティを返すメソッドでは、使いやすい Iterable ではなく List が返されます。

リアクティブストアを使用している場合は、使用しているリアクティブフレームワークに応じて ReactiveCrudRepository または RxJava3CrudRepository を選択できます。

Kotlin を使用している場合は、Kotlin のコルーチンを利用する CoroutineCrudRepository を選択できます。

さらに、Sort 抽象化、または最初の場合は Pageable 抽象化を指定できるメソッドが必要な場合は、PagingAndSortingRepository、ReactiveSortingRepository、RxJava3SortingRepository または CoroutineSortingRepository を継承できます。さまざまな並べ替えリポジトリは、3.0 より前の Spring Data バージョンのようにそれぞれの CRUD リポジトリを継承しなくなったことに注意してください。両方の機能が必要な場合は、両方のインターフェースを継承する必要があります。

Spring Data インターフェースを継承したくない場合は、リポジトリインターフェースに @RepositoryDefinition でアノテーションを付けることもできます。CRUD リポジトリインターフェースの 1 つを継承すると、エンティティを操作するためのメソッドの完全なセットが公開されます。公開するメソッドを選択したい場合は、公開するメソッドを CRUD リポジトリからドメインリポジトリにコピーします。その際、メソッドの戻り値の型を変更できます。Spring Data は、可能であれば戻り値の型を尊重します。例: 複数のエンティティを返すメソッドの場合、Iterable<T>、List<T>、Collection<T> または VAVR リストを選択できます。

アプリケーション内の多くのリポジトリに同じメソッドのセットが必要な場合は、継承元の独自のベースインターフェースを定義できます。このようなインターフェースには、@NoRepositoryBean のアノテーションを付ける必要があります。これにより、Spring Data はインスタンスを直接作成しようとして失敗し、そのリポジトリのエンティティを特定できないために失敗します。これは、ジェネリクス型変数がまだ含まれているためです。

次の例は、CRUD メソッド（この場合は findById および save）を選択的に公開する方法を示しています。

前の例では、すべてのドメインリポジトリと公開された findById(…) および save(…) に共通のベースインターフェースを定義しました。これらのメソッドは、Spring Data が提供する選択のストアのベースリポジトリ実装にルーティングされます（たとえば、JPA を使用する場合、実装は SimpleJpaRepository です）。これは、それらが CrudRepository のメソッドシグネチャーと一致するためです。そのため、UserRepository はユーザーを保存し、ID で個々のユーザーを検索し、メールアドレスで Users を検索するクエリをトリガーできるようになりました。

定義済みスコープ内のすべてのリポジトリインターフェースが Spring Data モジュールにバインドされているため、アプリケーションで一意の Spring Data モジュールを使用すると、物事が簡単になります。アプリケーションによっては、複数の Spring Data モジュールを使用する必要がある場合があります。そのような場合、リポジトリ定義は永続化テクノロジーを区別する必要があります。クラスパスで複数のリポジトリファクトリを検出すると、Spring Data は厳密なリポジトリ構成モードに入ります。厳密な構成では、リポジトリまたはドメインクラスの詳細を使用して、リポジトリ定義の Spring Data モジュールバインディングについて決定します。

次の例は、モジュール固有のインターフェース（この場合は JPA）を使用するリポジトリを示しています。

次の例は、汎用インターフェースを使用するリポジトリを示しています。

次の例は、アノテーション付きのドメインクラスを使用するリポジトリを示しています。

次の悪い例は、アノテーションが混在するドメインクラスを使用するリポジトリを示しています。

リポジトリ型の詳細および識別ドメインクラスアノテーションは、特定の Spring Data モジュールのリポジトリ候補を識別するための厳密なリポジトリ構成に使用されます。同じドメイン型で複数の永続化テクノロジ固有のアノテーションを使用することが可能であり、複数の永続化テクノロジでドメイン型を再利用できます。ただし、Spring Data は、リポジトリをバインドする一意のモジュールを決定できなくなります。

リポジトリを区別する最後の方法は、リポジトリベースパッケージをスコープすることです。ベースパッケージは、リポジトリインターフェース定義のスキャンの開始点を定義します。これは、適切なパッケージにリポジトリ定義があることを意味します。デフォルトのアノテーション駆動型の構成では、構成クラスのパッケージが使用されます。XML ベースの構成の基本パッケージは必須です。

次の例は、基本パッケージのアノテーション駆動型の構成を示しています。

クエリを解決するリポジトリインフラストラクチャでは、次の戦略を使用できます。XML 構成では、query-lookup-strategy 属性を使用して名前空間で戦略を構成できます。Java 構成の場合、EnableJpaRepositories アノテーションの queryLookupStrategy 属性を使用できます。特定のデータストアでは一部の戦略がサポートされていない場合があります。

Spring Data リポジトリインフラストラクチャに組み込まれているクエリビルダーメカニズムは、リポジトリのエンティティに対して制約クエリを構築できます。

次の例は、いくつかのクエリを作成する方法を示しています。

クエリメソッド名の解析は、主語と述語に分けられます。最初の部分（find … By、exists … By）はクエリのサブジェクトを定義し、2 番目の部分は述語を形成します。導入句（主語）には、さらに式を含めることができます。find （または他の導入キーワード）と By の間のテキストは、Distinct などの結果を制限するキーワードの 1 つを使用して、作成するクエリまたは Top/First は、クエリ結果を制限しますに個別のフラグを設定しない限り、説明的であると見なされます。

付録には、クエリメソッドのサブジェクトキーワードとクエリメソッドの述語キーワードの完全なリストが含まれています。これには、並べ替えや大文字小文字の修飾子が含まれます。ただし、最初の By は、実際の条件述語の開始を示す区切り文字として機能します。非常に基本的なレベルでは、エンティティプロパティの条件を定義し、And および Or と連結できます。

メソッドの解析の実際の結果は、クエリを作成する永続ストアによって異なります。ただし、注意すべき一般的な事項がいくつかあります。

前の例に示すように、プロパティ式は管理対象エンティティの直接プロパティのみを参照できます。クエリの作成時に、解析されたプロパティが管理対象ドメインクラスのプロパティであることをすでに確認しています。ただし、ネストされたプロパティを走査して制約を定義することもできます。次のメソッドシグネチャーを検討してください。

Person に ZipCode を含む Address があると仮定します。その場合、メソッドは x.address.zipCode プロパティトラバーサルを作成します。解決アルゴリズムは、パーツ全体（AddressZipCode）をプロパティとして解釈することから始まり、ドメインクラスでその名前（大文字でない）のプロパティをチェックします。アルゴリズムが成功すると、そのプロパティが使用されます。そうでない場合、アルゴリズムはキャメルケース部分のソースを右側から頭と尾に分割し、対応するプロパティ（この例では、AddressZip と Code）を見つけようとします。アルゴリズムがそのヘッドを持つプロパティを見つけると、テールを取得し、そこからツリーを構築し続け、今説明したメソッドでテールを分割します。最初の分割が一致しない場合、アルゴリズムは分割ポイントを左に移動し（Address、ZipCode）、続行します。

これはほとんどの場合に機能するはずですが、アルゴリズムが間違ったプロパティを選択する可能性があります。Person クラスにも addressZip プロパティがあるとします。アルゴリズムは最初の分割ラウンドですでに一致し、間違ったプロパティを選択して失敗します（addressZip の型にはおそらく code プロパティがないため）。

このあいまいさを解決するには、メソッド名内で _ を使用して、トラバーサルポイントを手動で定義します。メソッド名は次のようになります。

アンダースコア文字を予約文字として扱うため、標準の Java 命名規則に従うことを強くお勧めします（つまり、プロパティ名にアンダースコアを使用せず、代わりにキャメルケースを使用します）。

クエリでパラメーターを処理するには、前の例ですでに見たようにメソッドパラメーターを定義します。それに加えて、インフラストラクチャは Pageable や Sort などの特定の型を認識し、ページネーションとソートをクエリに動的に適用します。次の例は、これらの機能を示しています。

最初のメソッドでは、org.springframework.data.domain.Pageable インスタンスをクエリメソッドに渡して、静的に定義されたクエリにページングを動的に追加できます。Page は、使用可能な要素とページの総数を認識しています。これは、インフラストラクチャがカウントクエリをトリガーして全体の数を計算することによって行われます。これは（使用するストアによっては）高額になる可能性があるため、代わりに Slice を返すことができます。Slice は、次の Slice が使用可能かどうかのみを認識します。これは、より大きな結果セットをウォークスルーする場合に十分な場合があります。

並べ替えオプションも Pageable インスタンスを介して処理されます。並べ替えのみが必要な場合は、メソッドに org.springframework.data.domain.Sort パラメーターを追加します。ご覧のとおり、List を返すことも可能です。この場合、実際の Page インスタンスを構築するために必要な追加のメタデータは作成されません（つまり、必要だったはずの追加のカウントクエリは発行されません）。むしろ、指定された範囲のエンティティのみを検索するようにクエリを制限します。

first または top キーワードを使用して、クエリメソッドの結果を制限できます。これらのキーワードは、同じ意味で使用できます。オプションの数値を top または first に追加して、返される最大結果サイズを指定できます。数値が省略されている場合、結果サイズは 1 と見なされます。次の例は、クエリサイズを制限する方法を示しています。

制限式は、個別のクエリをサポートするデータストアの Distinct キーワードもサポートします。また、結果セットを 1 つのインスタンスに制限するクエリの場合、結果を Optional キーワードでラップすることがサポートされています。

ページネーションまたはスライスが制限クエリページネーション（および使用可能なページ数の計算）に適用される場合、制限された結果内で適用されます。

複数の結果を返すクエリメソッドは、標準の Java Iterable、List、Set を使用できます。さらに、Spring Data の Streamable、Iterable のカスタム拡張、Vavr (英語) によって提供されるコレクション型を返すことをサポートします。考えられるすべてのクエリメソッドの戻り値の型について説明している付録を参照してください。

戻り値の型として Java 8 Stream<T> を使用することにより、クエリメソッドの結果を段階的に処理できます。次の例に示すように、クエリ結果を Stream でラップする代わりに、データストア固有のメソッドを使用してストリーミングを実行します。

Spring Data 2.0 以降、個々の集約インスタンスを返すリポジトリ CRUD メソッドは、Java 8 の Optional を使用して、値が存在しない可能性があることを示します。さらに、Spring Data はクエリメソッドで次のラッパー型を返すことをサポートしています。

または、クエリメソッドは、ラッパー型をまったく使用しないことを選択できます。null を返すことにより、クエリ結果がないことが示されます。コレクション、コレクションの代替、ラッパー、ストリームを返すリポジトリメソッドは、null ではなく、対応する空の表現を返すことが保証されています。詳細については、"付録 C" を参照してください。

Spring の非同期メソッド実行機能を使用すると、リポジトリクエリを非同期で実行できます。これは、Spring TaskExecutor に送信されたタスクで実際のクエリが発生している間、メソッドは呼び出し直後に戻ることを意味します。非同期クエリはリアクティブクエリとは異なるため、混在させないでください。リアクティブサポートの詳細については、ストア固有のドキュメントを参照してください。次の例は、いくつかの非同期クエリを示しています。

Java 構成クラスでストア固有の @EnableJpaRepositories アノテーションを使用して、リポジトリのアクティブ化の構成を定義します。Spring コンテナーの Java ベースの構成の概要については、Spring リファレンスドキュメントの JavaConfig を参照してください。

Spring Data リポジトリを有効にするサンプル構成は次のようになります。

次の例に示すように、各 Spring Data モジュールには、Spring がスキャンする基本パッケージを定義できる repositories 要素が含まれています。

前の例では、Spring は、Repository またはそのサブインターフェースの 1 つを継承するインターフェースについて、com.acme.repositories とそのすべてのサブパッケージをスキャンするように指示されています。見つかったインターフェースごとに、インフラストラクチャは永続化テクノロジ固有の FactoryBean を登録して、クエリメソッドの呼び出しを処理する適切なプロキシを作成します。各 Bean は、インターフェース名から派生した Bean 名で登録されるため、UserRepository のインターフェースは userRepository で登録されます。ネストされたリポジトリインターフェースの Bean 名には、囲む型名がプレフィックスとして付けられます。基本パッケージ属性ではワイルドカードを使用できるため、スキャンされたパッケージのパターンを定義できます。

デフォルトでは、インフラストラクチャは、構成された基本パッケージにある永続化テクノロジー固有の Repository サブインターフェースを継承するすべてのインターフェースを選択し、そのための Bean インスタンスを作成します。ただし、どのインターフェースに Bean インスタンスが作成されているかをより細かく制御したい場合があります。これを行うには、リポジトリ宣言内でフィルター要素を使用します。セマンティクスは、Spring のコンポーネントフィルターの要素とまったく同じです。詳細については、これらの要素の Spring リファレンスドキュメントを参照してください。

例: 特定のインターフェースをリポジトリ Bean としてインスタンス化から除外するには、次の構成を使用できます。

前述の例には、SomeRepository で終わるすべてのインターフェースが含まれており、SomeOtherRepository で終わるインターフェースはインスタンス化から除外されます。

Spring コンテナーの外部（CDI 環境など）でリポジトリインフラストラクチャを使用することもできます。クラスパスにはまだいくつかの Spring ライブラリが必要ですが、通常は、プログラムでリポジトリを設定することもできます。リポジトリサポートを提供する Spring Data モジュールには、次のように使用できる永続化テクノロジ固有の RepositoryFactory が付属しています。

カスタム機能でリポジトリを強化するには、最初に、次のように、フラグメントインターフェースとカスタム機能の実装を定義する必要があります。

実装自体は Spring Data に依存せず、通常の Spring Bean にすることができます。そのため、標準の依存性注入動作を使用して、他の Bean（JdbcTemplate など）への参照を注入したり、アスペクトに参加したりすることができます。

次に、次のように、リポジトリインターフェースにフラグメントインターフェースを継承させることができます。

リポジトリインターフェースでフラグメントインターフェースを拡張すると、CRUD とカスタム機能が組み合わされ、クライアントで使用できるようになります。

Spring Data リポジトリは、リポジトリ構成を形成するフラグメントを使用して実装されます。フラグメントは、基本リポジトリ、機能面（QueryDsl など）、カスタムインターフェースとその実装です。リポジトリインターフェースにインターフェースを追加するたびに、フラグメントを追加して構成を強化します。ベースリポジトリとリポジトリアスペクトの実装は、各 Spring Data モジュールによって提供されます。

次の例は、カスタムインターフェースとその実装を示しています。

次の例は、CrudRepository を継承するカスタムリポジトリのインターフェースを示しています。

リポジトリは、宣言の順序でインポートされる複数のカスタム実装で構成されます。カスタム実装は、基本実装およびリポジトリの側面よりも優先度が高くなります。この順序付けにより、ベースリポジトリおよびアスペクトメソッドをオーバーライドし、2 つのフラグメントが同じメソッドシグネチャーを提供する場合のあいまいさを解決できます。リポジトリフラグメントは、単一のリポジトリインターフェースでの使用に限定されません。複数のリポジトリがフラグメントインターフェースを使用し、異なるリポジトリでカスタマイズを再利用できる場合があります。

次の例は、リポジトリフラグメントとその実装を示しています。

次の例は、前述のリポジトリフラグメントを使用するリポジトリを示しています。

前のセクションで説明したアプローチでは、ベースリポジトリの動作をカスタマイズしてすべてのリポジトリが影響を受けるようにする場合、各リポジトリインターフェースをカスタマイズする必要があります。代わりに、すべてのリポジトリの動作を変更するために、永続化テクノロジ固有のリポジトリベースクラスを継承する実装を作成できます。このクラスは、次の例に示すように、リポジトリプロキシのカスタムベースクラスとして機能します。

最後のステップは、カスタマイズされたリポジトリ基本クラスを Spring Data インフラストラクチャに認識させることです。構成では、次の例に示すように、repositoryBaseClass を使用してこれを行うことができます。

Querydsl (英語) は、流れるような API を使用して、静的に型指定された SQL のようなクエリの構築を可能にするフレームワークです。

次の例に示すように、いくつかの Spring Data モジュールは、QuerydslPredicateExecutor を介して Querydsl との統合を提供します。

Querydsl サポートを使用するには、次の例に示すように、リポジトリインターフェースで QuerydslPredicateExecutor を継承します。

前の例では、次の例に示すように、Querydsl Predicate インスタンスを使用して型安全なクエリを記述できます。

リポジトリプログラミングモデルをサポートする Spring Data モジュールには、さまざまな Web サポートが付属しています。Web 関連のコンポーネントでは、Spring MVC JAR がクラスパス上にある必要があります。それらのいくつかは、Spring HATEOAS [GitHub] (英語) との統合さえ提供します。一般に、統合サポートは、次の例に示すように、JavaConfig 構成クラスで @EnableSpringDataWebSupport アノテーションを使用することで有効になります。

@EnableSpringDataWebSupport アノテーションは、いくつかのコンポーネントを登録します。これらについては、このセクションの後半で説明します。また、クラスパスで Spring HATEOAS を検出し、統合コンポーネント（存在する場合）も登録します。

Spring JDBC モジュールを使用している場合は、おそらく DataSource に SQL スクリプトを取り込むためのサポートに精通しているでしょう。同様の抽象化がリポジトリレベルで利用できますが、ストアに依存しない必要があるため、データ定義言語として SQL を使用しません。ポピュレーターは XML（Spring の OXM 抽象化による）と JSON（Jackson による）をサポートして、リポジトリにデータを取り込むデータを定義します。

次の内容の data.json というファイルがあるとします。

Spring Data Commons で提供されるリポジトリ名前空間の populator 要素を使用して、リポジトリにデータを取り込むことができます。上記のデータを PersonRepository に入力するには、次のようなポピュレーターを宣言します。

上記の宣言により、data.json ファイルは Jackson ObjectMapper によって読み取られ、逆直列化されます。

JSON オブジェクトが非整列化される型は、JSON ドキュメントの _class 属性を調べることで決定されます。インフラストラクチャは最終的に、適切なリポジトリを選択して、デシリアライズされたオブジェクトを処理します。

代わりに、XML を使用してリポジトリにデータを取り込む必要のあるデータを定義するには、unmarshaller-populator エレメントを使用できます。Spring OXM で使用可能な XML マーシャラーオプションの 1 つを使用するように構成します。詳細については、Spring リファレンスドキュメントを参照してください。次の例は、JAXB を使用してリポジトリポピュレータをアンマーシャルする方法を示しています。

この章では、Query by Example の概要とその使用方法について説明します。

Query by Example（QBE）は、シンプルなインターフェースを備えた使いやすいクエリ手法です。動的なクエリの作成が可能になり、フィールド名を含むクエリを作成する必要がなくなります。実際、Query by Example では、ストア固有のクエリ言語を使用してクエリを記述する必要はまったくありません。

例示による問い合わせ API は、次の 4 つの部分で構成されています。

例示による問い合わせは、いくつかのユースケースに適しています。

例示による問い合わせには、いくつかの制限もあります。

Query by Example を開始する前に、ドメインオブジェクトが必要です。開始するには、次の例に示すように、リポジトリのインターフェースを作成します。

前の例は、単純なドメインオブジェクトを示しています。これを使用して Example を作成できます。デフォルトでは、null 値を持つフィールドは無視され、文字列はストア固有のデフォルトを使用して照合されます。

例は、of ファクトリメソッドを使用するか、ExampleMatcher を使用して作成できます。Example は不変です。次のリストは、簡単な例を示しています。

リポジトリを使用して、サンプルクエリを実行できます。これを行うには、リポジトリインターフェースに QueryByExampleExecutor<T> を継承させます。次のリストは、QueryByExampleExecutor インターフェースからの抜粋を示しています。

例はデフォルト設定に限定されません。次の例に示すように、ExampleMatcher を使用して、文字列照合、null 処理、プロパティ固有の設定に独自のデフォルトを指定できます。

デフォルトでは、ExampleMatcher はプローブに設定されたすべての値が一致することを期待しています。暗黙的に定義された述語のいずれかに一致する結果を取得する場合は、ExampleMatcher.matchingAny() を使用します。

個々のプロパティ（「名」や「姓」、ネストされたプロパティの場合は "address.city" など）の動作を指定できます。次の例に示すように、一致するオプションと大文字と小文字の区別を使用して調整できます。

マッチャーオプションを構成する別の方法は、ラムダ（Java 8 で導入）を使用することです。このアプローチは、実装者にマッチャーの変更を要求するコールバックを作成します。設定オプションはマッチャーインスタンス内に保持されているため、マッチャーを返す必要はありません。次の例は、ラムダを使用するマッチャーを示しています。

Example によって作成されたクエリは、構成の統合ビューを使用します。デフォルトのマッチング設定は ExampleMatcher レベルで設定できますが、個々の設定は特定のプロパティパスに適用できます。ExampleMatcher で設定された設定は、明示的に定義されていない限り、プロパティパス設定に継承されます。プロパティパッチの設定は、デフォルト設定よりも優先されます。次の表は、さまざまな ExampleMatcher 設定の範囲を説明しています。

QueryByExampleExecutor offers one more method, which we did not mention so far: <S extends T, R> R findBy(Example<S> example, Function<FluentQuery.FetchableFluentQuery<S>, R> queryFunction). As with other methods, it executes a query derived from an Example. However, with the second argument, you can control aspects of that execution that you cannot dynamically control otherwise. You do so by invoking the various methods of the FetchableFluentQuery in the second argument. sortBy lets you specify an ordering for your result. as lets you specify the type to which you want the result to be transformed. project limits the queried attributes. first, firstValue, one, oneValue, all, page, stream, count, and exists define what kind of result you get and how the query behaves when more than the expected number of results are available.

Spring Data Neo4j offers a couple of extensions or "mixins" that can be added to repositories. What is a mixin? According to Wikipedia (英語) mixins are a language concept that allows a programmer to inject some code into a class. Mixin programming is a style of software development, in which units of functionality are created in a class and then mixed in with other classes.

Java does not support that concept on the language level, but we do emulate it via a couple of interfaces and a runtime that adds appropriate implementations and interceptors for.

Mixins added by default are QueryByExampleExecutor and ReactiveQueryByExampleExecutor respectively. Those interfaces are explained in detail in Section 10.9.

Additional mixins provided are:

アクセサーメソッドがすべてターゲット集合体のプロパティに一致する射影インターフェースは、閉じた射影と見なされます。次の例（この章の前半でも使用しました）は、閉じた射影です。

閉じた射影を使用する場合、Spring Data はクエリの実行を最適化できます。これは、射影プロキシのバックアップに必要なすべての属性がわかっているためです。詳細については、リファレンスドキュメントのモジュール固有の部分を参照してください。

次の例に示すように、@Value アノテーションを使用して、射影インターフェースのアクセサーメソッドを使用して新しい値を計算することもできます。

射影を支える集約ルートは、target 変数で利用可能です。@Value を使用した射影インターフェースは、オープン射影です。この場合、Spring Data はクエリ実行最適化を適用できません。これは、SpEL 式が集約ルートの任意の属性を使用できるためです。

@Value で使用される式は複雑すぎてはいけません — String 変数でのプログラミングは避けたいです。非常に単純な式の場合、次の例に示すように、1 つのオプションはデフォルトのメソッド（Java 8 で導入）に頼ることです。

このアプローチでは、射影インターフェースで公開される他のアクセサーメソッドに純粋に基づいてロジックを実装できる必要があります。次の例に示すように、2 番目のより柔軟なオプションは、Spring Bean にカスタムロジックを実装し、SpEL 式からそれを呼び出すことです。

SpEL 式が myBean を参照し、getFullName(…) メソッドを呼び出し、射影ターゲットをメソッドパラメーターとして転送する方法に注目してください。SpEL 式の評価に裏付けられたメソッドは、メソッドパラメーターを使用することもできます。このパラメーターは、式から参照できます。メソッドのパラメーターは、args という名前の Object 配列を介して使用できます。次の例は、args 配列からメソッドパラメーターを取得する方法を示しています。

繰り返しますが、より複雑な式の場合は、前に説明したように、Spring Bean を使用し、式でメソッドを呼び出す必要があります。

射影インターフェースの Getter は、null 許容ラッパーを使用して null の安全性を向上させることができます。現在サポートされているラッパー型は次のとおりです。

基になる射影値が null でない場合、値はラッパー型の現在の表現を使用して返されます。バッキング値が null の場合、getter メソッドは使用されたラッパー型の空の表現を返します。

リスト 41 を実行するには、次の依存関係が必要です。

Neo4j 3.5 のエンタープライズバージョンの依存関係は、com.neo4j.test:neo4j-harness-enterprise および適切なリポジトリ構成で利用できます。

リスト 43 を実行するには、次の依存関係が必要です。

Neo4j 4.x/5.x のエンタープライズバージョンの依存関係は、com.neo4j.test:neo4j-harness-enterprise および適切なリポジトリ構成で利用できます。

もちろん、リスト 44 で示されているように、接続構成の原則は Testcontainers でも同じです。次の依存関係が必要です。

そして完全なテスト:

上記のアノテーションがユースケースに適合しないシナリオがいくつかあります。そのうちの 1 つは、ドライバーの初期化方法を 100% で制御したい場合です。テストコンテナーを実行している場合、次のようにネストされた静的構成クラスを使用してこれを行うことができます。

プロパティを使用したいが @DynamicPropertySource を使用できない場合は、初期化子を使用します。

エンティティを作成または変更したユーザーをキャプチャーする @CreatedBy と @LastModifiedBy、および変更が発生したときにキャプチャーする @CreatedDate と @LastModifiedDate を提供します。

ご覧のとおり、キャプチャーする情報に応じて、アノテーションを選択的に適用できます。変更が行われたときにキャプチャーすることを示すアノテーションは、JDK8 の日付と時刻の型、long、Long、レガシー Java Date と Calendar のプロパティで使用できます。

以下のスニペットに示すように、監査メタデータは必ずしもルートレベルのエンティティに存在する必要はありませんが、埋め込まれたエンティティに追加できます（実際に使用されているストアによって異なります）。

アノテーションを使用して監査メタデータを定義したくない場合は、ドメインクラスに Auditable インターフェースを実装させることができます。すべての監査プロパティの setter メソッドを公開します。

@CreatedBy または @LastModifiedBy を使用する場合、監査インフラストラクチャは何らかの形で現在のプリンシパルを認識する必要があります。そのために、現在のユーザーまたはアプリケーションと対話するシステムが誰であるかをインフラストラクチャに伝えるために実装する必要がある AuditorAware<T> SPI インターフェースを提供します。ジェネリクス型 T は、@CreatedBy または @LastModifiedBy アノテーションが付けられたプロパティの型を定義します。

次の例は、Spring Security の Authentication オブジェクトを使用するインターフェースの実装を示しています。

実装は、Spring Security が提供する Authentication オブジェクトにアクセスし、UserDetailsService 実装で作成したカスタム UserDetails インスタンスを検索します。ここでは、UserDetails 実装を介してドメインユーザーを公開しているが、見つかった Authentication に基づいて、どこからでも検索できると想定しています。

リアクティブインフラストラクチャを使用する場合、コンテキスト情報を利用して @CreatedBy または @LastModifiedBy 情報を提供することができます。アプリケーションと対話している現在のユーザーまたはシステムが誰であるかをインフラストラクチャに通知するために実装する必要がある ReactiveAuditorAware<T> SPI インターフェースを提供します。ジェネリクス型 T は、@CreatedBy または @LastModifiedBy でアノテーションが付けられたプロパティがどの型でなければならないかを定義します。

次の例は、リアクティブ Spring Security の Authentication オブジェクトを使用するインターフェースの実装を示しています。

実装は、Spring Security が提供する Authentication オブジェクトにアクセスし、UserDetailsService 実装で作成したカスタム UserDetails インスタンスを検索します。ここでは、UserDetails 実装を介してドメインユーザーを公開しているが、見つかった Authentication に基づいて、どこからでも検索できると想定しています。

これは、利用可能なデータベースの選択を使用して、Boot が接続が正常かどうかを確認するために実行するのと同じクエリを実行します。これを適用するには、次の構成を使用します。

リアクティブバリアントは基本的に同じで、リアクティブ型と対応するリアクティブインフラストラクチャクラスを使用します。

そしてもちろん、設定のリアクティブ版です。Spring Boot は非リアクティブアクチュエーターエンドポイントでも使用できるように既存のリアクティブインジケーターをラップするため、2 つの異なるレジストリクリーナーが必要です。

Sometimes you might want to do bulk loadings from a repository or delete whole subgraphs or interact in very specific ways with the Neo4j Java-Driver. This is possible as well. The following example shows how:

This interaction does of course not run in a Spring transaction, as the driver does not know about Spring.

Putting it all together, this test succeeds:

As a final word: All three interfaces and implementations are picked up by Spring Data Neo4j automatically. There is no need for further configuration. Also, the same overall repository could have been created with only one additional fragment (the interface defining all three methods) and one implementation. The implementation would than have had all three abstractions injected (template, client and driver).

All of this applies of course to reactive repositories as well. They would work with the ReactiveNeo4jTemplate and ReactiveNeo4jClient and the reactive session provided by the driver.

If you have recurring methods for all repositories, you could swap out the default repository implementation.

すぐに使える幅広い変換をサポートします。公式ドライバーマニュアルでサポートされている暗号型のリストを見つけてください: Cypher 値の操作 (英語) 。

ラッパー型のプリミティブ型も同様にサポートされます。

Neo4j クライアントとの対話は通常、次の呼び出しで終了します。

命令型バージョンはこの時点でデータベースと対話し、リクエストされた結果または要約を Optional<> または Collection でラップして取得します。

対照的に、リアクティブバージョンは、リクエストされた型のパブリッシャーを返します。データベースとの対話と結果の取得は、パブリッシャーがサブスクライブされるまで行われません。パブリッシャーは 1 回だけサブスクライブできます。

SDN のほとんどの場合と同様、両方のクライアントは構成されたドライバーインスタンスに依存します。

ドライバーは、4.0 データベースに対してのみリアクティブセッションを開くことができ、それより低いバージョンでは例外が発生して失敗します。

当社の Spring Boot スターターは、環境 (命令型またはリアクティブ) に適合する Neo4j クライアントのすぐに使用できる Bean を提供しており、通常は独自のインスタンスを構成する必要はありません。

find/load 操作に加えて、save 操作はデータを操作するときに最もよく使用される操作の 1 つです。通常、保存操作呼び出しでは、データベースに対して複数のステートメントを発行して、結果のグラフモデルが指定された Java モデルと一致することを確認します。

load ドキュメントでは、クエリの MATCH 部分がどのように見えるかだけでなく、データがどのように返されるかについても説明します。

最も単純なロード操作は findById 呼び出しです。これは、クエリした型のラベルを持つすべてのノードを照合し、ID 値に対してフィルターを実行します。

MATCH (n:Person) WHERE id(n) = 1364

提供されたカスタム ID がある場合、SDN は定義したプロパティを ID として使用します。

MATCH (n:Person) WHERE n.customId = 'anId'

返されるデータは地図射影 (英語) として定義されます。

RETURN n{.first_name, .personNumber, __internalNeo4jId__: id(n), __nodeLabels__: labels(n)}

ご覧のとおり、そこには __internalNeo4jId__ と __nodeLabels__ という 2 つの特別なフィールドがあります。データを Java オブジェクトにマッピングする場合、どちらも重要です。__internalNeo4jId__ の値は id(n) または指定されたカスタム ID のいずれかですが、マッピングプロセスでは参照する既知のフィールドが 1 つ存在する必要があります。__nodeLabels__ は、このノード上で定義されているラベルをすべて見つけてマッピングできることを保証します。これは、継承が使用され、具象クラスに対してクエリを実行しない場合、またはスーパー型のみを定義する関連が定義されている場合に必要です。

人間関連について話す: エンティティ内でリレーションシップを定義している場合、パターン内包表記 (英語) として返されたマップに追加されます。上記の戻り部分は次のようになります。

RETURN n{.first_name, …​, Person_Has_Hobby: [(n)-[:Has]→(n_hobbies:Hobby)|n_hobbies{__internalNeo4jId__: id(n_hobbies), .name, nodeLabels: labels(n_hobbies)}]}

SDN で使用されるマップ射影とパターン理解により、定義したプロパティと関連のみがクエリされることが保証されます。

自己参照ノードがある場合、または返されるデータにサイクルが発生する可能性のあるスキーマを作成している場合、SDN はカスケード / データ駆動型のクエリ作成にフォールバックします。特定のノードを検索する最初のクエリから開始して条件を考慮し、結果のノードをステップ順に調べ、それらの関連もマップされている場合は、その場でさらにクエリを作成します。このクエリの作成と実行のループは、クエリで新しい関連やノードが見つからなくなるまで継続します。作成方法は、保存 / 更新プロセスに似ています。

次のようなグラフが表示されます。

マッピングに示されているドメインモデル (簡潔にするためにコンストラクターとアクセサーは省略されています)。

ご覧のとおり、関連は発信的なものだけです。生成されたファインダーメソッド ( findById を含む) は常に、マップされるルートノードとの一致を試みます。それ以降、すべての関連オブジェクトがマッピングされます。1 つのオブジェクトのみを返す必要があるクエリでは、そのルートオブジェクトが返されます。多くのオブジェクトを返すクエリでは、一致するすべてのオブジェクトが返されます。返されたオブジェクトからの出力および受信関連には、当然のことながら値が設定されます。

次の Cypher クエリを想定します。

これはルートノードごとに 1 つのレコードを取得するの推奨に従っており、ここで一致させたいリーフノードに最適です。ただし、これは、0 または 1 個のマップされたオブジェクトを返すすべてのシナリオにのみ当てはまります。このクエリは以前と同様にすべてのリレーションシップを設定しますが、4 つのオブジェクトすべてを返すわけではありません。

これは、パス全体を返すことで変更できます。

ここでは、パス p が実際に 4 つのノードすべてへのパスを含む 3 行を返すという事実を利用します。4 つのノードすべてが設定され、リンクされて返されます。

これは、Neo4j ブラウザーまたは Cypher-Shell で $ 構文を使用して発行される標準の Cypher クエリとまったく同じ方法で実行できます (Neo4j 4.0 以降では、Cypher パラメーターの古い {foo} 構文がデータベースから削除されています)。

カスタムクエリでアノテーションが付けられた関数にパラメーターとして渡されたマップされたエンティティ ( @Node を持つすべてのもの) は、ネストされたマップに変換されます。次の例は、構造体を Neo4j パラメーターとして表します。

ムービーモデルに示されているように、アノテーションが付けられた Movie、Vertex、Actor クラスが与えられています。

Movie のインスタンスを上記のリポジトリメソッドに渡すと、次の Neo4j マップパラメーターが生成されます。

ノードはマップで表されます。マップには常に、マップされた ID プロパティである id が含まれます。labels では、静的ラベルと動的ラベルのすべてが使用可能になります。すべてのプロパティ (および関連の種類) は、エンティティが SDN によって書き込まれた場合にグラフに表示されるのと同じように、これらのマップに表示されます。値は正しい Cypher 型を持ち、それ以上の変換は必要ありません。

エンティティが、異なる型の他のノードと同じ型の関連を持っている場合、すべて同じリストに表示されます。このようなマッピングが必要で、カスタムパラメーターを操作する必要がある場合は、それに応じてマッピングを展開する必要があります。これを行う 1 つの方法は、相関サブクエリです (Neo4j 4.1+ が必要です)。

Spring 式言語 (SpEL) は、:#{} 内のカスタムクエリで使用できます。ここでのコロンはパラメーターを指しており、パラメーターが意味をなす場合にはそのような式を使用する必要があります。ただし、リテラル拡張機能を使用すると、標準の Cypher でパラメーターが許可されない場所 (ラベルや関連型など) で SpEL 式を使用できます。これは、SpEL 評価を受けるクエリ内のテキストブロックを定義する標準的な Spring Data 方法です。

次の例では、基本的に上記と同じクエリを定義しますが、WHERE 句を使用してさらなる 波括弧 を回避します。

ブロックされた SpEL は :#{ で始まり、指定された String パラメーターを名前 (#pt1) で参照します。これを上記の Cypher 構文と混同しないでください。SpEL 式は、両方のパラメーターを 1 つの値に連結し、最終的に Neo4jClient に渡します。SpEL ブロックは } で終わります。

SpEL は、さらに 2 つの問題も解決します。Sort オブジェクトをカスタムクエリに渡すことができる 2 つの拡張機能が提供されています。カスタムクエリのリスト 63 を覚えていますか ? orderBy 拡張機能を使用すると、動的ソートを備えた Pageable をカスタムクエリに渡すことができます。

ネイティブ Neo4j Java ドライバー org.neo4j.driver.types.Point 型を使用している場合は、派生ファインダーメソッドで次のキーワードとパラメーター型を使用できます。

エリア内のクエリ:

特定の点付近でクエリを実行します。