
# JSON の列

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

## 使う理由

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

## 例

```dart
@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](../spring-boot-starter-supabase/data.md)) | デコードされた JSON。ネストした JSON として送受信される |

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

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

## クエリ

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

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

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

## 拒否されるもの

- `@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`](entities.md): その子は、専用のテーブルの行です。
- PostgreSQL で、自分で作った配列の列 (`tags text[]`) に入る単純な値の `List` (`List<String>`、`List<double>`、`List<bool>`、`List<DateTime>`): これまでどおり保存され、読み込まれます。ビルドはそのようなリストをストアに任せます。配列のない SQLite は、起動時にそれを拒否します。`Set` と `Map` が配列になることはありません。
- メモリ上のストアは Dart のオブジェクトをそのまま保持し、SQL でないストアは自分で決めます。どちらもチェックされません。

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

## Spring (Java) との対応

```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)` があります。マッピングできないコレクションは、起動時ではなく、最初のステートメントで失敗します。

## 関連項目

- [エンティティ](entities.md)
- [@Query](query.md)
- [スキーマとマイグレーション](schema.md)
- [ストアとその機能](stores.md)
