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 を、あるいはデータベース関数を使ってください。
拒否されるもの
@Id、@Version、監査されるプロパティ、@MappedCollection、他の集約への参照に付けた@Json: エンティティが読まれるときのMappingException。- プロパティの型として読めない保存済みの値: クラスとプロパティの名前を示す
MappingException。値そのものは決して示されません。
@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
- ビルド時: リポジトリのストアが SQL のストアだとビルドが知っている場合 (
@UseStore('jdbc')、@UseDataSource、または設定のspring.datasource.url)。Map、Set、そして単純な値以外のListはビルドエラーです。 - アプリケーションの起動時: すべての SQL のストアで。リポジトリは作られず、
spring.data.jdbc.schema: validateとcreateも同じ行を報告します。
拒否されないもの:
List<int>とUint8List: これらはバイト列です (BLOB、BYTEA)。@MappedCollection: その子は、専用のテーブルの行です。- PostgreSQL で、自分で作った配列の列 (
tags text[]) に入る単純な値のList(List<String>、List<double>、List<bool>、List<DateTime>): これまでどおり保存され、読み込まれます。ビルドはそのようなリストをストアに任せます。配列のない SQLite は、起動時にそれを拒否します。SetとMapが配列になることはありません。 - メモリ上のストアは Dart のオブジェクトをそのまま保持し、SQL でないストアは自分で決めます。どちらもチェックされません。
独自のストアは、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) があります。マッピングできないコレクションは、起動時ではなく、最初のステートメントで失敗します。