@undefineds.co/drizzle-solid 0.2.6

package/README.md

@@ -0,0 +1,563 @@
+# Drizzle Solid
+
+一个为Solid Pod设计的类型安全ORM，基于Drizzle ORM构建，让您能够像操作传统数据库一样操作Solid Pod中的RDF数据。
+
+## ✨ 特性
+
+- 🔒 **类型安全**: 完整的 TypeScript 支持与严格模式提示
+- 🧭 **Drizzle 对齐**: 沿用 Drizzle ORM 的查询构建器与错误形态，降低迁移成本
+- 🌐 **Solid 实测**: CSS 集成测试覆盖 CRUD、条件组合、聚合与联结场景
+- 🔁 **智能回退**: SQL 查询自动转换为 SPARQL；当 CSS/Comunica 无法处理过滤器或聚合时由方言拉取数据并在内存中回放
+- 🔧 **灵活映射**: 自定义命名空间、谓词和列类型（字符串、数字、布尔、时间、JSON/Object）
+
+## 🔋 服务器支持
+
+drizzle-solid 支持两种 Solid 服务器：
+
+### 能力对比
+
+| 能力 | 原生 CSS | xpod |
+|------|----------|------|
+| **基础 CRUD** | ✅ LDP 模式 | ✅ LDP 模式 |
+| **SPARQL SELECT** | ❌ 不支持（Comunica 客户端执行） | ✅ 服务端索引下推 |
+| **SPARQL UPDATE** | ⚠️ 仅 BGP 写入 | ✅ 完整支持 |
+| **条件查询** (where) | Comunica 读文件到内存 | 索引下推（单 Pod） |
+| **聚合函数** (count/sum/avg) | Comunica 读文件到内存 | 索引下推（单 Pod） |
+| **GROUP BY / JOIN** | Comunica 读文件到内存 | 索引下推（单 Pod） |
+| **联邦查询** (跨 Pod) | Comunica 内存处理 | Comunica 内存处理 |
+| **SPARQL 端点** | ❌ 不支持 | ✅ `/-/sparql` Sidecar |
+| **SPARQL 1.1 覆盖率** | - | ~90% |
+
+### 原生 Community Solid Server (CSS)
+
+原生 CSS **不支持 SPARQL SELECT**，drizzle-solid 通过 **Comunica 客户端**读取文件到内存后执行查询：
+- ✅ 基本的 CRUD 操作（LDP）
+- ⚠️ 写入仅支持 BGP（Basic Graph Pattern）
+- ⚠️ 所有查询由 Comunica 客户端在内存中执行
+
+### xpod - 扩展的 CSS (推荐)
+
+**xpod** 使用 **QuintStore**（五元组存储，GSPOV）替代文件存储，通过 6 组索引实现查询下推：
+
+- ✅ **SPARQL SELECT 服务端执行**：查询下推到 QuintStore 索引
+- ✅ **Sidecar API**：`/-/sparql` 端点，权限继承自资源路径
+- ✅ **混合存储**：RDF → QuintStore 索引，非 RDF → 文件系统
+- ⚠️ **联邦查询**：跨 Pod 查询仍需 Comunica 内存处理
+- ⚠️ **SPARQL 覆盖**：约 90% W3C SPARQL 1.1 测试通过
+
+**仓库**：https://github.com/undefinedsco/xpod | **详细对比**：[xpod 特性文档](./docs/xpod-features.md)
+
+## 🚀 快速开始
+
+### 安装
+
+```bash
+yarn add drizzle-solid
+```
+
+### 基本用法
+
+```typescript
+import { drizzle } from 'drizzle-solid';
+import { podTable, string, int } from 'drizzle-solid';
+import { Session } from '@inrupt/solid-client-authn-node';
+
+// 定义表结构
+const profileTable = podTable('profile', {
+  name: string('name'),
+  email: string('email'),
+  age: int('age')
+}, {
+  // 相对 Pod 根的容器/资源路径，不需要 idp:// 前缀
+  base: '/profiles/',
+  type: 'https://schema.org/Person'
+});
+
+// 自定义 subject 模板示例：按年月目录、文件名是 id，仍指向单独文件
+const logsTable = podTable('logs', {
+  id: string('id').primaryKey(),
+  message: string('message')
+}, {
+  type: 'https://schema.org/DigitalDocument',
+  base: '/logs/',
+  subjectTemplate: '{yyyy}/{MM}/{dd}/{id}.ttl'
+});
+
+// subjectTemplate（选填）：
+// - 作用：控制每条记录主体 URI 的形态，支持占位符 {yyyy}/{MM}/{dd}/{HH}/{mm}/{ss}/{id}。
+// - 推断：未指定时按 base 判断：base 是容器（以 / 结尾且包含表名）→ document 模式；base 是具体文件 → fragment 模式。模板含 #（如 '#{id}'）也强制 fragment；其他模板按 document 处理，可用 {yyyy}/{MM}/{dd}/{id}.ttl 等。
+// - document 模式：每条记录独立文件，URI 形如 .../users/{id}.ttl，SELECT/UPDATE/DELETE 由 Comunica dereference 目标文件后本地求值；适合记录级隔离/按目录分片。
+// - fragment 模式：多条记录共享同一文件，主体是片段（.../file.ttl#{id}），SELECT 同样由 Comunica 拉取该文件求值；适合小表或聚合存放的数据。
+// - 示例：subjectTemplate: '{yyyy}/{MM}/{dd}/{id}.ttl'（document 分日期分片）；subjectTemplate: '#{id}'（fragment，共享文件）。
+
+// 创建数据库连接
+const session = new Session(); // 已认证的session
+const db = drizzle(session);
+
+// 初始化需要使用的表（创建容器、资源并注册 TypeIndex）
+await db.init([profileTable]);
+
+// 查询数据
+const profiles = await db.select().from(profileTable);
+
+// 插入数据
+await db.insert(profileTable).values({
+  name: 'Alice',
+  email: 'alice@example.com',
+  age: 30
+});
+
+// 使用 SPARQL 端点（适用于 xpod）
+const sparqlTable = podTable('posts', {
+  id: string('id').primaryKey(),
+  title: string('title'),
+}, {
+  type: 'https://schema.org/CreativeWork',
+  base: '/data/posts.ttl',                      // 资源路径
+  sparqlEndpoint: '/data/posts.ttl/-/sparql'    // xpod Sidecar 模式端点
+  // 💡 xpod 使用 Sidecar 模式：在资源路径后添加 /-/sparql 后缀
+  //    - 文件资源: /data/posts.ttl/-/sparql
+  //    - 容器: /data/users/-/sparql
+});
+await db.init([sparqlTable]); // 不会创建容器，直接使用端点执行 SPARQL UPDATE/SELECT
+await db.insert(sparqlTable).values({ id: 'post-1', title: 'Hello SPARQL' });
+
+### SPARQL Endpoint 模式兼容性说明 (重要!)
+
+当 `podTable` 配置 `sparqlEndpoint` 时，Drizzle Solid 会直接使用该端点执行所有 CRUD 操作。理解其行为模式对于数据一致性至关重要：
+
+1.  **Fragment Mode (聚合 Named Graph)**:
+    *   **定义**: 当表的 `base` 指向一个具体资源 URL (例如 `/data/posts.ttl`)，或者 `subjectTemplate` 使用片段 (例如 `'#{id}'`) 时，Drizzle Solid 会将所有数据操作集中在 `base` 对应的单一 Named Graph (`GRAPH <base_url>`) 中。
+    *   **行为**: 在此模式下，LDP 读写与 SPARQL 读写**完全兼容且互操作**。LDP 对 `base` 资源的 PATCH/GET 操作，与 SPARQL 对 `GRAPH <base_url>` 的 DML/SELECT 操作，都作用于相同的数据集，并能互相可见。**这是 SPARQL Endpoint 模式下的推荐用法**。
+    *   **示例**: `base: '/data/posts.ttl'`, `subjectTemplate: '#{id}'`。所有 posts 都存储在 `posts.ttl` 文件对应的 Named Graph 中。
+
+2.  **Document Mode (聚合视图，写操作不兼容)**:
+    *   **定义**: 当表的 `base` 指向一个容器 URL (例如 `/data/users/`)，且 `subjectTemplate` 生成文件路径 (例如 `'{id}.ttl'`) 时。
+    *   **读操作 (SELECT)**: SPARQL SELECT 查询指向容器的 `/sparql` 端点时，Community Solid Server (CSS) 会**聚合该容器内所有 LDP 子文件**的数据，形成一个统一的视图。因此，通过 LDP PUT 写入的子文件 (例如 `alice.ttl`)，**可以被 SPARQL SELECT 查询到**。
+    *   **写操作 (DML)**: SPARQL INSERT/UPDATE/DELETE 操作是针对**容器的聚合 Named Graph** (`GRAPH <container_url>`)。这些操作**不会**直接创建、修改或删除 LDP 子文件。
+        *   例如，通过 SPARQL INSERT 写入 `bob`，数据会存在容器 Graph 中，但**不会**创建 `bob.ttl` 文件 (LDP GET `/data/users/bob.ttl` 将返回 404)。
+        *   通过 SPARQL UPDATE `alice`，只会修改容器 Graph 中的 `alice` 数据（SPARQL 视图），而**不会**更新 `alice.ttl` 文件本身 (LDP GET `/data/users/alice.ttl` 将显示旧数据)。
+    *   **结论**: 在 Document Mode 下，SPARQL 读操作可以兼容 LDP 资源（因为聚合），但 **写操作与 LDP 资源的物理文件视图不兼容**。这意味着 LDP 客户端可能无法看到 SPARQL DML 操作的影响，反之亦然。**不建议混合使用 LDP Document Mode 和 SPARQL DML 操作**，除非您明确理解其数据存储的视图差异，并仅利用 SPARQL 作为聚合查询工具。
+
+
+```
+
+## 📚 示例教程
+
+我们提供了完整的示例来帮助您快速上手：
+
+### 🏗️ 示例1: 快速开始
+
+```bash
+yarn example:quick
+```
+
+这个示例展示：
+- 如何连接到 Solid Pod 并定义表结构
+- 使用 Drizzle 风格 API 执行插入、查询、更新、删除
+
+### 📖 示例2: 关系查询
+
+```bash
+yarn example:query
+```
+
+这个示例展示：
+- 如何定义表之间的关系
+- 使用 `with` 进行关联查询
+- 嵌套数据的加载方式
+
+### 🛠️ 示例3: 零配置数据发现
+
+```bash
+yarn example:discovery
+```
+
+这个示例展示：
+- 如何使用 TypeIndex 自动发现数据位置
+- SAI (Solid Application Interoperability) 数据授权
+- 无需硬编码路径的数据访问
+
+## 📖 详细文档
+
+### 表定义
+
+```typescript
+import { podTable, string, int, boolean, date, uri, eq, gte, and } from 'drizzle-solid';
+
+const userTable = podTable('users', {
+  name: string('name'),           // foaf:name
+  email: string('email'),         // foaf:mbox
+  age: int('age'),               // foaf:age
+  verified: boolean('verified'),     // 自定义谓词
+  createdAt: date('createdAt'),   // dcterms:created
+  organization: uri('organization')
+    .predicate('https://schema.org/member') // <org> schema:member <person>
+    .inverse()
+}, {
+  // 目标 Turtle 资源，必填，可以是相对 Pod 路径或绝对 URL
+  base: 'data/users.ttl',
+  // 主体类型
+  type: 'https://schema.org/Person',
+  // 可选：注册 TypeIndex（仅在提供 typeIndex 时才会尝试）
+  typeIndex: 'private' // 'public' | 'private' | undefined
+});
+
+// 初始化：在 CRUD 前确保容器/资源存在（会按 base 自动创建）
+await db.init([userTable]);
+```
+
+- 使用 `.inverse()` 可以把列映射为 `<object> predicate <subject>` 方向，适合例如 `<org> schema:member <person>` 这样的反向边；查询/写入都会自动交换 RDF 三元组的主体和宾语。
+
+### Drizzle 风格查询：`db.query` + `findByIRI`
+
+将 schema 传入 `drizzle(session, { schema })` 后，可通过 Drizzle 对齐的查询助手调用：
+
+```ts
+import * as schema from './schema';
+const db = drizzle(session, { schema });
+
+const users = await db.query.users.findMany({
+  where: { verified: true },
+  orderBy: [{ column: schema.users.name, direction: 'asc' }],
+  with: {
+    posts: true // 根据子表 referenceTarget + @id 预加载关联行
+  }
+});
+
+// 通过 IRI 查找单条记录（推荐使用 db.findByIri）
+const alice = await db.findByIri(schema.users, 'https://pod.example/data/users.ttl#alice');
+```
+
+- `findMany/findFirst/findById/count` 与 Drizzle ORM 行为一致，复用现有 `select` 管道。
+- `with` 支持基于 `reference(target)` 的引用外键（通过 `@id` 关联），结果会嵌套数组挂在相应键上。
+- `db.findByIri(table, iri)` 可直接接受绝对 IRI 或 fragment（无协议时按 `id` 匹配），推荐使用此方法。
+- TypeIndex 注册策略：仅当表配置了 `typeIndex: 'private' | 'public'` 时才会尝试写入 TypeIndex；未配置则跳过。
+
+### 支持的列类型
+
+Drizzle Solid 完全兼容所有 Drizzle ORM 数据库方言的列类型：
+
+#### 基础类型
+```typescript
+// 字符串类型
+string('name')     // 通用字符串
+text('content')    // 文本内容
+varchar('title')   // 可变长度字符串
+char('code')       // 固定长度字符串
+
+// 数字类型
+int('count')       // MySQL 风格整数
+integer('id')      // PostgreSQL 风格整数
+bigint('large')    // 大整数
+smallint('small')  // 小整数
+tinyint('tiny')    // 微整数 (MySQL)
+mediumint('medium') // 中等整数 (MySQL)
+serial('auto')     // 自增序列
+
+// 浮点数类型（内部映射为 xsd:decimal）
+real('price')      // 实数
+decimal('amount')  // 十进制数
+numeric('value')   // 数值
+float('ratio')     // 单精度浮点
+double('precise')  // 双精度浮点
+
+// 布尔类型
+boolean('active')  // 布尔值
+
+// 日期时间类型
+date('birthday')   // 日期
+datetime('event')  // 日期时间
+timestamp('created') // 时间戳
+
+// JSON 类型
+json('data')       // JSON 数据
+jsonb('config')    // 二进制 JSON (PostgreSQL)
+object('metadata') // 对象类型 (扩展)
+```
+
+### 查询操作
+
+```typescript
+// 查询所有记录
+const users = await db.select().from(userTable);
+
+// 条件查询
+const adults = await db.select()
+  .from(userTable)
+  .where(gte(userTable.age, 18));
+
+// 选择特定字段
+const names = await db.select({ name: userTable.name })
+  .from(userTable);
+
+// 使用条件构建器
+const verifiedAdults = await db.select()
+  .from(userTable)
+  .where(and(gte(userTable.age, 18), eq(userTable.verified, true)));
+
+// 排序、分页查询
+const recentUsers = await db.select()
+  .from(userTable)
+  .orderBy(userTable.createdAt, 'desc') // 默认升序，可显式指定 'desc'
+  .limit(10)  // 取前 10 条
+  .offset(10); // 跳过前 10 条，实现分页
+
+// DISTINCT 查询，去重后返回唯一记录
+const uniqueEmails = await db.select({ email: userTable.email })
+  .from(userTable)
+  .distinct();
+```
+
+### 聚合查询
+
+```typescript
+import { count, max } from 'drizzle-solid';
+
+const stats = await db
+  .select({
+    totalUsers: count(),
+    oldestAge: max(userTable.age)
+  })
+  .from(userTable)
+  .where(gte(userTable.age, 18));
+
+console.log(stats[0]);
+// { totalUsers: 42, oldestAge: 63 }
+```
+
+> 当前聚合支持 `count/sum/avg/min/max`，由客户端在内存中计算，选择列表需全部为聚合字段；`JOIN` 与 `GROUP BY` 亦已通过客户端回放实现（在 CSS 升级至最新 Comunica 前仍保留此策略）。
+
+### 插入数据
+
+```typescript
+// 插入单条记录
+await db.insert(userTable).values({
+  name: 'Bob',
+  email: 'bob@example.com',
+  age: 25
+});
+
+// 批量插入
+await db.insert(userTable).values([
+  { name: 'Alice', email: 'alice@example.com', age: 30 },
+  { name: 'Charlie', email: 'charlie@example.com', age: 35 }
+]);
+```
+
+### 更新数据
+
+```typescript
+await db.update(userTable)
+  .set({ age: 26 })
+  .where(eq(userTable.name, 'Bob'));
+```
+
+### 删除数据
+
+```typescript
+await db.delete(userTable)
+  .where(eq(userTable.name, 'Bob'));
+```
+
+## 🔍 数据发现与零配置访问 (Data Discovery & Interoperability)
+
+Drizzle Solid 实现了 Solid 的 **TypeIndex** 和 **SAI (Application Interoperability)** 规范，这意味着您**不需要**硬编码数据的具体路径（`base`）。只要定义好 RDF 类型，Drizzle 就会自动帮您找到数据，无论它是在您自己的 Pod 里，还是别人通过 SAI 授权给您的。
+
+### 核心概念
+
+- **TypeIndex**: 您的“个人数据索引”，记录了“我的笔记在哪里”、“我的联系人在哪里”。适合单用户场景。
+- **SAI Discovery**: 一种更高级的发现机制，用于发现**跨 Pod** 共享的数据（例如 Alice 分享给 Bob 的聊天室）。适合社交、协作场景。
+
+### 如何启用自动发现？
+
+只需在定义表时，移除 `base` 属性，并设置 `typeIndex: 'private'`（或 `'public'`）：
+
+```typescript
+const messageTable = podTable('message', {
+  id: id(),
+  content: string('content').predicate('http://schema.org/text'),
+}, {
+  type: 'http://schema.org/Message',
+  typeIndex: 'private' // ✨ 开启自动发现魔法
+});
+
+// 当您执行查询时，Drizzle 会自动：
+// 1. 查您的 Private TypeIndex
+// 2. 如果没找到，查 SAI Agent Registry (查看是否有授权给您的数据)
+// 3. 找到数据位置后，自动定向查询
+const messages = await db.select().from(messageTable);
+```
+
+### 跨 Pod 聊天应用示例 (SAI Chat)
+
+这是一个展示如何利用 SAI 发现机制构建“零配置”聊天应用的完整示例。Bob 不需要知道 Alice 的聊天室 URL，只要 Alice 授权了，Bob 的应用就能自动发现并加入聊天。
+
+> 查看完整可运行代码：[`examples/04-sai-chat.ts`](examples/04-sai-chat.ts)
+
+```typescript
+// 1. 定义通用的消息表（不绑定具体路径）
+const messageTable = podTable('message', {
+  id: id(),
+  content: string('content').predicate('http://schema.org/text'),
+  author: uri('author').predicate('http://schema.org/author'),
+  createdAt: datetime('createdAt').predicate('http://schema.org/dateCreated')
+}, {
+  type: 'http://schema.org/Message',
+  typeIndex: 'private', // 启用发现
+  autoRegister: false   // 对于访客 Bob，不仅不需要注册，而且不能注册到自己的 TypeIndex
+});
+
+// 2. Alice (房主) 初始化聊天室
+// Alice 需要明确指定存储位置 (base)
+const aliceChatTable = podTable('message', { ...messageTable.columns }, {
+    ...messageTable.config,
+    base: 'https://alice.pod/data/chat/room.ttl',
+    subjectTemplate: '#{id}' // 强制单文件存储模式
+});
+await db.insert(aliceChatTable).values({ ... });
+
+// ... (Alice 通过 SAI 授权给 Bob，此处省略 SAI 注册代码) ...
+
+// 3. Bob (访客) 发现并回复
+// Bob 初始化 Drizzle 时，完全不需要知道 room.ttl 的地址
+const bobDb = drizzle(bobSession);
+
+// 读取：自动发现 Alice 分享的数据
+const messages = await bobDb.select().from(messageTable);
+console.log(messages); // 包含 Alice 的消息
+
+// 写入：自动向发现的地址写入回复
+await bobDb.insert(messageTable).values({
+    content: 'Hi Alice! I found your chat room!',
+    author: bobSession.info.webId
+});
+```
+
+### Discovery 策略
+
+Drizzle Solid 使用组合策略 (`CompositeDiscovery`)：
+1.  **TypeIndex 优先**：检查用户的 `privateTypeIndex.ttl` 和 `publicTypeIndex.ttl`。
+2.  **SAI 后备**：如果 TypeIndex 未命中，检查用户的 Profile -> RegistrySet -> Agent Registry，寻找匹配当前 ClientID 的 Data Grant。
+
+这种设计确保了既能兼容旧的 Solid 应用（基于 TypeIndex），又能支持未来的互操作性规范（SAI）。
+
+架构说明见 `docs/guides/architecture.md`。
+
+## ✅ 当前 SQL 支持范围
+
+- 已实现：`select/insert/update/delete`、Drizzle 风格的 `where` 条件构建器（`eq/ne/lt/gte/like/inArray/not` 等）、`orderBy`、`limit/offset`、`distinct`、嵌套布尔组合，以及 `count/sum/avg/min/max` 聚合、`leftJoin/innerJoin` 和 `GROUP BY`。
+- 运行策略：
+  - **xpod + 单 Pod**：查询下推到 QuintStore 索引执行
+  - **原生 CSS / 联邦查询**：Comunica 将数据读入内存后执行
+- 未实现：`rightJoin`/`fullJoin`（待评估 xpod 支持情况）
+- 未覆盖：`HAVING`、窗口函数、`UNION/UNION ALL`、子查询与跨容器联结；如需这些能力，请暂时改用手写 SPARQL 或拆分查询。
+
+## 🗺️ Roadmap
+
+- **`rightJoin`/`fullJoin` 支持**: 待评估 xpod SPARQL 能力后实现，详见[设计方案](docs/guides/right-full-join-sparql-design.md)。
+
+## 🔧 配置
+
+### 自定义命名空间
+
+Drizzle Solid 不再内置 vocab 常量，请从 RDF vocab 库（例如 `@inrupt/vocab-common-rdf`）导入需要的术语；若需要扩展缺失字段，可使用 `extendNamespace`：
+
+```typescript
+import { podTable, string, extendNamespace } from 'drizzle-solid';
+import { SCHEMA_INRUPT as SCHEMA } from '@inrupt/vocab-common-rdf';
+
+const LINQ = extendNamespace(
+  { prefix: 'linq', uri: 'https://linq.dev/ns/' },
+  { favorite: 'profile#favorite' },
+  { namespace: 'https://linq.dev/ns/' }
+);
+
+const customTable = podTable('custom', {
+  title: string('title').predicate(`${SCHEMA.NAMESPACE}title`),
+  favorite: string('favorite').predicate(LINQ.favorite)
+}, {
+  base: 'idp:///custom/index.ttl', // 目标资源
+  type: `${SCHEMA.NAMESPACE}CreativeWork`,
+  namespace: LINQ
+});
+```
+
+### 认证配置
+
+```typescript
+import { Session } from '@inrupt/solid-client-authn-node';
+
+const session = new Session();
+await session.login({
+  oidcIssuer: 'https://solidcommunity.net',
+  redirectUrl: 'http://localhost:3000/callback',
+  clientName: 'My Solid App'
+});
+
+const db = drizzle(session);
+```
+
+### `base` / `@id` / `id` 与 Pod 根的关系
+
+- `podUrl`（Pod 根）由 WebID 推导，所有相对路径都基于它解析。
+- `base` 是表的目标 Turtle 资源（必填），可为相对路径或绝对 URL。示例：`base: '/data/contacts.ttl'` → `https://pod.example/data/contacts.ttl`。
+- 写入：
+  - 提供 `@id` 则直接作为 subject；
+  - 提供 `id`（或库自动生成）则 subject 形如 `base#<id>`（或按表的 subject 模板选择 `#`/`/`）。
+- 查询：
+  - `where({ '@id': 'https://…#foo' })` 精确匹配该 subject；
+  - `where({ id: 'foo' })` 匹配 fragment 为 `foo` 且落在该表 `base` 下的 subject。
+- `base` 同时决定存储地址（PUT/PATCH 目标）和 subject 生成；`podUrl` 只负责解析相对的 `base`。
+
+## 🏗️ 架构
+
+Drizzle Solid基于以下组件构建：
+
+- **PodDialect**: Solid Pod的Drizzle方言实现
+- **SPARQL转换器**: 将Drizzle查询转换为SPARQL
+- **Comunica执行器**: 执行SPARQL查询
+- **类型系统**: 完整的TypeScript类型支持
+
+### Comunica CRUD 流程
+
+- 查询会经过 AST → SPARQL 转换；若 Comunica 无法执行带过滤器/聚合的 `UPDATE`/`DELETE`，方言会先通过 `SELECT` 拉取命中的 subject，再以 PATCH 方式回写，实现与 SQL 行级操作一致的语义。
+- `PodDialect` 会自动推导目标容器与 `.ttl` 资源文件路径，必要时发送 `HEAD`/`PUT` 请求确保容器和资源已经存在，再交由 Comunica 处理数据修改。
+- 插入会预先读取现有资源以检测重复 subject，避免重复写入；删除或更新只针对匹配的 subject 生成最小化补丁。
+- 对于 `JOIN`、`GROUP BY` 与聚合，选取的数据仍由 SPARQL 拉取，但结果会在内存中组合或聚合，直到 CSS 升级到支持完整 SPARQL 1.1 为止。
+
+## 🤝 贡献
+
+欢迎贡献代码！请阅读 [CONTRIBUTING.md](CONTRIBUTING.md) 了解测试要求、提交流程与验证内容。
+
+在提交 PR 之前，请同步运行完整的 CSS 集成测试（覆盖 CRUD、TypeIndex 等场景）：
+
+```bash
+SOLID_ENABLE_REAL_TESTS=true npx vitest run tests/integration/css --runInBand
+```
+
+> `SOLID_ENABLE_REAL_TESTS=true` 会启用真实 Pod，`--runInBand` 保证所有 suite 共用一个会话并顺序执行，避免对 OIDC 服务造成并发压力。
+
+## 📄 许可证
+
+MIT License - 查看[LICENSE](LICENSE)文件了解详情。
+
+## 🔗 相关链接
+
+- [Drizzle ORM](https://orm.drizzle.team/)
+- [Solid Project](https://solidproject.org/)
+- [Community Solid Server](https://github.com/CommunitySolidServer/CommunitySolidServer)
+- [Inrupt Solid Client](https://github.com/inrupt/solid-client-js)
+
+
+## 📞 支持
+
+如果遇到问题，可先查阅：
+
+1. `docs/quick-start-local.md` 获取本地 CSS 启动与疑难解答
+2. `examples/README.md` 了解脚本入口与运行方式
+3. [Issue 列表](https://github.com/undefinedsco/drizzle-solid/issues) 提交复现步骤与日志
+
+---
+
+**开始您的 Solid 数据之旅！** 🚀

package/dist/core/aggregates.d.ts

@@ -0,0 +1,19 @@
+import { PodColumnBase } from './schema';
+export type AggregateFunction = 'count' | 'sum' | 'avg' | 'min' | 'max';
+export interface AggregateExpression {
+    kind: 'aggregate';
+    func: AggregateFunction;
+    column?: PodColumnBase | string;
+    distinct?: boolean;
+}
+interface AggregateOptions {
+    distinct?: boolean;
+}
+export declare function count(column?: PodColumnBase | string, options?: AggregateOptions): AggregateExpression;
+export declare function sum(column: PodColumnBase | string, options?: AggregateOptions): AggregateExpression;
+export declare function avg(column: PodColumnBase | string, options?: AggregateOptions): AggregateExpression;
+export declare function min(column: PodColumnBase | string, options?: AggregateOptions): AggregateExpression;
+export declare function max(column: PodColumnBase | string, options?: AggregateOptions): AggregateExpression;
+export declare function isAggregateExpression(value: unknown): value is AggregateExpression;
+export {};
+//# sourceMappingURL=aggregates.d.ts.map

package/dist/core/aggregates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aggregates.d.ts","sourceRoot":"","sources":["../../src/core/aggregates.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,CAAC;AAExE,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,EAAE,iBAAiB,CAAC;IACxB,MAAM,CAAC,EAAE,aAAa,GAAG,MAAM,CAAC;IAChC,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,UAAU,gBAAgB;IACxB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AA8BD,wBAAgB,KAAK,CACnB,MAAM,CAAC,EAAE,aAAa,GAAG,MAAM,EAC/B,OAAO,CAAC,EAAE,gBAAgB,GACzB,mBAAmB,CAErB;AAED,wBAAgB,GAAG,CACjB,MAAM,EAAE,aAAa,GAAG,MAAM,EAC9B,OAAO,CAAC,EAAE,gBAAgB,GACzB,mBAAmB,CAGrB;AAED,wBAAgB,GAAG,CACjB,MAAM,EAAE,aAAa,GAAG,MAAM,EAC9B,OAAO,CAAC,EAAE,gBAAgB,GACzB,mBAAmB,CAGrB;AAED,wBAAgB,GAAG,CACjB,MAAM,EAAE,aAAa,GAAG,MAAM,EAC9B,OAAO,CAAC,EAAE,gBAAgB,GACzB,mBAAmB,CAGrB;AAED,wBAAgB,GAAG,CACjB,MAAM,EAAE,aAAa,GAAG,MAAM,EAC9B,OAAO,CAAC,EAAE,gBAAgB,GACzB,mBAAmB,CAGrB;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,mBAAmB,CAElF"}

package/dist/core/aggregates.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.count = count;
+exports.sum = sum;
+exports.avg = avg;
+exports.min = min;
+exports.max = max;
+exports.isAggregateExpression = isAggregateExpression;
+function normalizeOptions(options) {
+    return options ? { ...options } : {};
+}
+function toColumnName(column) {
+    return column;
+}
+function ensureColumn(func, column) {
+    if (!column) {
+        throw new Error(`${func.toUpperCase()} aggregate requires a column reference`);
+    }
+}
+function createAggregate(func, column, options) {
+    const normalized = normalizeOptions(options);
+    return {
+        kind: 'aggregate',
+        func,
+        column: toColumnName(column),
+        distinct: normalized.distinct
+    };
+}
+function count(column, options) {
+    return createAggregate('count', column, options);
+}
+function sum(column, options) {
+    ensureColumn('sum', column);
+    return createAggregate('sum', column, options);
+}
+function avg(column, options) {
+    ensureColumn('avg', column);
+    return createAggregate('avg', column, options);
+}
+function min(column, options) {
+    ensureColumn('min', column);
+    return createAggregate('min', column, options);
+}
+function max(column, options) {
+    ensureColumn('max', column);
+    return createAggregate('max', column, options);
+}
+function isAggregateExpression(value) {
+    return !!value && typeof value === 'object' && value.kind === 'aggregate';
+}
+//# sourceMappingURL=aggregates.js.map

package/dist/core/aggregates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"aggregates.js","sourceRoot":"","sources":["../../src/core/aggregates.ts"],"names":[],"mappings":";;AA2CA,sBAKC;AAED,kBAMC;AAED,kBAMC;AAED,kBAMC;AAED,kBAMC;AAED,sDAEC;AArED,SAAS,gBAAgB,CAAC,OAA0B;IAClD,OAAO,OAAO,CAAC,CAAC,CAAC,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;AACvC,CAAC;AAED,SAAS,YAAY,CAAC,MAA+B;IACnD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,YAAY,CAAC,IAAyC,EAAE,MAA+B;IAC9F,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,CAAC,WAAW,EAAE,wCAAwC,CAAC,CAAC;IACjF,CAAC;AACH,CAAC;AAED,SAAS,eAAe,CACtB,IAAuB,EACvB,MAA+B,EAC/B,OAA0B;IAE1B,MAAM,UAAU,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC;IAC7C,OAAO;QACL,IAAI,EAAE,WAAW;QACjB,IAAI;QACJ,MAAM,EAAE,YAAY,CAAC,MAAM,CAAC;QAC5B,QAAQ,EAAE,UAAU,CAAC,QAAQ;KAC9B,CAAC;AACJ,CAAC;AAED,SAAgB,KAAK,CACnB,MAA+B,EAC/B,OAA0B;IAE1B,OAAO,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;AACnD,CAAC;AAED,SAAgB,GAAG,CACjB,MAA8B,EAC9B,OAA0B;IAE1B,YAAY,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IAC5B,OAAO,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;AACjD,CAAC;AAED,SAAgB,GAAG,CACjB,MAA8B,EAC9B,OAA0B;IAE1B,YAAY,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IAC5B,OAAO,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;AACjD,CAAC;AAED,SAAgB,GAAG,CACjB,MAA8B,EAC9B,OAA0B;IAE1B,YAAY,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IAC5B,OAAO,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;AACjD,CAAC;AAED,SAAgB,GAAG,CACjB,MAA8B,EAC9B,OAA0B;IAE1B,YAAY,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IAC5B,OAAO,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;AACjD,CAAC;AAED,SAAgB,qBAAqB,CAAC,KAAc;IAClD,OAAO,CAAC,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAK,KAA6B,CAAC,IAAI,KAAK,WAAW,CAAC;AACrG,CAAC"}