Uh oh!
There was an error while loading. Please reload this page.
Add granular query operation capabilities to driver schema - #49
Conversation
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
hotlong
commented
Jan 21, 2026
@copilot 目前实现已经非常完整，我只有一个小的建议供参考： • 默认值考虑：目前所有新标志的默认值似乎都是 false（在 JSON Schema 中显式设为 false，Zod 中虽未显式但在测试中体现了这一点）。这是一个安全的默认策略（“悲观策略”），确保了如果驱动没声明支持，引擎会兜底处理。这很好。 |
There was a problem hiding this comment.
Pull request overview
This pull request adds granular query operation capabilities to the driver schema, enabling ObjectQL to determine which query operations can be pushed to the database driver versus computed in-memory. The PR introduces 6 new capability flags for common query operations (filters, aggregations, sorting, pagination, window functions, and subqueries).
Changes:
- Added 6 new query capability boolean flags to
DriverCapabilitiesSchemaandDatasourceCapabilitiesschemas - Updated all test fixtures with realistic capability matrices for PostgreSQL, MongoDB, Salesforce, Redis, and a new memory driver example
- Regenerated JSON schemas and documentation with new capability fields
Reviewed changes
Copilot reviewed 10 out of 10 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| packages/spec/src/system/driver.zod.ts | Added 6 query capability fields to DriverCapabilitiesSchema with comprehensive JSDoc documentation and .describe() calls |
| packages/spec/src/system/datasource.zod.ts | Added 6 query capability fields to DatasourceCapabilities; removed aggregation field in favor of queryAggregations |
| packages/spec/src/system/driver.test.ts | Updated all test fixtures with new capability flags; added realistic examples for PostgreSQL, MongoDB, Salesforce, Redis, and memory drivers |
| packages/spec/json-schema/DriverInterface.json | Auto-generated JSON schema updated with new required capability fields |
| packages/spec/json-schema/DriverDefinition.json | Auto-generated JSON schema updated with new capability fields and defaults |
| packages/spec/json-schema/DriverCapabilities.json | Auto-generated JSON schema updated with new required capability fields |
| packages/spec/json-schema/DatasourceCapabilities.json | Auto-generated JSON schema updated with new capability fields and defaults |
| packages/spec/json-schema/Datasource.json | Auto-generated JSON schema updated with new capability fields |
| content/docs/references/system/integration/DatasourceCapabilities.mdx | Auto-generated documentation updated with new capability fields (missing descriptions) |
| content/docs/references/system/DriverCapabilities.mdx | Auto-generated documentation updated with new capability fields and descriptions |
| /** Can execute WHERE clause filters natively? */ | ||
| queryFilters: z.boolean().default(false), | ||
| /** Can perform aggregation (group by, sum, avg)? */ | ||
| queryAggregations: z.boolean().default(false), | ||
| /** Can perform ORDER BY sorting? */ | ||
| querySorting: z.boolean().default(false), | ||
| /** Can perform LIMIT/OFFSET pagination? */ | ||
| queryPagination: z.boolean().default(false), | ||
| /** Can perform window functions? */ | ||
| queryWindowFunctions: z.boolean().default(false), | ||
| /** Can perform subqueries? */ | ||
| querySubqueries: z.boolean().default(false), |
There was a problem hiding this comment.
The new query capability fields in DatasourceCapabilities lack .describe() method calls, which causes the auto-generated documentation to have empty descriptions. For consistency with DriverCapabilitiesSchema (which uses both JSDoc comments and .describe() calls) and to ensure proper documentation generation, each field should include a .describe() call with the description text.
For example:
queryFilters: z.boolean().default(false).describe('Can execute WHERE clause filters natively?')queryAggregations: z.boolean().default(false).describe('Can perform aggregation (group by, sum, avg)?')
This would ensure the generated documentation tables include meaningful descriptions for each capability.
| /** Can execute WHERE clause filters natively? */ | ||
| queryFilters: z.boolean().default(false), | ||
There was a problem hiding this comment.
The removal of the aggregation capability field and its replacement with queryAggregations is a breaking change. While this rename provides better clarity and consistency with the new query capability naming scheme, any existing code that references capabilities.aggregation will break.
Consider:
- Adding a migration guide or deprecation notice in the PR description
- If backwards compatibility is required, temporarily supporting both field names with the old one marked as deprecated
- Documenting this breaking change in a CHANGELOG or migration guide
| /** | |
| * @deprecatedUse`queryAggregations`instead. | |
| *Legacyaggregationcapabilityflagkeptforbackwardscompatibility. | |
| */ | |
| aggregation: z.boolean().default(false).describe('Deprecated: use queryAggregations'), | |
Add missing query operation capabilities (queryFilters, queryAggregations, querySorting, queryPagination, queryWindowFunctions, querySubqueries) to match the updated DriverCapabilitiesSchema. Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
Based on code review, updated capability flags to accurately reflect the current implementation. Only queryPagination, jsonFields, and arrayFields are actually supported. Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
Drivers currently can only declare high-level capabilities (transactions, joins, full-text search). No mechanism exists to specify support for individual query operations, preventing ObjectQL from determining whether to push operations to the driver or compute in-memory.
Changes
Schema Enhancements
DriverCapabilitiesSchemaandDatasourceCapabilities:queryFilters- WHERE clause supportqueryAggregations- GROUP BY/aggregation functionsquerySorting- ORDER BY supportqueryPagination- LIMIT/OFFSET supportqueryWindowFunctions- Window functions with OVER clausequerySubqueries- Nested SELECT supportTest Coverage
Generated Artifacts
Example
ObjectQL can now inspect these flags to determine whether to push query operations to the driver or handle them in-memory.
Original prompt
💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.