IMean Cassandra ORM (v2)

基于 Zod 的 Cassandra ORM，提供类型安全的 schema 定义、CQL 编译、schema 同步与可选的 ClickHouse 双写。

特性

• 类型安全：基于 Zod 的 schema 验证与类型推断
• 自动 CQL 生成：CRUD 与查询条件自动编译
• Schema 同步：自动创建与迁移表结构（含索引）
• 可选双写：best‑effort 写入 ClickHouse
• 向量搜索：支持 ANN 向量检索

安装

npm install imean-cassandra-orm

快速开始

1) 定义 Schema

import { z } from "zod";
import { defineTable, Types } from "imean-cassandra-orm";

const userSchema = defineTable({
  keyspace: "my_keyspace",
  tableName: "users",
  fields: {
    user_id: z.string(),
    email: z.string().email(),
    name: z.string(),
    age: z.number().int().positive(),
    is_active: z.boolean(),
    metadata: Types.json(),
    created_at: z.date(),
  },
  partitionKey: ["user_id"],
});

2) 初始化 Client（推荐简化方式）

import { createClientV2 } from "imean-cassandra-orm";

const { client, shutdown } = await createClientV2({
  cassandra: {
    contactPoints: ["127.0.0.1"],
    localDataCenter: "datacenter1",
  },
  clickhouse: {
    config: {
      host: "127.0.0.1",
      port: 8123,
      username: "default",
      password: "localpass",
      database: "default",
    },
  },
});

3) 基本 CRUD

const userModel = client.model(userSchema);
await userModel.syncSchema();

await userModel.insert({
  user_id: "u1",
  email: "[email protected]",
  name: "Alice",
  age: 20,
  is_active: true,
  metadata: { score: 95 },
  created_at: new Date(),
});

const found = await userModel.findOne({ user_id: "u1" });
await userModel.update({ user_id: "u1" }, { name: "Bob" });
await userModel.delete({ user_id: "u1" });

Schema 同步

await userModel.syncSchema(); // 自动创建/迁移表结构

查询语法

详见 QUERY_SYNTAX.md。

向量搜索

const vectorSchema = defineTable({
  keyspace: "my_keyspace",
  tableName: "docs",
  fields: {
    id: z.string(),
    embedding: Types.vector(128),
    title: z.string(),
  },
  partitionKey: ["id"],
  indexes: {
    embedding: { similarity_function: "COSINE" },
  },
});

const model = client.model(vectorSchema);
await model.syncSchema();

const results = await model.find(
  { embedding: new Array(128).fill(0).map(() => Math.random()) },
  { limit: 10 }
);

关闭连接

await shutdown();