CBDD/docs/features/query-and-indexing.md

Query And Indexing

Purpose And Business Outcome

Deliver predictable query correctness and performance using expression translation with index-aware execution.

Scope And Non-Goals

Scope:

• LINQ query translation
• Primary and secondary index usage
• Scan fallback where index optimization is not applicable

Non-goals:

• Full SQL compatibility
• Distributed query federation

User And System Workflows

1. Consumer submits LINQ expression.
2. Query planner evaluates index opportunities.
3. Engine executes index-backed or scan path.
4. Results are materialized to consumer entities.

Interfaces And APIs

• AsQueryable() and query provider components
• CollectionIndexManager
• Index implementations under src/CBDD.Core/Indexing

Permissions And Data Handling

• Query access follows host application authorization policy.
• Indexed data inherits the same sensitivity classification as source payloads.

Dependencies And Failure Modes

Dependencies:

• Valid index metadata and storage consistency
• Expression visitor correctness

Failure modes:

• Incorrect predicate translation
• Missing/ineffective indexes
• Performance regressions due to scan-heavy paths

Monitoring, Alerts, And Troubleshooting

• Track query-related regressions in automated tests.
• Use ../runbook.md for incident handling.
• Follow ../security.md for sensitive data and access constraints.
• Use ../troubleshooting.md for remediation.

Rollout And Change Considerations

• Query planner/index behavior changes require benchmark comparison and regression coverage.
• Document breaking semantics in release notes.

Validation Guidance

• Run query, index, and optimizer test suites in tests/CBDD.Tests.
• Confirm coverage gate with bash scripts/coverage-check.sh.