Split ObjectQL Protocol Specification into focused documents

Co-authored-by: huangyiirene <7665279+huangyiirene@users.noreply.github.com>

Author: Copilot

content/docs/02-objectql/aggregation.mdx

@@ -0,0 +1,145 @@
+---
+title: Aggregation Operations
+description: Complete reference for grouping and aggregating data in ObjectQL
+---
+
+# Aggregation Operations
+
+This document provides the complete specification for ObjectQL's Aggregation operations.
+
+## GroupBy
+
+```typescript
+db.aggregate(objectName: string, options: AggregateOptions)
+
+interface AggregateOptions {
+  group_by: string[]
+  having?: Filter[]
+  fields?: AggregateField[]
+  sort?: string | Sort[]
+  limit?: number
+}
+```
+
+### Basic GroupBy
+
+```typescript
+// Count by category
+await db.aggregate('product', {
+  group_by: ['category'],
+  fields: [
+    { field: '_id', function: 'count', alias: 'total' }
+  ]
+})
+
+// Result: [
+//   { category: 'Electronics', total: 45 },
+//   { category: 'Books', total: 123 }
+// ]
+```
+
+### Multiple Groupings
+
+```typescript
+// Sales by year and quarter
+await db.aggregate('order', {
+  group_by: ['YEAR(created)', 'QUARTER(created)'],
+  fields: [
+    { field: 'amount', function: 'sum', alias: 'total_sales' },
+    { field: '_id', function: 'count', alias: 'order_count' }
+  ],
+  sort: 'YEAR(created) desc, QUARTER(created) desc'
+})
+```
+
+## Aggregate Functions
+
+```typescript
+// Count
+{ field: '_id', function: 'count' }
+
+// Sum
+{ field: 'amount', function: 'sum' }
+
+// Average
+{ field: 'price', function: 'avg' }
+
+// Min
+{ field: 'price', function: 'min' }
+
+// Max
+{ field: 'price', function: 'max' }
+
+// Distinct count
+{ field: 'customer_id', function: 'count_distinct' }
+```
+
+## Having Clause
+
+Filter aggregated results:
+
+```typescript
+await db.aggregate('order', {
+  group_by: ['customer_id'],
+  fields: [
+    { field: 'amount', function: 'sum', alias: 'total_spent' },
+    { field: '_id', function: 'count', alias: 'order_count' }
+  ],
+  having: [
+    ['total_spent', '>', 1000]    // Only customers who spent > 1000
+  ]
+})
+```
+
+## Complete Aggregation Example
+
+```typescript
+// Monthly sales report with filters
+const monthlySales = await db.aggregate('invoice', {
+  // Pre-aggregation filters (WHERE clause)
+  filters: [
+    ['status', '=', 'paid'],
+    ['created', '>=', '2024-01-01']
+  ],
+  
+  // Group by
+  group_by: ['YEAR(created)', 'MONTH(created)'],
+  
+  // Aggregate calculations
+  fields: [
+    { field: 'amount', function: 'sum', alias: 'revenue' },
+    { field: '_id', function: 'count', alias: 'invoice_count' },
+    { field: 'amount', function: 'avg', alias: 'avg_invoice' },
+    { field: 'customer_id', function: 'count_distinct', alias: 'unique_customers' }
+  ],
+  
+  // Post-aggregation filters (HAVING clause)
+  having: [
+    ['revenue', '>', 50000]  // Only months with revenue > 50k
+  ],
+  
+  // Sort results
+  sort: 'YEAR(created) desc, MONTH(created) desc',
+  
+  // Limit results
+  limit: 12  // Last 12 months
+})
+
+// Result: [
+//   {
+//     year: 2024,
+//     month: 3,
+//     revenue: 125000,
+//     invoice_count: 45,
+//     avg_invoice: 2777.78,
+//     unique_customers: 32
+//   },
+//   ...
+// ]
+```
+
+## Next Steps
+
+- Learn [Query DSL](/docs/02-objectql/query-dsl) for basic queries
+- Master [Mutation Operations](/docs/02-objectql/mutation) for data modification
+- Review [Schema Definition](/docs/02-objectql/schema-definition) for data modeling

content/docs/02-objectql/meta.json

@@ -5,6 +5,10 @@
     "index",
     "core-concepts",
     "protocol-spec",
+    "schema-definition",
+    "query-dsl",
+    "aggregation",
+    "mutation",
     "core-features",
     "server-sdk"
   ]

content/docs/02-objectql/mutation.mdx

@@ -0,0 +1,78 @@
+---
+title: Mutation Operations
+description: Complete reference for inserting, updating, and deleting data in ObjectQL
+---
+
+# Mutation Operations
+
+This document provides the complete specification for ObjectQL's Mutation operations.
+
+## Insert
+
+```typescript
+await db.mutation('customer', {
+  action: 'insert',
+  data: {
+    name: 'Acme Corp',
+    email: 'contact@acme.com',
+    status: 'active'
+  }
+})
+```
+
+## Update
+
+```typescript
+await db.mutation('customer', {
+  action: 'update',
+  filters: [['_id', '=', customerId]],
+  data: {
+    status: 'inactive',
+    modified: new Date()
+  }
+})
+```
+
+## Delete
+
+```typescript
+await db.mutation('customer', {
+  action: 'delete',
+  filters: [['status', '=', 'archived']]
+})
+```
+
+## Batch Operations
+
+### Batch Insert
+
+```typescript
+// Batch insert
+await db.mutation('product', {
+  action: 'insert',
+  data: [
+    { name: 'Product 1', price: 10 },
+    { name: 'Product 2', price: 20 },
+    { name: 'Product 3', price: 30 }
+  ]
+})
+```
+
+### Batch Update
+
+```typescript
+// Batch update
+await db.mutation('task', {
+  action: 'update',
+  filters: [['project_id', '=', projectId]],
+  data: { status: 'cancelled' }
+})
+```
+
+## Next Steps
+
+- Learn [Query DSL](/docs/02-objectql/query-dsl) for querying data
+- Explore [Aggregation](/docs/02-objectql/aggregation) for data analysis
+- Review [Schema Definition](/docs/02-objectql/schema-definition) for data modeling
+- Explore [Core Features](/docs/02-objectql/core-features) for performance optimizations
+- Master the [Server SDK](/docs/02-objectql/server-sdk) API reference