> ## 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에 추가하며, 포함, 겹침, 거리 함수를 제공합니다.

여러 숫자 열이 한 묶음을 이루고 이를 하나의 값으로 쿼리하고 싶을 때
`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/` 디렉터리에 있습니다. 문 하나로 서버에
설치하세요:

```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 | 두 값이 공간을 공유하는지 여부 |
| `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 쌍마다 차원을 하나씩 추가 |
| `cube_agg(c)` | `cube` | 집계: 그룹의 모든 값을 감싸는 경계 상자 |
| `cube_scalar_agg(x)` | `cube` | 집계: 숫자 열의 경계 범위 |

## 예제

목표 측정값에 가장 가까운 센서 두 개를 찾은 다음, 영역 안에 있는 센서를 찾습니다:

```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/ko/extensions/install.md) — `INSTALL EXTENSION`의 동작 방식과 서버가 번들을 찾는 위치
* [사용 가능한 확장 기능](https://villagesql.com/docs/ko/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.