pgvector × TypeScript × Drizzle ORM × Next.js で作る型安全なベクトル検索（Server Actions・Zod境界検証）

npm i drizzle-orm postgres
npm i -D drizzle-kit
# 埋め込み生成に OpenAI を使う例（任意のプロバイダでよい）
npm i openai

// db/schema.ts
import { sql } from "drizzle-orm";
import {
  bigint,
  index,
  jsonb,
  pgTable,
  text,
  timestamp,
  vector,
} from "drizzle-orm/pg-core";

/** ドキュメントのチャンク（分割片）と埋め込みを格納するテーブル。 */
export const docChunks = pgTable(
  "doc_chunks",
  {
    id: bigint("id", { mode: "number" }).primaryKey().generatedAlwaysAsIdentity(),
    documentId: bigint("document_id", { mode: "number" }).notNull(),
    content: text("content").notNull(),
    // 次元はモデルに合わせる（例: text-embedding-3-large を dimensions=1024 で運用）
    embedding: vector("embedding", { dimensions: 1024 }).notNull(),
    metadata: jsonb("metadata").$type<Record<string, string>>().notNull().default({}),
    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
  },
  (table) => [
    // HNSW インデックス。演算子クラスは検索する距離に合わせる（コサインなら vector_cosine_ops）
    index("doc_chunks_embedding_idx").using(
      "hnsw",
      table.embedding.op("vector_cosine_ops"),
    ),
    // メタデータでのフィルタ用（テナント・カテゴリ等）
    index("doc_chunks_metadata_idx").using("gin", table.metadata),
  ],
);

export type DocChunk = typeof docChunks.$inferSelect;
export type NewDocChunk = typeof docChunks.$inferInsert;

// db/migrate.ts（マイグレーション実行の入口）
import { drizzle } from "drizzle-orm/postgres-js";
import { migrate } from "drizzle-orm/postgres-js/migrator";
import { sql } from "drizzle-orm";
import postgres from "postgres";

const connectionString = process.env.DATABASE_URL;
if (!connectionString) throw new Error("DATABASE_URL is not set"); // 起動時に明示的に失敗させる

const client = postgres(connectionString, { max: 1 });
const db = drizzle(client);

// ① 拡張を先に有効化（冪等。IF NOT EXISTS で再実行しても安全）
await db.execute(sql`CREATE EXTENSION IF NOT EXISTS vector`);
// ② スキーマ・インデックスのマイグレーションを適用
await migrate(db, { migrationsFolder: "./drizzle" });

await client.end();

// db/search.ts
import { cosineDistance, desc, gt, sql } from "drizzle-orm";
import { db } from "./client";
import { docChunks } from "./schema";

/** クエリ埋め込みに意味が近いチャンクを上位 k 件返す（型安全・パラメータバインド）。 */
export async function searchChunks(queryEmbedding: number[], limit = 5) {
  // cosineDistance(列, クエリ埋め込み) → SQL式。1 - 距離 = 類似度（0〜1, 大きいほど近い）
  const similarity = sql<number>`1 - (${cosineDistance(docChunks.embedding, queryEmbedding)})`;

  return db
    .select({
      id: docChunks.id,
      content: docChunks.content,
      similarity, // ← number として型付く
    })
    .from(docChunks)
    .where(gt(similarity, 0.3)) // 類似度の下限でノイズを足切り（値は計測で調整）
    .orderBy((t) => desc(t.similarity)) // 近い順。HNSW インデックスが効く形
    .limit(limit);
}

import { db } from "./client";
import { docChunks } from "./schema";

await db.insert(docChunks).values({
  documentId: 1,
  content: "返品は購入後30日以内に対応します。",
  embedding: [0.012, -0.041, 0.98 /* … 長さは dimensions=1024 と一致 */],
  metadata: { tenantId: "acme", category: "faq" },
});

// app/search/actions.ts
"use server";

import { z } from "zod";
import OpenAI from "openai";
import { searchChunks } from "@/db/search";

const openai = new OpenAI(); // APIキーは環境変数 OPENAI_API_KEY（ハードコード禁止）

// 境界バリデーション：信頼できない入力を最初に narrow する
const QuerySchema = z.object({
  q: z.string().trim().min(1, "検索語を入力してください").max(500),
});

export type SearchResult = {
  id: number;
  content: string;
  similarity: number;
};

/** クエリ文字列 → 埋め込み → pgvector 検索。失敗は型で表現する（throw しない）。 */
export async function search(
  formData: FormData,
): Promise<{ ok: true; results: SearchResult[] } | { ok: false; error: string }> {
  const parsed = QuerySchema.safeParse({ q: formData.get("q") });
  if (!parsed.success) {
    return { ok: false, error: parsed.error.issues[0]?.message ?? "入力が不正です" };
  }

  // クエリを埋め込みに変換（列の dimensions と必ず一致させる）
  const embedRes = await openai.embeddings.create({
    model: "text-embedding-3-large",
    input: parsed.data.q,
    dimensions: 1024, // ← vector(1024) と一致
  });
  const queryEmbedding = embedRes.data[0]?.embedding;
  if (!queryEmbedding) return { ok: false, error: "埋め込み生成に失敗しました" };

  const results = await searchChunks(queryEmbedding, 5);
  return { ok: true, results };
}

// app/search/search-form.tsx
"use client";

import { useActionState } from "react";
import { search, type SearchResult } from "./actions";

type State = { ok: true; results: SearchResult[] } | { ok: false; error: string } | null;

export function SearchForm() {
  const [state, formAction, isPending] = useActionState<State, FormData>(
    (_prev, formData) => search(formData),
    null,
  );

  return (
    <section aria-labelledby="search-heading">
      <h2 id="search-heading">ドキュメント検索</h2>

      <form action={formAction} role="search">
        <label htmlFor="q">検索語</label>
        <input id="q" name="q" type="search" required maxLength={500} autoComplete="off" />
        <button type="submit" disabled={isPending} aria-busy={isPending}>
          {isPending ? "検索中…" : "検索"}
        </button>
      </form>

      {/* 非同期の結果・エラーを支援技術に通知（視覚的にも論理的にも一貫） */}
      <div aria-live="polite" aria-atomic="true">
        {state?.ok === false && <p role="alert">{state.error}</p>}
        {state?.ok === true &&
          (state.results.length === 0 ? (
            <p>一致する結果はありませんでした。</p>
          ) : (
            <ul>
              {state.results.map((r) => (
                <li key={r.id}>
                  <p>{r.content}</p>
                  {/* 類似度はパーセント表記で意味を明示 */}
                  <span aria-label={`類似度 ${Math.round(r.similarity * 100)}パーセント`}>
                    {Math.round(r.similarity * 100)}%
                  </span>
                </li>
              ))}
            </ul>
          ))}
      </div>
    </section>
  );
}

-- drizzle/0001_hnsw_index.sql（手書きマイグレーション）
CREATE INDEX IF NOT EXISTS doc_chunks_embedding_idx
    ON doc_chunks
    USING hnsw (embedding vector_cosine_ops)
    WITH (m = 16, ef_construction = 64);

// または TS マイグレーション内で
await db.execute(sql`
  CREATE INDEX IF NOT EXISTS doc_chunks_embedding_idx
  ON doc_chunks USING hnsw (embedding vector_cosine_ops)
  WITH (m = 16, ef_construction = 64)
`);