> ## 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 파일을 바로 읽을 수 있습니다.
분석 파일은 있던 자리에 그대로 두고, 내보내기 단계나 운영해야 할 두 번째 엔진
없이 테이블 옆에서 쿼리합니다.

| | |
| - | - |
| **관리자** | VillageSQL |
| **소스 및 전체 문서** | [villagesql/vsql-duckdb](https://github.com/villagesql/vsql-duckdb) |
| **라이선스** | GPL-2.0 |
| **기능 단계** | 미리 보기 |

> [!WARNING]
>
> 이 확장 기능은 미리 보기 기능 세 가지를 선언하므로, 서버를
> `--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` | 비어 있음 | 객체 스토리지 자격 증명. 비밀 값은 키링에 보관 |
| `vsql_duckdb.memory_limit_mb` | `1024` | 내장 엔진의 메모리 상한 |
| `vsql_duckdb.threads` | `2` | 사용할 수 있는 스레드 수 |
| `vsql_duckdb.timeout_ms` | `30000` | 쿼리 하나가 실행될 수 있는 시간 |
| `vsql_duckdb.max_result_bytes` | `1048576` | 반환되는 결과의 크기 상한 |
| `vsql_duckdb.temp_directory` | 비어 있음 | 쿼리가 메모리를 초과할 때 디스크로 내보내는 위치. `allow_local_files`가 켜져 있을 때만 발생 |

`SHOW STATUS LIKE 'vsql_duckdb%'`는 카운터 두 개를 보고하며, 이 값은 서버
프로세스가 살아 있는 동안 유지됩니다:

```
+----------------------------+-------+
| 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을 실행할 수 있는 사람은 누구나 이 함수를 호출할 수 있습니다. 확장 기능을
> 설치하면 모든 계정이 두 스위치의 범위를 갖게 됩니다. 객체 스토리지 비밀 값은
> 키링에 있으며, `vsql_duckdb.s3_secret_keyring_id`는 그 이름만 가리킵니다.

> [!NOTE]
>
> `SET PERSIST`로 쓴 설정은 재시작 후에도 유지되지만, `UNINSTALL EXTENSION`이
> 이를 삭제합니다. 제거 후 다시 설치하면 모든 설정이 기본값으로 돌아가며, 재시작해도
> 이전 값은 돌아오지 않습니다.

## 참고 항목

* [확장 기능 관리](https://villagesql.com/docs/ko/extensions/managing.md) — 확장 기능 설정을 읽고 쓰는 방법
* [미리 보기 기능](https://villagesql.com/docs/ko/extensions/build/preview-capabilities.md) — 미리 보기 플래그가 켜는 것과 보장하는 것
* [사용 가능한 확장 기능](https://villagesql.com/docs/ko/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.