sonamu 0.7.4 → 0.7.6

package/src/types/types.ts

@@ -15,12 +15,18 @@ export type DistributiveOmit<T, K extends keyof any> = T extends any ? Omit<T, K
 /*
   Model-Defintion
 */
+export type GeneratedColumnType = "STORED" | "VIRTUAL";
+export type GeneratedColumn = {
+  type: GeneratedColumnType;
+  expression: string;
+};
 export type CommonProp = {
   name: string;
   nullable?: boolean;
   toFilter?: true;
   desc?: string;
   dbDefault?: string;
+  generated?: GeneratedColumn;
 };
 export type IntegerProp = CommonProp & {
   type: "integer";
@@ -99,7 +105,14 @@ export type VirtualProp = CommonProp & {
   type: "virtual";
   id: string;
 }; // PG: none / TS: any(id) / JSON: any
-
+export type VectorProp = CommonProp & {
+  type: "vector";
+  dimensions: number;
+};
+export type VectorArrayProp = CommonProp & {
+  type: "vector[]";
+  dimensions: number;
+};
 export type RelationType = "HasMany" | "BelongsToOne" | "ManyToMany" | "OneToOne";
 export type RelationOn = "CASCADE" | "SET NULL" | "NO ACTION" | "SET DEFAULT" | "RESTRICT";
 type _RelationProp = {
@@ -170,13 +183,82 @@ export type EntityProp =
   | UuidArrayProp
   | JsonProp
   | VirtualProp
+  | VectorProp
+  | VectorArrayProp
   | RelationProp;
 
+/**
+ * pgvector 거리 연산자 클래스
+ *
+ * @description
+ * - `vector_cosine_ops`: 코사인 거리 (Cosine Distance) - 권장
+ *   - SQL 연산자: `<=>`
+ *   - 벡터의 방향만 비교 (크기 무시), 1 - cosine_similarity
+ *   - 텍스트 임베딩, 시맨틱 검색에 가장 일반적으로 사용
+ *   - 사용 예: OpenAI, Voyage 등 대부분의 임베딩 모델에 권장
+ *
+ * - `vector_ip_ops`: 내적 (Inner Product)
+ *   - SQL 연산자: `<#>`
+ *   - 두 벡터의 내적을 계산 (sum(a[i] * b[i]))
+ *   - 정규화된 벡터에서 코사인 유사도와 동일한 결과
+ *   - 값이 클수록 유사 (음수 연산자이므로 ORDER BY에서 주의)
+ *   - 사용 예: 이미 정규화된 임베딩에서 가장 빠른 성능
+ *
+ * - `vector_l2_ops`: 유클리드 거리 (L2 Distance)
+ *   - SQL 연산자: `<->`
+ *   - 두 벡터 간의 직선 거리를 계산 (sqrt(sum((a[i] - b[i])^2)))
+ *   - 벡터의 크기(magnitude)가 중요할 때 사용
+ *   - 사용 예: 이미지 유사도, 절대적 거리 측정이 필요한 경우
+ */
+export type VectorOps = "vector_cosine_ops" | "vector_ip_ops" | "vector_l2_ops";
+
+type EntityIndexColumn = {
+  name: string;
+  nullsFirst?: boolean;
+  sortOrder?: "ASC" | "DESC";
+  /** pgvector 인덱스에서 사용할 거리 연산자 (vector 컬럼에만 적용) */
+  vectorOps?: VectorOps;
+};
 export type EntityIndex = {
-  type: "index" | "unique" | "fulltext";
-  columns: string[];
+  type: "index" | "unique" | "fulltext" | "hnsw" | "ivfflat";
+  columns: EntityIndexColumn[];
   name: string;
   parser?: "built-in" | "ngram";
+  nullsNotDistinct?: boolean; // unique index only
+  /**
+   * HNSW (Hierarchical Navigable Small World) 인덱스: 각 노드의 최대 연결 수
+   *
+   * @description
+   * 그래프에서 각 노드가 가질 수 있는 최대 연결 수입니다.
+   * HNSW는 빠른 검색 속도와 높은 정확도를 제공하므로 권장됩니다.
+   * - 기본값: 16
+   * - 범위: 2 ~ 100
+   * - 높을수록: 정확도↑, 빌드 시간↑, 메모리↑
+   * - 권장: 빠른 빌드(8), 균형(16), 높은 정확도(32), 최고 정확도(64)
+   */
+  m?: number;
+  /**
+   * HNSW (Hierarchical Navigable Small World) 인덱스: 구성 시 탐색 범위
+   *
+   * @description
+   * 인덱스 구성 시 각 노드에서 탐색할 범위입니다.
+   * - 기본값: 64
+   * - 범위: 4 ~ 1000
+   * - 높을수록: 정확도↑, 빌드 시간↑
+   * - 권장: 빠른 빌드(32), 균형(64), 높은 정확도(128), 최고 정확도(256)
+   */
+  efConstruction?: number;
+  /**
+   * IVFFlat (Inverted File with Flat Compression) 인덱스: 클러스터링 리스트 수
+   *
+   * @description
+   * 벡터를 클러스터링할 버킷 수를 지정합니다.
+   * IVFFlat은 빠른 빌드와 낮은 메모리 사용이 필요할 때 사용합니다.
+   * - 권장값: sqrt(row_count) ~ row_count / 1000
+   * - 예시: 10,000행 → 100, 100,000행 → 300, 1,000,000행 → 1000
+   * - 많을수록 정확도↑, 검색 속도↓
+   */
+  lists?: number;
 };
 export type EntityJson = {
   id: string;
@@ -327,6 +409,15 @@ export function isJsonProp(p: unknown): p is JsonProp {
 export function isVirtualProp(p: unknown): p is VirtualProp {
   return (p as VirtualProp)?.type === "virtual";
 }
+export function isVectorSingleProp(p: unknown): p is VectorProp {
+  return (p as VectorProp)?.type === "vector";
+}
+export function isVectorArrayProp(p: unknown): p is VectorArrayProp {
+  return (p as VectorArrayProp)?.type === "vector[]";
+}
+export function isVectorProp(p: unknown): p is VectorProp | VectorArrayProp {
+  return isVectorSingleProp(p) || isVectorArrayProp(p);
+}
 export function isRelationProp(p: unknown): p is RelationProp {
   return (p as RelationProp)?.type === "relation";
 }
@@ -439,7 +530,10 @@ export type MigrationColumnType =
   | "date[]"
   | "uuid"
   | "uuid[]"
-  | "json";
+  | "json"
+  | "vector"
+  | "vector[]"
+  | "tsvector";
 export type MigrationColumn = {
   name: string;
   type: MigrationColumnType;
@@ -449,12 +543,21 @@ export type MigrationColumn = {
   defaultTo?: string;
   precision?: number;
   scale?: number;
+  dimensions?: number;
+  generated?: GeneratedColumn;
 };
 export type MigrationIndex = {
+  type: "unique" | "index" | "fulltext" | "hnsw" | "ivfflat";
+  columns: EntityIndexColumn[];
   name: string;
-  columns: string[];
-  type: "unique" | "index" | "fulltext";
   parser?: "built-in" | "ngram";
+  nullsNotDistinct?: boolean;
+  /** HNSW (Hierarchical Navigable Small World): 각 노드의 최대 연결 수 */
+  m?: number;
+  /** HNSW (Hierarchical Navigable Small World): 구성 시 탐색 범위 */
+  efConstruction?: number;
+  /** IVFFlat (Inverted File with Flat Compression): 클러스터링 리스트 수 */
+  lists?: number;
 };
 export type MigrationForeign = {
   columns: string[];
@@ -698,7 +801,8 @@ export type RenderingNode = {
     | "array-images"
     | "object"
     | "object-pick"
-    | "record";
+    | "record"
+    | "vector";
   zodType: z.ZodTypeAny;
   element?: RenderingNode;
   children?: RenderingNode[];
@@ -709,12 +813,18 @@ export type RenderingNode = {
   nullable?: boolean;
 };
 
+const GeneratedColumnSchema = z.object({
+  type: z.enum(["STORED", "VIRTUAL"]),
+  expression: z.string(),
+});
+
 const BasePropFields = {
   name: z.string(),
   desc: z.string().optional(),
   nullable: z.boolean().optional(),
-  toFilter: z.literal(true).optional(),
+  toFilter: z.boolean().default(false).optional(),
   dbDefault: z.union([z.string(), z.number(), z.boolean()]).optional(),
+  generated: GeneratedColumnSchema.optional(),
 };
 
 // 부가 필드가 필요없는 prop
@@ -764,6 +874,7 @@ const EnumPropSchema = z
     ...BasePropFields,
     type: z.literal("enum"),
     id: z.string(),
+    length: z.number().optional(),
   })
   .strict();
 const EnumArrayPropSchema = z
@@ -822,6 +933,21 @@ const VirtualPropSchema = z
   })
   .strict();
 
+const VectorPropSchema = z
+  .object({
+    ...BasePropFields,
+    type: z.literal("vector"),
+    dimensions: z.number(),
+  })
+  .strict();
+const VectorArrayPropSchema = z
+  .object({
+    ...BasePropFields,
+    type: z.literal("vector[]"),
+    dimensions: z.number(),
+  })
+  .strict();
+
 // Relation 타입은 relationType에 따라 세분화
 const BaseRelationFields = {
   ...BasePropFields,
@@ -910,27 +1036,84 @@ const NormalPropTypes = [
   "uuid[]",
   "json",
   "virtual",
+  "vector",
+  "vector[]",
+] as const;
+
+// VIRTUAL Generated Column에서 사용 불가능한 타입들
+const VirtualGeneratedDisallowedTypes = [
+  "json",
+  "vector",
+  "vector[]",
+  "string[]",
+  "integer[]",
+  "bigInteger[]",
+  "boolean[]",
+  "date[]",
+  "uuid[]",
+  "number[]",
+  "numeric[]",
+  "enum[]",
 ] as const;
-export const NormalPropSchema = z.discriminatedUnion(
-  "type",
-  [
-    BasePropFieldsWithoutAdditional,
-    StringPropSchema,
-    StringArrayPropSchema,
-    EnumPropSchema,
-    EnumArrayPropSchema,
-    NumberPropSchema,
-    NumberArrayPropSchema,
-    NumericPropSchema,
-    NumericArrayPropSchema,
-    JsonPropSchema,
-    VirtualPropSchema,
-  ],
-  {
-    error: (iss) =>
-      `type은 ${NormalPropTypes.map((t) => `'${t}'`).join(", ")} 중 하나여야 합니다. 입력값: "${(iss.input as Record<string, unknown>)?.type}"`,
-  },
-);
+
+export const NormalPropSchema = z
+  .discriminatedUnion(
+    "type",
+    [
+      BasePropFieldsWithoutAdditional,
+      StringPropSchema,
+      StringArrayPropSchema,
+      EnumPropSchema,
+      EnumArrayPropSchema,
+      NumberPropSchema,
+      NumberArrayPropSchema,
+      NumericPropSchema,
+      NumericArrayPropSchema,
+      JsonPropSchema,
+      VirtualPropSchema,
+      VectorPropSchema,
+      VectorArrayPropSchema,
+    ],
+    {
+      error: (iss) =>
+        `type은 ${NormalPropTypes.map((t) => `'${t}'`).join(", ")} 중 하나여야 합니다. 입력값: "${(iss.input as Record<string, unknown>)?.type}"`,
+    },
+  )
+  .superRefine((data, ctx) => {
+    if (!data.generated) {
+      return;
+    }
+
+    // dbDefault와 generated 동시 사용 불가
+    if (data.dbDefault !== undefined) {
+      ctx.addIssue({
+        code: "custom",
+        message: "dbDefault와 generated는 함께 사용할 수 없습니다",
+        path: ["generated"],
+      });
+    }
+
+    // virtual 타입은 generated 불가
+    if (data.type === "virtual") {
+      ctx.addIssue({
+        code: "custom",
+        message: "virtual 타입은 generated column을 지원하지 않습니다",
+        path: ["generated"],
+      });
+    }
+
+    // VIRTUAL Generated Column 타입 제한 검증
+    if (data.generated.type === "VIRTUAL") {
+      if ((VirtualGeneratedDisallowedTypes as readonly string[]).includes(data.type)) {
+        ctx.addIssue({
+          code: "custom",
+          message: `VIRTUAL generated column은 ${data.type} 타입을 지원하지 않습니다. STORED를 사용하세요.`,
+          path: ["generated", "type"],
+          fatal: true,
+        });
+      }
+    }
+  });
 
 const AllPropTypes = [...NormalPropTypes, "relation"] as const;
 const EntityPropSchema = z.discriminatedUnion("type", [NormalPropSchema, RelationPropSchema], {
@@ -938,13 +1121,24 @@ const EntityPropSchema = z.discriminatedUnion("type", [NormalPropSchema, Relatio
     `type은 ${AllPropTypes.map((t) => `'${t}'`).join(", ")} 중 하나여야 합니다. 입력값: "${(iss.input as Record<string, unknown>)?.type}"`,
 });
 
+const EntityIndexColumnSchema = z.object({
+  name: z.string(),
+  nullsFirst: z.boolean().optional(),
+  sortOrder: z.enum(["ASC", "DESC"]).optional(),
+  vectorOps: z.enum(["vector_cosine_ops", "vector_ip_ops", "vector_l2_ops"]).optional(),
+});
+
 // EntityIndex 스키마 정의
 const EntityIndexSchema = z
   .object({
-    type: z.enum(["index", "unique", "fulltext"]),
-    columns: z.array(z.string()),
+    type: z.enum(["index", "unique", "fulltext", "hnsw", "ivfflat"]),
+    columns: z.array(EntityIndexColumnSchema),
     name: z.string().min(1).max(63),
     parser: z.enum(["built-in", "ngram"]).optional(),
+    nullsNotDistinct: z.boolean().optional(),
+    m: z.number().optional(),
+    efConstruction: z.number().optional(),
+    lists: z.number().optional(),
   })
   .strict();
 
@@ -1121,6 +1315,8 @@ export type RelationNode = {
 
 // biome-ignore lint/suspicious/noEmptyInterface: sonamu.generated.sso 에서 확장을 위해 준비된 빈 인터페이스
 export interface DatabaseSchemaExtend {}
+// biome-ignore lint/suspicious/noEmptyInterface: sonamu.generated.sso 에서 확장을 위해 준비된 빈 인터페이스
+export interface DatabaseForeignKeys {}
 export type ManyToManyBaseSchema<FromIdKey extends string, ToIdKey extends string> = {
   id: number;
 } & {
@@ -1149,22 +1345,4 @@ export type SonamuFastifyConfig = {
       options: ApiDecoratorOptions;
     },
   ) => void;
-  cache?: {
-    get: (key: string) => Promise<unknown | null>;
-    put: (key: string, value: unknown, ttl?: number) => Promise<void>;
-    resolveKey: (
-      path: string,
-      reqBody: {
-        [key: string]: unknown;
-      },
-    ) =>
-      | {
-          cache: false;
-        }
-      | {
-          cache: true;
-          key: string;
-          ttl?: number;
-        };
-  };
 };

package/src/vector/chunking.ts

@@ -0,0 +1,115 @@
+import { DEFAULT_VECTOR_CONFIG } from "./config";
+import type { Chunk, ChunkingConfig } from "./types";
+
+/**
+ * 텍스트 청킹
+ * - 현재 가이드에서는 400토큰 이하만 저장하므로 기본적으로 사용하지 않음
+ * - 추후 긴 문서 처리 시 사용
+ */
+export class Chunking {
+  private config: ChunkingConfig;
+
+  constructor(config: Partial<ChunkingConfig> = {}) {
+    this.config = { ...DEFAULT_VECTOR_CONFIG.chunking, ...config };
+  }
+
+  /**
+   * 텍스트를 청크로 분할
+   */
+  chunk(text: string): Chunk[] {
+    if (text.length < this.config.skipThreshold) {
+      return [
+        {
+          index: 0,
+          text: text.trim(),
+          startOffset: 0,
+          endOffset: text.length,
+        },
+      ];
+    }
+
+    const chunks: Chunk[] = [];
+    let currentPosition = 0;
+
+    while (currentPosition < text.length) {
+      const remainingText = text.slice(currentPosition);
+      const { chunk, length } = this.extractChunk(remainingText);
+
+      if (chunk.trim().length >= this.config.minChunkSize) {
+        chunks.push({
+          index: chunks.length,
+          text: chunk.trim(),
+          startOffset: currentPosition,
+          endOffset: currentPosition + length,
+        });
+      }
+
+      const advance = Math.max(length - this.config.chunkOverlap, this.config.minChunkSize);
+      currentPosition += advance;
+    }
+
+    return chunks;
+  }
+
+  /**
+   * 청킹이 필요한지 확인
+   */
+  needsChunking(text: string): boolean {
+    return text.length > this.config.chunkSize;
+  }
+
+  /**
+   * 예상 청크 수 계산
+   */
+  estimateChunkCount(text: string): number {
+    if (text.length <= this.config.chunkSize) {
+      return 1;
+    }
+    const effectiveChunkSize = this.config.chunkSize - this.config.chunkOverlap;
+    return Math.ceil(text.length / effectiveChunkSize);
+  }
+
+  private extractChunk(text: string): { chunk: string; length: number } {
+    if (text.length <= this.config.chunkSize) {
+      return { chunk: text, length: text.length };
+    }
+
+    for (const separator of this.config.separators) {
+      const result = this.splitBySeparator(text, separator);
+      if (result) return result;
+    }
+
+    return {
+      chunk: text.slice(0, this.config.chunkSize),
+      length: this.config.chunkSize,
+    };
+  }
+
+  private splitBySeparator(
+    text: string,
+    separator: string,
+  ): { chunk: string; length: number } | null {
+    const searchRange = text.slice(0, this.config.chunkSize + 100);
+
+    let lastIndex = -1;
+    let index = 0;
+
+    while (true) {
+      index = searchRange.indexOf(separator, index);
+      if (index === -1) break;
+      if (index <= this.config.chunkSize) {
+        lastIndex = index + separator.length;
+      }
+      index++;
+    }
+
+    if (lastIndex > this.config.minChunkSize) {
+      return {
+        chunk: text.slice(0, lastIndex),
+        length: lastIndex,
+      };
+    }
+
+    return null;
+  }
+}

package/src/vector/config.ts

@@ -0,0 +1,68 @@
+import type { VectorConfig } from "./types";
+
+/**
+ * 벡터 검색 기본 설정
+ * 사용자는 이 설정을 override하여 커스터마이즈할 수 있음
+ */
+export const DEFAULT_VECTOR_CONFIG: VectorConfig = {
+  // Voyage AI 설정
+  // apiKey는 Sonamu.secrets에서 로드되므로 여기서는 빈 문자열
+  voyage: {
+    apiKey: "",
+    baseUrl: "https://api.voyageai.com/v1/embeddings",
+    model: "voyage-3",
+    dimensions: 1024,
+    maxTokens: 32000,
+    batchSize: 100,
+  },
+
+  // OpenAI 설정
+  // apiKey는 Sonamu.secrets에서 로드되므로 여기서는 빈 문자열
+  openai: {
+    apiKey: "",
+    baseUrl: "https://api.openai.com/v1/embeddings",
+    model: "text-embedding-3-small",
+    dimensions: 1536,
+    maxTokens: 8191,
+    batchSize: 100,
+  },
+
+  // 청킹 설정 (필요시 사용)
+  chunking: {
+    chunkSize: 500,
+    chunkOverlap: 50,
+    minChunkSize: 50,
+    skipThreshold: 200,
+    separators: ["\n\n", "\n", "。", ". ", "! ", "? ", ", ", " "],
+  },
+
+  // 검색 설정
+  search: {
+    defaultLimit: 10,
+    similarityThreshold: 0.5,
+    vectorWeight: 0.7,
+    ftsWeight: 0.3,
+  },
+
+  // pgvector 설정
+  pgvector: {
+    iterativeScan: true,
+    efSearch: 100,
+  },
+};
+
+/**
+ * 설정 생성 헬퍼 함수
+ * 부분 설정만 제공하면 나머지는 기본값 사용
+ */
+export function createVectorConfig(
+  overrides: Partial<VectorConfig> = {}
+): VectorConfig {
+  return {
+    voyage: { ...DEFAULT_VECTOR_CONFIG.voyage, ...overrides.voyage },
+    openai: { ...DEFAULT_VECTOR_CONFIG.openai, ...overrides.openai },
+    chunking: { ...DEFAULT_VECTOR_CONFIG.chunking, ...overrides.chunking },
+    search: { ...DEFAULT_VECTOR_CONFIG.search, ...overrides.search },
+    pgvector: { ...DEFAULT_VECTOR_CONFIG.pgvector, ...overrides.pgvector },
+  };
+}