Dashboard\Classes\ReportQueryBuilder

Overview

ReportQueryBuilder provides a fluent interface for building dashboard report queries.

This is the recommended way to build report queries. For backward compatibility, the original ReportDataQueryBuilder class is still available.

Basic Usage

$result = ReportQueryBuilder::table('orders')
    ->dimension($dimension)
    ->metrics($metrics)
    ->orderBy($orderRule)
    ->groupByYear()
    ->hideEmptyValues()
    ->dateRange(Carbon::parse('2020-01-01'), now(), 'order_date')
    ->get($metricsConfiguration);

Using fromFetchData (recommended for data sources)

protected function fetchData(ReportFetchData $data): ReportFetchDataResult
{
    return ReportQueryBuilder::fromFetchData($data, 'my_table')
        ->dateColumn('created_at')
        ->get($data->metricsConfiguration);
}

With Custom Query Logic

$result = ReportQueryBuilder::fromFetchData($data, 'orders')
    ->dateColumn('order_date')
    ->onConfigureQuery(function ($query, $dimension, $metrics) {
        $query->where('status', 'completed');
        $query->join('customers', 'orders.customer_id', '=', 'customers.id');
    })
    ->get($data->metricsConfiguration);

Comparison with ReportDataQueryBuilder

Old approach (15 constructor parameters):

$builder = new ReportDataQueryBuilder(
    'orders', $dimension, $metrics, $orderRule, $filters, 100, null,
    'year', true, Carbon::parse('2020-01-01'), now(), null, 'order_date', null, false
);

New approach (fluent interface):

$builder = ReportQueryBuilder::table('orders')
    ->dimension($dimension)
    ->metrics($metrics)
    ->orderBy($orderRule)
    ->filters($filters)
    ->limit(100)
    ->groupByYear()
    ->hideEmptyValues()
    ->dateRange(Carbon::parse('2020-01-01'), now(), 'order_date');

---

Protected Properties

protected string $tableName

Table name for the query

protected ReportDimension $dimension

The dimension to query

protected ReportMetric[] $metrics

Metrics to aggregate

protected ReportDataOrderRule|null $orderRule

Ordering rule

protected [[ReportDimensionFilter[]|null]] $filters

Filters to apply

protected int|null $limit

Result limit

protected ReportDataPaginationParams|null $pagination

Pagination parameters

protected string $groupInterval

Group interval (day, week, month, quarter, year, full)

protected bool $hideEmptyValues

Whether to hide null dimension values

protected bool $totalsOnly

Only return totals, not rows

protected Carbon|null $dateStart

Date range start

protected Carbon|null $dateEnd

Date range end

protected string|null $dateColumn

Date column name for filtering

protected int|null $startTimestamp

Timestamp for relative intervals

protected string|null $timestampColumn

Timestamp column for relative filtering

protected callable|null $queryCallback

Query configuration callback

protected callable|null $metricsCallback

Metrics configuration callback

protected callable|null $metricCallback

Single metric configuration callback

---

Public Methods

public addMetric()

public addMetric(ReportMetric $metric): $this 

addMetric adds a single metric

public dateColumn()

public dateColumn(string $column): $this 

dateColumn sets the date column name

public dateRange()

public dateRange(
    Carbon $start,
    Carbon $end,
    string|null $column = null
): $this 

dateRange sets the date range and column for filtering

public dimension()

public dimension(ReportDimension $dimension): $this 

dimension sets the dimension to group by

public filters()

public filters(array $filters): $this 

filters sets dimension filters

public static fromFetchData()

public static fromFetchData(
    ReportFetchData $data,
    string $tableName
): static 

fromFetchData creates builder from ReportFetchData (backward compatible shorthand)

public get()

public get(
    array $metricsConfiguration = [],
    string|null $recordUrlTemplate = null
): ReportFetchDataResult 

get executes the query and returns results

public getMetricTotals()

public getMetricTotals(array $metricsConfiguration): array 

getMetricTotals returns totals for specified metrics

public getTotalRecords()

public getTotalRecords(): int 

getTotalRecords returns the total unpaginated count

public groupByDay()

public groupByDay(): $this 

groupByDay groups results by day

public groupByMonth()

public groupByMonth(): $this 

groupByMonth groups results by month

public groupByQuarter()

public groupByQuarter(): $this 

groupByQuarter groups results by quarter

public groupByWeek()

public groupByWeek(): $this 

groupByWeek groups results by week

public groupByYear()

public groupByYear(): $this 

groupByYear groups results by year

public groupInterval()

public groupInterval(string|null $interval): $this 

groupInterval sets the grouping interval

public hideEmptyValues()

public hideEmptyValues(bool $hide = true): $this 

hideEmptyValues hides null dimension values from results

public limit()

public limit(int $limit): $this 

limit sets the maximum number of results

public metrics()

public metrics(array $metrics): $this 

metrics sets the metrics to aggregate

public onConfigureMetric()

public onConfigureMetric(callable $callback): $this 

onConfigureMetric registers a callback for individual metric customization

public onConfigureMetrics()

public onConfigureMetrics(callable $callback): $this 

onConfigureMetrics registers a callback for metrics customization

public onConfigureQuery()

public onConfigureQuery(callable $callback): $this 

onConfigureQuery registers a callback for query customization

public orderBy()

public orderBy(ReportDataOrderRule|null $rule): $this 

orderBy sets the ordering rule

public paginate()

public paginate(ReportDataPaginationParams $params): $this 

paginate sets pagination parameters

public sinceTimestamp()

public sinceTimestamp(
    int $timestamp,
    string|null $column = null
): $this 

sinceTimestamp sets relative timestamp filtering

public static table()

public static table(string $tableName): static 

table creates a new builder instance for the given table

public timestampColumn()

public timestampColumn(string $column): $this 

timestampColumn sets the timestamp column name

public toQuery()

public toQuery(): QueryBuilder 

toQuery returns the underlying Laravel query builder

Use this for advanced customization or when you need direct access to the query. For most cases, use get() instead.

public toSql()

public toSql(): string 

toSql returns the SQL query string (for debugging)

public totalsOnly()

public totalsOnly(bool $totals = true): $this 

totalsOnly returns only aggregated totals, no rows

public when()

public when(mixed $condition, callable $callback): $this 

when conditionally applies configuration

public withoutGrouping()

public withoutGrouping(): $this 

withoutGrouping disables grouping (full interval)

Protected Methods

protected applyDateFilters()

protected applyDateFilters(QueryBuilder $query): void 

applyDateFilters applies date range or timestamp filtering

protected applyFilter()

protected applyFilter(
    QueryBuilder $query,
    ReportDimensionFilter $filter
): void 

applyFilter applies a single filter

protected applyFilters()

protected applyFilters(QueryBuilder $query): void 

applyFilters applies dimension filters

protected applyOrderRule()

protected applyOrderRule(QueryBuilder $query): void 

applyOrderRule applies ordering

protected buildDimensionColumns()

protected buildDimensionColumns(QueryBuilder $query): array 

buildDimensionColumns builds dimension select columns

protected buildMetricColumns()

protected buildMetricColumns(
    QueryBuilder $query,
    array $metrics
): array 

buildMetricColumns builds metric select columns

protected buildQuery()

protected buildQuery(
    bool $skipGrouping = false,
    bool $skipPagination = false,
    array $forceMetrics = []
): QueryBuilder 

buildQuery constructs the query builder

protected evalDbObjectName()

protected evalDbObjectName(string $name): string 

evalDbObjectName validates and trims a database object name

protected getAggregateSql()

protected getAggregateSql(string $function): string 

getAggregateSql returns SQL template for aggregate function

protected makeDateGroupingExpression()

protected makeDateGroupingExpression(string $column): string 

makeDateGroupingExpression creates SQL expression for date grouping

protected validate()

protected validate(): void 

validate ensures required properties are set