sonamu 0.7.11 → 0.7.12

package/src/database/base-model.ts

@@ -2,24 +2,13 @@
 
 import type { Knex } from "knex";
 import { group, isObject, omit, set } from "radashi";
+import type { ListResult } from "..";
 import { Sonamu } from "../api";
-import { EntityManager } from "../entity/entity-manager";
-import type { DatabaseSchemaExtend } from "../types/types";
+import type { DatabaseSchemaExtend, SonamuQueryMode } from "../types/types";
 import { getJoinTables, getTableNamesFromWhere } from "../utils/sql-parser";
 import { chunk } from "../utils/utils";
-import type {
-  EmbeddingItem,
-  EmbeddingProvider,
-  HybridSearchOptions,
-  HybridSearchResult,
-  ProgressCallback,
-  VectorSearchOptions,
-  VectorSearchResult,
-} from "../vector/types";
-import { VectorSearch } from "../vector/vector-search";
 import type {
   EnhancerMap,
-  ExecuteSubsetQueryResult,
   ResolveSubsetIntersection,
   UnionExtractedTTables,
 } from "./base-model.types";
@@ -69,118 +58,7 @@ export class BaseModelClass<
     return new PuriWrapper(db, new UpsertBuilder());
   }
 
-  // VectorSearch 인스턴스 캐시
-  private _vectorSearch: VectorSearch<any> | null = null;
-
-  /**
-   * 벡터 검색 인스턴스 반환
-   * - 기본 provider: voyage
-   * - 기본 dimensions: 1024 (DEFAULT_VECTOR_CONFIG 사용)
-   */
-  getVector<T = Record<string, unknown>>(): VectorSearch<T> {
-    if (this._vectorSearch) {
-      return this._vectorSearch as VectorSearch<T>;
-    }
-
-    const entity = EntityManager.get(this.modelName);
-
-    this._vectorSearch = new VectorSearch<T>(this.getDB("w"), entity.table);
-
-    return this._vectorSearch as VectorSearch<T>;
-  }
-
-  /**
-   * 벡터 검색 (코사인 유사도)
-   * @param query - 검색어
-   * @param options - 검색 옵션
-   */
-  async vectorSearch<T = Record<string, unknown>>(
-    query: string,
-    options: VectorSearchOptions & { provider?: EmbeddingProvider } = {},
-  ): Promise<VectorSearchResult<T>[]> {
-    const entity = EntityManager.get(this.modelName);
-    const vectorProp = entity.getVectorColumn();
-    if (!vectorProp) {
-      throw new Error(`${this.modelName} Entity에 vector 컬럼이 정의되지 않았습니다.`);
-    }
-
-    const vs = new VectorSearch<T>(this.getDB("w"), entity.table);
-    return vs.search(query, options.provider ?? "voyage", {
-      ...options,
-      embeddingColumn: options.embeddingColumn ?? vectorProp.name,
-    });
-  }
-
-  /**
-   * 하이브리드 검색 (Vector + FTS)
-   * @param query - 검색어
-   * @param options - 검색 옵션
-   */
-  async hybridSearch<T = Record<string, unknown>>(
-    query: string,
-    options: HybridSearchOptions & { provider?: EmbeddingProvider } = {},
-  ): Promise<HybridSearchResult<T>[]> {
-    const entity = EntityManager.get(this.modelName);
-    const vectorProp = entity.getVectorColumn();
-    if (!vectorProp) {
-      throw new Error(`${this.modelName} Entity에 vector 컬럼이 정의되지 않았습니다.`);
-    }
-
-    const vs = new VectorSearch<T>(this.getDB("w"), entity.table);
-    return vs.hybridSearch(query, options.provider ?? "voyage", {
-      ...options,
-      embeddingColumn: options.embeddingColumn ?? vectorProp.name,
-    });
-  }
-
-  /**
-   * 단일 레코드에 임베딩 저장
-   * @param id - 레코드 ID
-   * @param text - 임베딩할 텍스트
-   * @param options - provider, embeddingColumn 옵션
-   */
-  async saveEmbedding(
-    id: number,
-    text: string,
-    options: { provider?: EmbeddingProvider; embeddingColumn?: string } = {},
-  ): Promise<void> {
-    const entity = EntityManager.get(this.modelName);
-    const vectorProp = entity.getVectorColumn(options.embeddingColumn);
-    if (!vectorProp) {
-      throw new Error(`${this.modelName} Entity에 vector 컬럼이 정의되지 않았습니다.`);
-    }
-
-    const { provider = "voyage" } = options;
-    const vs = this.getVector();
-    return vs.saveEmbedding(id, text, provider, vectorProp.name);
-  }
-
-  /**
-   * 여러 레코드에 임베딩 일괄 저장
-   * @param items - { id, text } 배열
-   * @param options - provider, embeddingColumn, onProgress 옵션
-   */
-  async saveEmbeddingsBatch(
-    items: EmbeddingItem[],
-    options: {
-      provider?: EmbeddingProvider;
-      embeddingColumn?: string;
-      onProgress?: ProgressCallback;
-    } = {},
-  ): Promise<void> {
-    const entity = EntityManager.get(this.modelName);
-    const vectorProp = entity.getVectorColumn(options.embeddingColumn);
-    if (!vectorProp) {
-      throw new Error(`${this.modelName} Entity에 vector 컬럼이 정의되지 않았습니다.`);
-    }
-
-    const { provider = "voyage", onProgress } = options;
-    const vs = this.getVector();
-    return vs.saveEmbeddingsBatch(items, provider, vectorProp.name, onProgress);
-  }
-
   async destroy() {
-    this._vectorSearch = null;
     return DB.destroy();
   }
 
@@ -275,6 +153,11 @@ export class BaseModelClass<
   async executeSubsetQuery<
     T extends TSubsetKey,
     TComputedResults extends InferAllSubsets<TSubsetQueries, TLoaderQueries>,
+    LP extends {
+      num?: number;
+      page?: number;
+      queryMode?: SonamuQueryMode;
+    },
   >(
     params: {
       subset: T;
@@ -282,12 +165,12 @@ export class BaseModelClass<
       params: {
         num: number;
         page: number;
-        queryMode?: "list" | "count" | "both";
+        queryMode?: SonamuQueryMode;
       };
       debug?: boolean;
       optimizeCountQuery?: boolean;
     } & EnhancerParam<TSubsetKey, TComputedResults, TSubsetMapping>,
-  ): Promise<ExecuteSubsetQueryResult<TSubsetMapping, T>> {
+  ): Promise<ListResult<LP, TSubsetMapping[T]>> {
     const { subset, qb, params: queryParams, debug = false, optimizeCountQuery = false } = params;
 
     if (!this.loaderQueries) {
@@ -296,9 +179,13 @@ export class BaseModelClass<
 
     const { num, page } = queryParams;
 
-    // COUNT 쿼리 실행
+    // COUNT 쿼리 실행 (queryMode: list일 때는 0 리턴)
     const total = await this.executeCountQuery(qb, queryParams, debug, optimizeCountQuery);
 
+    if (queryParams?.queryMode === "count") {
+      return { total } as ListResult<LP, TSubsetMapping[T]>;
+    }
+
     // LIST 쿼리 실행
     const computedRows = await this.executeListQuery(subset, qb, queryParams, num, page, debug);
 
@@ -308,7 +195,13 @@ export class BaseModelClass<
       computedRows.map((row) => enhancer?.(row) ?? row),
     )) as TSubsetMapping[T][];
 
-    return { rows, total };
+    if (queryParams.queryMode === "list") {
+      // 리스트만 리턴
+      return { rows } as ListResult<LP, TSubsetMapping[T]>;
+    } else {
+      // 둘다 리턴
+      return { rows, total } as ListResult<LP, TSubsetMapping[T]>;
+    }
   }
 
   /**

package/src/database/base-model.types.ts

@@ -7,6 +7,7 @@
  * Enhancer, SubsetQuery 교집합 등 Model 계층에서 필요한 타입 정의.
  */
 
+import type { ListResult } from "..";
 import type { DatabaseSchemaExtend } from "../types/types";
 import type { Puri } from "./puri";
 import type { PuriSubsetFn } from "./puri-subset.types";
@@ -151,7 +152,5 @@ export type ExecuteSubsetQueryParams<
 export type ExecuteSubsetQueryResult<
   TSubsetMapping extends Record<string, any>,
   T extends string,
-> = {
-  rows: TSubsetMapping[T][];
-  total: number;
-};
+  LP extends { queryMode?: "list" | "count" | "both" },
+> = ListResult<LP, TSubsetMapping[T]>;

package/src/database/db.ts

@@ -56,30 +56,40 @@ export class DBClass {
     const instanceName = which === "w" ? "wdb" : "rdb";
 
     if (!this[instanceName]) {
-      let config: Knex.Config;
-      switch (process.env.NODE_ENV ?? "development") {
-        case "development":
-        case "staging":
-          config =
-            which === "w"
-              ? dbConfig.development_master
-              : (dbConfig.development_slave ?? dbConfig.development_master);
-          break;
-        case "production":
-          config =
-            which === "w"
-              ? dbConfig.production_master
-              : (dbConfig.production_slave ?? dbConfig.production_master);
-          break;
-        default:
-          throw new Error(`현재 ENV ${process.env.NODE_ENV}에는 설정 가능한 DB설정이 없습니다.`);
-      }
+      const config = this.getDBConfig(which);
       this[instanceName] = knex(config);
     }
 
     return this[instanceName];
   }
 
+  getDBConfig(which: DBPreset): Knex.Config {
+    const dbConfig = Sonamu.dbConfig;
+    if (process.env.NODE_ENV === "test") {
+      return {
+        ...dbConfig.test,
+        // 단일 풀
+        pool: {
+          min: 1,
+          max: 1,
+        },
+      };
+    }
+    switch (process.env.NODE_ENV ?? "development") {
+      case "development":
+      case "staging":
+        return which === "w"
+          ? dbConfig.development_master
+          : (dbConfig.development_slave ?? dbConfig.development_master);
+      case "production":
+        return which === "w"
+          ? dbConfig.production_master
+          : (dbConfig.production_slave ?? dbConfig.production_master);
+      default:
+        throw new Error(`현재 ENV ${process.env.NODE_ENV}에는 설정 가능한 DB설정이 없습니다.`);
+    }
+  }
+
   async destroy(): Promise<void> {
     if (this.wdb !== undefined) {
       await this.wdb.destroy();

package/src/database/puri-subset.test-d.ts

@@ -4,6 +4,7 @@ import type { Puri } from "./puri";
 import type { Hydrate, InferAllSubsets, LoadersResult } from "./puri-subset.types";
 import type { PuriWrapper } from "./puri-wrapper";
 
+/** biome-ignore lint/suspicious/noExplicitAny: Puri Subset 타입 시스템에서 any를 허용함 */
 type MockPuri<T> = Puri<DatabaseSchemaExtend, any, T>;
 
 describe("Hydrate", () => {

package/src/database/puri-subset.types.ts

@@ -1,3 +1,5 @@
+/** biome-ignore-all lint/suspicious/noExplicitAny: Puri Subset 타입 시스템에서 any를 허용함 */
+
 /**
  * Puri Subset 타입 시스템
  *

package/src/database/puri.ts

@@ -3,6 +3,7 @@
 
 import assert from "assert";
 import chalk from "chalk";
+import inflection from "inflection";
 import type { Knex } from "knex";
 import { Naite } from "../naite/naite";
 import type {
@@ -12,7 +13,6 @@ import type {
   Expand,
   ExtractColumnType,
   FulltextColumns,
-  HighlightOptions,
   InsertData,
   InsertResult,
   LeftJoinedMarker,
@@ -25,8 +25,11 @@ import type {
   SelectObject,
   SingleTableValue,
   SqlExpression,
+  TsHighlightOptions,
   TsQueryConfig,
   TsQueryOptions,
+  TsRankOptions,
+  VectorColumns,
   WhereCondition,
   WhereOperator,
 } from "./puri.types";
@@ -127,6 +130,9 @@ export class Puri<TSchema, TTables extends Record<string, any>, TResult> {
   static rawString(sql: string): SqlExpression<"string"> {
     return { _type: "sql_expression", _return: "string", _sql: sql };
   }
+  static rawStringArray(sql: string): SqlExpression<"string[]"> {
+    return { _type: "sql_expression", _return: "string[]", _sql: sql };
+  }
   static rawNumber(sql: string): SqlExpression<"number"> {
     return { _type: "sql_expression", _return: "number", _sql: sql };
   }
@@ -150,41 +156,93 @@ export class Puri<TSchema, TTables extends Record<string, any>, TResult> {
    *   }),
    * })
    */
-  static highlight(
+  static tsHighlight(
     column: string,
     query: string,
-    options?: HighlightOptions,
+    _options?: TsHighlightOptions,
   ): SqlExpression<"string"> {
+    const { parser = "websearch_to_tsquery", config = "simple", ...options } = _options ?? {};
+
+    const hlOptionParts = Object.entries(options).map(([key, value]) => {
+      return `${inflection.camelize(key)}=${value}`;
+    });
+
+    const hlOptions = hlOptionParts.length > 0 ? `, '${hlOptionParts.join(", ")}'` : "";
+
+    // TODO: rawBinding 메서드 만들어서 XSS 방지
+    return Puri.rawString(
+      `ts_headline('${config}', ${column}, ${parser}('${config}', '${query}')${hlOptions})`,
+    );
+  }
+
+  // ts_rank
+  static tsRank(column: string, query: string, options?: TsRankOptions): SqlExpression<"number"> {
+    return Puri._tsRank("ts_rank", column, query, options);
+  }
+
+  // ts_rank_cd
+  static tsRankCd(column: string, query: string, options?: TsRankOptions): SqlExpression<"number"> {
+    return Puri._tsRank("ts_rank_cd", column, query, options);
+  }
+
+  static _tsRank(
+    type: "ts_rank" | "ts_rank_cd",
+    column: string,
+    query: string,
+    options?: TsRankOptions,
+  ): SqlExpression<"number"> {
     const {
       parser = "websearch_to_tsquery",
       config = "simple",
-      maxWords,
-      minWords,
-      shortWord,
-      highlightAll,
-      maxFragments,
-      startSel,
-      stopSel,
-      fragmentDelimiter,
+      normalization,
+      weights,
     } = options ?? {};
 
-    const hlOptionParts: string[] = [];
+    const weightClause = weights ? `ARRAY[${weights.join(", ")}], ` : "";
+    const normalizationClause = normalization ? `, ${normalization}` : "";
 
-    if (maxWords !== undefined) hlOptionParts.push(`MaxWords=${maxWords}`);
-    if (minWords !== undefined) hlOptionParts.push(`MinWords=${minWords}`);
-    if (shortWord !== undefined) hlOptionParts.push(`ShortWord=${shortWord}`);
-    if (highlightAll !== undefined) hlOptionParts.push(`HighlightAll=${highlightAll}`);
-    if (maxFragments !== undefined) hlOptionParts.push(`MaxFragments=${maxFragments}`);
-    if (startSel !== undefined) hlOptionParts.push(`StartSel="${startSel}"`);
-    if (stopSel !== undefined) hlOptionParts.push(`StopSel="${stopSel}"`);
-    if (fragmentDelimiter !== undefined)
-      hlOptionParts.push(`FragmentDelimiter="${fragmentDelimiter}"`);
+    return Puri.rawNumber(
+      `${type}(${weightClause}${column}, ${parser}('${config}', '${query}')${normalizationClause})`,
+    );
+  }
 
-    const hlOptions = hlOptionParts.length > 0 ? `, '${hlOptionParts.join(", ")}'` : "";
+  /**
+   * PGroonga FullText 인덱스 검색 점수
+   *
+   * @example
+   * .select({
+   *   score: Puri.score(),
+   * })
+   */
+  static score(): SqlExpression<"number"> {
+    return Puri.rawNumber("pgroonga_score(tableoid, ctid)");
+  }
 
-    // TODO: rawBinding 메서드 만들어서 XSS 방지
-    return Puri.rawString(
-      `ts_headline('${config}', ${column}, ${parser}('${config}', '${query}')${hlOptions})`,
+  /**
+   * PGroonga FullText 인덱스 검색 하이라이팅
+   *
+   * @example
+   * .select({
+   *   title: Puri.highlight("posts.title", search),
+   * })
+   */
+  static highlight(column: string, query: string | string[]): SqlExpression<"string">;
+  static highlight(columns: string[], query: string | string[]): SqlExpression<"string[]">;
+
+  static highlight(
+    columnOrColumns: string | string[],
+    query: string | string[],
+  ): SqlExpression<"string"> | SqlExpression<"string[]"> {
+    const queryClause = `ARRAY[${(Array.isArray(query) ? query : [query]).map((q) => `'${q}'`).join(",")}]`;
+
+    // 단일 컬럼인 경우
+    if (typeof columnOrColumns === "string") {
+      return Puri.rawString(`pgroonga_highlight_html(${columnOrColumns}, ${queryClause})`);
+    }
+
+    // 컬럼 배열인 경우
+    return Puri.rawStringArray(
+      `pgroonga_highlight_html(ARRAY[${columnOrColumns.join(",")}], ${queryClause})`,
     );
   }
 
@@ -200,7 +258,7 @@ export class Puri<TSchema, TTables extends Record<string, any>, TResult> {
     for (const [alias, columnOrFunction] of Object.entries(flatSelect)) {
       if (typeof columnOrFunction === "object" && columnOrFunction._type === "sql_expression") {
         // SQL 함수인 경우
-        selectClauses.push(this.knex.raw(`${columnOrFunction._sql} as ${alias}`));
+        selectClauses.push(this.knex.raw(`${columnOrFunction._sql} as "${alias}"`));
       } else {
         // 일반 컬럼인 경우
         const columnPath = columnOrFunction as string;
@@ -526,8 +584,40 @@ export class Puri<TSchema, TTables extends Record<string, any>, TResult> {
     return this;
   }
 
+  /**
+   * PGroonga FullText 인덱스 검색
+   * - 사용할 PGroonga 인덱스와 동일한 컬럼 구성으로 검색해야 인덱스가 사용됩니다.
+   *
+   * 단일 컬럼 검색:
+   * ```sql
+   * WHERE name &@~ 'search'
+   * ```
+   *
+   * 복합 컬럼 검색:
+   * ```sql
+   * WHERE ARRAY[name::text, description::text] &@~ 'search'
+   * ```
+   */
+  whereSearch<TColumn extends AvailableColumns<TTables>>(
+    column: TColumn | TColumn[],
+    value: string,
+    options?: {
+      weights?: number[]; // 정수 배열
+    },
+  ): this {
+    const { weights } = options ?? {};
+    const columnExpr = Array.isArray(column)
+      ? `ARRAY[${column.map((c) => `${c}::text`).join(",")}]`
+      : column;
+    const pgroongaCondition = `pgroonga_condition(?${weights?.length ? `, weights => ARRAY[${weights.join(",")}]` : ""})`;
+
+    this.knexQuery.whereRaw(`${columnExpr} &@~ ${pgroongaCondition}`, [value]);
+
+    return this;
+  }
+
   // WHERE FULLTEXT
-  whereSearch<TColumn extends AvailableColumns<TTables> | SqlExpression<"string">>(
+  whereTsSearch<TColumn extends AvailableColumns<TTables> | SqlExpression<"string">>(
     column: TColumn,
     value: string,
     options?: TsQueryOptions | TsQueryConfig,
@@ -578,6 +668,127 @@ export class Puri<TSchema, TTables extends Record<string, any>, TResult> {
     return this;
   }
 
+  /**
+   * 벡터 유사도 검색 설정
+   *
+   * - SELECT에 similarity 컬럼 추가
+   * - WHERE col IS NOT NULL 추가
+   * - threshold가 있으면 WHERE 조건 추가
+   * - 기존 ORDER BY를 clear하고 원시 연산자로 정렬 (HNSW 인덱스 최적화)
+   *
+   * @param column 벡터 컬럼 경로
+   * @param embedding 쿼리 임베딩 벡터
+   * @param options method, threshold, as 등 옵션
+   *
+   * @example
+   * ```typescript
+   * // cosine similarity (기본값)
+   * qb.vectorSimilarity("columnName", queryVector, {
+   *   method: "cosine",
+   *   threshold: 0.5
+   * });
+   *
+   * // L2 distance
+   * qb.vectorSimilarity("columnName", queryVector, {
+   *   method: "l2",
+   *   threshold: 1.5  // 거리가 1.5 이하인 결과만
+   * });
+   *
+   * // Inner product
+   * qb.vectorSimilarity("columnName", queryVector, {
+   *   method: "inner_product",
+   *   threshold: 0.7
+   * });
+   * ```
+   */
+  vectorSimilarity(
+    column: VectorColumns<TTables>,
+    embedding: number[],
+    options: {
+      method?: "cosine" | "l2" | "inner_product";
+      threshold?: number;
+    } = {},
+  ): Puri<TSchema, TTables, TResult & { similarity: number }> {
+    const { method = "cosine", threshold } = options;
+    if (
+      !Array.isArray(embedding) ||
+      embedding.length === 0 ||
+      embedding.some((v) => !Number.isFinite(v))
+    ) {
+      throw new Error("Invalid embedding vector: expected a non-empty array of finite numbers");
+    }
+    const vectorLiteral = JSON.stringify(embedding.map((v) => Number(v)));
+
+    // method별 연산자 및 similarity 계산식
+    // - cosine: <=> (cosine distance, 0~2), similarity = 1 - distance
+    // - l2: <-> (euclidean distance), similarity = distance (낮을수록 유사)
+    // - inner_product: <#> (negative inner product), similarity = -distance (높을수록 유사)
+    const operatorMap = {
+      cosine: "<=>",
+      l2: "<->",
+      inner_product: "<#>",
+    } as const;
+    const operator = operatorMap[method];
+
+    // SELECT에 similarity 추가
+    if (method === "cosine") {
+      // cosine: similarity = 1 - cosine_distance (0~1, 높을수록 유사)
+      this.knexQuery.select(
+        this.knex.raw(`1 - (?? <=> ?::vector) as similarity`, [column, vectorLiteral]),
+      );
+    } else if (method === "l2") {
+      // l2: distance 그대로 반환 (낮을수록 유사)
+      this.knexQuery.select(
+        this.knex.raw(`?? <-> ?::vector as similarity`, [column, vectorLiteral]),
+      );
+    } else {
+      // inner_product: pgvector는 음수 반환하므로 부호 반전 (높을수록 유사)
+      this.knexQuery.select(
+        this.knex.raw(`-(?? <#> ?::vector) as similarity`, [column, vectorLiteral]),
+      );
+    }
+
+    // WHERE col IS NOT NULL
+    this.knexQuery.whereNotNull(column);
+
+    // threshold가 있으면 WHERE 추가
+    if (typeof threshold === "number") {
+      if (!Number.isFinite(threshold)) {
+        throw new Error(`Invalid vectorSimilarity threshold: ${threshold}`);
+      }
+
+      if (method === "cosine") {
+        // similarity >= threshold  <=>  cosine_distance <= (1 - threshold)
+        this.knexQuery.whereRaw(`?? ${operator} ?::vector <= ?`, [
+          column,
+          vectorLiteral,
+          1 - threshold,
+        ]);
+      } else if (method === "l2") {
+        // distance <= threshold (거리가 threshold 이하)
+        this.knexQuery.whereRaw(`?? ${operator} ?::vector <= ?`, [
+          column,
+          vectorLiteral,
+          threshold,
+        ]);
+      } else {
+        // inner_product: -distance >= threshold  <=>  distance <= -threshold
+        this.knexQuery.whereRaw(`?? ${operator} ?::vector <= ?`, [
+          column,
+          vectorLiteral,
+          -threshold,
+        ]);
+      }
+    }
+
+    // 기존 ORDER BY clear 후 원시 연산자로 정렬 (HNSW 인덱스 최적화)
+    // 모든 method에서 ASC: 거리/음수값이 작을수록 유사
+    this.knexQuery.clear("order");
+    this.knexQuery.orderByRaw(`?? ${operator} ?::vector`, [column, vectorLiteral]);
+
+    return this as any;
+  }
+
   // 기본 쿼리 메서드들
   limit(count: number): this {
     if (count < 0) {

package/src/database/puri.types.test-d.ts

@@ -108,7 +108,7 @@ describe("ExtractColumnType", () => {
       type Tables = {
         users: MockSchema["users"];
         department: MockSchema["departments"] & LeftJoinedMarker; // nullable FK
-        company: MockSchema["companies"] & LeftJoinedMarker; // non-null FK → 마커 없음
+        company: MockSchema["companies"]; // non-null FK → 마커 없음
       };
       type Result = ExtractColumnType<Tables, "company.id">;