Statistics API

Burst Statistics v3.3.0 exposes a PHP API for querying analytics data programmatically. The entry point is the Statistics class, backed by the Query_Data value object that constructs and sanitizes SQL queries.

---

Architecture Overview

Statistics (class-statistics.php)
  └── Query_Data (class-query-data.php)   ← value object, builds SQL
  └── Goal_Statistics (class-goal-statistics.php)  ← goal-specific queries

All queries target a set of custom database tables prefixed with {$wpdb->prefix}burst_. Execution time for every query is automatically stored in burst_query_stats for slow-query analysis.

---

Database Tables

Table	Purpose
burst_statistics	Raw page-hit records
burst_sessions	Session records (browser, device, referrer, etc.)
burst_browsers	Browser lookup table
burst_browser_versions	Browser version lookup table
burst_platforms	OS/platform lookup table
burst_devices	Device type lookup table
burst_referrers	Referrer lookup table
burst_goals	Goal definitions
burst_goal_statistics	Goal completion events
burst_known_uids	Known visitor UIDs with first/last seen timestamps
burst_query_stats	Query execution time statistics

burst_statistics schema

Breaking change

In v3.3.0 the columns browser_id, browser_version_id, platform_id, device_id, first_time_visit, and bounce were moved from burst_statistics to burst_sessions. Any custom SQL or filters that reference statistics.browser_id, statistics.device_id, statistics.first_time_visit, or statistics.bounce must be updated to use the sessions.* prefix. A database migration runs automatically on upgrade via the move_columns_to_sessions upgrade routine.

Column	Type	Description
ID	int AUTO_INCREMENT	Primary key
page_url	varchar(191)	URL of the visited page
page_id	int(11)	WordPress post/page ID
page_type	varchar(191)	Post type (e.g. post, page)
time	int	Unix timestamp of the hit
uid	varchar(64)	Visitor unique identifier
time_on_page	int	Time spent on page (milliseconds)
parameters	TEXT	Serialized URL parameters
fragment	varchar(255)	URL fragment
session_id	int	FK → burst_sessions.ID

burst_sessions schema (selected columns)

The following columns were added to burst_sessions in v3.3.0:

Column	Type	Description
browser_id	int	FK → burst_browsers.ID
browser_version_id	int	FK → burst_browser_versions.ID
platform_id	int	FK → burst_platforms.ID
device_id	int	FK → burst_devices.ID
first_time_visit	tinyint	1 if this session is the visitor's first
bounce	tinyint	1 if the session is a bounce (default 1)

---

The Query_Data Class

Query_Data is the query builder. Pass an associative array of options to its constructor; it validates and sanitizes every value before use.

use Burst\Admin\Statistics\Query_Data;

$qd = new Query_Data( [
    'date_start' => strtotime( '2024-01-01' ),
    'date_end'   => strtotime( '2024-01-31' ),
    'select'     => [ 'pageviews', 'visitors' ],
    'filters'    => [ 'device' => 'mobile' ],
    'group_by'   => 'page_url',
    'order_by'   => 'pageviews DESC',
    'limit'      => 10,
] );

Constructor Parameters

Parameter	Type	Default	Description
date_start	int	0	Start of the date range (Unix timestamp)
date_end	int	0	End of the date range (Unix timestamp)
select	string[]	['*']	Metrics to retrieve (see Available Metrics)
filters	array	[]	Key/value filters (see Available Filters)
filter_exclusions	array	[]	Per-filter mode: 'include' or 'exclude'; automatically set when a filter value is prefixed with !
group_by	string|string[]	[]	Field(s) to group by
order_by	string|string[]	[]	Field(s) to order by, e.g. 'pageviews DESC'
limit	int	0	Maximum rows to return (0 = unlimited)
joins	array	[]	Additional JOIN configurations
date_modifiers	array	[]	Date interval settings for period grouping
having	array	[]	HAVING clause conditions
custom_select	string	''	Raw SELECT fragment (admin-only; validated and prepared)
custom_select_parameters	array	[]	Prepared-statement parameters for custom_select
custom_where	string	''	Raw WHERE fragment (admin-only; validated and prepared)
custom_where_parameters	array	[]	Prepared-statement parameters for custom_where
subquery	string	''	Wraps the main query as a subquery with the given alias
union	array	[]	SQL strings to UNION with the main query
distinct	bool	false	Add DISTINCT to SELECT
window	array	[]	Window function definitions keyed by alias
exclude_bounces	bool	false	Automatically set to true when filters['bounces'] = 'exclude'

Strict Mode

Query_Data automatically applies strict mode for non-administrator users. In strict mode:

• Only a limited set of metrics may be selected (see burst_allowed_metric_keys filter).
• Only a limited set of filter keys are accepted.
• custom_select and custom_where are silently ignored.

The default strict-mode metric allowlist is:

pageviews, visitors, sessions, bounce_rate, avg_time_on_page,
first_time_visitors, page_url, referrer, device

Filter Exclusions

Prefix any filter value with ! to exclude rather than include matching rows:

$qd = new Query_Data( [
    'date_start' => $start,
    'date_end'   => $end,
    'select'     => [ 'pageviews', 'page_url' ],
    'filters'    => [ 'device' => '!mobile' ],   // exclude mobile
] );

---

Available Metrics

These are the metric keys accepted in the select parameter:

Key	Label	Notes
pageviews	Pageviews
visitors	Visitors	Distinct UIDs
sessions	Sessions	Distinct session IDs
first_time_visitors	New visitors
avg_time_on_page	Avg. time on page	Milliseconds
avg_session_duration	Avg. session duration
bounce_rate	Bounce rate	Percentage
bounces	Bounced visitors
conversions	Goal completions	Requires goal_id filter
conversion_rate	Goal conv. rate
page_url	Page
referrer	Referrer
host	Domain
device	Device
browser	Browser
platform	Platform
device_id	Device (ID)	Resolved from sessions.device_id
browser_id	Browser (ID)	Resolved from sessions.browser_id
platform_id	Platform (ID)	Resolved from sessions.platform_id
count	Count	Alias for pageviews
period	Period	Used with group_by: 'period'
time	Time	Raw timestamp column
time_on_page	Time on page
uid	UID
page_id	Page ID

⭐ Pro

The following metrics are available in Burst Statistics Pro:

Key	Label
country_code	Country
city	City
state	State
continent_code	Continent
source	Source (UTM)
medium	Medium (UTM)
campaign	Campaign (UTM)
term	Term (UTM)
content	Content (UTM)
parameter	URL Parameter
product	Product
sales	Sales
revenue	Revenue
page_value	Page value
sales_conversion_rate	Sales conv. rate
avg_order_value	Avg. order value
adds_to_cart	Added to cart
entrances	Entrances
exit_rate	Exit rate
time_per_session	Time per session

Burst Statistics Pro

---

Available Filters

Filters narrow query results. Pass them as an associative array to Query_Data via the filters key.

Key	Description	Values
page_url	Filter by page URL	String, supports * wildcard suffix
page_id	Filter by WordPress page ID	Integer
page_type	Filter by post type	Public post type string
referrer	Filter by referrer URL	String
device	Filter by device type	desktop, tablet, mobile, other
browser	Filter by browser name	String
platform	Filter by OS/platform	String
device_id	Filter by device lookup ID	Integer
browser_id	Filter by browser lookup ID	Integer
platform_id	Filter by platform lookup ID	Integer
goal_id	Filter by goal ID (admin only)	Integer
bounces	Include/exclude bounced sessions (admin only)	include, exclude
new_visitor	Filter first-time visitors (admin only)	include, exclude
entry_exit_pages	Filter entry or exit pages (admin only)	entry, exit
host	Filter by domain/host (admin only)	String
parameter	Filter by URL parameter (admin only)	key, key=value

⭐ Pro

The following filters are available in Burst Statistics Pro:

Key	Description	Values	Notes
time_per_session	Filter sessions by total time spent	"MIN-MAX" or "MIN-" in seconds	Added in v3.3.0. E.g. "30-120" for 30–120 s; "600-" for 600 s and above.

$qd = new Query_Data( [
    'date_start' => $start,
    'date_end'   => $end,
    'select'     => [ 'pageviews', 'sessions' ],
    'filters'    => [ 'time_per_session' => '30-120' ],  // sessions with 30–120 s total
] );

The value is sanitized by sanitize_time_per_session_filter(). Both MIN and MAX are integers representing seconds; internally they are multiplied by 1000 to compare against the millisecond time_on_page column. If MAX is omitted (open-ended range), use the "MIN-" format.

Burst Statistics Pro

---

The Statistics Class

Obtain the singleton via:

$statistics = \Burst\burst_loader()->admin->statistics;

---

get_live_visitors_data()

Returns the number of visitors currently active on the site (within the last 10 minutes, excluding sessions that have been idle longer than the exit margin).

$count = $statistics->get_live_visitors_data();
// returns int

---

get_live_traffic_data()

Returns an array of the most recent page-hit objects within the last 10 minutes. Each object includes entry/exit/checkout flags.

$rows = $statistics->get_live_traffic_data();

Return shape (per object):

Property	Type	Description
active_time	float	time + time_on_page / 1000
utm_source	string	Session referrer
page_url	string	Page URL
time	int	Hit timestamp
time_on_page	int	Time on page (ms)
uid	string	Visitor UID
page_id	int	WordPress page ID
entry	bool	Whether this is the visitor's entry hit
checkout	bool	Whether this page is the checkout page
exit	bool	Whether the visitor appears to have exited

---

get_today_data( array $args )

Returns summary statistics for today's dashboard block.

Parameters:

Parameter	Type	Description
$args['date_start']	int	Start of today (timestamp). Default 0.
$args['date_end']	int	End of today (timestamp). Default 0.

Return shape:

[
    'live'       => [ 'value' => string, 'tooltip' => string ],
    'today'      => [ 'value' => string, 'tooltip' => string ],
    'mostViewed' => [ 'title' => string, 'value' => string, 'tooltip' => string ],
    'referrer'   => [ 'title' => string, 'value' => string, 'tooltip' => string ],
    'pageviews'  => [ 'title' => string, 'value' => string, 'tooltip' => string ],
    'timeOnPage' => [ 'title' => string, 'value' => string, 'tooltip' => string ],
]

---

get_insights_data( array $args )

Returns chart-ready datasets and labels for the insights panel.

Parameters:

Parameter	Type	Description
$args['date_start']	int	Start timestamp. Default 0.
$args['date_end']	int	End timestamp. Default 0.
$args['metrics']	string[]	Metrics to chart. Default ['pageviews', 'visitors'].
$args['filters']	array	Filters to apply. Default [].

Return shape:

[
    'labels'   => string[],       // human-readable period labels
    'datasets' => [
        [
            'data'            => (int|float)[],
            'backgroundColor' => string,   // RGBA
            'borderColor'     => string,   // RGBA
            'label'           => string,
            'fill'            => string,
        ],
        // one entry per metric
    ],
]

The interval (hour / day / week / month) is determined automatically from the date range:

Range	Interval
≤ 2 days	Hour
3–48 days	Day
49–364 days	Week
> 364 days	Month

---

get_insights_date_modifiers( int $date_start, int $date_end )

Returns the date format strings and interval metadata used to build insight charts.

$modifiers = $statistics->get_insights_date_modifiers( $start, $end );

Return shape:

Key	Type	Description
interval	string	hour, day, week, or month
interval_in_seconds	int	Interval length in seconds
nr_of_intervals	int	Number of data points in the range
sql_date_format	string	MySQL DATE_FORMAT() pattern
php_date_format	string	PHP date() pattern for array keys
php_pretty_date_format	string	PHP date() pattern for display labels

---

get_compare_data( array $args )

Returns current-period and previous-period summary metrics for comparison widgets.

Parameters:

Parameter	Type	Description
$args['date_start']	int	Start of current period (timestamp).
$args['date_end']	int	End of current period (timestamp).
$args['compare_date_start']	int|null	Start of comparison period. Defaults to the equivalent prior period.
$args['compare_date_end']	int|null	End of comparison period.
$args['filters']	array	Filters to apply to both periods.

Return shape:

[
    'current'  => [
        'pageviews'           => int,
        'sessions'            => int,
        'visitors'            => int,
        'first_time_visitors' => int,
        'avg_time_on_page'    => int,
        'bounced_sessions'    => int,
        'bounce_rate'         => float,
    ],
    'previous' => [
        'pageviews'        => int,
        'sessions'         => int,
        'visitors'         => int,
        'bounced_sessions' => int,
        'bounce_rate'      => float,
    ],
]

---

get_compare_goals_data( array $args )

⭐ Pro

Returns current-period and previous-period goal/conversion metrics.

Goal Conversion Tracking

Parameters:

Parameter	Type	Description
$args['date_start']	int	Start timestamp.
$args['date_end']	int	End timestamp.
$args['filters']	array	Filters, may include goal_id.
$args['compare_date_start']	int|null	Start of comparison period.
$args['compare_date_end']	int|null	End of comparison period.

Return shape:

[
    'view'     => 'goals',
    'current'  => [
        'pageviews'           => int,
        'visitors'            => int,
        'sessions'            => int,
        'first_time_visitors' => int,
        'conversions'         => int,
        'conversion_rate'     => float,
    ],
    'previous' => [
        'pageviews'       => int,
        'visitors'        => int,
        'sessions'        => int,
        'conversions'     => int,
        'conversion_rate' => float,
    ],
]

---

get_data( array $select, int $start, int $end, array $filters )

Low-level single-row query. Returns one associative array of metric values for the given period.

$row = $statistics->get_data(
    [ 'pageviews', 'visitors', 'sessions' ],
    strtotime( '2024-01-01' ),
    strtotime( '2024-01-31' ),
    [ 'device' => 'mobile' ]
);
// [ 'pageviews' => 1200, 'visitors' => 340, 'sessions' => 400 ]

---

get_devices_title_and_value_data( array $args )

Returns pageview counts grouped by device type.

Parameters:

Parameter	Type	Description
$args['date_start']	int	Start timestamp. Default 0.
$args['date_end']	int	End timestamp. Default 0.
$args['filters']	array	Filters to apply. Default [].

Return shape:

[
    'all'     => [ 'count' => int ],
    'desktop' => [ 'count' => int ],
    'tablet'  => [ 'count' => int ],
    'mobile'  => [ 'count' => int ],
    'other'   => [ 'count' => int ],
]

---

get_devices_subtitle_data( array $args )

Returns the most common browser and OS for each device type.

Parameters:

Parameter	Type	Description
$args['date_start']	int	Start timestamp. Default 0.
$args['date_end']	int	End timestamp. Default 0.
$args['filters']	array	Filters to apply. Default [].

Return shape:

[
    'desktop' => [ 'os' => string, 'browser' => string, 'device_id' => int ],
    'tablet'  => [ 'os' => string, 'browser' => string, 'device_id' => int ],
    'mobile'  => [ 'os' => string, 'browser' => string, 'device_id' => int ],
    'other'   => [ 'os' => string, 'browser' => string, 'device_id' => int ],
]

---

get_datatables_data( array $args )

Returns data for the sortable data table components in the dashboard.

Parameters:

Parameter	Type	Description
$args['date_start']	int	Start timestamp. Default 0.
$args['date_end']	int	End timestamp. Default 0.
$args['metrics']	string[]	Metrics to include as columns. Default ['pageviews'].
$args['filters']	array	Filters to apply. Default [].
$args['group_by']	string	Field to group rows by.
$args['limit']	int	Maximum number of rows. Default 0 (unlimited).

Return shape:

[
    'columns' => [
        [ 'name' => string, 'id' => string, 'sortable' => 'true', 'right' => 'true' ],
        // …
    ],
    'data'    => array[],   // raw rows from the database
    'metrics' => string[],
]

---

get_var( Query_Data $qd )

Executes a query and returns a single scalar value.

$qd  = new Query_Data( [ 'date_start' => $start, 'date_end' => $end, 'select' => [ 'pageviews' ] ] );
$val = $statistics->get_var( $qd );

---

get_row( Query_Data $qd, string $output_type = 'OBJECT' )

Executes a query and returns a single row.

$row = $statistics->get_row( $qd, ARRAY_A );

$output_type accepts OBJECT, ARRAY_A, or ARRAY_N.

---

get_results( Query_Data $qd, string $output_type = 'OBJECT' )

Executes a query and returns all matching rows.

$rows = $statistics->get_results( $qd, ARRAY_A );

---

build_raw_sql( Query_Data $data )

Builds and returns the raw SQL string from a Query_Data object without executing it. Useful for debugging.

$sql = $statistics->build_raw_sql( $qd );
error_log( $sql );

caution

The returned SQL is built for direct use with $wpdb. Do not attempt to re-prepare it.

---

get_sql_select_for_metric( string $metric, Query_Data $query_data )

Returns the SQL fragment for a single metric. Respects the exclude_bounces flag.

$sql = $statistics->get_sql_select_for_metric( 'visitors', $qd );
// 'COUNT(DISTINCT statistics.uid)'

Changed in v3.3.0: browser_id, platform_id, device_id, and first_time_visit now resolve to sessions.* instead of statistics.*. For example:

$sql = $statistics->get_sql_select_for_metric( 'browser_id', $qd );
// 'sessions.browser_id'

$sql = $statistics->get_sql_select_for_metric( 'first_time_visit', $qd );
// 'sessions.first_time_visit'

---

format_number( int $number, int $precision = 2 )

Formats a number with locale-aware separators and shorthand suffixes for large values (k, M, G, …).

echo $statistics->format_number( 123456 ); // '123k'
echo $statistics->format_number( 1234 );   // '1,234'

---

format_uplift( float $original_value, float $new_value )

Returns a formatted uplift string such as +12% or -5%, or an empty string when there is no change.

---

calculate_uplift( float $original_value, float $new_value )

Returns the percentage change as an integer.

---

calculate_uplift_status( float $original_value, float $new_value )

Returns 'positive', 'negative', or ''.

---

get_lookup_table_name_by_id( string $item, int $id )

Resolves a lookup-table ID to a human-readable name. Results are object-cached.

$name = $statistics->get_lookup_table_name_by_id( 'device', 2 );
// 'mobile'

$item must be one of: browser, browser_version, platform, device.

---

is_campaign_conversion_query( Query_Data $data )

Returns true when the query selects campaign parameters together with conversion or sales metrics.

---

is_parameter_conversion_query( Query_Data $data )

Returns true when the query selects URL parameters together with conversion or sales metrics.

---

Goal Statistics

The Goal_Statistics class handles goal-specific queries.

$goal_stats = \Burst\burst_loader()->admin->goal_statistics;

get_goals_data( array $args )

Returns the full data payload for a goal detail card.

Parameters:

Parameter	Type	Description
$args['goal_id']	int	Goal ID to query. Default 0.
$args['date_start']	int	Start timestamp. Default 0.
$args['date_end']	int	End timestamp. Default 0.

Return shape (abbreviated):

[
    'today'               => [ 'value' => int, 'tooltip' => string ],
    'total'               => [ 'value' => int, 'tooltip' => string ],
    'topPerformer'        => [ 'title' => string, 'value' => int, 'tooltip' => string ],
    'conversionMetric'    => [ 'title' => string, 'value' => int, 'tooltip' => string, 'icon' => string ],
    'conversionPercentage'=> [ 'title' => string, 'value' => int, 'tooltip' => string ],
    'bestDevice'          => [ 'title' => string, 'value' => int, 'tooltip' => string, 'icon' => mixed ],
    'dateCreated'         => int,
    'dateStart'           => int,
    'dateEnd'             => int,
    'status'              => string,
    'goalId'              => int,
]

get_live_goals_count( array $args )

Returns the number of goal completions for a given goal since midnight today.

$count = $goal_stats->get_live_goals_count( [ 'goal_id' => 3 ] );

---

Hooks Reference

burst_on_page_offset

Adjusts the number of seconds added to a visitor's last-seen time before they are considered to have left a page. Used in live traffic and live visitor calculations.

Parameters:

Parameter	Type	Description
$offset	int	Offset in seconds. Default 60.

Example:

add_filter( 'burst_on_page_offset', function( $offset ) {
    return 90; // consider visitors active for 90 s after their last hit
} );

---

burst_live_traffic_args

Filters the Query_Data object used to fetch the raw live traffic rows before it is executed.

Parameters:

Parameter	Type	Description
$qd	Query_Data	Query object for the live traffic query.

Example:

add_filter( 'burst_live_traffic_args', function( $qd ) {
    $qd->limit = 50; // cap live traffic at 50 rows
    return $qd;
} );

---

burst_possible_filters_with_prefix

Defines the mapping from filter keys to their fully-qualified SQL column references. Extend this to add custom filterable columns.

Parameters:

Parameter	Type	Description
$filters	array<string, string>	Map of filter key → table.column.

Changed in v3.3.0: The built-in mappings for browser, browser_id, platform, platform_id, device, device_id, and new_visitor now resolve to sessions.* instead of statistics.*.

Example:

add_filter( 'burst_possible_filters_with_prefix', function( $filters ) {
    $filters['my_custom_column'] = 'statistics.my_custom_column';
    return $filters;
} );

---

burst_mappable_filters

Defines which filter keys should be resolved through the lookup tables (i.e. their string value is converted to an integer ID before querying).

Parameters:

Parameter	Type	Description
$mappable	string[]	List of filter keys that map to lookup table IDs. Default: ['browser', 'browser_version', 'platform', 'device'].

Example:

add_filter( 'burst_mappable_filters', function( $mappable ) {
    $mappable[] = 'my_lookup_filter';
    return $mappable;
} );

---

burst_datatable_data

Filters the raw data rows returned for a datatable before they are sent to the client.

Parameters:

Parameter	Type	Description
$data	array	Array of result rows (associative).
$qd	Query_Data	The query object that produced the data.

Example:

add_filter( 'burst_datatable_data', function( $data, $qd ) {
    foreach ( $data as &$row ) {
        $row['pageviews'] = max( 0, (int) $row['pageviews'] );
    }
    return $data;
}, 10, 2 );

---

burst_select_sql_for_metric

Provides SQL for custom metric keys that are not built into the Statistics class. Return false to indicate no SQL is available for the metric.

Parameters:

Parameter	Type	Description
$metric	string	The metric key that was not matched internally.

Example:

add_filter( 'burst_select_sql_for_metric', function( $metric ) {
    if ( $metric === 'my_metric' ) {
        return 'COUNT(DISTINCT statistics.my_column)';
    }
    return $metric;
} );

---

burst_build_where_clause

Filters the assembled WHERE clause string before it is included in the final SQL.

Parameters:

Parameter	Type	Description
$where	string	Current WHERE fragment (may be empty or start with AND).
$data	Query_Data	The current query object.

Example:

add_filter( 'burst_build_where_clause', function( $where, $data ) {
    $where .= " AND statistics.page_type != 'attachment' ";
    return $where;
}, 10, 2 );

---

burst_available_joins

Defines the available JOIN configurations that the query builder can auto-detect and include.

Parameters:

Parameter	Type	Description
$joins	array	Map of alias → join configuration.
$data	Query_Data	The current query object.

Each join configuration has the shape:

[
    'table'      => 'burst_sessions',          // table name without prefix, or raw subquery SQL
    'on'         => 'statistics.session_id = sessions.ID',
    'type'       => 'INNER',                   // INNER or LEFT
    'depends_on' => [],                        // aliases that must be joined first
]

Changed in v3.3.0: The built-in session_bounces join now reads directly from burst_sessions (SELECT ID as session_id, bounce FROM burst_sessions) instead of aggregating bounce values from burst_statistics. Custom code that relied on the previous subquery shape should be updated accordingly.

Example:

add_filter( 'burst_available_joins', function( $joins, $data ) {
    $joins['my_table'] = [
        'table'      => 'my_custom_table',
        'on'         => 'statistics.ID = my_table.statistic_id',
        'type'       => 'LEFT',
        'depends_on' => [],
    ];
    return $joins;
}, 10, 2 );

---

burst_allowed_metric_keys

Filters the list of metric keys permitted in strict (non-admin) mode.

Parameters:

Parameter	Type	Description
$keys	string[]	Allowed metric keys.
$is_strict	bool	Whether strict mode is active.

Example:

add_filter( 'burst_allowed_metric_keys', function( $keys, $is_strict ) {
    if ( $is_strict ) {
        $keys[] = 'bounce_rate';
    }
    return $keys;
}, 10, 2 );

---

burst_allowed_metrics

Filters the full associative array of allowed metrics (key → label) after strict-mode filtering is applied.

Parameters:

Parameter	Type	Description
$metrics	array<string, string>	Allowed metrics map.
$is_strict	bool	Whether strict mode is active.

Example:

add_filter( 'burst_allowed_metrics', function( $metrics, $is_strict ) {
    $metrics['my_metric'] = 'My Metric';
    return $metrics;
}, 10, 2 );

---

burst_statistics_allowed_filter_keys

Filters the list of filter keys accepted by Query_Data.

Parameters:

Parameter	Type	Description
$keys	string[]	Allowed filter keys.
$is_strict	bool	Whether strict mode is active.

Example:

add_filter( 'burst_statistics_allowed_filter_keys', function( $keys, $is_strict ) {
    $keys[] = 'my_custom_filter';
    return $keys;
}, 10, 2 );

---

burst_statistics_allowed_group_by

Filters the list of accepted group_by values.

Parameters:

Parameter	Type	Description
$group_by	string[]	Allowed group-by fields.
$is_strict	bool	Whether strict mode is active.

Example:

add_filter( 'burst_statistics_allowed_group_by', function( $group_by, $is_strict ) {
    $group_by[] = 'my_custom_column';
    return $group_by;
}, 10, 2 );

---

burst_statistics_allowed_order_by

Filters the list of accepted order_by values.

Parameters:

Parameter	Type	Description
$order_by	string[]	Allowed order-by clauses (e.g. 'pageviews DESC').
$is_strict	bool	Whether strict mode is active.

Example:

add_filter( 'burst_statistics_allowed_order_by', function( $order_by, $is_strict ) {
    $order_by[] = 'my_column DESC';
    $order_by[] = 'my_column ASC';
    return $order_by;
}, 10, 2 );

---

burst_allowed_metrics_labels

Filters the full map of metric keys to their translated display labels.

Parameters:

Parameter	Type	Description
$labels	array<string, string>	Map of metric key → translated label.

Example:

add_filter( 'burst_allowed_metrics_labels', function( $labels ) {
    $labels['my_metric'] = __( 'My Metric', 'my-plugin' );
    return $labels;
} );

---

burst_allowed_post_types

Filters the list of post types accepted as a valid value for the page_type filter in strict mode.

Parameters:

Parameter	Type	Description
$post_types	array	Array of public post type slugs. Default: get_post_types( ['public' => true] ).

Example:

add_filter( 'burst_allowed_post_types', function( $post_types ) {
    $post_types[] = 'my_private_type';
    return $post_types;
} );

---

Custom Queries: End-to-End Example

The following example queries pageviews and unique visitors grouped by page URL for the current month, filtered to desktop visitors only, and returns the top 10 results.

use Burst\Admin\Statistics\Query_Data;

$statistics = \Burst\burst_loader()->admin->statistics;

$start = strtotime( 'first day of this month midnight' );
$end   = time();

$qd = new Query_Data( [
    'date_start' => $start,
    'date_end'   => $end,
    'select'     => [ 'page_url', 'pageviews', 'visitors' ],
    'filters'    => [ 'device' => 'desktop' ],
    'group_by'   => 'page_url',
    'order_by'   => 'pageviews DESC',
    'limit'      => 10,
] );

$rows = $statistics->get_results( $qd, ARRAY_A );

foreach ( $rows as $row ) {
    printf(
        "%s — %s pageviews, %s visitors\n",
        $row['page_url'],
        $statistics->format_number( (int) $row['pageviews'] ),
        $statistics->format_number( (int) $row['visitors'] )
    );
}

Adding a custom WHERE clause (admin context only)

$qd = new Query_Data( [
    'date_start'               => $start,
    'date_end'                 => $end,
    'select'                   => [ 'pageviews', 'page_url' ],
    'group_by'                 => 'page_url',
    'custom_where'             => 'AND statistics.page_url LIKE %s',
    'custom_where_parameters'  => [ '%/blog/%' ],
] );

$rows = $statistics->get_results( $qd, ARRAY_A );

caution

custom_where and custom_select are only processed for users with admin access (non-strict mode). In strict mode these parameters are silently discarded. All custom SQL is validated against a blocklist of dangerous keywords and patterns before use.