Add query best practices documentation

[Copilot]

Query Best Practices Documentation

Task: Create best practices documentation for querying in ObjectQL.

Completed:

• Create comprehensive query best practices guide
• Rename to reflect "best practices" positioning
• Remove Chinese translation (English only)
• Address code review feedback

Recent Changes (Code Review Fixes):

1. Added star rating legend - Clarified that ⭐ = lowest, ⭐⭐⭐⭐⭐ = highest
2. Fixed object mutation patterns - Updated code examples to use immutable transformations with spread syntax instead of direct property assignment
3. Clarified AI hallucination example - Added explicit label "Example of AI hallucination:" before SQL code block
4. Removed broken link - Removed reference to non-existent performance.md file

Documentation Content:

• Primary Guide: docs/guide/query-best-practices.md (17KB)
  • Comparative analysis: JSON-DSL vs REST vs GraphQL
  • 10+ optimization patterns with quantified impact
  • Scenario-based recommendations
  • Decision tree and migration paths
  • All code examples now follow immutable data transformation patterns

Integration:

• Cross-referenced in 5 locations
• Navigation entry: "Data & Logic Layers" → "Query Best Practices"
• Links from: README.md, querying.md, query-language.md, api/index.md

Original prompt

评估我目前的查询语法有替代或者优化方案吗？给我写文档回复就行。

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[huangyiirene]

@copilot 你这个文档算不算是查询的最佳实践，要不要调整一下文件位置还有全部用英文。

[Copilot]

@copilot 你这个文档算不算是查询的最佳实践，要不要调整一下文件位置还有全部用英文。

Good point! I've made the following changes in commit 812b9f3:

1. ✅ Renamed file to query-best-practices.md to reflect it's a best practices guide
2. ✅ Removed Chinese translation (query-syntax-alternatives-zh.md) - using English only
3. ✅ Updated title to "Query Best Practices"
4. ✅ Updated all cross-references and navigation menu

The document is now positioned as a best practices guide under "Data & Logic Layers" → "Query Best Practices" in the documentation navigation.

[Copilot]

Pull request overview

This PR adds comprehensive query best practices documentation in response to a request for evaluation of query syntax alternatives and optimization strategies. The documentation provides detailed comparisons between JSON-DSL, REST, and GraphQL interfaces along with quantified performance optimization techniques.

Changes:

• Added a new 17KB best practices guide covering three query interfaces with performance benchmarks, optimization patterns, and scenario-based recommendations
• Integrated navigation and cross-references across 5 documentation locations to improve discoverability

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
docs/guide/query-best-practices.md	New comprehensive guide with comparative analysis, 10+ optimization patterns with quantified impact metrics, and decision trees
docs/.vitepress/config.mts	Added navigation entry for "Query Best Practices" in the guide sidebar
docs/guide/querying.md	Added cross-reference callout linking to the new best practices guide
docs/spec/query-language.md	Added cross-reference callout linking to the best practices guide
docs/api/index.md	Added cross-reference callout linking to the best practices guide
README.md	Added "Query Approaches" section with summary and link to detailed guide

[Copilot]

The star rating system lacks an explicit legend defining what the ratings represent (e.g., 5 stars = excellent, 1 star = poor). Without this context, readers must infer the meaning, which could lead to misinterpretation. Consider adding a note below the table or in the column header, such as "Performance (⭐ = lowest, ⭐⭐⭐⭐⭐ = highest)" to clarify the rating scale.

[Copilot]

Added rating scale legend below the table in commit 619ab62: "Rating scale: ⭐ = lowest, ⭐⭐⭐⭐⭐ = highest"

[Copilot]

The code mutates the task objects retrieved from the database by directly assigning properties. This pattern can lead to unexpected behavior if the task objects are frozen or have property descriptors that prevent assignment. Consider using a more explicit approach such as creating new objects or using spread syntax to make the transformation explicit.

Suggested change

	for (const task of tasks) {
	task.project = await app.object('project').findOne(task.project_id);
	task.assignee = await app.object('user').findOne(task.assignee_id);
	const tasksWithRelations = [];
	for (const task of tasks) {
	const project = await app.object('project').findOne(task.project_id);
	const assignee = await app.object('user').findOne(task.assignee_id);
	tasksWithRelations.push({
	...task,
	project,
	assignee
	});

[Copilot]

Fixed in commit 619ab62. Updated code to use immutable pattern with spread syntax, creating new objects in an enrichedTasks array instead of mutating the original task objects.

[Copilot]

Similar to a previous example, this code mutates task objects directly. This pattern is repeated in multiple code examples throughout the document. Consider establishing a consistent pattern for handling data transformations to improve maintainability and avoid potential issues with object mutation.

Suggested change

	// Bad: N+1 queries
	const tasks = await taskRepo.find();
	for (const task of tasks) {
	task.assignee = await userRepo.findOne(task.assignee_id);
	}
	// Good: Batched loading (1+1 queries)
	const tasks = await taskRepo.find();
	const userIds = tasks.map(t => t.assignee_id);
	const users = await userRepo.find({
	filters: [['id', 'in', userIds]]
	});
	const userMap = new Map(users.map(u => [u.id, u]));
	tasks.forEach(task => {
	task.assignee = userMap.get(task.assignee_id);
	});
	// Bad: N+1 queries (inefficient, but shown immutably)
	const tasks = await taskRepo.find();
	const tasksWithAssignee = await Promise.all(
	tasks.map(async (task) => ({
	...task,
	assignee: await userRepo.findOne(task.assignee_id),
	})),
	);
	// Good: Batched loading (1+1 queries, immutable transformation)
	const tasks = await taskRepo.find();
	const userIds = tasks.map((t) => t.assignee_id);
	const users = await userRepo.find({
	filters: [['id', 'in', userIds]],
	});
	const userMap = new Map(users.map((u) => [u.id, u]));
	const tasksWithAssigneeBatched = tasks.map((task) => ({
	...task,
	assignee: userMap.get(task.assignee_id),
	}));

[Copilot]

Applied consistent immutable pattern in commit 619ab62. Both bad and good examples now use map() to create new objects with spread syntax instead of forEach() with mutations.

[Copilot]

The SQL example demonstrates a hallucinated function but doesn't clearly indicate this is intentional to show AI failure modes. While the error comment is present, adding an explicit note like "Example of AI hallucination:" before the code block would make the educational intent clearer and prevent confusion about whether this is a documentation error.

[Copilot]

Added explicit label in commit 619ab62: "Example of AI hallucination:" now appears before the SQL code block to clearly indicate this demonstrates an AI failure mode.

[Copilot]

The references to ../api/graphql.md, ../api/rest.md, and ./performance.md may be broken links if these files don't exist in the repository. Since this is a new documentation file being added, verify that all referenced files exist or update the links to point to existing documentation. Dead links negatively impact documentation usability.

Suggested change

	- [Performance Tuning](./performance.md) - Advanced optimization strategies
	- Performance Tuning - Advanced optimization strategies

[Copilot]

Fixed in commit 619ab62. Removed the broken link to performance.md as this file doesn't exist. The other links (graphql.md, rest.md) have been verified to exist.

[huangyiirene]

@copilot fix

[Copilot]

@copilot fix

Fixed all review issues in commit 619ab62:

1. ✅ Added star rating legend (⭐ = lowest, ⭐⭐⭐⭐⭐ = highest)
2. ✅ Fixed object mutation patterns - using immutable transformations with spread syntax
3. ✅ Added "Example of AI hallucination:" label for clarity
4. ✅ Removed broken link to non-existent performance.md file

All code examples now follow immutable data transformation patterns instead of direct property mutations.