```
인자 및 결과 타입
VDF 매개변수 및 결과는 타입 안전 인자 및 결과 타입으로 전달됩니다.
프레임워크는 함수 시그니처에서 이를 감지하고 자동으로 적응합니다 —
`make_func` 등록 구문은 변경되지 않습니다.
**인자 타입:** `IntArg`, `RealArg`, `StringArg`, `CustomArg` — 각각
`is_null()` 및 `value()`를 제공합니다. 매개변수화된 사용자 정의 타입의 경우,
`CustomArgWith`는 캐시된 구문 분석된 매개변수 구조체를 반환하는 `params()`
액세서를 추가합니다(참조: [매개변수화된 타입](/docs/ko/mysql-8.4/0.0.5/type-operations#parameterized-types)).
**결과 타입:** `IntResult`, `RealResult`, `StringResult`, `CustomResult`
— 각각 `set_null()`, `warning(msg)`, `error(msg)`를 제공합니다. 스칼라
결과는 추가로 `set(value)`를 제공합니다. 버퍼 결과는 `buffer()` 및
`set_length(len)`을 제공합니다. `StringResult`는 추가로
`set(std::string_view)`를 제공하여, 뷰에서 최대 `buffer().size()` 바이트를
복사하고 길이를 한 번에 설정합니다. 매개변수화된 사용자 정의 타입의 경우,
`CustomResultWith
`는 `params()` 액세서를 추가합니다.
**스팬 타입:** 바이트 기반 인자 및 결과 타입의 `value()` 및 `buffer()`는
`vsql::Span`를 반환합니다 — `data()`, `size()`, `empty()`,
`begin()`/`end()`, `operator[]`를 갖는, 연속된 `T` 구간에 대한 소유하지 않는
뷰입니다. C++20에서는 `std::span`의 별칭이며, C++17에서는 이 SDK가
최소한의 호환 구현을 제공하므로 동일한 코드가 두 표준에서 컴파일됩니다.
``를 통해 사용할 수 있습니다.
`warning(msg)`는 행에 대해 SQL NULL을 반환하고 SQL 경고를 추가합니다. 엄격 모드(`STRICT_TRANS_TABLES`)에서는 MySQL이 INSERT/UPDATE에서 이를 문장 오류로 승격시키므로, 엄격 컨텍스트에서는 `error(msg)`처럼 동작합니다. 인코딩 함수의 구문 분석 불가능한 문자열과 같은 복구 가능한 잘못된 입력에 사용합니다. 손상된 저장 데이터 또는 계속 실행이 안전하지 않은 조건에는 `error(msg)`를 사용합니다. 두 메시지 모두 필요한 경우 서버의 내부 오류 버퍼에 맞게 잘립니다.
**스칼라 예제** — 두 정수를 더합니다:
```cpp theme={null}
using namespace vsql;
void add_impl(IntArg a, IntArg b, IntResult out) {
if (a.is_null() || b.is_null()) { out.set_null(); return; }
out.set(a.value() + b.value());
}
// Registration is unchanged:
make_func<&add_impl>("add").returns(INT).param(INT).param(INT).build();
```
**이진 예제** — 사용자 정의 타입 버퍼를 제자리에서 변환합니다:
```cpp theme={null}
using namespace vsql;
void rot13_impl(CustomArg in, CustomResult out) {
if (in.is_null()) { out.set_null(); return; }
auto src = in.value(); // vsql::Span
auto dst = out.buffer(); // vsql::Span
for (size_t i = 0; i < src.size(); i++) { dst[i] = transform(src[i]); }
out.set_length(src.size());
}
```
`StringResult` 및 `CustomResult`의 경우, `buffer()`에 쓴 다음 작성된 바이트
수와 함께 `set_length()`를 호출합니다. `buffer().size()`는 최대 용량입니다.
사용자 정의 타입을 반환하는 VDF(`returns(CUSTOM(MYTYPE))`)의 경우, 서버는
결과 버퍼를 해석된 반환 타입의 `persisted_length`에 맞춰 자동으로 크기
조정합니다 — 확장 작성자는 이 경우 함수 빌더에 `.buffer_size(...)`를 선언할
필요가 없습니다. `prerun`이 버퍼를 더 크게 늘리면 그 큰 크기가 유지됩니다.
예를 들어 이 덕분에 `SVECTOR::from_string('[…1024 floats…]')`이 결과 버퍼
공간이 부족해지는 일 없이 넓은 벡터를 인코딩할 수 있습니다.
동일한 확장 내에서 함수 간에 다른 스타일을 사용할 수 있습니다 — 각 함수의
스타일은 자체 시그니처에 따라 결정됩니다.
집계 VDF
집계 VDF는 각 `GROUP BY` 그룹 내에서 여러 행에 걸쳐 상태를 누적하고 그룹당 단일
결과를 반환합니다. SQL `SUM` 또는 `COUNT`와 유사합니다. 등록하려면
`make_aggregate_func("name")`을 사용합니다. State 타입은
그룹별 누적 버퍼입니다. `prerun` 및 `postrun`은 이를 할당하고 삭제하기 위해
자동으로 생성됩니다.
결과 함수는 `void(const State&, ResultType)` 시그니처를 가져야 하며,
`ResultType`은 `IntResult`, `RealResult`, `StringResult`, `CustomResult`,
또는 `CustomResultWith` 중 하나입니다. `out.set(value)`를 호출하여 값을
반환하거나 `out.set_null()`을 호출하여 SQL NULL을 반환합니다.
`.clear<>()` 및 `.accumulate<>()`가 모두 필요합니다. 빌더는 이를 컴파일
타임에(`build()`를 통해) 강제하고, 서버는 `INSTALL EXTENSION` 시점에 다시
검증합니다 — `clear`는 상태를 재설정하고, `accumulate`는 행을 결합하며, 결과
함수는 최종 상태를 읽습니다.
```cpp theme={null}
#include
#include
using namespace vsql;
// State type: nullopt means no non-NULL rows seen yet.
using SumState = std::optional;
void my_clear(SumState &s) { s = std::nullopt; }
void my_acc(SumState &s, IntArg v) {
if (!v.is_null()) s = s.value_or(0) + v.value();
}
void my_result(const SumState &s, IntResult out) {
if (!s.has_value()) { out.set_null(); return; }
out.set(s.value());
}
// Registration:
// make_aggregate_func("my_sum")
// .returns(INT)
// .param(INT)
// .clear<&my_clear>()
// .accumulate<&my_acc>()
// .build()
```
빌더 메서드 작동 방식:
* `make_aggregate_func()`은 `prerun` 및 `postrun`을 자동 생성합니다(`State`를 값 초기화하고 삭제합니다).
* `.clear<&fn>()`은 사용자의 `void(State&)` 재설정 함수를 등록합니다.
* `.accumulate<&fn>()`은 사용자의 `void(State&, TypedArgs...)` 결합 함수를 등록합니다. `TypedArgs`는 함수 시그니처에서 추론됩니다(`IntArg`, `StringArg` 등).
* 결과 타입(`IntResult`, `RealResult` 등)은 결과 함수 시그니처에서 추론됩니다.
NULL을 절대 반환하지 않는 카운터의 경우, 단순한 상태 타입을 사용합니다:
```cpp theme={null}
using CountState = long long;
void count_clear(CountState &s) { s = 0; }
void count_acc(CountState &s, IntArg v) { if (!v.is_null()) s++; }
void count_result(const CountState &s, IntResult out) { out.set(s); }
```
`StringResult` 집계 VDF는 텍스트를 반환합니다: 결과는 `utf8mb4_bin` 문자
집합 및 콜레이션을 보고하므로, 클라이언트는 이를 16진수가 아닌 문자로 표시합니다
— 스칼라 VDF STRING 경로와 동일합니다. 또한 `.max_result_length(n)`을 동일한
방식으로 존중하여, 구체화된 집계 결과(`GROUP BY`/`DISTINCT` 임시 테이블,
`CREATE TABLE ... SELECT`, 또는 UNION)의 크기를 조정하여 인자 너비에서
잘리지 않도록 합니다. 크기 조정 규칙 및 상한선은
[사용자 정의 버퍼 크기](/docs/ko/mysql-8.4/0.0.5/create#custom-buffer-sizes)를
참조하세요.
문장별 상태 (Prerun 및 Postrun)
일부 VDF는 단일 쿼리가 처리하는 모든 행에 걸친 상태를 필요로 합니다 — 호출
카운터, 캐시된 결과, 열린 리소스. **prerun** 훅에서 할당하고, VDF 본문에서
액세스하고, **postrun** 훅에서 해제합니다. 두 훅은 문장당 한 번 실행되며,
VDF 본문은 행당 한 번 실행됩니다.
`.prerun<&Hook>()` 및 `.postrun<&Hook>()`으로 등록합니다. 필수 시그니처는
다음과 같습니다:
| 훅 | 필수 시그니처 |
| ------- | -------------------------------------------- |
| Prerun | `void(vsql::PrerunArgs, vsql::PrerunResult)` |
| Postrun | `void(vsql::PostrunArgs)` |
`PrerunResult::set_user_data(void*)`를 사용하여 상태를 저장하고,
`PostrunArgs::delete_state()`를 사용하여 이를 해제합니다. `prerun`이
`set_user_data(new T{})`를 호출하면, `postrun`은 **반드시**
`delete_state()`를 호출해야 합니다 — SDK는 자동 해제하지 않습니다.
`PrerunArgs::type_at(i)`는 행을 읽기 전에 각 인자의 선언된 SQL
타입을 노출합니다. 반환된 `PrerunArgType`의 조건식 `is_int()`, `is_real()`,
`is_str()`, `is_custom()`은 열 타입을 반영합니다. 이를 `prerun`에서 인자
타입을 검증하거나 `PrerunResult::request_buffer_size(n)`을 호출하여 결과
버퍼 크기를 조정하는 데 사용합니다.
```cpp theme={null}
#include
using namespace vsql;
struct CallCounter { long long n = 0; };
void ba_call_index_prerun(PrerunArgs, PrerunResult out) {
out.set_user_data(new CallCounter{});
}
void ba_call_index(CallCounter &state, IntResult out) {
state.n++;
out.set(state.n);
}
void ba_call_index_postrun(PostrunArgs args) {
args.delete_state();
}
// Registration:
// make_func<&ba_call_index>("ba_call_index")
// .returns(INT).no_params()
// .prerun<&ba_call_index_prerun>()
// .postrun<&ba_call_index_postrun>()
// .build()
```
## 가변 인자 VDF
**가변 인자** VDF는 임의의 SQL 타입의 임의 개수의 인자를 수용합니다. func
빌더에 `.varargs()`로 선언하며, 이는 `.no_params()` 및 `.param(TYPE)`과 상호
배타적입니다. 본문은 일반적인 고정 인자 타입 대신 `vsql::VarArgs` 인자를
받습니다.
가변 인자 등록은 VEF 프로토콜 3을 필요로 합니다. 이전 서버는 설치 시 확장을
거부합니다.
프레임워크는 가변 인자 VDF의 인자 개수 또는 타입을 검증할 수 없습니다. 모든
가변 인자 등록은 잘못된 입력에 `PrerunResult::error()`를 호출하거나 결과
버퍼 크기를 조정하기 위해 `PrerunResult::request_buffer_size(n)`을 호출하는
prerun 훅과 짝을 이루어야 합니다.
범위-기반 for 루프로 인자를 반복합니다. 각 `AnyArg` 요소는 값을 읽기 전에
타입 검사를 요구합니다:
| 조건식 | 액세서 | 반환 타입 |
| ------------- | ------------- | --------------------------------- |
| `is_int()` | `as_int()` | `long long` |
| `is_real()` | `as_real()` | `double` |
| `is_str()` | `as_str()` | `std::string_view` |
| `is_custom()` | `as_custom()` | `vsql::Span` |
액세서를 사용하기 전에 `is_null()`을 확인하세요 — 네 가지 모두 NULL 인자에서 정의되지 않습니다.
```cpp theme={null}
#include
#include
using namespace vsql;
constexpr size_t kBytearrayLen = 4;
void ba_concat_all_prerun(PrerunArgs args, PrerunResult out) {
if (args.size() == 0) {
out.error("ba_concat_all requires at least one argument");
return;
}
for (size_t i = 0; i < args.size(); i++) {
auto t = args.type_at(i);
if (!t.is_custom() && !t.is_str()) {
out.error("ba_concat_all: argument " + std::to_string(i) +
" must be BYTEARRAY");
return;
}
}
out.request_buffer_size(args.size() * kBytearrayLen);
}
void ba_concat_all(VarArgs args, StringResult out) {
auto dst = out.buffer();
size_t off = 0;
for (auto a : args) {
if (a.is_null() || !a.is_custom()) { out.set_null(); return; }
auto bytes = a.as_custom();
std::memcpy(dst.data() + off, bytes.data(), bytes.size());
off += bytes.size();
}
out.set_length(off);
}
// Registration:
// make_func<&ba_concat_all>("ba_concat_all")
// .returns(STRING).varargs()
// .prerun<&ba_concat_all_prerun>()
// .build()
```
## VEF\_GENERATE\_REGISTRATION
`VEF_GENERATE_REGISTRATION`은 확장 등록을 수행하지만 `extern "C"` 엔트리
포인트를 정의하지 않는 내부 `_vef_do_register()` 헬퍼를 생성합니다.
`vef_register` 동작을 사용자 정의해야 할 때 사용합니다 — 예를 들어 테스트
빌드에서 등록 후 디스크립터를 패치하기 위해서입니다. 일반 확장의 경우 대신
`VEF_GENERATE_ENTRY_POINTS`를 사용합니다.
```cpp theme={null}
VEF_GENERATE_REGISTRATION(
make_extension()
.func(make_func<&my_impl>("my_func").returns(INT).build()))
// Then define your own extern "C" vef_register/vef_unregister that call
// _vef_do_register() and optionally modify the result.
```
## 사용자 정의 타입 연산
전체 타입 연산 빌더 참조 — 인코딩, 디코딩, 비교, 해시, 내장 기본값, 매개변수화된 타입 — 는 [타입 연산](/docs/ko/mysql-8.4/0.0.5/type-operations)을 참조하세요.
## 미리보기 기능
다음 VEF 기능은 선택적으로 활성화하는 미리보기 헤더로 사용할 수 있습니다. ABI 및 API는 여전히 활발히 개발 중입니다. 전체 참조는 [미리보기 기능](/docs/ko/mysql-8.4/0.0.5/preview-capabilities)을 참조하세요.
* **확장 시스템 변수** — [미리보기 기능 → 시스템 변수](/docs/ko/mysql-8.4/0.0.5/preview-capabilities#system-variables)
* **확장 상태 변수** — [미리보기 기능 → 상태 변수](/docs/ko/mysql-8.4/0.0.5/preview-capabilities#status-variables)
* **키링 액세스** — [미리보기 기능 → 키링 액세스](/docs/ko/mysql-8.4/0.0.5/preview-capabilities#keyring-access)
* **컬럼 저장** — [미리보기 기능 → 컬럼 저장](/docs/ko/mysql-8.4/0.0.5/preview-capabilities#column-storage)
## 확장 등록 메타데이터 검사
`INFORMATION_SCHEMA.EXTENSION_REGISTRATION`은 로드된 각 확장의 인메모리 VEF
등록 구조체를 JSON 문서로 노출합니다. `INSTALL EXTENSION` 후 서버가 확장의
함수, 타입, 시스템 변수를 올바르게 해석했는지 확인하는 데 사용합니다.
```sql theme={null}
SELECT EXTENSION_NAME, NEGOTIATED_PROTOCOL, REGISTRATION_JSON
FROM INFORMATION_SCHEMA.EXTENSION_REGISTRATION
WHERE EXTENSION_NAME = 'my_ext';
```
| 열 | 타입 | 설명 |
| --------------------- | ----------------- | ----------------------------------------------------------------- |
| `EXTENSION_NAME` | `VARCHAR(64)` | 설치된 확장의 이름입니다. |
| `NEGOTIATED_PROTOCOL` | `BIGINT UNSIGNED` | 확장과 서버 간에 협상된 VEF 프로토콜 버전입니다. |
| `REGISTRATION_JSON` | `TEXT` | `funcs` 및 `types` 배열을 포함하는 `vef_registration_t` 구조체의 JSON 직렬화입니다. |
## 참고 자료
* [C++로 확장 만들기](/docs/ko/mysql-8.4/0.0.5/create) — 종단간 빌드 단계, CMake 설정 및 설치
* [C++ 테스트](/docs/ko/mysql-8.4/0.0.5/testing) — 로컬 개발 서버, MTR 및 실패 디버깅
* [타입 연산](/docs/ko/mysql-8.4/0.0.5/type-operations) — 인코딩, 디코딩, 비교, 해시, 매개변수화된 타입
* [C++ API 참조](/docs/ko/mysql-8.4/0.0.5/extension-api-reference) — VDF 계약, null 처리 및 버퍼 크기 조정
* [확장 아키텍처](/docs/ko/mysql-8.4/0.0.5/architecture) — 라이프사이클, Victionary 캐싱, 성능 패턴 및 보안 모델