Merge pull request #983 from objectstack-ai/copilot/unify-architecture-remove-dataenginequeryoptions

Author: hotlong

.changeset/queryast-convergence.md

@@ -0,0 +1,20 @@
+---
+"@objectstack/spec": minor
+"@objectstack/core": minor
+"@objectstack/objectql": minor
+"@objectstack/client": minor
+"@objectstack/runtime": patch
+"@objectstack/plugin-auth": patch
+---
+
+Deprecate DataEngineQueryOptions in favor of QueryAST-aligned EngineQueryOptions.
+
+Engine, Protocol, and Client now use standard QueryAST parameter names:
+- `filter` → `where`
+- `select` → `fields`
+- `sort` → `orderBy`
+- `skip` → `offset`
+- `populate` → `expand`
+- `top` → `limit`
+
+The old DataEngine* schemas and types are preserved with `@deprecated` markers for backward compatibility.

apps/studio/src/lib/create-broker-shim.ts

@@ -75,7 +75,7 @@ export function createBrokerShim(kernel: any): BrokerShim {
                         }
 
                         try {
-                            await ql.update(params.object, params.data, { filter: params.id });
+                            await ql.update(params.object, params.data, { where: { id: params.id } });
                         } catch (err: any) {
                             console.warn(`[BrokerShim] update failed: ${err.message}`);
                             throw err;
@@ -87,7 +87,7 @@ export function createBrokerShim(kernel: any): BrokerShim {
                 }
                 if (method === 'delete') {
                     try {
-                        await ql.delete(params.object, { filter: params.id });
+                        await ql.delete(params.object, { where: { id: params.id } });
                         return { object: params.object, id: params.id, deleted: true };
                     } catch (err: any) {
                         console.warn(`[BrokerShim] delete failed: ${err.message}`);

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

@@ -24,8 +24,8 @@ The Data Engine acts as the "Driver" layer in the Hexagonal Architecture.
 ## TypeScript Usage
 
 ```typescript
-import { BaseEngineOptions, DataEngineAggregateOptions, DataEngineAggregateRequest, DataEngineBatchRequest, DataEngineCountOptions, DataEngineCountRequest, DataEngineDeleteOptions, DataEngineDeleteRequest, DataEngineExecuteRequest, DataEngineFilter, DataEngineFindOneRequest, DataEngineFindRequest, DataEngineInsertOptions, DataEngineInsertRequest, DataEngineQueryOptions, DataEngineRequest, DataEngineSort, DataEngineUpdateOptions, DataEngineUpdateRequest, DataEngineVectorFindRequest } from '@objectstack/spec/data';
-import type { BaseEngineOptions, DataEngineAggregateOptions, DataEngineAggregateRequest, DataEngineBatchRequest, DataEngineCountOptions, DataEngineCountRequest, DataEngineDeleteOptions, DataEngineDeleteRequest, DataEngineExecuteRequest, DataEngineFilter, DataEngineFindOneRequest, DataEngineFindRequest, DataEngineInsertOptions, DataEngineInsertRequest, DataEngineQueryOptions, DataEngineRequest, DataEngineSort, DataEngineUpdateOptions, DataEngineUpdateRequest, DataEngineVectorFindRequest } from '@objectstack/spec/data';
+import { BaseEngineOptions, DataEngineAggregateOptions, DataEngineAggregateRequest, DataEngineBatchRequest, DataEngineCountOptions, DataEngineCountRequest, DataEngineDeleteOptions, DataEngineDeleteRequest, DataEngineExecuteRequest, DataEngineFilter, DataEngineFindOneRequest, DataEngineFindRequest, DataEngineInsertOptions, DataEngineInsertRequest, DataEngineQueryOptions, DataEngineRequest, DataEngineSort, DataEngineUpdateOptions, DataEngineUpdateRequest, DataEngineVectorFindRequest, EngineAggregateOptions, EngineCountOptions, EngineDeleteOptions, EngineQueryOptions, EngineUpdateOptions } from '@objectstack/spec/data';
+import type { BaseEngineOptions, DataEngineAggregateOptions, DataEngineAggregateRequest, DataEngineBatchRequest, DataEngineCountOptions, DataEngineCountRequest, DataEngineDeleteOptions, DataEngineDeleteRequest, DataEngineExecuteRequest, DataEngineFilter, DataEngineFindOneRequest, DataEngineFindRequest, DataEngineInsertOptions, DataEngineInsertRequest, DataEngineQueryOptions, DataEngineRequest, DataEngineSort, DataEngineUpdateOptions, DataEngineUpdateRequest, DataEngineVectorFindRequest, EngineAggregateOptions, EngineCountOptions, EngineDeleteOptions, EngineQueryOptions, EngineUpdateOptions } from '@objectstack/spec/data';
 
 // Validate data
 const result = BaseEngineOptions.parse(data);
@@ -68,7 +68,7 @@ Options for DataEngine.aggregate operations
 | :--- | :--- | :--- | :--- |
 | **method** | `string` | ✅ |  |
 | **object** | `string` | ✅ |  |
-| **query** | `Object` | ✅ | Options for DataEngine.aggregate operations |
+| **query** | `Object` | ✅ |  |
 
 
 ---
@@ -108,7 +108,7 @@ Options for DataEngine.count operations
 | :--- | :--- | :--- | :--- |
 | **method** | `string` | ✅ |  |
 | **object** | `string` | ✅ |  |
-| **query** | `Object` | optional | Options for DataEngine.count operations |
+| **query** | `Object` | optional |  |
 
 
 ---
@@ -136,8 +136,8 @@ Options for DataEngine.delete operations
 | :--- | :--- | :--- | :--- |
 | **method** | `string` | ✅ |  |
 | **object** | `string` | ✅ |  |
-| **id** | `string \| number` | optional | ID for single delete, or use filter in options |
-| **options** | `Object` | optional | Options for DataEngine.delete operations |
+| **id** | `string \| number` | optional | ID for single delete, or use where in options |
+| **options** | `Object` | optional |  |
 
 
 ---
@@ -186,7 +186,7 @@ Reference: [__schema0](./__schema0)
 | :--- | :--- | :--- | :--- |
 | **method** | `string` | ✅ |  |
 | **object** | `string` | ✅ |  |
-| **query** | `Object` | optional | Query options for IDataEngine.find() operations |
+| **query** | `Object` | optional |  |
 
 
 ---
@@ -199,7 +199,7 @@ Reference: [__schema0](./__schema0)
 | :--- | :--- | :--- | :--- |
 | **method** | `string` | ✅ |  |
 | **object** | `string` | ✅ |  |
-| **query** | `Object` | optional | Query options for IDataEngine.find() operations |
+| **query** | `Object` | optional |  |
 
 
 ---
@@ -268,7 +268,7 @@ This schema accepts one of the following structures:
 | :--- | :--- | :--- | :--- |
 | **method** | `string` | ✅ |  |
 | **object** | `string` | ✅ |  |
-| **query** | `Object` | optional | Query options for IDataEngine.find() operations |
+| **query** | `Object` | optional |  |
 
 ---
 
@@ -280,7 +280,7 @@ This schema accepts one of the following structures:
 | :--- | :--- | :--- | :--- |
 | **method** | `string` | ✅ |  |
 | **object** | `string` | ✅ |  |
-| **query** | `Object` | optional | Query options for IDataEngine.find() operations |
+| **query** | `Object` | optional |  |
 
 ---
 
@@ -306,8 +306,8 @@ This schema accepts one of the following structures:
 | **method** | `string` | ✅ |  |
 | **object** | `string` | ✅ |  |
 | **data** | `Record<string, any>` | ✅ |  |
-| **id** | `string \| number` | optional | ID for single update, or use filter in options |
-| **options** | `Object` | optional | Options for DataEngine.update operations |
+| **id** | `string \| number` | optional | ID for single update, or use where in options |
+| **options** | `Object` | optional |  |
 
 ---
 
@@ -319,8 +319,8 @@ This schema accepts one of the following structures:
 | :--- | :--- | :--- | :--- |
 | **method** | `string` | ✅ |  |
 | **object** | `string` | ✅ |  |
-| **id** | `string \| number` | optional | ID for single delete, or use filter in options |
-| **options** | `Object` | optional | Options for DataEngine.delete operations |
+| **id** | `string \| number` | optional | ID for single delete, or use where in options |
+| **options** | `Object` | optional |  |
 
 ---
 
@@ -332,7 +332,7 @@ This schema accepts one of the following structures:
 | :--- | :--- | :--- | :--- |
 | **method** | `string` | ✅ |  |
 | **object** | `string` | ✅ |  |
-| **query** | `Object` | optional | Options for DataEngine.count operations |
+| **query** | `Object` | optional |  |
 
 ---
 
@@ -344,7 +344,7 @@ This schema accepts one of the following structures:
 | :--- | :--- | :--- | :--- |
 | **method** | `string` | ✅ |  |
 | **object** | `string` | ✅ |  |
-| **query** | `Object` | ✅ | Options for DataEngine.aggregate operations |
+| **query** | `Object` | ✅ |  |
 
 ---
 
@@ -381,8 +381,8 @@ This schema accepts one of the following structures:
 | **method** | `string` | ✅ |  |
 | **object** | `string` | ✅ |  |
 | **vector** | `number[]` | ✅ |  |
-| **filter** | `Record<string, any> \| [__schema0](./__schema0)` | optional | Data Engine query filter conditions |
-| **select** | `string[]` | optional |  |
+| **where** | `Record<string, any> \| [__schema0](./__schema0)` | optional |  |
+| **fields** | `string[]` | optional |  |
 | **limit** | `integer` | optional |  |
 | **threshold** | `number` | optional |  |
 
@@ -446,8 +446,8 @@ Options for DataEngine.update operations
 | **method** | `string` | ✅ |  |
 | **object** | `string` | ✅ |  |
 | **data** | `Record<string, any>` | ✅ |  |
-| **id** | `string \| number` | optional | ID for single update, or use filter in options |
-| **options** | `Object` | optional | Options for DataEngine.update operations |
+| **id** | `string \| number` | optional | ID for single update, or use where in options |
+| **options** | `Object` | optional |  |
 
 
 ---
@@ -461,11 +461,96 @@ Options for DataEngine.update operations
 | **method** | `string` | ✅ |  |
 | **object** | `string` | ✅ |  |
 | **vector** | `number[]` | ✅ |  |
-| **filter** | `Record<string, any> \| [__schema0](./__schema0)` | optional | Data Engine query filter conditions |
-| **select** | `string[]` | optional |  |
+| **where** | `Record<string, any> \| [__schema0](./__schema0)` | optional |  |
+| **fields** | `string[]` | optional |  |
 | **limit** | `integer` | optional |  |
 | **threshold** | `number` | optional |  |
 
 
 ---
 
+## EngineAggregateOptions
+
+QueryAST-aligned options for DataEngine.aggregate operations
+
+### Properties
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **context** | `Object` | optional |  |
+| **where** | `Record<string, any> \| [__schema0](./__schema0)` | optional |  |
+| **groupBy** | `string[]` | optional |  |
+| **aggregations** | `Object[]` | optional |  |
+
+
+---
+
+## EngineCountOptions
+
+QueryAST-aligned options for DataEngine.count operations
+
+### Properties
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **context** | `Object` | optional |  |
+| **where** | `Record<string, any> \| [__schema0](./__schema0)` | optional |  |
+
+
+---
+
+## EngineDeleteOptions
+
+QueryAST-aligned options for DataEngine.delete operations
+
+### Properties
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **context** | `Object` | optional |  |
+| **where** | `Record<string, any> \| [__schema0](./__schema0)` | optional |  |
+| **multi** | `boolean` | optional |  |
+
+
+---
+
+## EngineQueryOptions
+
+QueryAST-aligned query options for IDataEngine.find() operations
+
+### Properties
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **context** | `Object` | optional |  |
+| **where** | `Record<string, any> \| [__schema0](./__schema0)` | optional |  |
+| **fields** | `[__schema1](./__schema1)[]` | optional |  |
+| **orderBy** | `Object[]` | optional |  |
+| **limit** | `number` | optional |  |
+| **offset** | `number` | optional |  |
+| **top** | `number` | optional |  |
+| **cursor** | `Record<string, any>` | optional |  |
+| **search** | `Object` | optional |  |
+| **expand** | `Record<string, [__schema2](./__schema2)>` | optional |  |
+| **distinct** | `boolean` | optional |  |
+
+
+---
+
+## EngineUpdateOptions
+
+QueryAST-aligned options for DataEngine.update operations
+
+### Properties
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **context** | `Object` | optional |  |
+| **where** | `Record<string, any> \| [__schema0](./__schema0)` | optional |  |
+| **upsert** | `boolean` | optional |  |
+| **multi** | `boolean` | optional |  |
+| **returning** | `boolean` | optional |  |
+
+
+---
+

content/docs/references/data/driver.mdx

@@ -57,6 +57,7 @@ const result = DriverCapabilities.parse(data);
 | **arrayFields** | `boolean` | ✅ | Supports array field types |
 | **vectorSearch** | `boolean` | ✅ | Supports vector embeddings and similarity search |
 | **schemaSync** | `boolean` | ✅ | Supports automatic schema synchronization |
+| **batchSchemaSync** | `boolean` | ✅ | Supports batched schema sync to reduce schema DDL round-trips |
 | **migrations** | `boolean` | ✅ | Supports database migrations |
 | **indexes** | `boolean` | ✅ | Supports index creation and management |
 | **connectionPooling** | `boolean` | ✅ | Supports connection pooling |

packages/client/src/client.hono.test.ts

@@ -52,14 +52,14 @@ describe('ObjectStackClient (with Hono Server)', () => {
                         if (protocol) {
                             return await protocol.findData({ object: params.object, query: params.query || params.filters });
                         }
-                        const records = await ql.find(params.object, { filter: params.filters });
+                        const records = await ql.find(params.object, { where: params.filters });
                         return { object: params.object, records, total: records.length };
                     }
                     if (method === 'find') {
                         if (protocol) {
                             return await protocol.findData({ object: params.object, query: params.query || params.filters });
                         }
-                        const records = await ql.find(params.object, { filter: params.filters });
+                        const records = await ql.find(params.object, { where: params.filters });
                         return { object: params.object, records, total: records.length };
                     }
                 }

packages/client/src/client.msw.test.ts

@@ -57,15 +57,15 @@ describe('ObjectStackClient (with MSW Plugin)', () => {
                             return await protocol.findData({ object: params.object, query: params.query });
                         }
                         const queryOpts = params.query || {};
-                        const records = await ql.find(params.object, { filter: queryOpts.filters || queryOpts.filter });
+                        const records = await ql.find(params.object, { where: queryOpts.filters || queryOpts.filter || queryOpts.where });
                         return { object: params.object, records, total: records.length };
                     }
                     if (method === 'find') {
                         if (protocol) {
                             return await protocol.findData({ object: params.object, query: params.query });
                         }
                         const queryOpts = params.query || {};
-                        const records = await ql.find(params.object, { filter: queryOpts.filters || queryOpts.filter });
+                        const records = await ql.find(params.object, { where: queryOpts.filters || queryOpts.filter || queryOpts.where });
                         return { object: params.object, records, total: records.length };
                     }
                 }

packages/client/src/index.ts

@@ -113,6 +113,16 @@ export interface ClientConfig {
  */
 export type DiscoveryResult = GetDiscoveryResponse;
 
+/**
+ * @deprecated Use `data.query()` with standard QueryAST parameters instead.
+ * This interface uses legacy parameter names (filter/sort/top/skip) that
+ * require translation to QueryAST. Prefer QueryAST fields directly:
+ *   - filter → where
+ *   - select → fields
+ *   - sort → orderBy
+ *   - skip → offset
+ *   - top → limit
+ */
 export interface QueryOptions {
   select?: string[]; // Simplified Selection
   /** @canonical Preferred filter parameter (singular). */
@@ -1423,6 +1433,10 @@ export class ObjectStackClient {
       return this.unwrapResponse<PaginatedResult<T>>(res);
     },
 
+    /**
+     * @deprecated Use `data.query()` with standard QueryAST parameters instead.
+     * This method uses legacy parameter names. Internally adapts to HTTP GET params.
+     */
     find: async <T = any>(object: string, options: QueryOptions = {}): Promise<PaginatedResult<T>> => {
         const route = this.getRoute('data');
         const queryParams = new URLSearchParams();

packages/core/src/contracts/data-engine.ts

@@ -1,12 +1,12 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import { 
-  DataEngineQueryOptions, 
+  EngineQueryOptions,
   DataEngineInsertOptions, 
-  DataEngineUpdateOptions, 
-  DataEngineDeleteOptions,
-  DataEngineAggregateOptions, 
-  DataEngineCountOptions,
+  EngineUpdateOptions, 
+  EngineDeleteOptions,
+  EngineAggregateOptions, 
+  EngineCountOptions,
   DataEngineRequest,
 } from '@objectstack/spec/data';
 
@@ -17,22 +17,26 @@ import {
  * Following the Dependency Inversion Principle - plugins depend on this interface,
  * not on concrete database implementations.
  * 
+ * All query methods use standard QueryAST parameter names
+ * (where/fields/orderBy/limit/offset/expand) to eliminate mechanical translation
+ * between the Engine and Driver layers.
+ * 
  * Aligned with 'src/data/data-engine.zod.ts' in @objectstack/spec.
  */
 
 export interface IDataEngine {
-  find(objectName: string, query?: DataEngineQueryOptions): Promise<any[]>;
-  findOne(objectName: string, query?: DataEngineQueryOptions): Promise<any>;
+  find(objectName: string, query?: EngineQueryOptions): Promise<any[]>;
+  findOne(objectName: string, query?: EngineQueryOptions): Promise<any>;
   insert(objectName: string, data: any | any[], options?: DataEngineInsertOptions): Promise<any>;
-  update(objectName: string, data: any, options?: DataEngineUpdateOptions): Promise<any>;
-  delete(objectName: string, options?: DataEngineDeleteOptions): Promise<any>;
-  count(objectName: string, query?: DataEngineCountOptions): Promise<number>;
-  aggregate(objectName: string, query: DataEngineAggregateOptions): Promise<any[]>;
+  update(objectName: string, data: any, options?: EngineUpdateOptions): Promise<any>;
+  delete(objectName: string, options?: EngineDeleteOptions): Promise<any>;
+  count(objectName: string, query?: EngineCountOptions): Promise<number>;
+  aggregate(objectName: string, query: EngineAggregateOptions): Promise<any[]>;
 
   /**
    * Vector Search (AI/RAG)
    */
-  vectorFind?(objectName: string, vector: number[], options?: { filter?: any, limit?: number, select?: string[], threshold?: number }): Promise<any[]>;
+  vectorFind?(objectName: string, vector: number[], options?: { where?: any, limit?: number, fields?: string[], threshold?: number }): Promise<any[]>;
 
   /**
    * Batch Operations (Transactional)