
# データベース関数

リポジトリのメソッドに付けた `@Procedure('name')` は、データベース関数を名前で呼び出します。メソッドのパラメーターが名前付きの引数になり、関数が返すものは、[`@Query`](query.md) の結果と同じように読まれます。

## 使う理由

データベースの中にあるべき処理があります。一緒に起きなければならない複数の書き込み、クライアントよりプランナーのほうがうまく扱えるクエリ、すべてのクライアントが従わなければならないルールです。関数は、REST API のようにトランザクションのないストアで、複数の書き込みをアトミックに行う方法でもあります。手で呼び出すには、その SQL、引数の順序、行のマッパーが必要です。`@Procedure` なら、名前とメソッドのシグネチャーだけです。

## 例

```dart
abstract interface class Accounts
    implements CrudRepository<Account, int> {
  // select * from "transfer"("from_id" => ?, "to_id" => ?, "amount" => ?)
  @Procedure('transfer')
  Future<void> transfer(int fromId, int toId, int amount);

  @Procedure('accounts_over')
  Future<List<Account>> over(int balance);
}
```

```sql
create function accounts_over(balance int) returns setof accounts
language sql stable as $$ select * from accounts where accounts.balance > $1 $$;
```

## 引数

- メソッドの各パラメーターが関数の一つの引数になり、**名前で**渡されます。
- 名前は、列と同じく、パラメーターの名前をスネークケースにしたものです。`accountId` は `account_id` になります。マッピングの命名戦略が名前を決めます。
- 値は、列の値と同じように変換されます。enum はその `name` です。
- リストは、一つの配列の引数になります。
- `@Procedure('schema.name')` は、サーチパスの外にある関数を呼び出します。

## 結果

関数が返すものは、`@Query` の行と同じように読まれます。

| メソッドが返すもの | 何から |
|---|---|
| `Future<List<Account>>`、`Future<Set<Account>>`、`Stream<Account>` | 行。リポジトリのエンティティ、または列から名前で組み立てられるアプリケーションのクラス。`Stream` は、購読されたときに関数を呼び出す。 |
| `Future<List<int>>`、`Future<Set<String>>` | 各行の一つの列。 |
| `Future<Account?>`、`Future<int>` | 一つの値。行がなければ、null 許容の型では `null`、そうでなければエラー。 |
| `Future<List<Map<String, Object?>>>` | マップとしての行。 |
| `Future<void>` | 何もない。関数が返すものは無視される。 |

ビルドがメソッドを検査し、誤りはリポジトリの問題の一つになります。

- `Page` や `Slice` は返せません。関数は、件数を数えられるクエリではないためです。
- `Pageable` や `Sort` のパラメーターはありません。メソッドのパラメーターは、どれも関数の引数です。
- `@Procedure` は、`@Query`、`@Modifying`、`@Lock` と一緒には使えません。
- 関数の名前は空ではいけません。

`@Procedure` の付いたメソッドは、名前が何であっても、派生クエリとして読まれることはありません。

## ストア

リポジトリのストアは、データベース関数を持っていなければなりません ([ストアとその機能](stores.md) を参照)。関数のないストアでは、リポジトリは作成されるときに失敗し、ビルドがストアを知っている場合はビルド時に失敗します。

| ストア | 呼び出し |
|---|---|
| PostgreSQL 上の SQL | `select * from "name"("argument" => ?)`。呼び出し元の現在のトランザクションの中で実行される。ロールバックは、関数が書き込んだものを取り消す。 |
| SQLite 上の SQL | 関数なし |
| メモリ上 | 関数なし |
| `supabase` ([spring_boot_starter_supabase](../spring-boot-starter-supabase/data.md)) | `POST /rest/v1/rpc/name` (`rpc` は REST API 自身のパスです)。現在のユーザーとして。リクエストは一つなので、それ自体でアトミック。 |

## エラー

失敗は、リポジトリの他のメソッドと同じく、[`DataAccessException`](errors.md) です。

- 存在しない関数は、PostgreSQL では `BadSqlGrammarException` です。
- 呼び出し元にない権限、または関数がステート `42501` で発生させた例外は、`PermissionDeniedDataAccessException` です。
- 引数の数が違うのは、`InvalidDataAccessApiUsageException` です。

## ジェネレーターが書くもの

ジェネレーターは、`@Procedure` メソッドごとに、`ProcedureMethod` の定数 (メソッドの名前、アノテーション、パラメーター、結果の形と要素) と、リポジトリの操作の呼び出しを書きます。

```dart
// For: @Procedure('accounts_over')
//      Future<List<Account>> over(int balance);
static const _over = ProcedureMethod(
  r'over',
  Procedure(r'accounts_over'),
  parameters: [r'balance'],
  element: ClassType<Account>(),
);

@override
Future<List<Account>> over(int balance) =>
    this.operations.procedure<List<Account>>(_over, [balance]);
```

定数は `functions:` としてリポジトリの操作に渡され、各メソッドは `functions` の `StoreRequirement` として渡されます。

## ランタイム

生成されたコードの下には、ライブラリが直接使える二つの層があります。

ストア: `FunctionDataStore.callFunction(name, arguments)` は関数を呼び出し、その行を、列名から値へのマップとして返します。

```dart
final rows = await store.callFunction('restock', {
  'sku': 'A-1',
  'quantity': 5,
});
```

リポジトリの操作: `ProcedureMethod` は、一つの `@Procedure` メソッドを記述します (名前、アノテーション、パラメーター、結果の形と要素)。`RepositoryOperations.procedure<R>` と `procedureStream<E>` が、パラメーターの順に並べた引数でそれを呼び出します。

```dart
const named = ProcedureMethod(
  'named',
  Procedure('authors_named'),
  parameters: ['prefix'],
  element: ClassType<Author>(),
);

final authors = RepositoryFactory(
  mappingContext: mappingContext,
  converter: converter,
  stores: [store],
).operations<Author, int>(
  'Authors',
  annotations: const [UseStore('jdbc')],
  functions: const [named],
);

final found = await authors.procedure<List<Author>>(named, ['He']);
```

## Spring (Java) との対応

Spring Data JPA の `@Procedure("name")` です。Spring Data JDBC にはありません。ストアの呼び出しは、`SimpleJdbcCall.withFunctionName(name).execute(arguments)` に当たります。

## 関連項目

- [ストアとその機能](stores.md)
- [@Query](query.md)
- [トランザクション](transactions.md)
- [PostgreSQL](postgresql.md)
- [ジェネレーターとデータ](../spring-core-dart-generator/data.md)
