> ## Documentation Index
> Fetch the complete documentation index at: https://villagesql.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# MySQL 用 vsql_duckdb 拡張機能

> vsql_duckdb 拡張機能は MySQL の中で DuckDB を実行するため、クエリがオブジェクトストレージやディスク上の Parquet、CSV、および JSON ファイルを読み取り、行を JSON として返せます。

`vsql_duckdb` はサーバープロセスの中で DuckDB を実行するため、SQL ステートメントがオブジェクトストレージやディスクから Parquet、CSV、および JSON ファイルを直接読み取れます。分析用ファイルは元の場所に置いたまま、エクスポート手順や運用すべき第 2 のエンジンなしに、自分のテーブルと並べてクエリできます。

| | |
| - | - |
| **メンテナー** | VillageSQL |
| **ソースと完全なドキュメント** | [villagesql/vsql-duckdb](https://github.com/villagesql/vsql-duckdb) |
| **ライセンス** | GPL-2.0 |
| **機能** | プレビュー |

> [!WARNING]
>
> この拡張機能は 3 つのプレビュー機能を宣言しているため、サーバーを `--vsql_allow_preview_extensions=ON` で起動する必要があります。また、0.0.6 より新しい VillageSQL サーバーが必要です。

## インストール

`vsql_duckdb` はサーバーに同梱されていないため、まずリポジトリからビルドし、生成された `vsql_duckdb.veb` をシステム変数 `veb_dir` が示すディレクトリにコピーします。その後、インストールします。

```sql theme={null}
INSTALL EXTENSION vsql_duckdb;
```

インストールされたことを確認します。

```sql theme={null}
SELECT EXTENSION_NAME
FROM INFORMATION_SCHEMA.EXTENSIONS
WHERE EXTENSION_NAME = 'vsql_duckdb';
```

```
+----------------+
| EXTENSION_NAME |
+----------------+
| vsql_duckdb    |
+----------------+
```

ビルド手順は[リポジトリ](https://github.com/villagesql/vsql-duckdb)にあります。

## 追加される機能

| 関数 | 戻り値 | 説明 |
| - | - | - |
| `duckdb_query(sql)` | text | DuckDB クエリを実行し、行を JSON 配列として返す |
| `duckdb_scalar(sql)` | text | DuckDB クエリを実行し、最初の行の最初の値を返す |
| `duckdb_status()` | text | DuckDB のバージョン、リンクされているリーダー、および現在の設定を報告する |

| 設定 | デフォルト | 制御内容 |
| - | - | - |
| `vsql_duckdb.allow_local_files` | `OFF` | クエリがサーバー自身のディスク上のファイルを読み取れるかどうか |
| `vsql_duckdb.enable_external_access` | `ON` | クエリがネットワークに到達できるかどうか |
| `vsql_duckdb.s3_endpoint`, `vsql_duckdb.s3_region`, `vsql_duckdb.s3_url_style`, `vsql_duckdb.s3_use_ssl` | `duckdb_status()` を参照 | オブジェクトストレージの場所と、そのアドレス指定方法 |
| `vsql_duckdb.s3_key_id`, `vsql_duckdb.s3_secret_keyring_id`, `vsql_duckdb.s3_secret_keyring_auth_id` | 空 | オブジェクトストレージの認証情報。シークレットは keyring に保持される |
| `vsql_duckdb.memory_limit_mb` | `1024` | 組み込みエンジンのメモリ上限 |
| `vsql_duckdb.threads` | `2` | 使用できるスレッド数 |
| `vsql_duckdb.timeout_ms` | `30000` | 1 つのクエリが実行できる時間 |
| `vsql_duckdb.max_result_bytes` | `1048576` | 返される結果のサイズ上限 |
| `vsql_duckdb.temp_directory` | 空 | クエリがメモリに収まらないときにディスクへ退避する場所。これは `allow_local_files` が有効な間だけ起こる |

`SHOW STATUS LIKE 'vsql_duckdb%'` は 2 つのカウンターを報告します。これらはサーバープロセスの存続期間中、保持されます。

```
+----------------------------+-------+
| Variable_name              | Value |
+----------------------------+-------+
| vsql_duckdb.queries_failed | 0     |
| vsql_duckdb.queries_total  | 0     |
+----------------------------+-------+
```

`queries_total` は、成功したかエラーを発生させたかを問わず、実行された `duckdb_query()` または `duckdb_scalar()` の呼び出しを数えます。空の結果または NULL 値のために `NULL` を返す `duckdb_scalar()` の呼び出しは、成功として数えられます。`sql` 引数自体が `NULL` である呼び出しは、どちらのカウンターも増やさずに `NULL` を返します。`queries_failed` はエラーを発生させた呼び出しだけを数え、`queries_total` に含まれます。

## 例

自身が何であるかを尋ねます。

```sql theme={null}
SELECT duckdb_status() AS status\G
```

```
*************************** 1. row ***************************
status: {
  "duckdb_version": "v1.5.5",
  "readers": ["core_functions", "httpfs", "json", "parquet"],
  "engine_error": "",
  "object_storage_credential": "not configured",
  "s3_endpoint": "",
  "s3_region": "",
  "s3_url_style": "vhost",
  "s3_use_ssl": true,
  "enable_external_access": true,
  "allow_local_files": false,
  "memory_limit_mb": 1024,
  "threads": 2,
  "timeout_ms": 30000,
  "max_result_bytes": 1048576
}
```

ファイルに触れないクエリを実行します。

```sql theme={null}
SELECT duckdb_scalar('SELECT 6 * 7') AS answer;
```

```
+--------+
| answer |
+--------+
| 42     |
+--------+
```

CSV を読み取り、行を JSON として受け取ります。サーバー自身のディスクからの読み取りはデフォルトでオフなので、まず有効にします。

```sql theme={null}
SET GLOBAL vsql_duckdb.allow_local_files = ON;

SELECT duckdb_query(
    'SELECT sku, units * unit_price AS total
     FROM read_csv_auto(''/path/to/sales.csv'')
     ORDER BY total DESC') AS rows_json\G
```

```
*************************** 1. row ***************************
rows_json: [{"sku":"A-100","total":59.97},{"sku":"A-101","total":24.5},{"sku":"A-102","total":21.7}]
```

終わったら再び無効にしてください。無効にするまで有効のままです。

```sql theme={null}
SET GLOBAL vsql_duckdb.allow_local_files = OFF;
```

結果は JSON なので、`JSON_TABLE` を使えば、自分のテーブルと結合できる行に戻せます。

> [!WARNING]
>
> `allow_local_files` はサーバーアカウントが読めるすべてのファイルを開き、`enable_external_access` はデフォルトで有効なので、クエリはネットワークにも到達できます。拡張機能の関数はストアド関数のように権限を付与できないため、ここで SQL を実行できる人は誰でもそれらを呼び出せます。拡張機能をインストールすると、すべてのアカウントが両方のスイッチの範囲に到達できるようになります。オブジェクトストレージのシークレットは keyring にあり、`vsql_duckdb.s3_secret_keyring_id` はその名前を指すだけです。

> [!NOTE]
>
> `SET PERSIST` で書き込んだ設定は再起動後も残りますが、`UNINSTALL EXTENSION` はそれを削除します。アンインストールと再インストールの後は、すべての設定がデフォルトに戻り、再起動しても古い値は戻りません。

## 関連項目

* [拡張機能の管理](https://villagesql.com/docs/ja/extensions/managing.md) — 拡張機能の設定の読み書き方法
* [プレビュー機能](https://villagesql.com/docs/ja/extensions/build/preview-capabilities.md) — プレビューフラグが有効にするものと、それが約束するもの
* [利用可能な拡張機能](https://villagesql.com/docs/ja/extensions/catalog) — 完全なカタログ
* [villagesql/vsql-duckdb](https://github.com/villagesql/vsql-duckdb) — ソース、ビルド手順、および既知の制限事項


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.