Tablestore ODM

Tablestore ODM 是一个基于 阿里云表格存储 (Tablestore) 的对象文档映射 (ODM) 库，旨在简化与 Tablestore 的交互，提供更直观、类型安全的数据操作体验。

特性

- Schema 定义： 使用 Zod 进行数据模型定义和验证，确保数据类型安全。
- 模型抽象： 将 Tablestore 表映射为 JavaScript 类，提供 CRUD 方法。
- 查询构建器： 提供链式调用的查询构建器，支持范围查询和多元索引查询。
- 范围查询 (Range Query): 使用 startWith 和 endAt 指定范围，支持正向和反向查询，可设置 limit 限制返回数量，使用 filter 进行服务端过滤。
- 多元索引查询 (Search Query): 支持全文检索、精确匹配、前缀匹配、范围查询、通配符查询、地理位置查询等多种查询类型，并支持排序、分页和结果折叠。
- 类型安全： 充分利用 TypeScript 的类型推断，减少运行时错误。
- 连接管理： 统一管理 Tablestore 客户端连接。
- 灵活配置： 支持自定义配置，并允许透传 Tablestore SDK 的其他选项。
- 批量操作： 支持 insertMany 和 deleteMany 进行批量插入和删除操作。
- GSI 支持： 支持全局二级索引 (GSI) 的查询。
- 字段类型转换： 自动处理 JavaScript 类型与 Tablestore 类型的转换，例如 number 到 Long，Date 到时间戳等。

安装

``bash
npm install tablestore-odm

`

使用

$3

1. 定义 Schema：

`typescript
import { z } from "zod";
import { createSchema } from "tablestore-odm";

const UserSchema = z.object({
id: z.string(),
name: z.string(),
age: z.number().int().positive(),
email: z.string().email().optional(),
});

const userSchema = createSchema(UserSchema, {
primaryKeys: ["id"],
timestamps: true, // 自动管理 createdAt 和 updatedAt 字段
});
`

2. 创建 Model：

`typescript
import { Connection, createModel } from "tablestore-odm";

const connection = new Connection({
endpoint: "your_endpoint",
accessKeyId: "your_access_key_id",
secretAccessKey: "your_secret_access_key",
instancename: "your_instance_name",
});

const UserModel = createModel(
"User",
userSchema,
"your_user_table_name",
connection
);

`

`typescript

async function main() {
// 创建用户
const [createErr, createdUser] = await UserModel.create({
id: "user123",
name: "Alice",
age: 30,
email: "",
});

if (createErr) {
console.error("创建用户失败:", createErr);
return;
}

console.log("创建用户成功:", createdUser);

// 查询用户
const [findErr, foundUser] = await UserModel.findById({ id: "user123" });

if (findErr) {
console.error("查询用户失败:", findErr);
return;
}

if (foundUser) {
console.log("查询用户成功:", foundUser);

// 更新用户
const [updateErr] = await UserModel.updateById(
{ id: "user123" },
{ age: 31 }
);

if (updateErr) {
console.error("更新用户失败:", updateErr);
return;
}

console.log("更新用户成功");

// 删除用户
const [deleteErr] = await UserModel.deleteById({ id: "user123" });

if (deleteErr) {
console.error("删除用户失败:", deleteErr);
return;
}

console.log("删除用户成功");
} else {
console.log("未找到用户");
}
}

main();

`

- 范围查询

` typescript
// 查询年龄在 20 到 30 岁之间的用户
const [err, result] = await UserModel.range()
.startWith({ age: 20 })
.endAt({ age: 30 })
.filter((q) => q.greaterThanOrEqual("age", 20).lessThanOrEqual("age", 30)) // 使用 filter 进行服务端过滤
.exec();

if (err) {
console.error("范围查询失败:", err);
} else {
console.log("范围查询结果:", result?.rows);
}
`

- 多元索引查询

` typescript
// 假设有一个名为 "user_search_index" 的多元索引
const [err, result] = await UserModel.search("user_search_index")
.filter((q) => q.match("name", "Alice")) // 匹配名字包含 "Alice" 的用户
.limit(10)
.exec();

if (err) {
console.error("多元索引查询失败:", err);
} else {
console.log("多元索引查询结果:", result?.rows);
console.log("总匹配数:", result?.totalCount);
}

// 精确匹配
UserModel.search("user_search_index").filter(q => q.term("city", "Beijing")).exec();


`

$3

` typescript
// 批量插入
const [insertErr, insertedKeys] = await UserModel.insertMany([
{ id: "user4", name: "David", age: 25 },
{ id: "user5", name: "Eve", age: 28 },
]);

if (insertErr) {
console.error("批量插入失败:", insertErr);
} else {
console.log("批量插入成功，插入的主键:", insertedKeys);
}

// 批量删除
const [deleteErr, deletedKeys] = await UserModel.deleteMany([
{ id: "user4" },
{ id: "user5" },
]);

if (deleteErr) {
console.error("批量删除失败:", deleteErr);
} else {
console.log("批量删除成功，删除的主键:", deletedKeys);
}

``

许可证

MIT 许可证