JSON の列

エンティティのプロパティに付けた @Json() は、そのプロパティを JSON として一つの列に保存します。アプリケーションのクラス、そのリストやマップ、あるいは単なる Map<String, Object?> や List のデータです。

使う理由

集約に属していて、単独では読まれない値があります。設定、住所のリスト、Webhook の生のペイロードなどです。専用のテーブルを作るのは無駄な作業で、データベースの列の型では保持できません。JSON の列は値を丸ごと保持し、アプリケーションは自分のクラスのまま扱えます。

例

@Table('profiles')
class UserProfile {
  @Id()
  int? id;

  @Json() // PostgreSQL: jsonb
  Settings settings; // a class of the application

  @Json(binary: false) // PostgreSQL: json
  Map<String, Object?> raw;

  @Json()
  List<Address>? addresses;
}

値は、アプリケーションの ObjectMapper によって書き込まれ、読み込まれます。コントローラーと Feign クライアントが使う Bean なので、その設定と、クラスの @Json… アノテーションが適用されます。Bean がなければ、デフォルト設定のマッパーが使われます。ビルドは、プロパティの型のクラスを、ネストしたものも含めて、コントローラーのボディと同じように記述します。アプリケーションのパッケージのクラスに @Introspected を付ける必要はありません。

null のプロパティは SQL の NULL であり、JSON の null ではありません。

各ストアが保持するもの

ストア 保持するもの
PostgreSQL jsonb の列。binary: false では json (書かれたとおりのテキスト: キーの順序、空白)。CAST(? AS JSONB) でテキストとしてバインドされる
SQLite TEXT の列の JSON テキスト。スターターが作るテーブルには CHECK (json_valid("column")) が付く
その他の SQL データベース TEXT の列の JSON テキスト
メモリ上 デコードされた JSON。出し入れのたびにコピーされる
supabase (spring_boot_starter_supabase) デコードされた JSON。ネストした JSON として送受信される

spring.data.jdbc.schema: create はこれらの列の型を書き、validate はそれをチェックします (スキーマとマイグレーション を参照)。PostgreSQL は正確に jsonb か json を、SQLite はテキストの列を求めます。JSON の列には DEFAULT が付きません。行に値がないときは、プロパティのデフォルト値が使われます。

独自のダイアレクトは、そのデータベースが JSON をどう保持するかを一か所で伝えます。SqlDialect.jsonStorage(Json) が JsonStorage を返します (列の型、既存の列のテスト、ステートメントがバインドするマーカーと値、ドライバーが返すものの読み取り)。

クエリ

@Query は、リポジトリ自身のメソッドと同じようにこの列を読みます。中身で絞り込むには、これを使います。

@Query("select * from profiles where settings ->> 'theme' = :theme")
Future<List<UserProfile>> themed(String theme);

派生クエリは、@Json のプロパティで絞り込むことも並べ替えることもできません (findBySettings、OrderBySettings、それによる Sort)。ビルドエラーになり、実行時にはどのストアでも InvalidDataAccessApiUsageException になります。SQL のストアではデータベースの JSON 演算子を使った @Query を、あるいはデータベース関数を使ってください。

拒否されるもの

@Json のない Map や List

SQL データベースには、Map、List、Set のための列がありません。SQL のストアでは、@Json のないそのようなプロパティは、ステートメントが一つも実行される前に、直し方とともに拒否されます。

Invalid repository Parcels:
  - Parcel.meta: a Map<String, Object?> property without @Json has no column on a SQL store: add @Json() to keep it as JSON, or @MappedCollection for rows of a child table

拒否されないもの:

独自のストアは、DataStoreDescriptor(collectionsNeedJson: true) でビルドのチェックを求め、EntityCheckingDataStore を実装することで、リポジトリが作られるときにエンティティについての自分の問題を報告します (ストアとその機能 を参照)。配列の列を持つダイアレクトは、SqlDialect.storesCollection(type) をオーバーライドします。

Spring (Java) との対応

@Table("profiles")
class UserProfile {
  @Id Long id;
  Settings settings; // needs a @WritingConverter and a @ReadingConverter to PGobject
}

Spring Data JDBC には JSON のアノテーションがありません。アプリケーションが、クラスごとに PostgreSQL の PGobject へのコンバーターの組を登録します。Hibernate には @JdbcTypeCode(SqlTypes.JSON) があります。マッピングできないコレクションは、起動時ではなく、最初のステートメントで失敗します。

関連項目