Skip to content

Commit cd96c2e

Browse files
hotlonghotlong
committed
Add JSON schema definitions for Data Engine and Driver configurations
- Introduced DataEngineSort.json for defining sorting options in data engine queries. - Added DataEngineUpdateOptions.json to specify options for update operations in the data engine. - Created DataEngineUpdateRequest.json to structure update requests including method, object, data, and options. - Implemented DataEngineVectorFindRequest.json for vector search requests with filtering and selection capabilities. - Defined DriverCapabilities.json to outline the capabilities of various drivers including CRUD operations and transaction support. - Added DriverConfig.json to configure driver instances with properties like name, type, capabilities, and connection settings. - Created DriverInterface.json to specify the interface for drivers, including supported operations and versioning. - Introduced DriverOptions.json for additional options in driver operations such as transaction handling and timeout settings. - Added PoolConfig.json to define connection pool settings including minimum and maximum connections, and timeout configurations.
1 parent 6ce592b commit cd96c2e

29 files changed

Lines changed: 4345 additions & 2 deletions

‎content/docs/references/data/data-engine.mdx‎

Lines changed: 262 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,262 @@
1+
---
2+
title: Data Engine
3+
description: Data Engine protocol schemas
4+
---
5+
6+
# Data Engine
7+
8+
<Callout type="info">
9+
**Source:** `packages/spec/src/data/data-engine.zod.ts`
10+
</Callout>
11+
12+
## TypeScript Usage
13+
14+
```typescript
15+
import { DataEngineAggregateOptionsSchema, DataEngineAggregateRequestSchema, DataEngineBatchRequestSchema, DataEngineContractSchema, DataEngineCountOptionsSchema, DataEngineCountRequestSchema, DataEngineDeleteOptionsSchema, DataEngineDeleteRequestSchema, DataEngineExecuteRequestSchema, DataEngineFilterSchema, DataEngineFindOneRequestSchema, DataEngineFindRequestSchema, DataEngineInsertOptionsSchema, DataEngineInsertRequestSchema, DataEngineQueryOptionsSchema, DataEngineRequestSchema, DataEngineSortSchema, DataEngineUpdateOptionsSchema, DataEngineUpdateRequestSchema, DataEngineVectorFindRequestSchema } from '@objectstack/spec/data';
16+
import type { DataEngineAggregateOptions, DataEngineAggregateRequest, DataEngineBatchRequest, DataEngineContract, DataEngineCountOptions, DataEngineCountRequest, DataEngineDeleteOptions, DataEngineDeleteRequest, DataEngineExecuteRequest, DataEngineFilter, DataEngineFindOneRequest, DataEngineFindRequest, DataEngineInsertOptions, DataEngineInsertRequest, DataEngineQueryOptions, DataEngineRequest, DataEngineSort, DataEngineUpdateOptions, DataEngineUpdateRequest, DataEngineVectorFindRequest } from '@objectstack/spec/data';
17+
18+
// Validate data
19+
const result = DataEngineAggregateOptionsSchema.parse(data);
20+
```
21+
22+
---
23+
24+
## DataEngineAggregateOptions
25+
26+
Options for DataEngine.aggregate operations
27+
28+
### Properties
29+
30+
| Property | Type | Required | Description |
31+
| :--- | :--- | :--- | :--- |
32+
| **filter** | `Record<string, any> \| any` | optional | Data Engine query filter conditions |
33+
| **groupBy** | `string[]` | optional | |
34+
| **aggregations** | `object[]` | optional | |
35+
36+
---
37+
38+
## DataEngineAggregateRequest
39+
40+
### Properties
41+
42+
| Property | Type | Required | Description |
43+
| :--- | :--- | :--- | :--- |
44+
| **method** | `string` | ✅ | |
45+
| **object** | `string` | ✅ | |
46+
| **query** | `object` | ✅ | Options for DataEngine.aggregate operations |
47+
48+
---
49+
50+
## DataEngineBatchRequest
51+
52+
### Properties
53+
54+
| Property | Type | Required | Description |
55+
| :--- | :--- | :--- | :--- |
56+
| **method** | `string` | ✅ | |
57+
| **requests** | `object \| object \| object \| object \| object \| object \| object \| object \| object[]` | ✅ | |
58+
| **transaction** | `boolean` | optional | |
59+
60+
---
61+
62+
## DataEngineContract
63+
64+
Standard Data Engine Contract
65+
66+
### Properties
67+
68+
| Property | Type | Required | Description |
69+
| :--- | :--- | :--- | :--- |
70+
71+
---
72+
73+
## DataEngineCountOptions
74+
75+
Options for DataEngine.count operations
76+
77+
### Properties
78+
79+
| Property | Type | Required | Description |
80+
| :--- | :--- | :--- | :--- |
81+
| **filter** | `Record<string, any> \| any` | optional | Data Engine query filter conditions |
82+
83+
---
84+
85+
## DataEngineCountRequest
86+
87+
### Properties
88+
89+
| Property | Type | Required | Description |
90+
| :--- | :--- | :--- | :--- |
91+
| **method** | `string` | ✅ | |
92+
| **object** | `string` | ✅ | |
93+
| **query** | `object` | optional | Options for DataEngine.count operations |
94+
95+
---
96+
97+
## DataEngineDeleteOptions
98+
99+
Options for DataEngine.delete operations
100+
101+
### Properties
102+
103+
| Property | Type | Required | Description |
104+
| :--- | :--- | :--- | :--- |
105+
| **filter** | `Record<string, any> \| any` | optional | Data Engine query filter conditions |
106+
| **multi** | `boolean` | optional | |
107+
108+
---
109+
110+
## DataEngineDeleteRequest
111+
112+
### Properties
113+
114+
| Property | Type | Required | Description |
115+
| :--- | :--- | :--- | :--- |
116+
| **method** | `string` | ✅ | |
117+
| **object** | `string` | ✅ | |
118+
| **id** | `any` | optional | ID for single delete, or use filter in options |
119+
| **options** | `object` | optional | Options for DataEngine.delete operations |
120+
121+
---
122+
123+
## DataEngineExecuteRequest
124+
125+
### Properties
126+
127+
| Property | Type | Required | Description |
128+
| :--- | :--- | :--- | :--- |
129+
| **method** | `string` | ✅ | |
130+
| **command** | `any` | optional | |
131+
| **options** | `Record<string, any>` | optional | |
132+
133+
---
134+
135+
## DataEngineFilter
136+
137+
Data Engine query filter conditions
138+
139+
---
140+
141+
## DataEngineFindOneRequest
142+
143+
### Properties
144+
145+
| Property | Type | Required | Description |
146+
| :--- | :--- | :--- | :--- |
147+
| **method** | `string` | ✅ | |
148+
| **object** | `string` | ✅ | |
149+
| **query** | `object` | optional | Query options for IDataEngine.find() operations |
150+
151+
---
152+
153+
## DataEngineFindRequest
154+
155+
### Properties
156+
157+
| Property | Type | Required | Description |
158+
| :--- | :--- | :--- | :--- |
159+
| **method** | `string` | ✅ | |
160+
| **object** | `string` | ✅ | |
161+
| **query** | `object` | optional | Query options for IDataEngine.find() operations |
162+
163+
---
164+
165+
## DataEngineInsertOptions
166+
167+
Options for DataEngine.insert operations
168+
169+
### Properties
170+
171+
| Property | Type | Required | Description |
172+
| :--- | :--- | :--- | :--- |
173+
| **returning** | `boolean` | optional | |
174+
175+
---
176+
177+
## DataEngineInsertRequest
178+
179+
### Properties
180+
181+
| Property | Type | Required | Description |
182+
| :--- | :--- | :--- | :--- |
183+
| **method** | `string` | ✅ | |
184+
| **object** | `string` | ✅ | |
185+
| **data** | `Record<string, any> \| Record<string, any>[]` | ✅ | |
186+
| **options** | `object` | optional | Options for DataEngine.insert operations |
187+
188+
---
189+
190+
## DataEngineQueryOptions
191+
192+
Query options for IDataEngine.find() operations
193+
194+
### Properties
195+
196+
| Property | Type | Required | Description |
197+
| :--- | :--- | :--- | :--- |
198+
| **filter** | `Record<string, any> \| any` | optional | Data Engine query filter conditions |
199+
| **select** | `string[]` | optional | |
200+
| **sort** | `Record<string, Enum<'asc' \| 'desc'>> \| Record<string, Enum<'1' \| '-1'>> \| object[]` | optional | Sort order definition |
201+
| **limit** | `integer` | optional | |
202+
| **skip** | `integer` | optional | |
203+
| **top** | `integer` | optional | |
204+
| **populate** | `string[]` | optional | |
205+
206+
---
207+
208+
## DataEngineRequest
209+
210+
Virtual ObjectQL Request Protocol
211+
212+
---
213+
214+
## DataEngineSort
215+
216+
Sort order definition
217+
218+
---
219+
220+
## DataEngineUpdateOptions
221+
222+
Options for DataEngine.update operations
223+
224+
### Properties
225+
226+
| Property | Type | Required | Description |
227+
| :--- | :--- | :--- | :--- |
228+
| **filter** | `Record<string, any> \| any` | optional | Data Engine query filter conditions |
229+
| **upsert** | `boolean` | optional | |
230+
| **multi** | `boolean` | optional | |
231+
| **returning** | `boolean` | optional | |
232+
233+
---
234+
235+
## DataEngineUpdateRequest
236+
237+
### Properties
238+
239+
| Property | Type | Required | Description |
240+
| :--- | :--- | :--- | :--- |
241+
| **method** | `string` | ✅ | |
242+
| **object** | `string` | ✅ | |
243+
| **data** | `Record<string, any>` | ✅ | |
244+
| **id** | `any` | optional | ID for single update, or use filter in options |
245+
| **options** | `object` | optional | Options for DataEngine.update operations |
246+
247+
---
248+
249+
## DataEngineVectorFindRequest
250+
251+
### Properties
252+
253+
| Property | Type | Required | Description |
254+
| :--- | :--- | :--- | :--- |
255+
| **method** | `string` | ✅ | |
256+
| **object** | `string` | ✅ | |
257+
| **vector** | `number[]` | ✅ | |
258+
| **filter** | `Record<string, any> \| any` | optional | Data Engine query filter conditions |
259+
| **select** | `string[]` | optional | |
260+
| **limit** | `integer` | optional | |
261+
| **threshold** | `number` | optional | |
262+

‎content/docs/references/data/driver.mdx‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
---
2+
title: Driver
3+
description: Driver protocol schemas
4+
---
5+
6+
# Driver
7+
8+
<Callout type="info">
9+
**Source:** `packages/spec/src/data/driver.zod.ts`
10+
</Callout>
11+
12+
## TypeScript Usage
13+
14+
```typescript
15+
import { DriverCapabilitiesSchema, DriverConfigSchema, DriverInterfaceSchema, DriverOptionsSchema, PoolConfigSchema } from '@objectstack/spec/data';
16+
import type { DriverCapabilities, DriverConfig, DriverInterface, DriverOptions, PoolConfig } from '@objectstack/spec/data';
17+
18+
// Validate data
19+
const result = DriverCapabilitiesSchema.parse(data);
20+
```
21+
22+
---
23+
24+
## DriverCapabilities
25+
26+
### Properties
27+
28+
| Property | Type | Required | Description |
29+
| :--- | :--- | :--- | :--- |
30+
| **create** | `boolean` | optional | Supports CREATE operations |
31+
| **read** | `boolean` | optional | Supports READ operations |
32+
| **update** | `boolean` | optional | Supports UPDATE operations |
33+
| **delete** | `boolean` | optional | Supports DELETE operations |
34+
| **bulkCreate** | `boolean` | optional | Supports bulk CREATE operations |
35+
| **bulkUpdate** | `boolean` | optional | Supports bulk UPDATE operations |
36+
| **bulkDelete** | `boolean` | optional | Supports bulk DELETE operations |
37+
| **transactions** | `boolean` | optional | Supports ACID transactions |
38+
| **savepoints** | `boolean` | optional | Supports transaction savepoints |
39+
| **isolationLevels** | `Enum<'read-uncommitted' \| 'read-committed' \| 'repeatable-read' \| 'serializable'>[]` | optional | Supported transaction isolation levels |
40+
| **queryFilters** | `boolean` | optional | Supports WHERE clause filtering |
41+
| **queryAggregations** | `boolean` | optional | Supports GROUP BY and aggregation functions |
42+
| **querySorting** | `boolean` | optional | Supports ORDER BY sorting |
43+
| **queryPagination** | `boolean` | optional | Supports LIMIT/OFFSET pagination |
44+
| **queryWindowFunctions** | `boolean` | optional | Supports window functions with OVER clause |
45+
| **querySubqueries** | `boolean` | optional | Supports subqueries |
46+
| **queryCTE** | `boolean` | optional | Supports Common Table Expressions (WITH clause) |
47+
| **joins** | `boolean` | optional | Supports SQL joins |
48+
| **fullTextSearch** | `boolean` | optional | Supports full-text search |
49+
| **jsonQuery** | `boolean` | optional | Supports JSON field querying |
50+
| **geospatialQuery** | `boolean` | optional | Supports geospatial queries |
51+
| **streaming** | `boolean` | optional | Supports result streaming (cursors/iterators) |
52+
| **jsonFields** | `boolean` | optional | Supports JSON field types |
53+
| **arrayFields** | `boolean` | optional | Supports array field types |
54+
| **vectorSearch** | `boolean` | optional | Supports vector embeddings and similarity search |
55+
| **geoSpatial** | `boolean` | optional | Supports geospatial queries (deprecated: use geospatialQuery) |
56+
| **schemaSync** | `boolean` | optional | Supports automatic schema synchronization |
57+
| **migrations** | `boolean` | optional | Supports database migrations |
58+
| **indexes** | `boolean` | optional | Supports index creation and management |
59+
| **connectionPooling** | `boolean` | optional | Supports connection pooling |
60+
| **preparedStatements** | `boolean` | optional | Supports prepared statements (SQL injection prevention) |
61+
| **queryCache** | `boolean` | optional | Supports query result caching |
62+
63+
---
64+
65+
## DriverConfig
66+
67+
### Properties
68+
69+
| Property | Type | Required | Description |
70+
| :--- | :--- | :--- | :--- |
71+
| **name** | `string` | ✅ | Driver instance name |
72+
| **type** | `Enum<'sql' \| 'nosql' \| 'cache' \| 'search' \| 'graph' \| 'timeseries'>` | ✅ | Driver type category |
73+
| **capabilities** | `object` | ✅ | Driver capability flags |
74+
| **connectionString** | `string` | optional | Database connection string (driver-specific format) |
75+
| **poolConfig** | `object` | optional | Connection pool configuration |
76+
77+
---
78+
79+
## DriverInterface
80+
81+
### Properties
82+
83+
| Property | Type | Required | Description |
84+
| :--- | :--- | :--- | :--- |
85+
| **name** | `string` | ✅ | Driver unique name |
86+
| **version** | `string` | ✅ | Driver version |
87+
| **supports** | `object` | ✅ | |
88+
89+
---
90+
91+
## DriverOptions
92+
93+
### Properties
94+
95+
| Property | Type | Required | Description |
96+
| :--- | :--- | :--- | :--- |
97+
| **transaction** | `any` | optional | Transaction handle |
98+
| **timeout** | `number` | optional | Timeout in ms |
99+
| **skipCache** | `boolean` | optional | Bypass cache |
100+
| **traceContext** | `Record<string, string>` | optional | OpenTelemetry context or request ID |
101+
| **tenantId** | `string` | optional | Tenant Isolation identifier |
102+
103+
---
104+
105+
## PoolConfig
106+
107+
### Properties
108+
109+
| Property | Type | Required | Description |
110+
| :--- | :--- | :--- | :--- |
111+
| **min** | `number` | optional | Minimum number of connections in pool |
112+
| **max** | `number` | optional | Maximum number of connections in pool |
113+
| **idleTimeoutMillis** | `number` | optional | Time in ms before idle connection is closed |
114+
| **connectionTimeoutMillis** | `number` | optional | Time in ms to wait for available connection |
115+

0 commit comments

Comments
 (0)