// ... read src, write result to dst ...
out.set_length(src.size());
}
```
`.param(COMPLEX)`および`.returns(COMPLEX)`で登録します。
```cpp theme={null}
.func(make_func<&complex_conjugate_impl>("complex_conjugate")
.returns(COMPLEX)
.param(COMPLEX)
.build())
```
完全な`CustomArg`/`CustomResult`APIについては、[開発ガイド](/docs/ja/mysql-8.4/0.0.5/development#argument-and-result-types)を参照してください。これには、パラメータ化された型用の`CustomArgWith`および`CustomResultWith
`が含まれます。
### 決定性関数
デフォルトでは、VDFは非決定性として登録されます。非決定性関数は、次の3つのSQLコンテキストでブロックされます。生成された列、`CHECK`制約、および式デフォルト値（列の`DEFAULT (expr)`）。これらの機能のいずれかを使用すると、非決定性VDFがエラーを返します。関数が常に同じ入力に対して同じ出力を生成し、副作用がない場合は、ビルダーチェーンに`.deterministic()`を追加して、決定性として宣言できます。
オプティマイザは、この情報を使用して、関数を1つのステートメントに対して1回評価し、行ごとに呼び出すのではなく、行間で値を再利用する場合があります。非決定性関数を誤って決定性としてマークすると、サーバーが異なる出力を生成する必要がある入力に対して同じ結果を返す可能性があります。関数が外部状態、ランダム性、または時間に依存しない場合にのみ、`.deterministic()`を追加してください。
**ビルダーのシグネチャ:** `.deterministic(bool d = true)` - 引数なしの形式は、デフォルトで`true`になります。
**例:**
```cpp theme={null}
.func(make_func<&complex_add_impl>("complex_add")
.returns(COMPLEX)
.param(COMPLEX)
.param(COMPLEX)
.deterministic()
.build())
```
`complex_add`は決定性として宣言されているため、生成された列の定義で使用できます。
```sql theme={null}
-- Deterministic VDFs can be used in generated columns
CREATE TABLE t (
a COMPLEX,
b COMPLEX,
result COMPLEX GENERATED ALWAYS AS (complex_add(a, b)) STORED
);
-- STORED vs VIRTUAL follows standard MySQL generated column rules
```
カスタムバッファサイズ
可変長のデータを返す関数の場合は、特定のバッファサイズを要求します。
```cpp theme={null}
make_func<&large_result_impl>("large_result")
.returns(STRING)
.param(INT)
.buffer_size(65536) // Request 64KB buffer
.build()
```
`buffer()`と`set_length()`を使用して値を自分で構築する場合、バッファは`buffer().size()`バイトに固定されます。それを超えて書き込むとメモリオーバーフローが発生するため、超過しないようにガードしてください。
```cpp theme={null}
void large_result_impl(StringArg input, StringResult out) {
if (input.is_null()) { out.set_null(); return; }
size_t needed = calculate_output_size(input.value());
auto buf = out.buffer();
if (needed > buf.size()) {
out.error("Output exceeds buffer size");
return;
}
// Write output into buf.data()
out.set_length(actual_output_length);
}
```
`STRING`結果の場合、`out.set(sv)`はsnprintfスタイルのオーバーフロー契約に従います。収まる分だけバイトをコピーし、`set_length`を介して値の完全なサイズを報告します。報告されたサイズがバッファを超えると、サーバーは結果バッファを拡張して関数を再呼び出しするため、要求されたバッファより大きい`STRING`値は切り捨てられなくなります。
その契約は行の評価時に適用されます。*マテリアライズされた*`STRING`結果（GROUP BY/DISTINCTの一時テーブル、`CREATE TABLE ... SELECT`、またはUNION内）は、関数が`.max_result_length(n)`を宣言しない限り、引数の幅で切り捨てられます。これは結果列のサイズを設定します（文字数単位で、`VEF_MAX_RESULT_LENGTH`（16 MiB）が上限です）。
```cpp theme={null}
make_func<&large_result_impl>("large_result")
.returns(STRING)
.max_result_length(65536)
.build()
```
関数の最大出力サイズに基づいて、`.buffer_size()`を使用して十分なバッファサイズを要求します。バッファサイズを正しく設定すると、バッファの拡張と再実行のラウンドトリップのコストを回避できます。
関数を実装する前に、[C++ APIリファレンス](/docs/ja/mysql-8.4/0.0.5/extension-api-reference)を確認して、完全なVDF契約を確認してください。これには、nullチェック、結果の型、バッファのサイズ設定、およびエラー処理が含まれます。
## ステップ4：カスタム型を作成する
カスタム型を使用すると、`ORDER BY`、インデックス、および集約関数で機能する`COMPLEX`、`UUID`、または`VECTOR`などの新しい列タイプを定義できます。拡張機能にのみ関数を登録する場合は、ステップ5に進みます。
完全な実装のウォークスルーについては、[C++でのカスタム型](/docs/ja/mysql-8.4/0.0.5/custom-types)を参照してください。型にパラメータがある場合（例：`VECTOR(1536)`）、[パラメータ化された型](/docs/ja/mysql-8.4/0.0.5/type-operations#parameterized-types)を参照してください。
ステップ5：ビルド構成を更新する
`CMakeLists.txt`を編集して、拡張機能をVEBファイルとしてビルドします。
```cmake theme={null}
cmake_minimum_required(VERSION 3.18)
project(my_extension)
# Find VillageSQL Extension Framework
find_package(VillageSQLExtensionFramework QUIET)
# The framework detects build flags via 4 methods (in order):
# 1. Explicit MYSQL_INCLUDE_FLAGS/MYSQL_CXXFLAGS
# 2. VillageSQL_BUILD_DIR (reads CMakeCache.txt from VillageSQL build)
# 3. VSQL_BASE_DIR (uses mysql_config)
# 4. Default - mysql_config from PATH
# Build shared library with your source files
add_library(extension SHARED
src/extension.cc
src/my_functions.cc
)
# Create VEB archive
VEF_CREATE_VEB(
NAME my_extension
LIBRARY_TARGET extension
MANIFEST ${CMAKE_CURRENT_SOURCE_DIR}/manifest.json
)
# Install VEB to VillageSQL extensions directory
install(FILES ${VEB_OUTPUT} DESTINATION ${INSTALL_DIR})
```
**構成に関する注意:**
* `VillageSQLExtensionFramework`は、拡張機能をビルドするためのCMakeヘルパーを提供します。
* `VEF_CREATE_VEB()`は、ライブラリ、マニフェスト、およびメタデータを`.veb`アーカイブにパッケージ化します。
* フレームワークは、MySQL/VillageSQLビルドフラグを自動的に検出します。
* ライブラリターゲット名は通常`extension`です（任意の名前を使用できます）。
* VEB名は、`manifest.json`の名前と一致する必要があります。
* デフォルトでは、拡張機能は安定したABIヘッダーに対してビルドされます。不安定な開発ヘッダーに対してビルドするには、`-DVSQL_USE_DEV_ABI=ON`を設定します。
***
## ステップ6：ビルドディレクトリを作成する
別のビルドディレクトリを作成します。
```bash theme={null}
mkdir build
cd build
```
## ステップ7：CMakeとMakeでビルドする
拡張機能を構成してビルドします。
```bash theme={null}
# Configure the build
cmake ..
# Or, if building against VillageSQL source:
cmake .. -DVillageSQL_BUILD_DIR=/path/to/villagesql/build
# Or, to build against the unstable dev ABI headers:
cmake .. -DVSQL_USE_DEV_ABI=ON
# Build the extension
make
```
これにより、次のものが作成されます。
* コンパイルされた共有ライブラリ（`.so`ファイル）
* VEBパッケージ（`.veb`ファイル）- マニフェストとライブラリを含むtarアーカイブ
### ビルドを確認する
VEBファイルの内容を確認します。
```bash theme={null}
make show_veb
```
次のものが表示されるはずです。
```
manifest.json
lib/myext.so
```
## ステップ8：インストールしてテストする
### オプションA：VillageSQL拡張ディレクトリにインストールする
インストールターゲットを使用して、VEBをVillageSQLインストールにコピーします。
```bash theme={null}
make install
```
これにより、`.veb`ファイルが、`VillageSQL_VEB_INSTALL_DIR`で構成されたディレクトリにコピーされます。
### オプションB：手動インストール
VEBファイルを手動でコピーします。
```bash theme={null}
# Find the VEF directory
mysql -u root -p -e "SHOW VARIABLES LIKE 'veb_dir';"
# Copy the VEB file
sudo cp my-awesome-extension.veb /path/to/veb_dir/
```
### 拡張機能をテストする
1. **VillageSQLに接続します。**
```bash theme={null}
mysql -u root -p
```
2. **拡張機能をインストールします。**
```sql theme={null}
INSTALL EXTENSION my_awesome_extension;
```
3. **インストールを確認します。**
```sql theme={null}
SELECT * FROM INFORMATION_SCHEMA.EXTENSIONS;
```
4. **関数をテストします。**
```sql theme={null}
SELECT my_reverse('Hello, World!');
-- Output: !dlroW ,olleH
SELECT count_vowels('VillageSQL');
-- Output: 3
```
## テストの作成
拡張機能が正しく機能することを確認するために、テストファイルを追加します。
1. **`mysql-test/t/`にテストファイルを作成します。**
```sql theme={null}
-- mysql-test/t/my_basic.test
SELECT my_reverse('abc');
SELECT my_reverse('');
SELECT my_reverse(NULL);
```
2. **期待される結果を生成します。**
```bash theme={null}
cd /path/to/villagesql/build/mysql-test
perl mysql-test-run.pl --suite=/path/to/your/extension/mysql-test --record
```
3. **テストを実行します。**
```bash theme={null}
perl mysql-test-run.pl --suite=/path/to/your/extension/mysql-test
```
## トラブルシューティング
### 拡張機能がロードされない
エラーログを確認し、VEBの内容を確認します。
```bash theme={null}
make show_veb
tail -f /var/log/mysql/error.log
```
### 関数が見つからない
インストールと登録を確認します。
```sql theme={null}
SELECT * FROM INFORMATION_SCHEMA.EXTENSIONS;
```
### ビルドエラー
```bash theme={null}
# Verify mysql_config is available
which mysql_config
mysql_config --version
# Check compiler version
gcc --version # or clang --version
# Verify CMake version (3.18+ required)
cmake --version
```
## 拡張機能の例
既存のVillageSQL拡張機能から学習します。
複素数データ型の実装
拡張機能を作成するための最小限のテンプレート
## 次のステップ
拡張機能をインストールおよび管理する方法を学びます。
引数と結果の型、集約、システム変数、およびテスト
ライフサイクル、キャッシュ、パフォーマンス、およびセキュリティモデル
VillageSQLをソースコードからビルドします。
## リソース
* [VillageSQL拡張テンプレート](https://github.com/villagesql/vsql-extension-template)
* [MySQL UDF APIドキュメント](https://dev.mysql.com/doc/extending-mysql/8.4/en/adding-loadable-function.html)
* [CMakeドキュメント](https://cmake.org/documentation/)
* [VillageSQLコミュニティDiscord](https://discord.gg/KSr6whd3Fr)