# 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`](../runbook.md) for incident handling.
- Follow [`../security.md`](../security.md) for sensitive data and access constraints.
- Use [`../troubleshooting.md`](../troubleshooting.md#query-and-index-issues) 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`.