fandhe-db

fandhe-db

fandhe-db 是一款使用 Rust 构建、本地优先、专为向量设计的查询数据库。它由一个包含 2 个 crate 的工作区组成：fandhe-db-engine（核心引擎、SQL 表层、HNSW/BM25/混合搜索、redb 持久化、RLS）和 fandhe-db-wire-server（兼容 PostgreSQL wire protocol v3 的二进制文件）。它可以接受未经修改的 psql / psycopg / pg 客户端连接，并执行包含 USING PLAN / USING OPERATION_ID 扩展语法的 SQL。0.2.0 的表层如下。

• SQL：DDL（CREATE / ALTER / DROP TABLE、VIEW、INDEX、TYPE 及约束）、JOIN / CTE / 子查询 / 集合运算 / 窗口函数
• wire：显式事务、游标、COPY、扩展查询协议、TLS 1.3、SCRAM-SHA-256
• NoSQL：通过 --surface nosql 启用的 HTTP/1.1 JSON NoSQL 表层（POST /v1/session / POST /v1/query）

目标版本为 fandhe-db-engine / fandhe-db-wire-server 的 crates.io 0.2.0（2026-10-08 发布，是从旧名 fandhe-vector-db-* 0.1.0 更名后的首个版本；没有 tag / release，固定到 publish commit SHA dc888f6ea146d3078153d64a6848f5c8cf044431）。旧名 fandhe-vector-db-engine / fandhe-vector-db-wire-server 的 0.1.0 仍保留在 crates.io 上，但不会更新。crate 名称、环境变量名称以及 ValidatedInsert / BoundInsertForm 的迁移，请参阅 references/getting-started/migration-0-2.md。lib 名称 engine / wire_server 和二进制名称 wire-server 保持不变。

该项目没有官方文档网站；来源包括公开仓库 https://github.com/Fandhe-AI/fandhe-db 的 README、CHANGELOG、docs/design/ ADR，以及 crates.io 的 .crate tarball（第一手来源）。docs.rs 上的 fandhe-db-engine/0.2.0 也提供已渲染的 rustdoc 页面，但签名的依据应以 tarball 中的 src/ 为准。

规格说明的定位 — 规格说明的事实来源是私有仓库 Fandhe-AI/fandhe-db-spec（非公开），本技能无法访问该仓库，因此仅涵盖可从公开来源和公开 ADR 追踪的内容。crate 源码中的 doc comment（rustdoc）以日语编写，references 正文会用日语概述，签名（类型和标识符）部分则逐字以英语转录。对于仅留下私有 spec 参考 ID 的行为，各页面的 ## Notes 中会明确注明「因 spec 未公开而未记载」。

与其他技能的区分 — upstash 是 @upstash/vector 托管 SaaS 客户端（REST 向量 API），supabase 则是使用 pgvector 扩展和 Postgres RLS 的客户端；两者都不是向量数据库引擎本身。mssql / drizzle / supabase 是 SQL 客户端 / ORM，与本技能的 SQL 表层（USING PLAN 等扩展语法，以及数据库侧实现的 DDL、JOIN、CTE、事务）不同。nosql-surface/ 的 HTTP JSON 表层是数据库引擎提供的 API，与 upstash（SaaS 的 REST 客户端）和 fandhe-backend（Rust HTTP 服务框架）不同。本技能的 performance/ 涉及 CPU SIMD（isa / dispatch）以及通过 wgpu 实现的 GPU 批处理内核，不是 nvidia-cuda / apple-silicon / amd-rocm 所涵盖的 GPU 语言与运行时层（CUDA / MSL / HIP）的参考资料。fandhe-ai / fandhe-backend / fandhe-frontend 是同属 fandhe org 的其他库，与本项目的 API 无关；如需了解向量数据库引擎本身，请参阅本技能（fandhe-db）。

目录结构

skills/fandhe-db/
  SKILL.md
  references/
    getting-started/
      README.md
      overview.md
      crate-layout.md
      lib.md
      core.md
      error-format.md
      development-setup.md
      migration-0-2.md
      json.md
    sql/
      README.md
      sql-module.md
      lexer.md
      parser.md
      allowlist.md
      using-plan.md
      using-operation-id.md
      mode.md
      explain.md
      plan.md
      scan.md
      copy.md
      cursor.md
      params.md
      statement-splitter.md
      transaction.md
      declarative-predicate.md
      ddl-column-type.md
      where-tree.md
      where-negation.md
      describe.md
      cte.md
      relation.md
    sql-execution/
      README.md
      exec.md
      aggregate.md
      group-by.md
      expr-program.md
      scalar-index.md
      scalar-plan.md
      udf-call.md
      arena-cache.md
      hnsw-cache.md
      hnsw-hybrid.md
      sparse-cache.md
      visible-cache.md
      ddl.md
      check-constraint.md
      view.md
      view-buffered.md
      join.md
      set-op.md
      subquery.md
      window.md
      partitioned.md
      returning.md
      relation-snapshot.md
      generation-key.md
      order-value.md
      distinct.md
      string-fn.md
      numeric-fn.md
      datetime-fn.md
    search/
      README.md
      search-engine.md
      hnsw.md
      sparse.md
      hybrid.md
      rerank.md
      scoring-boost.md
      precision.md
      query-planner.md
      tiering.md
    storage/
      README.md
      storage.md
      row-codec.md
      catalog.md
      txn.md
      recovery.md
      incremental.md
      arena.md
      buffer-pool.md
      constraint.md
      column-rewrite.md
      bytea.md
      uuid.md
      key-index.md
      datetime.md
      numeric.md
      scalar-float.md
    security/
      README.md
      policy.md
      rls.md
      tenant.md
      crypto.md
    wire-server/
      README.md
      main-cli.md
      server.md
      handshake.md
      auth.md
      bind-guard.md
      framing.md
      protocol-dispatch.md
      simple-query.md
      result-encoder.md
      response-buffer.md
      error-response.md
      limits.md
      search-engine-opt.md
      lib.md
      extended-query.md
      binary-param.md
      copy.md
      wire-stream.md
      tls.md
      tls-opt.md
      auth-method-opt.md
      surface.md
      durability-opt.md
      dml-limits-opt.md
      ddl-permission-opt.md
      hnsw-scope-opt.md
    nosql-surface/
      README.md
      overview.md
      session.md
      query-common.md
      op-search.md
      op-scan.md
      op-aggregate.md
      op-insert.md
      op-update-delete.md
      partitioned-dml.md
      ddl.md
      filter.md
      explain.md
      response-schema.md
      sql-nosql-mapping.md
      error-response.md
      http-module.md
    performance/
      README.md
      kernel.md
      isa.md
      dispatch.md
      gpu-batch.md
      batch-search.md
      batch-fallback.md
      batch-limits.md
      parallel-search.md
      f16.md
      sq8.md
    extensions/
      README.md
      wasm-udf.md
      declarative-filter.md
      embedding.md
      chunking.md
      dictionary.md
  samples/
    README.md
    start-wire-server.md
    connect-psql.md
    connect-psycopg.md
    connect-node-pg.md
    connect-extended-query.md
    connect-http-curl.md
    txn-status.md
    e2e-three-client.md
    e2e-three-client-http.md
    e2e-three-client-tls.md
    docker-compose.md
  scripts/
    README.md
    install.md
    make-targets.md
    run-wire-server.md

探索步骤

根据任务查找类别，并在类别的 README.md 中确定目标页面：

1. 在下方映射表中查找与任务对应的类别
2. 参阅该类别的 references/{category}/README.md，确定目标页面
3. 读取相应的 .md 页面以查看详情

タスク → カテゴリ マッピング

タスク	カテゴリ	参照 README
リポジトリの位置づけ・crate 構成・features・依存、engine クレートルート・VectorCore/EngineCore コア API、JSON 値、ErrorClass/WireError の wire_code 写像、開発環境構築・Makefile、0.1.0 → 0.2.0 移行（crate 改名・環境変数改名）を知りたい	getting-started	references/getting-started/README.md
SQL 表層のトークナイザ・意味論束縛・AST 許可リスト、USING PLAN / USING OPERATION_ID / HINT ORDER 拡張構文、recall/precision モード解決、EXPLAIN 応答、DDL 列型、CTE、リレーション、WHERE 木・否定、トランザクション文、カーソル、COPY、バインドパラメータ、文分割を知りたい	sql	references/sql/README.md
SQL 実行計画本体（RLS→SCALAR→DISTANCE 順）、集計・GROUP BY、DDL 実行・CHECK 制約、VIEW、JOIN、集合演算、サブクエリ、ウィンドウ関数、RETURNING、DISTINCT、文字列・数値・日時関数、式ステップコンパイル、スカラー二次索引、宣言的 UDF 呼び出し、世代整合キャッシュを知りたい	sql-execution	references/sql-execution/README.md
検索エンジン選択・構築、HNSW 近似最近傍探索、BM25 転置索引、RRF hybrid 融合、リランキング、宣言的スコアリングブースト、precision 確信度ゲート、LLM クエリプランニング・ティアリングを知りたい	search	references/search/README.md
redb ベース永続化層、行エンコーダー、スキーマカタログ、制約・列書き換え、列型（bytea / uuid / numeric / datetime / float）、キー索引、トランザクションハンドル、障害回復・commit_boundary・ledger、増分インデックス反映、ベクトルアリーナ、バッファプールを知りたい	storage	references/storage/README.md
テナント境界・可視性文脈の構築判定、RLS 暗黙適用フックと可視行限定検索、行ストア統合層の参照実装、パスワード・鍵の暗号処理を知りたい	security	references/security/README.md
wire-server バイナリの CLI フラグ・起動、接続受け付けループ、StartupMessage/認証フロー、Argon2id・SCRAM-SHA-256 認証方式、TLS 1.3、メッセージフレーミング、簡易クエリ・拡張クエリプロトコル、バイナリパラメータ、COPY、応答バイト列生成、ErrorResponse 横断写像、タイムアウト・同時接続数制御、--surface 選択、各種 *-opt 起動オプションを知りたい	wire-server	references/wire-server/README.md
--surface nosql の HTTP/1.1 JSON NoSQL 表層、POST /v1/session / POST /v1/query の op 別 JSON スキーマ（search / scan / aggregate / insert / update・delete / DDL / explain）、filter、レスポンススキーマ、SQL との対応、エラー射影を知りたい	nosql-surface	references/nosql-surface/README.md
検索カーネル境界・CPU 参照実装、SIMD 実行時検出・ディスパッチ決定表、wgpu GPU バッチ検索、CPU-SIMD への縮退フォールバック、一括投入上限、並列 Top-k、f16/i8(SQ8) 量子化を知りたい	performance	references/performance/README.md
WASM UDF サンドボックス実行契約、宣言的メタデータフィルタ、埋め込み変換注入点、チャンク分割、シンボル・タームインデックス抽出を知りたい	extensions	references/extensions/README.md
wire-server の起動方法、無改造 psql/psycopg/pg クライアントからの接続例、拡張クエリ接続、HTTP（curl）接続、トランザクション状態、3 クライアント e2e ハーネス（wire / HTTP / TLS）、Docker 開発環境など典型的な使い方を知りたい	samples	samples/README.md
開発環境構築・Makefile タスク・wire-server 起動コマンドなどインストール・CLI コマンドを知りたい	scripts	scripts/README.md