@simplysm/sd-claude 14.0.88 → 14.0.89

package/claude/references/sd-simplysm14/apis/orm-common/expr.md

@@ -1,113 +1,128 @@
 # @simplysm/orm-common — expr (SQL 표현식 빌더)
 
-dialect 독립 SQL 표현식을 JSON AST(`Expr`)로 만드는 `expr` 객체. `where`/`having`/`search` 콜백에선 비교·논리 함수(`WhereExprUnit` 반환), `select`/`orderBy`/`groupBy` 콜백에선 값·함수·집계(`ExprUnit<T>` 반환)를 쓴다. `ExprInput<T>` = `ExprUnit<T> | T`(리터럴 직접 전달 가능). `ExprUnit.n` 게터는 nullable 을 non-null 타입으로 좁힌다.
-
-## 값 생성
-
-- `expr.val(dataType, value): ExprUnit` — 리터럴 래핑. `dataType` 은 `"string"|"number"|"boolean"|"DateTime"|"DateOnly"|"Time"|"Uuid"|"Bytes"`, `value` 는 그 값(undefined=NULL 허용). UPDATE/UPSERT 쓰기값에 주로 사용.
-- `expr.col(dataType, ...path): ExprUnit` — column 참조 직접 생성(보통은 프록시 사용, 내부용).
-- `expr.raw(dataType)\`SQL ${expr}\`: ExprUnit` — Raw SQL 이스케이프 해치. 태그드 템플릿, 보간값은 자동 파라미터화. ORM 미지원 DB 함수가 필요할 때만.
-- `expr.toExpr(value): Expr` — `ExprInput` → `Expr` AST 변환(내부 헬퍼).
-
-## WHERE — 비교 (WhereExprUnit 반환)
-
-- `expr.eq(source, target)` — 동등(=). **NULL 안전**(MySQL `<=>`, MSSQL/PG `IS NULL OR =`).
-- `expr.gt(source, target)` — 초과(>).
-- `expr.lt(source, target)` — 미만(<).
-- `expr.gte(source, target)` — 이상(>=).
-- `expr.lte(source, target)` — 이하(<=).
-- `expr.between(source, from?, to?)` — 범위(BETWEEN). `from`/`to` undefined 면 해당 방향 무제한(한쪽만 주면 `>=`/`<=`).
-- `expr.null(source)` — IS NULL 검사.
-- `expr.like(source, pattern)` — LIKE 패턴(`%`=0+, `_`=1자, 특수문자 `\` 이스케이프).
-- `expr.regexp(source, pattern)` — 정규식 매칭(구문은 DBMS 의존).
-- `expr.in(source, values)` — IN 값 목록.
-- `expr.inQuery(source, query)` — IN (서브쿼리). `query` 는 단일 column SELECT Queryable(아니면 throw).
-- `expr.exists(query)` — EXISTS 서브쿼리(행 1개 이상이면 true). SELECT 절은 패킷 절약 위해 제거됨.
-
-## WHERE — 논리
-
-- `expr.not(arg: WhereExprUnit)` — 부정(NOT).
-- `expr.and(conditions: WhereExprUnit[])` — AND 결합. 빈 배열 throw.
-- `expr.or(conditions: WhereExprUnit[])` — OR 결합. 빈 배열 throw.
-
-## SELECT — 문자열 (ExprUnit 반환)
-
-- `expr.concat(...args)` — CONCAT(NULL 은 빈 문자열 취급).
-- `expr.left(source, length)` / `expr.right(source, length)` — 좌/우 N자 추출.
-- `expr.trim(source)` — 양쪽 공백 제거.
-- `expr.padStart(source, length, fillString)` — 좌측 패딩(LPAD), 목표 길이까지 `fillString` 반복.
-- `expr.replace(source, from, to)` — 치환.
-- `expr.upper(source)` / `expr.lower(source)` — 대/소문자 변환.
-- `expr.length(source)` — 문자 수(CHAR_LENGTH).
-- `expr.byteLength(source)` — 바이트 길이(UTF-8 CJK 3바이트).
-- `expr.substring(source, start, length?)` — 부분 문자열(1-base 인덱스, length 생략 시 끝까지).
-- `expr.indexOf(source, search)` — 위치(1-base, 없으면 0).
+`expr` 객체로 dialect 독립 SQL 표현식을 JSON AST(`Expr`)로 조립한다. where/having 콜백은 `WhereExprUnit[]` 를, select/orderBy/groupBy/update 콜백은 `ExprUnit<T>` 또는 리터럴을 반환한다. 모든 인자는 `ExprInput<T>`(= `ExprUnit<T> | T`) — 컬럼·중첩 식·리터럴을 섞어 넘길 수 있다.
+
+핵심 래퍼:
+
+- `class ExprUnit<TPrimitive>` — 타입 추적 표현식 래퍼. `dataType: ColumnPrimitiveStr`, `expr: Expr`(AST), `get n` (= 반환 타입에서 `undefined` 제거한 non-null 버전, nullable 컬럼을 비-nullable 로 단언할 때).
+- `class WhereExprUnit` — WHERE 조건 래퍼(`expr: WhereExpr`). 비교/논리 연산이 반환.
+- `type ExprInput<T> = ExprUnit<T> | T` — 표현식 또는 리터럴 입력.
+- `interface SwitchExprBuilder<T>` — `switch()` 가 반환하는 CASE 빌더(`.case(cond, then)` 체이닝 + `.default(value)` 종료).
+- `expr.toExpr(value): Expr` — `ExprInput` 을 `Expr` AST 로 변환(내부용, 직접 AST 다룰 때).
+
+## 값 생성 (val / col / raw)
+
+- `val(dataType, value): ExprUnit` — 리터럴을 ExprUnit 으로. `dataType`=`"string"|"number"|"boolean"|"DateTime"|"DateOnly"|"Time"|"Uuid"|"Bytes"`. `value`=값(undefined 허용 시 nullable 반환). update/insert 값에 타입을 명시할 때.
+- `col(dataType, ...path): ExprUnit` — 컬럼 참조 직접 생성(보통 콜백 프록시가 대신). `path`=alias·컬럼명 분절.
+- `raw(dataType)\`SQL ${val}\`: ExprUnit` — 이스케이프 해치. ORM 미지원 DB 함수를 태그드 템플릿으로. 보간 값은 자동 파라미터화. `dataType`=반환 타입.
+
+```typescript
+expr.val("string", "active")
+expr.raw("string")`JSON_EXTRACT(${u.metadata}, '$.email')`
+```
+
+## WHERE — 비교 (eq / gt / lt / gte / lte / between)
+
+전부 `(source: ExprUnit<T>, target: ExprInput<T>) => WhereExprUnit`(between 제외).
+
+- `eq(source, target)` — `=` (NULL 안전: MySQL `<=>`, MSSQL/PG `IS NULL OR =`).
+- `gt` / `lt` / `gte` / `lte` — `>` / `<` / `>=` / `<=`.
+- `between(source, from?, to?)` — BETWEEN. `from`/`to` undefined 면 그 방향 무제한(`from`만 주면 `>=`, `to`만 주면 `<=`).
+
+## WHERE — NULL / 문자열 / IN / EXISTS
+
+- `null(source): WhereExprUnit` — `IS NULL`.
+- `like(source, pattern)` — `LIKE`(`%`=다수, `_`=단일, `\` 이스케이프). 부분/접두 검색.
+- `regexp(source, pattern)` — 정규식 매칭(구문은 DBMS별 상이).
+- `in(source, values: ExprInput[])` — `IN (값목록)`.
+- `inQuery(source, query: Queryable)` — `IN (SELECT ...)`. 서브쿼리가 단일 컬럼만 SELECT 해야 함(아니면 throw).
+- `exists(query: Queryable)` — `EXISTS (SELECT ...)`. SELECT 절은 제거해 패킷 절약. 상관 서브쿼리로 존재 검사.
+
+```typescript
+db.user().where((u) => [expr.in(u.status, ["active", "pending"]), expr.exists(db.order().where((o) => [expr.eq(o.userId, u.id)]))])
+```
+
+## WHERE — 논리 (not / and / or)
+
+- `not(arg: WhereExprUnit)` — 조건 부정.
+- `and(conditions: WhereExprUnit[])` — AND 결합. 빈 배열이면 throw.
+- `or(conditions: WhereExprUnit[])` — OR 결합. 빈 배열이면 throw.
+
+## SELECT — 문자열
+
+- `concat(...args)` — CONCAT(NULL→빈문자). 반환 `ExprUnit<string>`.
+- `left(source, length)` / `right(source, length)` — 좌/우에서 length 글자.
+- `trim(source)` — 양쪽 공백 제거.
+- `padStart(source, length, fillString)` — LPAD, 대상 길이까지 왼쪽 채움.
+- `replace(source, from, to)` — 문자열 치환.
+- `upper(source)` / `lower(source)` — 대/소문자.
+- `length(source)` — 문자 수(반환 `number`). `byteLength(source)` — 바이트 수(UTF-8 CJK 3B).
+- `substring(source, start, length?)` — 부분 추출(1-기반 인덱스, length 생략 시 끝까지).
+- `indexOf(source, search)` — 위치(1-기반, 없으면 0).
+
+(string 입력류는 `<T extends string|undefined>` 로 nullable 전파.)
 
 ## SELECT — 숫자
 
-- `expr.abs(source)` — 절대값.
-- `expr.round(source, digits: number)` — 반올림(소수 `digits` 자리).
-- `expr.ceil(source)` / `expr.floor(source)` — 올림/내림.
+- `abs(source)` — 절대값. `round(source, digits)` — 반올림(digits 자리). `ceil(source)` — 올림. `floor(source)` — 내림. 모두 nullable 전파.
 
 ## SELECT — 날짜
 
-- `expr.year/month/day(source)` — 연/월/일 추출(`DateTime|DateOnly`).
-- `expr.hour/minute/second(source)` — 시/분/초 추출(`DateTime|Time`).
-- `expr.isoWeek(source)` — ISO 주 번호(월요일 시작, 1~53). `DateOnly`.
-- `expr.isoWeekStartDate(source)` — 해당 주 월요일 날짜. `DateOnly`.
-- `expr.isoYearMonth(source)` — 해당 월 1일. `DateOnly`.
-- `expr.dateDiff(unit: DateUnit, from, to)` — 날짜 차(`to - from`). `unit` = `"year"|"month"|"day"|"hour"|"minute"|"second"`.
-- `expr.dateAdd(unit, source, value)` — 날짜 가감(`value` 음수 허용). 반환 타입은 source 와 동일.
-- `expr.formatDate(source, format: string)` — 포맷 문자열로 변환(규칙 DBMS 의존).
+- `year/month/day(source)` — DateTime|DateOnly 에서 연/월/일(`number`). `hour/minute/second(source)` — DateTime|Time 에서 시/분/초.
+- `isoWeek(source)` — ISO 주번호(1~53). `isoWeekStartDate(source)` — 주의 월요일(`DateOnly`). `isoYearMonth(source)` — 해당 월 1일(`DateOnly`).
+- `dateDiff(unit, from, to)` — 날짜 차(`to - from`). `unit`=`DateUnit`(`"year"|"month"|"day"|"hour"|"minute"|"second"`).
+- `dateAdd(unit, source, value)` — 날짜 더하기(음수 허용, 결과 타입은 source 와 동일).
+- `formatDate(source, format)` — 포맷 문자열(`"%Y-%m-%d"`, 규칙 DBMS별 상이) → `string`.
+
+(nullable source 면 결과도 nullable.)
 
-## SELECT — 조건
+## SELECT — 조건 (coalesce / nullIf / is / switch / if)
 
-- `expr.coalesce(...args)` — 첫 non-null 반환(COALESCE). 마지막 인자가 non-nullable 이면 결과도 non-nullable.
-- `expr.nullIf(source, value)` — `source===value` 면 NULL, 아니면 source.
-- `expr.is(condition: WhereExprUnit): ExprUnit<boolean>` — WHERE 조건을 boolean 값으로 SELECT.
-- `expr.switch<T>()` — CASE WHEN 빌더. `.case(condition, then).case(...).default(value)` 체이닝으로 분기 구성. 타입은 then/default 의 ExprUnit 또는 non-null 리터럴에서 추론(전부 null 이면 throw).
-- `expr.if(condition, then, else_)` — 삼항(IF/IIF). then/else 중 최소 하나 non-null(전부 null throw).
+- `coalesce(...args)` — 첫 non-null(COALESCE). 마지막 인자가 non-nullable 이면 결과도 non-nullable.
+- `nullIf(source, value)` — `source === value` 면 NULL, 아니면 source(빈문자→NULL 정규화 등). 결과 nullable.
+- `is(condition: WhereExprUnit): ExprUnit<boolean>` — WHERE 조건을 boolean 컬럼으로(SELECT 절에서).
+- `switch<T>(): SwitchExprBuilder<T>` — CASE WHEN. `.case(cond, then)` 체이닝 후 `.default(value)` 로 종료. then/default 중 하나는 non-null 이어야 타입 추론(전부 null 이면 throw).
+- `if<T>(condition, then, else_): ExprUnit<T>` — 삼항(IF). then/else 중 하나는 non-null 필요(아니면 throw).
 
-## SELECT — 집계
+```typescript
+db.user().select((u) => ({
+  grade: expr.switch<string>().case(expr.gte(u.score, 90), "A").case(expr.gte(u.score, 80), "B").default("F"),
+  isAdult: expr.is(expr.gte(u.age, 18)),
+}))
+```
 
-집계는 모든 값 NULL/행 없음일 때만 NULL(NULL 행은 무시).
-- `expr.count(arg?, distinct?: boolean)` — COUNT. `arg` 생략 시 전체 행, `distinct:true` 면 중복 제거.
-- `expr.sum(arg)` — 합계(nullable number).
-- `expr.avg(arg)` — 평균(nullable number).
-- `expr.max(arg)` / `expr.min(arg)` — 최대/최소(nullable, 입력 타입 유지).
+## SELECT — 집계 (count / sum / avg / max / min)
 
-## SELECT — 기타
+집계는 행이 없거나 전부 NULL 일 때만 NULL(NULL 행은 무시). count 만 항상 `number`, 나머지는 nullable.
 
-- `expr.greatest(...args)` / `expr.least(...args)` — 인자 중 최대/최소값(GREATEST/LEAST). 인자 중 ExprUnit 없으면 throw.
-- `expr.rowNum(): ExprUnit<number>` — 단순 행 순번(1-base).
-- `expr.random(): ExprUnit<number>` — 0~1 난수(무작위 정렬 등).
-- `expr.cast(source, targetType: DataType): ExprUnit` — 타입 변환(CAST). `targetType` 예: `{ type: "varchar", length: 20 }`.
-- `expr.subquery(dataType, queryable): ExprUnit` — 스칼라 서브쿼리(정확히 1행 1열). `queryable` 은 `getSelectQueryDef()` 를 가진 객체.
+- `count(arg?, distinct?)` — 행 수. `arg` 생략 시 전체, `distinct:true` 면 중복 제거.
+- `sum(arg)` / `avg(arg)` — number 컬럼 합/평균(`number|undefined`).
+- `max(arg)` / `min(arg)` — 임의 타입 최대/최소(`T|undefined`, 타입은 arg 따라감).
 
-## SELECT — Window 함수
+## SELECT — 기타 (greatest / least / rowNum / random / cast / subquery)
 
-`spec: WinSpecInput` = `{ partitionBy?: ExprInput[]; orderBy?: [ExprInput, ("ASC"|"DESC")?][] }`.
-- `expr.rowNumber(spec)` — ROW_NUMBER()(파티션 내 1-base 순번).
-- `expr.rank(spec)` — RANK()(동순위 후 건너뜀: 1,1,3).
-- `expr.denseRank(spec)` — DENSE_RANK()(동순위 후 연속: 1,1,2).
-- `expr.ntile(n: number, spec)` — NTILE(n)(파티션을 n 그룹으로, 1~n).
-- `expr.lag(column, spec, options?)` / `expr.lead(column, spec, options?)` — 이전/다음 행 값. `options` = `{ offset?: number; default?: ExprInput }`(offset 기본 1, default 는 경계값).
-- `expr.firstValue(column, spec)` / `expr.lastValue(column, spec)` — 프레임 첫/마지막 값.
-- `expr.sumOver/avgOver(column, spec)` — window 합/평균(누적합·이동평균).
-- `expr.countOver(spec, column?)` — window 카운트(column 생략 시 전체).
-- `expr.minOver/maxOver(column, spec)` — window 최소/최대.
+- `greatest(...args)` / `least(...args)` — 여러 값 중 최대/최소(인자 중 ExprUnit 1개 이상 필요, 없으면 throw).
+- `rowNum(): ExprUnit<number>` — 행 순번(1-기반). `random(): ExprUnit<number>` — 0~1 난수(무작위 정렬용).
+- `cast(source, targetType: DataType): ExprUnit` — 타입 변환. `targetType`=`{ type: "varchar", length: 20 }` 등. 결과 타입은 targetType 으로 추론, nullable 전파.
+- `subquery(dataType, queryable): ExprUnit` — 스칼라 서브쿼리(1행 1컬럼). SELECT 절에서 상관 집계 등에. 결과 nullable.
 
 ```typescript
-db.order().select((o) => ({
-  ...o,
-  rowNum: expr.rowNumber({ partitionBy: [o.userId], orderBy: [[o.createdAt, "DESC"]] }),
-  runningTotal: expr.sumOver(o.amount, { partitionBy: [o.userId], orderBy: [[o.createdAt, "ASC"]] }),
-}));
+db.user().select((u) => ({ id: u.id, postCount: expr.subquery("number", db.post().where((p) => [expr.eq(p.userId, u.id)]).select(() => ({ c: expr.count() }))) }))
 ```
 
-## 관련 타입 / 클래스
+## SELECT — Window 함수
+
+전부 `spec: { partitionBy?: ExprInput[]; orderBy?: [ExprInput, ("ASC"|"DESC")?][] }` 를 받아 OVER 절 구성.
 
-- `class ExprUnit<T>` — 값 표현식 래퍼. `dataType`/`expr`(AST)/`$infer`(타입). `.n` 게터로 non-null 좁히기.
-- `class WhereExprUnit` — WHERE 절 표현식 래퍼(`expr` AST 만).
-- `type ExprInput<T> = ExprUnit<T> | T`.
-- `interface SwitchExprBuilder<T>` — `expr.switch()` 빌더 인터페이스(`case`/`default`).
+- `rowNumber(spec): ExprUnit<number>` — ROW_NUMBER(파티션 내 1-기반 순번).
+- `rank(spec)` / `denseRank(spec)` — RANK(동순위 후 건너뜀: 1,1,3) / DENSE_RANK(연속: 1,1,2).
+- `ntile(n, spec)` — NTILE, 파티션을 n 그룹으로(1~n).
+- `lag(column, spec, options?)` / `lead(column, spec, options?)` — 이전/다음 행 값. `options.offset`(기본 1), `options.default`(없을 때 기본값). 결과 nullable.
+- `firstValue(column, spec)` / `lastValue(column, spec)` — 프레임 첫/마지막 값(nullable).
+- `sumOver(column, spec)` / `avgOver(column, spec)` — 윈도우 합/평균(누적합·이동평균).
+- `countOver(spec, column?)` — 윈도우 행 수(`column` 생략 시 전체).
+- `minOver(column, spec)` / `maxOver(column, spec)` — 윈도우 최소/최대(nullable).
+
+```typescript
+db.order().select((o) => ({ ...o, runningTotal: expr.sumOver(o.amount, { partitionBy: [o.userId], orderBy: [[o.createdAt, "ASC"]] }) }))
+```

package/claude/references/sd-simplysm14/apis/orm-common/queryable.md

@@ -1,111 +1,145 @@
-# @simplysm/orm-common — Queryable (쿼리 작성)
+# @simplysm/orm-common — Queryable (쿼리 작성·실행 · 프로시저 · 검색)
 
-`db.user()` 등 등록된 팩토리 호출로 받는 체이닝 쿼리 빌더. 옵션·필터·조인을 immutable 체이닝으로 쌓은 뒤 종결 메서드로 실행한다. 콜백 인자 `columns`/`u` 등은 `QueryableRecord`(column → `ExprUnit` 프록시)이며, 표현식은 [expr.md](./expr.md) 로 만든다.
+`db.user()` 처럼 컨텍스트 멤버를 호출하면 `Queryable<TData, TFrom>` 를 받는다. immutable 체이닝으로 옵션·필터·조인·그룹을 쌓고, 종단 메서드(execute/single/count/insert/...)로 실행한다. where/select/orderBy 콜백 안에서는 [expr.md](./expr.md) 의 `expr` 로 표현식을 만든다. 프로시저는 `Executable`, 텍스트 검색 구문은 `parseSearchQuery` 가 처리한다.
 
-`Queryable<TData, TFrom>` — `TData` 결과 데이터 타입, `TFrom` 소스 TableBuilder(CUD 연산은 TableBuilder 기반에서만 가능, View/서브쿼리는 `never`).
+`Queryable<TData, TFrom>`: `TData`=결과 행 타입(컬럼+조인). `TFrom`=소스 TableBuilder(CUD 가능 여부). select/groupBy/join 등으로 컬럼 구조가 바뀌면 `TFrom` 이 `never` 가 되어 CUD 불가.
 
-## 옵션 (SELECT 컬럼 / DISTINCT / LOCK)
+## 옵션 (select / distinct / lock)
 
-- `select(fn: (cols) => R): Queryable<...>` — SELECT column 재지정. `fn` 은 원본 column 프록시를 받아 `{별칭: ExprUnit | 리터럴 | 중첩객체}` 반환. CUD 소스성 상실(`TFrom=never`).
-- `distinct(): Queryable` — DISTINCT 적용. 이후 `count()` 직접 호출 불가(`wrap()` 필요).
-- `lock(): Queryable` — FOR UPDATE 행 잠금. 트랜잭션 내 배타 잠금이 필요할 때.
+- `select(fn: (cols) => R): Queryable<...>` — 출력 컬럼 재정의. `fn` 은 원본 컬럼(`QueryableRecord`)을 받아 새 구조(ExprUnit·리터럴·중첩 객체) 반환. raw 리터럴은 자동 ExprUnit 래핑. 이후 CUD 불가.
+- `distinct(): Queryable` — DISTINCT 적용. count() 전이면 `wrap()` 필요.
+- `lock(): Queryable` — FOR UPDATE 행 잠금. 트랜잭션 내 배타 잠금 획득용. `TFrom` 유지.
 
-## 행 제한 (TOP / LIMIT)
+```typescript
+db.user().select((u) => ({ userName: u.name, upper: expr.upper(u.email) }))
+```
+
+## 행 제한 (top / limit)
 
-- `top(count: number): Queryable` — 상위 N행. ORDER BY 없이도 사용 가능.
-- `limit(skip: number, take: number): Queryable` — 페이지네이션(OFFSET `skip`, LIMIT `take`). **ORDER BY 선행 필수**(없으면 throw).
+- `top(count: number): Queryable` — 상위 N 행(ORDER BY 없이도 가능). first()/exists() 가 내부적으로 `top(1)` 사용.
+- `limit(skip, take): Queryable` — OFFSET/LIMIT 페이지네이션. `skip`=건너뛸 수, `take`=가져올 수. **ORDER BY 선행 필수**, 없으면 throw.
 
-## 정렬 (ORDER BY)
+## 정렬 (orderBy)
 
-- `orderBy(fnOrKey, orderBy?: "ASC"|"DESC"): Queryable` — 정렬 조건 추가(여러 번 호출 시 순서대로 누적).
-  - `fnOrKey` — 정렬 column 을 반환하는 함수 `(cols) => ExprUnit`, 또는 체인 경로 문자열(`"id"`, `"user.name"` — `obj.getChainValue` 로 해석. 동적 정렬 루프용).
-  - `orderBy` — 방향. 기본 ASC.
+- `orderBy(fnOrKey, orderBy?): Queryable` — 정렬 조건 추가(여러 번 호출 시 순서 누적). `fnOrKey`=컬럼 반환 함수 또는 체인 경로 문자열(`"user.name"`, 동적 정렬용 `obj.getChainValue`). `orderBy`=`"ASC"|"DESC"`, 기본 ASC.
+
+```typescript
+db.user().orderBy((u) => u.name).orderBy((u) => u.age, "DESC").orderBy("id", "DESC")
+```
 
-## 검색 (WHERE / search)
+## 필터 (where / search)
 
-- `where(predicate: (cols) => WhereExprUnit[]): Queryable` — WHERE 조건 추가. 배열 내부는 AND, 여러 번 호출도 AND 누적. 조건은 `expr.eq` 등으로 생성.
-- `search(fn: (cols) => ExprUnit<string|undefined>[], searchText: string): Queryable` — 다중 column 텍스트 검색. `fn` 은 검색 대상 column 들, `searchText` 는 검색 문법 문자열(공백=OR, `+`=필수, `-`=제외, `"..."`=구문, `*`=와일드카드). 빈 문자열이면 변화 없이 self 반환. 내부적으로 `lower(col) LIKE pattern` 조합을 AND/OR 로 조립. (문법 상세: README 검색 파서)
+- `where(predicate: (cols) => WhereExprUnit[]): Queryable` — WHERE 조건 추가. 배열 내 여러 조건·여러 번 호출 모두 AND 결합.
+- `search(fn: (cols) => ExprUnit<string|undefined>[], searchText): Queryable` — 텍스트 검색. `fn`=검색 대상 컬럼들. `searchText` 를 `parseSearchQuery` 로 파싱해 컬럼별 `LIKE lower(...)` 조건 생성(OR 묶음 + 필수 AND + 제외 NOT). `searchText` 가 공백이면 self 반환(조건 무추가).
 
 ```typescript
-db.user().where((u) => [expr.eq(u.isActive, true)]).search((u) => [u.name, u.email], "John -withdrawn");
+db.user().where((u) => [expr.eq(u.isActive, true)]).search((u) => [u.name, u.email], "John -withdrawn")
 ```
 
-## 그룹 (GROUP BY / HAVING)
+## 그룹 (groupBy / having)
 
-- `groupBy(fn: (cols) => ExprUnit[]): Queryable` — GROUP BY. 이후 `count()` 직접 호출 불가(`wrap()` 필요).
-- `having(predicate: (cols) => WhereExprUnit[]): Queryable` — 그룹 필터(GROUP BY 이후). AND 누적.
+- `groupBy(fn: (cols) => ExprUnit[]): Queryable<TData, never>` — GROUP BY. 이후 CUD 불가. count() 전이면 `wrap()` 필요.
+- `having(predicate: (cols) => WhereExprUnit[]): Queryable<TData, never>` — GROUP BY 이후 필터. 여러 번 호출 시 AND 누적.
 
-## 조인 (JOIN / JOIN SINGLE / INCLUDE)
+```typescript
+db.order()
+  .select((o) => ({ userId: o.userId, total: expr.sum(o.amount) }))
+  .groupBy((o) => [o.userId])
+  .having((o) => [expr.gte(o.total, 10000)])
+```
+
+## 조인 (join / joinSingle / include)
 
-- `join<A, R>(as: A, fn: (qr, cols) => Queryable<R>): Queryable<TData & { [as]?: R[] }>` — 1:N LEFT JOIN, 결과에 **배열**로 추가. `qr` 는 `JoinQueryable`(`.from(table)`/`.select(cols)`/`.union(...)`), `cols` 는 바깥 column. 조인 조건은 반환 Queryable 의 `where` 로.
-- `joinSingle<A, R>(as, fn): Queryable<... & { [as]?: R }>` — N:1/1:1 LEFT JOIN, 결과에 **단일 객체**로 추가.
-- `include(fn: (item) => PathProxy): Queryable` — TableBuilder 의 FK/FKT 관계를 자동 조인. `fn` 은 타입 안전 경로 프록시(`item.user.company` 처럼 관계 필드만 접근 가능, ColumnPrimitive 필드는 접근 불가). 다단계·중복 include 지원. 관계 미정의 시 throw, View 기반 queryable 에선 사용 불가.
+- `join(as, fn): Queryable<TData & { [as]?: R[] }>` — 1:N LEFT JOIN, 결과에 배열로 추가. `as`=속성 이름. `fn=(qr, cols) => qr.from(Table).where(...)` 로 조인 조건 작성(`qr` 은 `JoinQueryable`).
+- `joinSingle(as, fn): Queryable<... & { [as]?: R }>` — N:1/1:1 LEFT JOIN, 단일 객체로 추가. `as` 동일 키면 덮어씀.
+- `include(fn: (item: PathProxy) => PathProxy): Queryable` — 빌더 관계 기반 자동 조인. `fn` 은 PathProxy 로 관계 경로 선택(`(p) => p.user.company` 처럼 중첩 가능, 컬럼 필드는 접근 불가=컴파일 에러). FK→단일, FKTarget→배열(single 이면 단일). 관계 미정의·TableBuilder 아님이면 throw. 같은 경로 중복 호출은 무시.
+
+`JoinQueryable`(join 콜백의 `qr`): `.from(Table)` 조인 대상 지정, `.select(columns)` 커스텀 컬럼, `.union(...queries)` 2개 이상 UNION(미만이면 throw).
 
 ```typescript
-db.post().include((p) => p.user.company);
-db.user().join("posts", (qr, u) => qr.from(Post).where((p) => [expr.eq(p.userId, u.id)]));
+db.post().joinSingle("user", (qr, p) => qr.from(User).where((u) => [expr.eq(u.id, p.userId)]))
+db.user().include((u) => u.company).include((u) => u.posts)
 ```
 
-## 서브쿼리 / UNION / 재귀
+## 서브쿼리·결합 (wrap / union / recursive)
 
-- `wrap(): Queryable<TData, never>` — 현재 쿼리를 서브쿼리로 래핑. `distinct()`/`groupBy()` 후 `count()` 하려면 필수.
-- `static Queryable.union<TData>(...queries): Queryable<TData, never>` — 여러 Queryable UNION(중복 제거). 최소 2개, 미만 시 throw. (`JoinQueryable.union` 도 동일 의미)
-- `recursive(fn: (qr: RecursiveQueryable) => Queryable): Queryable<TData, never>` — 재귀 CTE(WITH RECURSIVE). 계층 데이터 조회. `qr.from(table)`/`qr.select(cols)`/`qr.union(...)` 로 재귀 본문 정의, 재귀 측은 `self` 프로퍼티로 base 를 자기 참조.
+- `wrap(): Queryable<TData, never>` — 현재 쿼리를 서브쿼리로 래핑(새 alias). distinct()/groupBy() 후 count() 하기 전 필수.
+- `static Queryable.union(...queries): Queryable` — 2개 이상 Queryable 을 UNION(중복 제거). 미만이면 throw. 첫 쿼리의 컬럼 구조 기준.
+- `recursive(fn: (cte) => Queryable): Queryable<TData, never>` — 재귀 CTE. base 쿼리(현재)+`fn` 이 정의한 재귀부. `cte` 는 `RecursiveQueryable`: `.from(Table)`/`.select(cols)`/`.union(...)` 제공하며 자기참조용 `self` 속성을 결과에 부여(`e.self[0].id`). 계층 데이터(조직도·트리)에.
 
 ```typescript
-const count = await db.user().select((u) => ({ name: u.name })).distinct().wrap().count();
+db.employee()
+  .where((e) => [expr.null(e.managerId)])
+  .recursive((cte) => cte.from(Employee).where((e) => [expr.eq(e.managerId, e.self[0].id)]))
 ```
 
-## 종결 — SELECT 실행
+## SELECT 실행
 
-- `execute(): Promise<TData[]>` — SELECT 실행, 결과 배열.
+- `execute(): Promise<TData[]>` — SELECT 실행, 행 배열 반환.
 - `single(): Promise<TData | undefined>` — 단일 결과. 2건 이상이면 throw.
-- `first(): Promise<TData | undefined>` — 첫 결과(내부적으로 `top(1)`).
-- `count(fn?: (cols) => ExprUnit): Promise<number>` — 행 수. `fn` 지정 시 해당 column 카운트. `distinct()`/`groupBy()` 직후 호출 시 throw(`wrap()` 먼저).
-- `exists(): Promise<boolean>` — 조건 충족 행 존재 여부(`top(1)` 후 길이 검사).
-- `getSelectQueryDef(): SelectQueryDef` / `getResultMeta(outputColumns?): ResultMeta` — 실행용 def·결과 메타 생성(executor·서브쿼리 합성에서 사용).
+- `first(): Promise<TData | undefined>` — 첫 결과만(`top(1)`).
+- `count(fn?): Promise<number>` — 행 수. `fn` 지정 시 해당 컬럼 COUNT. distinct()/groupBy() 직후 호출하면 throw(`wrap()` 먼저). 결과 없으면 0.
+- `exists(): Promise<boolean>` — 조건 충족 행 존재 여부(`top(1)` 길이).
+- `getSelectQueryDef(): SelectQueryDef` / `getResultMeta(outputColumns?): ResultMeta` — 실행 없이 AST·결과 메타 생성(executor·서브쿼리 내부에서 사용).
 
-## 종결 — INSERT
+## INSERT
 
-각 INSERT 는 `outputColumns` 미전달 시 `void`, 전달 시 해당 column 만 뽑은 레코드를 반환(반환 자동증가 PK 수신 등).
-- `insert(records: TFrom["$inferInsert"][], outputColumns?): Promise<void | Pick<...>[]>` — 다건 INSERT. MSSQL 1000행 제한 때문에 1000건씩 청크 분할. AI column 에 명시값 있으면 자동 overrideIdentity.
-- `insertIfNotExists(record, outputColumns?): Promise<void | Pick<...>>` — 현재 WHERE 조건 매칭이 없을 때만 INSERT.
-- `insertInto(targetTable, outputColumns?): Promise<void | Pick<...>[]>` — 현재 SELECT 결과를 다른 테이블에 INSERT INTO ... SELECT. `targetTable` column 구조가 현재 데이터와 호환되어야 함(타입 매칭).
-- `getInsertQueryDef` / `getInsertIfNotExistsQueryDef` / `getInsertIntoQueryDef` — 각 def 생성기.
+- `insert(records): Promise<void>` / `insert(records, outputColumns): Promise<Pick<...>[]>` — 레코드 배열 삽입. MSSQL 1000행 제한 대응 1000개씩 청크 분할. `outputColumns` 지정 시 삽입된 컬럼 반환. AI 컬럼에 명시값 있으면 overrideIdentity 자동 설정. 빈 배열은 무동작.
+- `insertIfNotExists(record[, outputColumns])` — WHERE 조건에 일치하는 데이터 없을 때만 단건 삽입. 현재 체인의 where 가 존재 검사 조건.
+- `insertInto(targetTable[, outputColumns])` — 현재 SELECT 결과를 다른 테이블에 INSERT INTO ... SELECT. `targetTable` 컬럼이 현재 데이터 형태와 호환(`DataToColumnBuilderRecord`)이어야 함.
 
 ```typescript
-const [inserted] = await db.user().insert([{ name: "Hong" }], ["id"]);
+const [row] = await db.user().insert([{ name: "홍길동" }], ["id"]);
 ```
 
-## 종결 — UPDATE / DELETE
+## UPDATE / DELETE
 
-- `update(recordFwd: (cols) => QueryableWriteRecord, outputColumns?): Promise<void | Pick<...>[]>` — UPDATE. `recordFwd` 는 column → 갱신값(`ExprInput`) 매핑 반환. 기존 값 참조 가능(`expr.mul(p.price, ...)`). WHERE 는 미리 체이닝.
-- `delete(outputColumns?): Promise<void | Pick<...>[]>` — DELETE. WHERE 미리 체이닝.
-- `getUpdateQueryDef` / `getDeleteQueryDef` — def 생성기.
+- `update(recordFwd[, outputColumns])` — `recordFwd=(cols) => ({ col: ExprInput })` 로 갱신값 지정(기존 값 참조 가능: `expr.mul(p.price, 1.1)`). where 로 대상 한정. `outputColumns` 시 갱신 행 반환.
+- `delete([outputColumns])` — where 조건 행 삭제. `outputColumns` 시 삭제된 행 반환.
 
-## 종결 — UPSERT
+```typescript
+await db.user().where((u) => [expr.eq(u.id, 1)]).update((u) => ({ name: expr.val("string", "새이름") }));
+```
+
+## UPSERT
 
-- `upsert(updateFn, insertFn?, outputColumns?): Promise<void | Pick<...>[]>` — WHERE 매칭 있으면 UPDATE, 없으면 INSERT.
-  - `updateFn: (cols) => QueryableWriteRecord` — 갱신/삽입 공통값(insertFn 생략 시 INSERT 도 이 값 사용).
-  - `insertFn?: (updateRecord) => QueryableWriteRecord` — INSERT 전용값(update 결과를 받아 변형). UPDATE/INSERT 데이터가 다를 때.
-  - `outputColumns?` — 반환 column.
-- `getUpsertQueryDef(...)` — def 생성기.
+- `upsert(updateFn[, insertFn][, outputColumns])` — where 일치 시 UPDATE, 없으면 INSERT(MERGE 패턴). `updateFn=(cols) => 갱신값`. `insertFn=(updateRecord) => 삽입값`(생략 시 update 값 재사용, updateRecord 를 받아 추가 컬럼 합치기 가능). `outputColumns` 시 영향 행 반환.
 
 ```typescript
 await db.user()
   .where((u) => [expr.eq(u.email, "t@t.com")])
-  .upsert(() => ({ name: expr.val("string", "x"), email: expr.val("string", "t@t.com") }));
+  .upsert(() => ({ loginCount: expr.val("number", 1) }), (up) => ({ ...up, email: expr.val("string", "t@t.com") }));
 ```
 
-## DDL Helper / 기타
+`get...QueryDef` 류(`getInsertQueryDef`/`getUpdateQueryDef`/`getUpsertQueryDef` 등)는 실행 없이 AST 반환. `switchFk(enabled)` 는 이 테이블 FK 제약 on/off(Table/View 기반 아니면 throw).
+
+## 결과 타입 유틸
+
+- `type QueryableRecord<TData>` — 각 컬럼을 `ExprUnit` 으로, 중첩 관계를 재귀 래핑한 콜백 인자 타입.
+- `type QueryableWriteRecord<TData>` — 컬럼을 `ExprInput`(쓰기) 으로 매핑(update/upsert 입력).
+- `type UnwrapQueryableRecord<R>` — select 결과 구조를 데이터 타입으로 역변환(ExprUnit→값).
+- `type PathProxy<TObject>` — include 의 타입 안전 경로 프록시(관계 필드만 노출).
+- `getMatchedPrimaryKeys(fkCols, targetTable): string[]` — FK 컬럼 수와 대상 PK 를 매칭해 PK 이름 배열 반환. 개수 불일치 시 throw. include 내부 조인 조건 생성에 사용.
+
+## 프로시저 실행 (Executable / executable)
+
+`DbContext.executable(Procedure)` 가 `() => Executable` 팩토리를 반환한다. `Executable<TParams, TReturns>` 는 프로시저 실행 래퍼.
+
+- `executable(db: DbContextBase, builder: ProcedureBuilder): () => Executable` — 팩토리(보통 `DbContext.executable()` 보호 메서드가 호출).
+- `Executable.execute(params): Promise<TReturns[][]>` — 실행. `params` 는 `ProcedureBuilder.params()` 키별 값(리터럴 또는 ExprUnit). 결과는 결과셋 배열의 배열(다중 SELECT 대응).
+- `Executable.getExecProcQueryDef(params?): ExecProcQueryDef` — 실행 AST 생성. 파라미터 미정의 프로시저에 값 전달 시 throw.
+
+```typescript
+const [rows] = await db.getUserById().execute({ userId: 1 });
+```
 
-- `switchFk(enabled: boolean): Promise<void>` — 이 테이블 FK 제약 활성/비활성(트랜잭션 내 가능). TableBuilder/ViewBuilder 기반에서만.
-- `queryable(db, tableOrView, as?): () => Queryable` — Table/View 용 Queryable 팩토리 함수(보통 `DbContext.queryable()` 가 호출). `as` 미지정 시 자동 alias.
-- `getMatchedPrimaryKeys(fkCols, targetTable): string[]` — FK column 배열과 대상 PK 매칭(개수 불일치 시 throw). include 내부 헬퍼.
+## 검색 파서 (parseSearchQuery)
 
-## 관련 타입
+`Queryable.search()` 내부에서 검색 문법 문자열을 SQL LIKE 패턴으로 변환. 직접 호출도 가능.
 
-- `QueryableRecord<TData>` — column → `ExprUnit` 프록시 레코드(콜백 인자 타입).
-- `QueryableWriteRecord<TData>` — column → `ExprInput`(쓰기 콜백 반환 타입).
-- `UnwrapQueryableRecord<R>` — `select` 결과 `ExprUnit` 언래핑 → 데이터 타입.
-- `PathProxy<TObject>` — `include` 경로 수집용 타입 안전 프록시(관계 필드만 노출).
+- `parseSearchQuery(searchText: string): ParsedSearchQuery` — `{ or, must, not }`(각각 LIKE 패턴 배열) 반환.
+  - `or: string[]` — 공백 구분 일반 토큰(OR, 하나 이상 일치).
+  - `must: string[]` — `+토큰` 또는 `"정확한 구문"`(AND, 필수 포함).
+  - `not: string[]` — `-토큰`(NOT, 제외).
+- 문법: `term1 term2`(OR), `+term`(필수), `-term`(제외), `"구문"`(정확·필수), `*`(와일드카드→`%`). 와일드카드 없는 토큰은 `%토큰%`(부분 일치)로 변환. 이스케이프 `\\ \* \% \" \+ \-`. 닫히지 않은 따옴표는 일반 텍스트 처리.
+- `interface ParsedSearchQuery` — 위 `or`/`must`/`not` 세 패턴 배열을 담는 타입.