@simplysm/sd-claude 14.0.98 → 14.0.99

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

@@ -1,142 +1,186 @@
-# @simplysm/orm-common — Queryable (쿼리 작성·실행 · 프로시저 · 검색)
+# @simplysm/orm-common — queryable
 
-`db.user()` 처럼 컨텍스트 멤버를 호출하면 `Queryable<TData, TFrom>` 를 받는다. immutable 체이닝으로 옵션·필터·조인·그룹을 쌓고, 종단 메서드(`execute`/`single`/`count`/`insert`/...)로 실행한다. where/select/orderBy 콜백 안에서는 [expr.md](./expr.md) 의 `expr` 로 표현식을 만든다. 프로시저는 `Executable`, 텍스트 검색 구문은 `parseSearchQuery` 가 처리한다. 표준 조회 흐름·안티패턴은 orm.md/orm-union.md 참조.
+`db.X()` 가 반환하는 `Queryable` 체이닝으로 SELECT/INSERT/UPDATE/DELETE/UPSERT 쿼리를 구성·실행하는 군. 모든 옵션 메서드는 새 `Queryable` 을 반환하는 불변 체이닝이며, 콜백은 컬럼 프록시(`QueryableRecord`)를 받아 `expr` 표현식을 만든다. 종단 메서드(`execute`/`single`/`count` 등)에서 QueryDef 를 빌드해 `db.executeDefs` 로 실행한다. 프로시저 실행은 `Executable`, 텍스트 검색 파싱은 `parseSearchQuery`.
 
-## Queryable<TData, TFrom>
+`Queryable<TData, TFrom>` — `TData` 는 결과 행 타입, `TFrom` 은 소스 TableBuilder(CUD 연산에 필요, 커스텀 컬럼/조인 결과는 `never`).
 
-`TData` = 결과 데이터 타입, `TFrom` = 소스 `TableBuilder`(CUD 가능 여부). `select`/`join`/`groupBy`/`distinct`/`wrap`/`union` 등을 거치면 `TFrom` 이 `never` 가 되어 CUD 가 막힌다(파생 컬럼 위에서는 INSERT/UPDATE 불가).
+## SELECT 옵션 (체이닝)
 
-### 옵션 — select / distinct / lock
-
-- `select(fn)` — projection. `fn` 은 원본 컬럼 프록시를 받아 새 컬럼 객체 반환. 반환 객체 안에서 `expr.*` 도출(coalesce/CASE/산식)을 한 번에 작성. 결과 `TData` 가 새 shape 로 바뀜.
-- `distinct()` — `DISTINCT` 적용. 이후 `count()` 하려면 `wrap()` 먼저(아니면 throw).
-- `lock()` — `FOR UPDATE` 행 잠금. 트랜잭션 내에서 선택 행 배타 잠금이 필요할 때.
+- `select(fn)` — SELECT 컬럼 매핑. `fn` 은 컬럼 프록시를 받아 새 구조(`{ alias: 컬럼/표현식 }`)를 반환. 결과 타입이 매핑 형태로 바뀌고 `TFrom` 은 `never`(이후 CUD 불가). 리터럴 상수도 자동으로 `ExprUnit` 으로 래핑됨.
+- `distinct()` — 중복 행 제거(DISTINCT). 이후 `count()` 는 `wrap()` 필요.
+- `lock()` — 선택 행에 배타적 잠금(FOR UPDATE). 트랜잭션 내에서만 의미.
+- `top(count)` — 상위 N행. ORDER BY 없이도 가능.
+- `limit(skip, take)` — OFFSET/LIMIT 페이지네이션. **먼저 `orderBy()` 가 있어야 함**(없으면 throw).
+- `orderBy(fnOrKey, dir?)` — 정렬 추가(여러 번 누적). `fnOrKey` 는 컬럼 반환 함수 또는 체인 경로 문자열(`"id"`, `"user.name"` — `obj.getChainValue` 로 해석). `dir` 기본 `ASC`.
 
 ```typescript
-db.user().select((u) => ({ userName: u.name, userEmail: u.email }))
+const users = await db.user()
+  .select((u) => ({ userName: u.name, userEmail: u.email }))
+  .orderBy((u) => u.createdAt, "DESC")
+  .limit(0, 20)
+  .execute();
 ```
 
-### 제한 — top / limit
+## WHERE / 검색
 
-- `top(count)` — 상위 `count` 행만. ORDER BY 없이도 사용 가능.
-- `limit(skip, take)` — 페이지네이션. `skip`=OFFSET, `take`=LIMIT. **호출 전 `orderBy()` 필수**(없으면 throw).
+- `where(predicate)` — 조건 배열을 반환하는 콜백. 여러 번 호출 시 AND 누적. 배열 안 여러 조건도 AND.
+- `search(fn, searchText)` — `fn` 이 반환한 문자열 컬럼들에 텍스트 검색을 적용. 구문은 `parseSearchQuery` 규칙(공백=OR, `+`=필수, `-`=제외, `"..."`=구문, `*`=와일드카드). 빈 검색어면 그대로 반환. 내부적으로 `LOWER(col) LIKE pattern` 조합.
 
 ```typescript
-db.user().orderBy((u) => u.createdAt, "DESC").limit(page * 50, 50)
+db.user()
+  .where((u) => [expr.eq(u.isActive, true)])
+  .search((u) => [u.name, u.email], "John Doe -withdrawn");
 ```
 
-### 정렬 — orderBy
+## GROUP BY / HAVING
 
-- `orderBy(fnOrKey, orderBy?)` — 정렬 조건 추가(여러 번 호출 시 순서대로). `fnOrKey`=컬럼 반환 함수 또는 체인 경로 문자열(`"user.name"`, 동적 정렬용). `orderBy`=`"ASC" | "DESC"`(기본 ASC).
-
-### 필터 — where / search
-
-- `where(predicate)` — WHERE 조건 추가(여러 번 호출 시 AND 결합). `predicate` 는 컬럼 프록시를 받아 `WhereExprUnit[]` 반환. select 로 만든 파생 컬럼 이름도 직접 참조 가능(framework 가 AST inline).
-- `search(fn, searchText)` — 텍스트 검색. `fn`=검색 대상 문자열 컬럼 배열 반환, `searchText`=검색 구문(`parseSearchQuery` 규칙: 공백=OR, `+`=필수, `-`=제외, `"..."`=구문, `*`=와일드카드). 빈 문자열이면 조건 미추가. 내부적으로 `LOWER(col) LIKE pattern` 조합으로 변환.
+- `groupBy(fn)` — 그룹화 컬럼 배열 반환. 반환 `TFrom` 은 `never`.
+- `having(predicate)` — GROUP BY 이후 필터(여러 번 누적, AND). 반환 `TFrom` 은 `never`.
 
 ```typescript
-db.user()
-  .where((u) => [expr.eq(u.isActive, true)])
-  .search((u) => [u.name, u.email], "John -withdrawn")
+db.order()
+  .select((o) => ({ userId: o.userId, total: expr.sum(o.amount) }))
+  .groupBy((o) => [o.userId])
+  .having((o) => [expr.gte(o.total, 10000)]);
 ```
 
-### 그룹 — groupBy / having
-
-- `groupBy(fn)` — GROUP BY. `fn` 은 그룹 컬럼 배열 반환. 이후 `count()` 하려면 `wrap()` 먼저(아니면 throw).
-- `having(predicate)` — 그룹 필터(여러 번 호출 시 AND). 집계 컬럼 기준 필터링.
+## JOIN
 
-### 조인 — join / joinSingle / include
+- `join(as, fn)` — 1:N LEFT JOIN. 결과에 `as` 프로퍼티가 **배열**로 추가됨. `fn(qr, cols)` 의 `qr.from(Table)` 로 조인 대상을 잡고 `where` 로 조건을 건다.
+- `joinSingle(as, fn)` — N:1/1:1 LEFT JOIN. 결과에 `as` 가 **단일 객체(optional)** 로 추가됨. 집계·도출 컬럼을 outer 행에 부착하는 표준 수단(orm.md: SELECT 절 subquery/exists 금지).
+- `include(fn)` — TableBuilder 의 FK/FKT 관계를 자동 JOIN. `fn` 은 타입 안전 path proxy 를 받아 관계 경로를 지정(`(p) => p.user.company` → 다단계). 비-컬럼(관계) 필드만 접근 가능. 관계 미정의 시 throw, TableBuilder 기반이 아니면 throw. 같은 경로 중복 호출은 무시.
 
-- `join(as, fn)` — 1:N LEFT JOIN. 결과에 `as` 키로 배열 추가. `fn(qr, cols)` 의 `qr.from(Table).where(...)` 로 조인 조건·서브쿼리 정의.
-- `joinSingle(as, fn)` — N:1/1:1 LEFT JOIN. 결과에 `as` 키로 단일 객체(또는 undefined) 추가. 도메인 boolean·집계는 SELECT subquery 대신 `joinSingle` 안 `from+where+select(aggregate)` 로 부착(orm.md).
-- `include(fn)` — `TableBuilder` 의 FK/FKT 관계를 자동 조인. `fn(item)` 은 PathProxy 로 관계 경로만 접근(컬럼은 컴파일 에러). 다단계(`p.user.company`)·다중 호출 지원. 관계 미정의면 throw.
+`join`/`joinSingle` 의 `fn` 첫 인자 `qr`(`JoinQueryable`)는 `from(Table)` / `select(columns)` / `union(...queries)` 를 제공한다.
 
 ```typescript
-db.post()
-  .joinSingle("user", (qr, p) => qr.from(User).where((u) => [expr.eq(u.id, p.userId)]))
-  .include((p) => p.user.company)
+db.post().include((p) => p.user.company);
+
+db.product()
+  .joinSingle("state", (q, p) =>
+    q.from(StockLine).where((x) => [expr.eq(x.productId, p.id)])
+      .select((x) => ({ sumQty: expr.sum(x.qty), cnt: expr.count() })),
+  )
+  .select((p) => ({ id: p.id, totalQty: expr.coalesce(p.state!.sumQty, 0) }));
 ```
 
-### 서브쿼리 — wrap / union / recursive
+## 서브쿼리 / UNION / 재귀 CTE
 
-- `wrap()` — 현재 Queryable 을 서브쿼리(derived table)로 감쌈. `distinct()`/`groupBy()` 후 `count()` 호출에 필요한 자리에서만 사용(불필요한 wrap 금지, orm.md).
-- `static Queryable.union(...queries)` — 2개 이상 Queryable 을 UNION 결합(중복 제거). 결과는 derived table 로 취급되어 이후 `orderBy`/`limit`/`where` 등은 union 결과 위에 적용. 각 소스에 predicate pushdown 하려면 union 전에 미리 호출. 2개 미만이면 `ArgumentError`. 이종 엔티티 합치기는 orm-union.md.
-- `recursive(fn)` — 재귀 CTE(WITH RECURSIVE). 계층 데이터(조직도·카테고리 트리)용. `fn(cte)` 의 `cte.from(Table)` 안에서 `self` 로 상위 결과를 자기참조.
+- `wrap()` — 현재 Queryable 을 서브쿼리(파생 테이블)로 감쌈. `distinct()`/`groupBy()` 이후 `count()` 호출 전에 필요.
+- `Queryable.union(...queries)` (static) — 2개 이상 Queryable 을 UNION(중복 제거). **2개 미만이면 `ArgumentError`**. 첫 쿼리의 컬럼 구조를 기준으로 alias 변환. 결과는 파생 테이블이라 이후 fluent 연산은 외부에 적용됨(예시 스타일은 orm-union.md).
+- `recursive(fn)` — WITH RECURSIVE CTE. `fn(cte)` 의 `cte.from(Table)`/`cte.select(...)`/`cte.union(...)` 로 재귀 본문 정의. 재귀 대상에 `self` 프로퍼티(베이스 행 참조)가 추가됨. 계층(조직도·트리) 조회용.
 
 ```typescript
-const items = await Queryable.union(inQr, outQr).orderBy((r) => r.date, "DESC").limit(0, 50).execute();
+const combined = Queryable.union(
+  db.user().where((u) => [expr.eq(u.type, "admin")]),
+  db.user().where((u) => [expr.eq(u.type, "manager")]),
+);
+
+db.employee()
+  .where((e) => [expr.null(e.managerId)])
+  .recursive((cte) => cte.from(Employee).where((e) => [expr.eq(e.managerId, e.self[0].id)]));
 ```
 
-### 종단 — SELECT 실행
-
-- `execute()` — SELECT 실행, 결과 배열 반환.
-- `single()` — 단일 결과 또는 undefined. 2건 이상이면 `ArgumentError`.
-- `first()` — 첫 결과 또는 undefined(`top(1)`).
-- `exists()` — 조건 일치 행 존재 여부 `boolean`(`top(1)`).
-- `count(fn?)` — 행 수. `fn`=셀 컬럼 지정(생략 시 전체). `distinct()`/`groupBy()` 직후 호출 시 throw(→ `wrap()` 먼저).
-- `getSelectQueryDef()` / `getResultMeta(outputColumns?)` — 실행 없이 `SelectQueryDef` AST / 결과 변환 메타(`ResultMeta`) 산출. 서브쿼리 합성·저수준 실행용.
+## 실행 — SELECT 종단
 
-### 종단 — INSERT
-
-- `insert(records, outputColumns?)` — 배열 삽입(MSSQL 1000행 제한 대비 1000개씩 청크 분할). `records`=`$inferInsert[]`. `outputColumns` 지정 시 삽입된 행의 해당 컬럼 배열 반환(예: 생성된 `id`). 빈 배열이면 즉시 반환.
-- `insertIfNotExists(record, outputColumns?)` — 현재 WHERE 조건에 맞는 행이 없을 때만 1건 삽입. `outputColumns` 지정 시 삽입 행 반환.
-- `insertInto(targetTable, outputColumns?)` — 현재 SELECT 결과를 다른 테이블에 INSERT INTO ... SELECT. `targetTable` 컬럼이 현재 데이터 shape 와 맞아야 함.
+- `execute(): Promise<TData[]>` — SELECT 실행, 결과 배열 반환.
+- `single(): Promise<TData | undefined>` — 단일 결과. 2건 이상이면 `ArgumentError`.
+- `first(): Promise<TData | undefined>` — 첫 결과만(`top(1)`).
+- `count(fn?): Promise<number>` — 행 수. `fn` 으로 특정 컬럼 카운트. `distinct()`/`groupBy()` 직후 호출 시 throw(먼저 `wrap()`). 결과 없으면 0.
+- `exists(): Promise<boolean>` — 조건에 맞는 행 존재 여부(`top(1)` 후 길이 검사).
+- `getSelectQueryDef(): SelectQueryDef` — 빌드된 SELECT AST. `getResultMeta(outputColumns?)` — 결과 파싱용 `ResultMeta`.
 
 ```typescript
-const [created] = await db.user().insert([{ name: "홍길동" }], ["id"]);
+const total = await db.user().where((u) => [expr.eq(u.isActive, true)]).count();
+const user = await db.user().where((u) => [expr.eq(u.id, 1)]).single();
 ```
 
-### 종단 — UPDATE / DELETE / UPSERT
+## 실행 — INSERT (TableBuilder 기반만)
 
-- `update(recordFwd, outputColumns?)` — UPDATE. `recordFwd(cols)` 가 갱신 컬럼/값 객체 반환(`ExprInput`, 리터럴 직접 전달 — `expr.val` 불필요). `outputColumns` 지정 시 갱신 행 반환.
-- `delete(outputColumns?)` — DELETE. `outputColumns` 지정 시 삭제 행 반환.
-- `upsert(updateFn, insertFn?, outputColumns?)` — WHERE 조건 일치 시 UPDATE, 없으면 INSERT. `insertFn` 생략 시 update 값으로 insert. `insertFn(updateRecord)` 는 update 결과를 받아 insert 레코드 산출. `outputColumns` 지정 시 영향 행 반환.
-- 각 종단마다 `getUpdateQueryDef`/`getDeleteQueryDef`/`getUpsertQueryDef`/`getInsertQueryDef`/`getInsertIfNotExistsQueryDef`/`getInsertIntoQueryDef` 로 실행 없이 def 만 얻을 수 있음.
+- `insert(records)` / `insert(records, outputColumns)` — 레코드 배열 삽입. MSSQL 1000행 제한 때문에 1000개 단위 청크로 분할. `outputColumns` 지정 시 삽입된 레코드 배열 반환(`Pick<columns, K>[]`). 빈 배열이면 즉시 반환. AI 컬럼에 명시값이 있으면 자동 `overrideIdentity`.
+- `insertIfNotExists(record)` / `(record, outputColumns)` — WHERE 조건에 맞는 데이터가 없을 때만 단건 삽입. `outputColumns` 지정 시 단건 반환.
+- `insertInto(targetTable)` / `(targetTable, outputColumns)` — 현재 SELECT 결과를 다른 테이블에 INSERT(INSERT INTO ... SELECT). 대상 테이블 컬럼이 현재 데이터와 호환되어야 함(타입 제약).
+- `getInsertQueryDef` / `getInsertIfNotExistsQueryDef` / `getInsertIntoQueryDef` — 각 AST 생성기.
 
 ```typescript
-await db.user().where((u) => [expr.eq(u.id, 1)]).update(() => ({ name: "수정" }));
-await db.user().where((u) => [expr.eq(u.email, "a@b.com")]).upsert(() => ({ name: "A", email: "a@b.com" }));
+const [inserted] = await db.user().insert([{ name: "Gildong Hong" }], ["id"]);
+
+await db.user()
+  .where((u) => [expr.eq(u.email, "t@t.com")])
+  .insertIfNotExists({ name: "t", email: "t@t.com" });
 ```
 
-### DDL 헬퍼
+## 실행 — UPDATE / DELETE / UPSERT (TableBuilder 기반만)
 
-- `switchFk(enabled)` — 이 테이블의 FK 제약 활성/비활성 토글. `enabled` true=활성, false=비활성. 대량 적재 전 FK 일시 해제용. Table/View 기반에서만.
+- `update(recordFwd)` / `(recordFwd, outputColumns)` — `recordFwd(cols)` 가 갱신 컬럼/값을 반환. 값은 `ExprInput`(리터럴 직접 가능). `outputColumns` 지정 시 갱신된 레코드 배열 반환. WHERE/JOIN/limit 가 함께 반영됨.
+- `delete()` / `delete(outputColumns)` — DELETE. `outputColumns` 지정 시 삭제된 레코드 배열 반환.
+- `upsert(updateFn)` / `upsert(updateFn, insertFn?, outputColumns?)` — WHERE 매칭 시 UPDATE, 아니면 INSERT(MERGE). `insertFn(updateRecord)` 미지정 시 update 와 동일 데이터로 삽입. `insertFn` 은 update 레코드를 인자로 받아 변형 가능.
+- `getUpdateQueryDef` / `getDeleteQueryDef` / `getUpsertQueryDef` — AST 생성기.
+- `switchFk(enabled)` — 이 Queryable 소스 테이블의 FK 제약 활성/비활성(트랜잭션 내 가능).
 
-## queryable / getMatchedPrimaryKeys (factory)
+```typescript
+await db.user().where((u) => [expr.eq(u.id, 1)]).update((u) => ({ name: "새이름" }));
+
+await db.user().where((u) => [expr.eq(u.isExpired, true)]).delete(["id", "name"]);
 
-- `queryable(db, tableOrView, as?)` — Table/View 별 Queryable 팩토리 함수 생성. `DbContext` 내부에서 멤버 등록에 쓰임(보통 `this.queryable(...)` 로 호출). `as` 미지정 시 호출마다 새 alias.
-- `getMatchedPrimaryKeys(fkCols, targetTable)` — FK 컬럼 배열과 대상 테이블 PK 를 매칭해 PK 컬럼명 배열 반환. 개수 불일치 시 throw. include/조인 조건 생성 내부에서 사용.
+await db.user()
+  .where((u) => [expr.eq(u.email, "t@t.com")])
+  .upsert(() => ({ loginCount: 1 }), (update) => ({ ...update, email: "t@t.com" }));
+```
 
-타입 export: `QueryableRecord<TData>`(컬럼 프록시 타입), `QueryableWriteRecord<TData>`(쓰기용 `ExprInput` 레코드), `UnwrapQueryableRecord<R>`(select 결과 역추론), `PathProxy<T>`(include 경로 프록시).
+## Executable (프로시저 실행)
 
-## Executable<TParams, TReturns> / executable
+`DbContext.executable(Procedure)` 가 반환하는 팩토리(`db.getUserById()`)가 `Executable` 을 만든다.
 
-저장 프로시저 실행 래퍼. `db.getUserById()` 로 인스턴스를 얻어 실행한다.
+```typescript
+class Executable<TParams, TReturns> {
+  execute(params: InferColumnExprs<TParams>): Promise<InferColumnExprs<TReturns>[][]>;
+  getExecProcQueryDef(params?): ExecProcQueryDef;
+}
+function executable(db, builder): () => Executable;
+```
 
-- `execute(params)` — 프로시저 실행. `params`=`InferColumnExprs<TParams>`(`ExprInput` 또는 리터럴). 결과는 `TReturns[][]`(다중 결과셋). 정의에 파라미터가 없는데 전달하면 throw.
-- `getExecProcQueryDef(params?)` — 실행 없이 `ExecProcQueryDef` 만 산출.
-- `executable(db, builder)` — `Executable` 팩토리 생성(`DbContext` 멤버 등록용, 보통 `this.executable(...)`).
+- `execute(params)` — 프로시저 실행. 파라미터는 `ExprInput`(리터럴 또는 `ExprUnit`). 결과는 다중 결과셋(`행[][]`). 파라미터 없는 프로시저에 params 를 주면 throw.
 
 ```typescript
 const [rows] = await db.getUserById().execute({ userId: 1n });
 ```
 
-## parseSearchQuery / ParsedSearchQuery
-
-`search()` 가 내부적으로 쓰는 검색 구문 파서. 검색 문자열을 SQL LIKE 패턴으로 변환한다. 커스텀 검색 UI 를 직접 만들 때 외부에서도 호출 가능.
+## 검색 파서 — parseSearchQuery
 
 ```typescript
 function parseSearchQuery(searchText: string): ParsedSearchQuery;
-interface ParsedSearchQuery { or: string[]; must: string[]; not: string[]; }
+interface ParsedSearchQuery { or: string[]; must: string[]; not: string[]; } // 각각 LIKE 패턴
 ```
 
-- `or`: string[] — 일반 검색어(OR 조건) LIKE 패턴. 공백으로 구분된 토큰.
-- `must`: string[] — 필수 포함(AND 조건) LIKE 패턴. `+term` 또는 `"구문"`(따옴표 = 정확 일치 = 필수).
-- `not`: string[] — 제외(NOT 조건) LIKE 패턴. `-term`.
+검색 문자열을 SQL LIKE 패턴으로 파싱. `Queryable.search()` 내부에서 사용하지만 직접도 가능.
 
-구문 규칙: 와일드카드 없는 단어 `apple` → `%apple%`(부분 일치), `app*` → `app%`(시작 일치), `*apple` → `%apple`(끝 일치). 이스케이프 `\\` `\*` `\%` `\"` `\+` `\-` 는 리터럴 문자로 처리. 닫히지 않은 따옴표는 일반 텍스트로 취급.
+| 구문 | 의미 |
+| ---- | ---- |
+| `term1 term2` | OR (하나 이상 일치) → `or` |
+| `+term` | 필수 포함(AND) → `must` |
+| `-term` | 제외(NOT) → `not` |
+| `"exact phrase"` | 정확한 구문(필수) → `must` |
+| `term*` / `*term` / `a*ple` | 와일드카드 `%` 로 변환(접두/접미/중간 일치) |
+| 와일드카드 없는 `term` | `%term%` (부분 문자열) |
+
+이스케이프: `\\` `\*` `\%` `\"` `\+` `\-` 는 각 리터럴 문자. 닫히지 않은 따옴표는 따옴표 포함 일반 텍스트로 처리.
 
 ```typescript
-parseSearchQuery('apple "맛있는 과일" -banana +strawberry');
-// { or: ["%apple%"], must: ["%맛있는 과일%", "%strawberry%"], not: ["%banana%"] }
+parseSearchQuery('apple "delicious fruit" -banana +strawberry');
+// { or: ["%apple%"], must: ["%delicious fruit%", "%strawberry%"], not: ["%banana%"] }
 ```
+
+## 관련 타입 / 헬퍼 export
+
+- `QueryableRecord<TData>` — 컬럼이 `ExprUnit` 으로 래핑된 프록시 타입(콜백 인자).
+- `QueryableWriteRecord<TData>` — 쓰기(update/upsert) 값 레코드(`ExprInput`).
+- `UnwrapQueryableRecord<R>` — `select` 결과를 다시 데이터 타입으로 역변환.
+- `PathProxy<TObject>` — `include()` 의 타입 안전 경로 프록시(관계 필드만 접근).
+- `queryable(db, tableOrView, as?)` — Table/View 용 Queryable 팩토리 함수(`DbContext.queryable` 의 기반).
+- `getMatchedPrimaryKeys(fkCols, targetTable)` — FK 컬럼 배열과 대상 PK 매칭(개수 불일치 시 throw, include 내부용).
+
+## 주의사항
+
+- CUD(insert/update/delete/upsert)·`insertInto` 는 `TFrom` 이 살아있는(=`select`/`groupBy`/join 결과가 아닌) TableBuilder 기반 Queryable 에서만. 아니면 throw.
+- 도출 컬럼 위 필터·정렬은 `wrap()` 없이 `.select(...).where(...)` 로 — framework 가 projected AST 를 inline(orm.md). `wrap()` 은 `distinct`/`groupBy` 후 `count` 처럼 명시 요구 시에만.
+- where 비교·CUD 값은 리터럴 그대로 — `expr.val` 로 감싸지 말 것(orm.md). `expr.val` 은 `select` 에서 상수 컬럼 만들 때처럼 `ExprUnit` 이 요구되는 자리에서만.