Merge pull request #86 from objectstack-ai/copilot/evaluate-query-syntax-optimization

Author: huangyiirene

README.md

@@ -147,6 +147,18 @@ ObjectQL's driver architecture supports custom database implementations. Potenti
 
 ---
 
+## 🔍 Query Approaches
+
+ObjectQL supports three distinct query interfaces, each optimized for different scenarios:
+
+* **JSON-DSL (Core):** AI-friendly protocol, server-side logic, cross-driver compatibility
+* **REST API:** Simple CRUD operations, mobile apps, third-party integrations  
+* **GraphQL:** Complex data graphs, modern SPAs, efficient multi-table fetching
+
+**Looking for best practices?** Check out the [Query Best Practices Guide](./docs/guide/query-best-practices.md) for detailed comparisons, performance strategies, and optimization techniques.
+
+---
+
 ## 🛠️ Validation & Logic
 
 ObjectQL includes a powerful validation engine that runs universally.

docs/.vitepress/config.mts

@@ -26,6 +26,7 @@ const guideSidebar = [
       { text: 'Data Modeling', link: '/guide/data-modeling' },
       { text: 'Unified ID Migration', link: '/guide/migration-id-field' },
       { text: 'Querying Data', link: '/guide/querying' },
+      { text: 'Query Best Practices', link: '/guide/query-best-practices' },
       { text: 'Formulas & Rules Syntax', link: '/guide/formulas-and-rules' },
       { text: '↳ Quick Reference', link: '/guide/formulas-and-rules-quick-ref' },
       { text: 'Business Logic (Hooks)', link: '/guide/logic-hooks' },

docs/api/index.md

@@ -29,6 +29,9 @@ ObjectQL uses a **unified `id` field** as the primary key across all database dr
 | **GraphQL** | Modern frontends with complex data requirements | `POST /api/graphql` | [Read Guide](./graphql.md) |
 | **Metadata** | Admin interfaces, schema discovery | `/api/metadata/*` | [Read Guide](./metadata.md) |
 
+> **🚀 Want to optimize your queries?**  
+> Check out the [Query Best Practices Guide](../guide/query-best-practices.md) for performance optimization strategies, detailed comparisons, and recommendations to help you choose the best approach for your use case.
+
 ## Quick Links
 
 ### Core Concepts