> ## 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_cube 拡張機能

> vsql_cube 拡張機能は、最大 100 次元の点とボックスを格納する cube カラム型を、包含、重なり、および距離の関数とともに MySQL に追加します。

複数の数値カラムがひとまとまりで、それらを 1 つの値としてクエリしたいときに `vsql_cube` を使用します。AND 条件を連ねれば、行が範囲内に入るかどうかは判定できますが、距離で行をランク付けすることはできません。`cube` 型はその両方を行います。これは PostgreSQL の `cube` 拡張機能の移植です。PostgreSQL の関数名の多くはそのまま引き継がれています。`cube()` コンストラクタ、演算子、およびそれらのサポート関数 (`cube_contained`、`cube_overlap`、`distance_taxicab`、`distance_chebyshev`) は、以下の名前付き関数になります。

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

## インストール

インストールスクリプト、Docker イメージ、またはリリース tarball で VillageSQL をインストールした場合、`vsql_cube.veb` はすでにサーバーの `lib/veb/` ディレクトリにあります。1 つのステートメントでサーバーにインストールします。

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

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

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

```
+----------------+
| EXTENSION_NAME |
+----------------+
| vsql_cube      |
+----------------+
```

自分でビルドするには、[リポジトリ](https://github.com/villagesql/vsql-cube)のビルド手順に従ってください。

## 追加される機能

### cube 型

カラムを `` `cube`(N) `` として宣言します。`N` は値が持てる最大の次元数で、1 から 100 までです。`cube` は MySQL の予約語なのでバッククォートが必要で、次元数は必須です。

```sql theme={null}
CREATE TABLE sensors (
    id      INT PRIMARY KEY,
    name    VARCHAR(32),
    reading `cube`(3)
);
```

値は座標の文字列として書きます。カラムがそれを解析します。

```sql theme={null}
INSERT INTO sensors VALUES
    (1, 'north', '12.5,40.1,3.0'),
    (2, 'south', '48.0,12.7,9.5'),
    (3, 'east',  '30.2,25.0,6.1');
```

### 関数

| 関数 | 戻り値 | 説明 |
| - | - | - |
| `cube_point_nd(x, y, ...)` | `cube` | 座標から点を作る |
| `cube_box_nd(lower..., upper...)` | `cube` | 下側の角に続けて上側の角を指定してボックスを作る |
| `cube_point(x)`, `cube_box(x, y)` | `cube` | 1 次元の点またはボックスを作る |
| `cube_from_string(s)`, `cube_to_string(c)` | `cube`, string | テキストと `cube` を相互に変換する |
| `cube_dim(c)` | int | 次元数 |
| `cube_coord(c, n)` | real | 座標 `n`。左下の角から数え、次に右上の角を数える。範囲外は NULL |
| `cube_ll_coord(c, n)`, `cube_ur_coord(c, n)` | real | 左下または右上の角の座標 `n` |
| `cube_is_point(c)` | int | 値が点なら 1、ボックスなら 0 |
| `cube_contains(a, b)`, `cube_contained_by(a, b)` | int | 一方の値が他方を囲むかどうか |
| `cube_overlaps(a, b)` | int | 2 つの値が空間を共有するかどうか |
| `cube_distance(a, b)` | real | ユークリッド距離 |
| `cube_taxicab_distance(a, b)` | real | マンハッタン距離 |
| `cube_chebyshev_distance(a, b)` | real | チェビシェフ距離 |
| `cube_union(a, b)`, `cube_inter(a, b)` | `cube` | 両方を含む最小のボックス。それらの交差 |
| `cube_enlarge(c, r, n)` | `cube` | 最初の `n` 次元で値を `r` だけ広げる |
| `cube_subset(c, d1, d2, ...)` | `cube` | 列挙した次元 (1 から数える) からなる新しい値 |
| `cube_add_dim(c, lo, hi, ...)` | `cube` | lo/hi のペアごとに 1 つの次元を追加する |
| `cube_agg(c)` | `cube` | 集約: グループ内のすべての値の外接ボックス |
| `cube_scalar_agg(x)` | `cube` | 集約: 数値カラムの外接範囲 |

## 例

目標の読み取り値に最も近い 2 つのセンサーを見つけ、次に領域内のセンサーを見つけます。

```sql theme={null}
SELECT name, ROUND(cube_distance(reading, cube_point_nd(30, 25, 6)), 2) AS dist
FROM sensors
ORDER BY dist
LIMIT 2;
```

```
+-------+-------+
| name  | dist  |
+-------+-------+
| east  |  0.22 |
| south | 22.08 |
+-------+-------+
```

```sql theme={null}
SELECT name FROM sensors
WHERE cube_contains(cube_box_nd(10, 10, 0, 35, 45, 7), reading) = 1;
```

```
+-------+
| name  |
+-------+
| north |
| east  |
+-------+
```

> [!NOTE]
>
> `cube` 引数はカラムから次元数を得るため、呼び出しが動作するのは、`cube` 引数のいずれかがカラムの値であるか、`cube_union` や `cube_enlarge` のようにカラムの次元数を保つ関数の結果である場合です。`cube_dim(cube_point_nd(1, 2))` のようにそのような引数を持たない呼び出しは、`ERROR 3219 (HY000): Cannot initialize function 'cube_dim': cannot determine
>     type parameters for vsql_cube.cube in argument 1` で失敗します。同じ理由で、`cube_point_nd()` で包むのではなく、素の座標文字列を挿入してください。
>
> `cube_point_nd`、`cube_box_nd`、`cube_subset`、および `cube_add_dim` の各座標引数には、カンマ区切りの文字列も渡せます。リストは端から端へつながります。したがって、`cube_point_nd('1,2,3')` と `cube_point_nd(1, 2, 3)` は同じ点を作ります。
> 座標がカラムにある場合は文字列を渡してください。これは個別の引数では表現できない唯一のケースです。

## 関連項目

* [MySQL での多次元範囲クエリ](https://villagesql.com/docs/en/guides/cube-queries.md) — 包含、距離、および最近傍クエリの詳しい解説
* [拡張機能のインストール](https://villagesql.com/docs/ja/extensions/install.md) — `INSTALL EXTENSION` の仕組みと、サーバーがバンドルを探す場所
* [利用可能な拡張機能](https://villagesql.com/docs/ja/extensions/catalog) — 完全なカタログ
* [villagesql/vsql-cube](https://github.com/villagesql/vsql-cube) — ソース、ビルド手順、および完全な関数リファレンス


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