Skip to content

Commit 64c6cf1

Browse files
huangyiirenehuangyiirene
authored
Merge pull request #34 from objectstack-ai/copilot/split-objectql-protocol-specification
2 parents 1c41033 + f2aba06 commit 64c6cf1

14 files changed

Lines changed: 1668 additions & 1364 deletions

File tree

‎content/docs/02-objectql/protocol-spec.mdx‎

Lines changed: 0 additions & 682 deletions
This file was deleted.

‎content/docs/02-objectql/protocol-spec/aggregation.mdx‎

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
---
2+
title: Aggregation Operations
3+
description: Complete reference for grouping and aggregating data in ObjectQL
4+
---
5+
6+
# Aggregation Operations
7+
8+
This document provides the complete specification for ObjectQL's Aggregation operations.
9+
10+
## GroupBy
11+
12+
```typescript
13+
db.aggregate(objectName: string, options: AggregateOptions)
14+
15+
interface AggregateOptions {
16+
group_by: string[]
17+
having?: Filter[]
18+
fields?: AggregateField[]
19+
sort?: string | Sort[]
20+
limit?: number
21+
}
22+
```
23+
24+
### Basic GroupBy
25+
26+
```typescript
27+
// Count by category
28+
await db.aggregate('product', {
29+
group_by: ['category'],
30+
fields: [
31+
{ field: '_id', function: 'count', alias: 'total' }
32+
]
33+
})
34+
35+
// Result: [
36+
// { category: 'Electronics', total: 45 },
37+
// { category: 'Books', total: 123 }
38+
// ]
39+
```
40+
41+
### Multiple Groupings
42+
43+
```typescript
44+
// Sales by year and quarter
45+
await db.aggregate('order', {
46+
group_by: ['YEAR(created)', 'QUARTER(created)'],
47+
fields: [
48+
{ field: 'amount', function: 'sum', alias: 'total_sales' },
49+
{ field: '_id', function: 'count', alias: 'order_count' }
50+
],
51+
sort: 'YEAR(created) desc, QUARTER(created) desc'
52+
})
53+
```
54+
55+
## Aggregate Functions
56+
57+
```typescript
58+
// Count
59+
{ field: '_id', function: 'count' }
60+
61+
// Sum
62+
{ field: 'amount', function: 'sum' }
63+
64+
// Average
65+
{ field: 'price', function: 'avg' }
66+
67+
// Min
68+
{ field: 'price', function: 'min' }
69+
70+
// Max
71+
{ field: 'price', function: 'max' }
72+
73+
// Distinct count
74+
{ field: 'customer_id', function: 'count_distinct' }
75+
```
76+
77+
## Having Clause
78+
79+
Filter aggregated results:
80+
81+
```typescript
82+
await db.aggregate('order', {
83+
group_by: ['customer_id'],
84+
fields: [
85+
{ field: 'amount', function: 'sum', alias: 'total_spent' },
86+
{ field: '_id', function: 'count', alias: 'order_count' }
87+
],
88+
having: [
89+
['total_spent', '>', 1000] // Only customers who spent > 1000
90+
]
91+
})
92+
```
93+
94+
## Complete Aggregation Example
95+
96+
```typescript
97+
// Monthly sales report with filters
98+
const monthlySales = await db.aggregate('invoice', {
99+
// Pre-aggregation filters (WHERE clause)
100+
filters: [
101+
['status', '=', 'paid'],
102+
['created', '>=', '2024-01-01']
103+
],
104+
105+
// Group by
106+
group_by: ['YEAR(created)', 'MONTH(created)'],
107+
108+
// Aggregate calculations
109+
fields: [
110+
{ field: 'amount', function: 'sum', alias: 'revenue' },
111+
{ field: '_id', function: 'count', alias: 'invoice_count' },
112+
{ field: 'amount', function: 'avg', alias: 'avg_invoice' },
113+
{ field: 'customer_id', function: 'count_distinct', alias: 'unique_customers' }
114+
],
115+
116+
// Post-aggregation filters (HAVING clause)
117+
having: [
118+
['revenue', '>', 50000] // Only months with revenue > 50k
119+
],
120+
121+
// Sort results
122+
sort: 'YEAR(created) desc, MONTH(created) desc',
123+
124+
// Limit results
125+
limit: 12 // Last 12 months
126+
})
127+
128+
// Result: [
129+
// {
130+
// year: 2024,
131+
// month: 3,
132+
// revenue: 125000,
133+
// invoice_count: 45,
134+
// avg_invoice: 2777.78,
135+
// unique_customers: 32
136+
// },
137+
// ...
138+
// ]
139+
```
140+
141+
## Next Steps
142+
143+
- Learn [Query DSL](/docs/02-objectql/protocol-spec/query-dsl) for basic queries
144+
- Master [Mutation Operations](/docs/02-objectql/protocol-spec/mutation) for data modification
145+
- Review [Schema Definition](/docs/02-objectql/protocol-spec/schema-definition) for data modeling

‎content/docs/02-objectql/protocol-spec/index.mdx‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
---
2+
title: Protocol Specification
3+
description: Overview and reference guide for ObjectQL's protocol specification
4+
---
5+
6+
# Protocol Specification
7+
8+
ObjectQL uses a protocol-driven architecture with a comprehensive specification covering data modeling, querying, aggregation, and mutation operations. This specification ensures consistency across implementations and provides a clear contract for developers.
9+
10+
## Core Components
11+
12+
The ObjectQL protocol specification is divided into four main components:
13+
14+
### [Schema Definition](/docs/02-objectql/protocol-spec/schema-definition)
15+
16+
Define your data model with:
17+
- **Object definitions** - Database tables with metadata
18+
- **Field types** - Text, numeric, date/time, boolean, select, relationship, and special fields
19+
- **Field constraints** - Validation, indexes, and dependencies
20+
21+
### [Query DSL](/docs/02-objectql/protocol-spec/query-dsl)
22+
23+
Query your data with:
24+
- **Filters** - Comparison, string, list, null, and compound operators
25+
- **Sorting** - Single or multiple field ordering
26+
- **Pagination** - Limit and skip for efficient data retrieval
27+
- **Field selection** - Choose specific fields including related data
28+
29+
### [Aggregation Operations](/docs/02-objectql/protocol-spec/aggregation)
30+
31+
Analyze your data with:
32+
- **GroupBy** - Group records by one or more fields
33+
- **Aggregate functions** - Count, sum, average, min, max, distinct count
34+
- **Having clause** - Filter aggregated results
35+
- **Pre and post-aggregation filters** - WHERE and HAVING clauses
36+
37+
### [Mutation Operations](/docs/02-objectql/protocol-spec/mutation)
38+
39+
Modify your data with:
40+
- **Insert** - Create new records
41+
- **Update** - Modify existing records
42+
- **Delete** - Remove records
43+
- **Batch operations** - Efficient bulk operations
44+
45+
## Protocol Principles
46+
47+
The ObjectQL protocol follows these key principles:
48+
49+
1. **Declarative** - Describe what you want, not how to get it
50+
2. **Type-safe** - Strong typing for reliability
51+
3. **Composable** - Build complex operations from simple building blocks
52+
4. **Efficient** - Optimized for performance at scale
53+
5. **Consistent** - Uniform patterns across all operations
54+
55+
## Quick Start
56+
57+
Here's a complete example using all protocol components:
58+
59+
```typescript
60+
// 1. Define schema
61+
const schema = {
62+
objects: {
63+
customer: {
64+
label: 'Customer',
65+
fields: {
66+
name: { type: 'text', required: true },
67+
email: { type: 'email', unique: true },
68+
status: { type: 'select', options: ['active', 'inactive'] }
69+
}
70+
}
71+
}
72+
}
73+
74+
// 2. Insert data
75+
await db.mutation('customer', {
76+
action: 'insert',
77+
data: { name: 'Acme Corp', email: 'contact@acme.com', status: 'active' }
78+
})
79+
80+
// 3. Query data
81+
const customers = await db.query('customer', {
82+
filters: [['status', '=', 'active']],
83+
sort: 'name asc',
84+
limit: 10
85+
})
86+
87+
// 4. Aggregate data
88+
const stats = await db.aggregate('customer', {
89+
group_by: ['status'],
90+
fields: [{ field: '_id', function: 'count', alias: 'total' }]
91+
})
92+
```
93+
94+
## Next Steps
95+
96+
- Start with [Schema Definition](/docs/02-objectql/protocol-spec/schema-definition) to model your data
97+
- Learn [Query DSL](/docs/02-objectql/protocol-spec/query-dsl) to retrieve data
98+
- Master [Aggregation](/docs/02-objectql/protocol-spec/aggregation) for data analysis
99+
- Understand [Mutation Operations](/docs/02-objectql/protocol-spec/mutation) for data modification
100+
- Explore [Core Features](/docs/02-objectql/core-features) for advanced capabilities
101+
- Check [Core Concepts](/docs/02-objectql/core-concepts) for foundational knowledge

‎content/docs/02-objectql/protocol-spec/meta.json‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
{
2+
"title": "Protocol Specification",
3+
"pages": [
4+
"schema-definition",
5+
"query-dsl",
6+
"aggregation",
7+
"mutation"
8+
]
9+
}

‎content/docs/02-objectql/protocol-spec/mutation.mdx‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
---
2+
title: Mutation Operations
3+
description: Complete reference for inserting, updating, and deleting data in ObjectQL
4+
---
5+
6+
# Mutation Operations
7+
8+
This document provides the complete specification for ObjectQL's Mutation operations.
9+
10+
## Insert
11+
12+
```typescript
13+
await db.mutation('customer', {
14+
action: 'insert',
15+
data: {
16+
name: 'Acme Corp',
17+
email: 'contact@acme.com',
18+
status: 'active'
19+
}
20+
})
21+
```
22+
23+
## Update
24+
25+
```typescript
26+
await db.mutation('customer', {
27+
action: 'update',
28+
filters: [['_id', '=', customerId]],
29+
data: {
30+
status: 'inactive',
31+
modified: new Date()
32+
}
33+
})
34+
```
35+
36+
## Delete
37+
38+
```typescript
39+
await db.mutation('customer', {
40+
action: 'delete',
41+
filters: [['status', '=', 'archived']]
42+
})
43+
```
44+
45+
## Batch Operations
46+
47+
### Batch Insert
48+
49+
```typescript
50+
// Batch insert
51+
await db.mutation('product', {
52+
action: 'insert',
53+
data: [
54+
{ name: 'Product 1', price: 10 },
55+
{ name: 'Product 2', price: 20 },
56+
{ name: 'Product 3', price: 30 }
57+
]
58+
})
59+
```
60+
61+
### Batch Update
62+
63+
```typescript
64+
// Batch update
65+
await db.mutation('task', {
66+
action: 'update',
67+
filters: [['project_id', '=', projectId]],
68+
data: { status: 'cancelled' }
69+
})
70+
```
71+
72+
## Next Steps
73+
74+
- Learn [Query DSL](/docs/02-objectql/protocol-spec/query-dsl) for querying data
75+
- Explore [Aggregation](/docs/02-objectql/protocol-spec/aggregation) for data analysis
76+
- Review [Schema Definition](/docs/02-objectql/protocol-spec/schema-definition) for data modeling
77+
- Explore [Core Features](/docs/02-objectql/core-features) for performance optimizations
78+
- Master the [Server SDK](/docs/02-objectql/server-sdk) API reference

0 commit comments

Comments
 (0)