ReportEngineProtocol

Protocol defining the contract for report engine implementations.

Report engines execute queries against various data sources
and return structured results for display or export.

Key concepts:
- **Execute**: Run a query and return results
- **Validate**: Check query syntax before execution
- **Zero-cliff**: Same protocol for SQL, Elastic, ClickHouse

Source: report_engine.py

Methods

execute

async def execute(self,
    query: str,
    parameters: dict[str, Any] | None = None,
) -> ReportResult

Execute a report query and return results.

    Args:
        query: The query string (SQL, Elastic DSL JSON, etc.)
        parameters: Optional query parameters for parameterized queries

    Returns:
        ReportResult containing rows and metadata

    Raises:
        QueryExecutionError: If query execution fails
        ValidationError: If query is invalid

validate

async def validate(self, query: str) -> bool

Validate query syntax without executing.

    Args:
        query: The query string to validate

    Returns:
        True if query is syntactically valid, False otherwise

Adapters

• SQLReportEngine
• ElasticReportEngine
• ClickHouseReportEngine