Piwik\

RankingQuery

The ranking query class wraps an arbitrary SQL query with more SQL that limits the number of results while aggregating the rest in an a new "Others" row.

It also allows for some more fancy things that can be configured via method calls of this class. The advanced use cases are explained in the doc comments of the methods.

The general use case looks like this:

// limit to 500 rows + "Others"
$rankingQuery = new RankingQuery();
$rankingQuery->setLimit(500);

// idaction_url will be "Others" in the row that contains the aggregated rest
$rankingQuery->addLabelColumn('idaction_url');

// the actual query. it's important to sort it before the limit is applied
$sql = 'SELECT idaction_url, COUNT(*) AS nb_hits
        FROM log_link_visit_action
        GROUP BY idaction_url
        ORDER BY nb_hits DESC';

// execute the query
$rankingQuery->execute($sql);

For more examples, see RankingQueryTest.php

Methods

The class defines the following methods:

__construct()

Constructor.

Signature

  • It accepts the following parameter(s):
    • $limit (int|Piwik\false) — The result row limit. See setLimit().

setLimit()

Set the limit after which everything is grouped to "Others".

Signature

  • It accepts the following parameter(s):

    • $limit (int) —
  • It does not return anything.

setOthersLabel()

Set the value to use for the label in the 'Others' row.

Signature

  • It accepts the following parameter(s):

    • $value (string) —
  • It does not return anything.

addLabelColumn()

Add a label column.

Labels are the columns that are replaced with "Others" after the limit.

Signature

  • It accepts the following parameter(s):

    • $labelColumn (string|array) —
  • It does not return anything.

getLabelColumns()

Signature

  • It returns a array value.

addColumn()

Add a column that has be added to the outer queries.

Signature

  • It accepts the following parameter(s):

    • $column (Piwik\$column) —

    • $aggregationFunction (string|bool) — If set, this function is used to aggregate the values of "Others", eg, 'min', 'max' or 'sum'.

  • It does not return anything.

setColumnToMarkExcludedRows()

Sets a column that will be used to filter the result into two categories.

Rows where this column has a value > 0 will be removed from the result and put into another array. Both the result and the array of excluded rows are returned by execute().

Signature

  • It accepts the following parameter(s):
    • $column (Piwik\$column) — string Name of the column.
  • It does not return anything.
  • It throws one of the following exceptions:
    • Exception — if method is used more than once.

partitionResultIntoMultipleGroups()

This method can be used to parition the result based on the possible values of one table column.

This means the query will split the result set into other sets of rows for each possible value you provide (where the rows of each set have a column value that equals a possible value). Each of these new sets of rows will be individually limited resulting in several limited result sets.

For example, you can run a query aggregating some data on the log_action table and partition by log_action.type with the possible values of Matomo (formerly Piwik)\Tracker\Action::TYPE_PAGE_URL, Piwik\Tracker\Action::TYPE_OUTLINK, Matomo\Tracker\Action::TYPE_DOWNLOAD. The result will be three separate result sets that are aggregated the same ways, but for rows where log_action.type = TYPE_OUTLINK, for rows where log_action.type = TYPE_ACTION_URL and for rows log_action.type = TYPE_DOWNLOAD.

Signature

  • It accepts the following parameter(s):
    • $partitionColumn (Piwik\$partitionColumn) — string The column name to partion by.
    • $possibleValues (Piwik\$possibleValues) — Array of possible column values.
  • It does not return anything.
  • It throws one of the following exceptions:
    • Exception — if method is used more than once.

execute()

Executes the query.

The object has to be configured first using the other methods.

Signature

  • It accepts the following parameter(s):

    • $innerQuery (Piwik\$innerQuery) — string The "payload" query that does the actual data aggregation. The ordering has to be specified in this query. RankingQuery cannot apply ordering itself.
    • $bind (Piwik\$bind) — array Bindings for the inner query.
  • Returns: array — The format depends on which methods have been used to configure the ranking query.

generateRankingQuery()

Generate the SQL code that does the magic.

If you want to get the result, use execute() instead. If you want to run the query yourself, use this method.

Signature

  • It accepts the following parameter(s):

    • $innerQuery (Piwik\$innerQuery) — string The "payload" query that does the actual data aggregation. The ordering has to be specified in this query. RankingQuery cannot apply ordering itself.
  • Returns: string — The entire ranking query SQL.