# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.

from typing import Dict, List, Union, Optional
from datetime import datetime
from typing_extensions import Literal, TypeAlias

from pydantic import Field as FieldInfo

from .._models import BaseModel
from .chart_type import ChartType
from .measurement_type import MeasurementType
from .reporting_query_date_trunc import ReportingQueryDateTrunc
from .reporting_column_metadata_output import ReportingColumnMetadataOutput
from .reporting.datasources.reporting_query_datasource import ReportingQueryDatasource

__all__ = [
    "ReportingQueryResponse",
    "Data",
    "DataResultDataResultItem",
    "DataVisualization",
    "DataVisualizationFieldMapping",
    "DataVisualizationFieldMappingMeasure",
    "DataVisualizationFieldMappingDimension",
    "DataVisualizationFieldMappingDimensionDimensionBase",
    "DataVisualizationFieldMappingDimensionDimensionDate",
    "DataVisualizationFieldMappingSeries",
    "DataVisualizationFieldMappingSeriesValue",
    "Pagination",
]


class DataResultDataResultItem(BaseModel):
    """A distinct value from a datasource column with id and display name.

    Can be null for optional fields.
    """

    id: str
    """Value identifier"""

    name: str
    """Human-readable value name"""


class DataVisualizationFieldMappingMeasure(BaseModel):
    field: str
    """Column name for y-axis value/measure"""

    label: str
    """Human-readable label for this measure"""

    aggregation: Optional[MeasurementType] = None
    """Aggregation function used for this measure"""


class DataVisualizationFieldMappingDimensionDimensionBase(BaseModel):
    """Dimension specification for non-date columns (string, number, boolean)"""

    field: str
    """Column name for x-axis/dimension"""

    type: Literal["string", "number", "boolean"]
    """Data type of the dimension field"""


class DataVisualizationFieldMappingDimensionDimensionDate(BaseModel):
    """Dimension specification for date columns with truncation and date range"""

    date_trunc: ReportingQueryDateTrunc = FieldInfo(alias="dateTrunc")
    """Date truncation level for grouping (year, month, week, day, hour)"""

    field: str
    """Date column name for x-axis/dimension"""

    type: Literal["date"]
    """Data type indicating a date dimension"""

    from_: Optional[datetime] = FieldInfo(alias="from", default=None)
    """Start date for date range (ISO 8601 format).

    Derived from date filter or query results.
    """

    to: Optional[datetime] = None
    """End date for date range (ISO 8601 format).

    Derived from date filter or query results.
    """


DataVisualizationFieldMappingDimension: TypeAlias = Union[
    DataVisualizationFieldMappingDimensionDimensionBase, DataVisualizationFieldMappingDimensionDimensionDate
]


class DataVisualizationFieldMappingSeriesValue(BaseModel):
    id: Union[str, float, bool, None] = None
    """Unique identifier value for this series"""

    name: Union[str, float, bool, None] = None
    """Display name for this series (resolved from related table if applicable)"""


class DataVisualizationFieldMappingSeries(BaseModel):
    field: str
    """Secondary groupBy field that defines separate lines/series in line charts"""

    values: List[DataVisualizationFieldMappingSeriesValue]
    """List of unique values for this series field, with id and resolved display name"""


class DataVisualizationFieldMapping(BaseModel):
    """
    Field mapping describing which fields to use for dimensions (x-axis) and measures (y-axis)
    """

    measures: List[DataVisualizationFieldMappingMeasure]
    """Measure fields (y-axis values). Contains measurement columns from the query."""

    dimension: Optional[DataVisualizationFieldMappingDimension] = None
    """Dimension field (x-axis).

    Present for grouped queries, omitted for non-grouped queries.
    """

    series: Optional[List[DataVisualizationFieldMappingSeries]] = None
    """Series definitions for multi-line charts.

    Present when there are secondary groupBy fields beyond the primary dimension
    (e.g., topicId when grouping by createdAt and topicId). Each series represents a
    separate line in the chart.
    """


class DataVisualization(BaseModel):
    """
    Visualization metadata describing compatible chart types and field mappings for rendering
    """

    compatible_charts: List[ChartType] = FieldInfo(alias="compatibleCharts")
    """
    Chart types that are compatible with the query structure and can display the
    data
    """

    field_mapping: DataVisualizationFieldMapping = FieldInfo(alias="fieldMapping")
    """
    Field mapping describing which fields to use for dimensions (x-axis) and
    measures (y-axis)
    """

    recommended_chart: ChartType = FieldInfo(alias="recommendedChart")
    """
    Recommended default chart type based on query structure (e.g., line for
    time-series, table for categories)
    """


class Data(BaseModel):
    columns: List[ReportingColumnMetadataOutput]
    """Column metadata describing the structure of the results.

    For non-groupBy queries, includes all datasource columns. For groupBy queries,
    includes groupBy columns and measurement columns.
    """

    datasource: ReportingQueryDatasource

    results: List[Dict[str, Optional[DataResultDataResultItem]]]

    visualization: DataVisualization
    """
    Visualization metadata describing compatible chart types and field mappings for
    rendering
    """


class Pagination(BaseModel):
    """Pagination metadata returned in a paginated response."""

    limit: int
    """Number of items per page."""

    skip: int
    """Number of items skipped."""

    total: int
    """Total number of items available."""

    total_pages: int = FieldInfo(alias="totalPages")
    """Total number of pages available."""

    total_count: Optional[int] = FieldInfo(alias="totalCount", default=None)
    """Total number of items without filters applied.

    Used to distinguish between truly empty results and empty filtered results.
    """


class ReportingQueryResponse(BaseModel):
    """
    Successful response from reporting query with column metadata and visualization hints
    """

    data: Data

    pagination: Pagination
    """Pagination metadata returned in a paginated response."""
