API Reference

ArchiveProcessor

Piwik\

ArchiveProcessor

Used by Archiver instances to insert and aggregate archive data.

See also

  • Archiver - to learn how plugins should implement their own analytics aggregation logic.
  • LogAggregator - to learn how plugins can perform data aggregation across Matomo (formerly Piwik)'s log tables.

Examples

Inserting numeric data

// function in an Archiver descendant
public function aggregateDayReport()
{
    $archiveProcessor = $this->getProcessor();

    $myFancyMetric = // ... calculate the metric value ...
    $archiveProcessor->insertNumericRecord('MyPlugin_myFancyMetric', $myFancyMetric);
}

Inserting serialized DataTables

// function in an Archiver descendant
public function aggregateDayReport()
{
    $archiveProcessor = $this->getProcessor();

    $maxRowsInTable = Config::getInstance()->General['datatable_archiving_maximum_rows_standard'];j

    $dataTable = // ... build by aggregating visits ...
    $serializedData = $dataTable->getSerialized($maxRowsInTable, $maxRowsInSubtable = $maxRowsInTable,
                                                $columnToSortBy = Metrics::INDEX_NB_VISITS);

    $archiveProcessor->insertBlobRecords('MyPlugin_myFancyReport', $serializedData);
}

Aggregating archive data

// function in Archiver descendant
public function aggregateMultipleReports()
{
    $archiveProcessor = $this->getProcessor();

    // aggregate a metric
    $archiveProcessor->aggregateNumericMetrics('MyPlugin_myFancyMetric');
    $archiveProcessor->aggregateNumericMetrics('MyPlugin_mySuperFancyMetric', 'max');

    // aggregate a report
    $archiveProcessor->aggregateDataTableRecords('MyPlugin_myFancyReport');
}

Methods

The class defines the following methods:

  • getParams() — Returns the Parameters object containing the site, period and segment we're archiving data for.
  • getLogAggregator() — Returns a [LogAggregator](/api-reference/Piwik/DataAccess/LogAggregator) instance for the site, period and segment this ArchiveProcessor will insert archive data for.
  • aggregateDataTableRecords() — Sums records for every subperiod of the current period and inserts the result as the record for this period.
  • aggregateNumericMetrics() — Aggregates one or more metrics for every subperiod of the current period and inserts the results as metrics for the current period.
  • insertNumericRecords() — Caches multiple numeric records in the archive for this processor's site, period and segment.
  • insertNumericRecord() — Caches a single numeric record in the archive for this processor's site, period and segment.
  • insertBlobRecord() — Caches one or more blob records in the archive for this processor's site, period and segment.

getParams()

Returns the Parameters object containing the site, period and segment we're archiving data for.

Signature

getLogAggregator()

Returns a [LogAggregator](/api-reference/Piwik/DataAccess/LogAggregator) instance for the site, period and segment this ArchiveProcessor will insert archive data for.

Signature

aggregateDataTableRecords()

Sums records for every subperiod of the current period and inserts the result as the record for this period.

DataTables are summed recursively so subtables will be summed as well.

Signature

  • It accepts the following parameter(s):

    • $recordNames (string|array) — Name(s) of the report we are aggregating, eg, 'Referrers_type'.
    • $maximumRowsInDataTableLevelZero (int) — Maximum number of rows allowed in the top level DataTable.
    • $maximumRowsInSubDataTable (int) — Maximum number of rows allowed in each subtable.
    • $defaultColumnToSortByBeforeTruncation (string|null) — The name of the column to sort by before truncating a DataTable. If not set, and the table contains nb_visits or INDEX_NB_VISITS, we will sort by visits.
    • $columnsAggregationOperation (array) — Operations for aggregating columns, see Row::sumRow().
    • $columnsToRenameAfterAggregation (array) — Columns mapped to new names for columns that must change names when summed because they cannot be summed, eg, array('nb_uniq_visitors' => 'sum_daily_nb_uniq_visitors').
    • $countRowsRecursive (bool|array) — if set to true, will calculate the recursive rows count for all record names which makes it slower. If you only need it for some records pass an array of recordNames that defines for which ones you need a recursive row count.

  • Returns: array — Returns the row counts of each aggregated report before truncation, eg,

              array(
              'report1' => array('level0' => $report1->getRowsCount,
                                 'recursive' => $report1->getRowsCountRecursive()),
              'report2' => array('level0' => $report2->getRowsCount,
                                 'recursive' => $report2->getRowsCountRecursive()),
              ...
          )

aggregateNumericMetrics()

Aggregates one or more metrics for every subperiod of the current period and inserts the results as metrics for the current period.

Signature

  • It accepts the following parameter(s):

    • $columns

    • $operationsToApply

  • Returns: array|int — Returns the array of aggregate values. If only one metric was aggregated, the aggregate value will be returned as is, not in an array. For example, if array('nb_visits', 'nb_hits') is supplied for $columns,

                  array(
                  'nb_visits' => 3040,
                  'nb_hits' => 405
              )

          could be returned. If `array('nb_visits')` or `'nb_visits'` is used for `$columns`,
          then `3040` would be returned.

insertNumericRecords()

Caches multiple numeric records in the archive for this processor's site, period and segment.

Signature

  • It accepts the following parameter(s):
    • $numericRecords (array) — A name-value mapping of numeric values that should be archived, eg, array('Referrers_distinctKeywords' => 23, 'Referrers_distinctCampaigns' => 234)
  • It does not return anything or a mixed result.

insertNumericRecord()

Caches a single numeric record in the archive for this processor's site, period and segment.

Numeric values are not inserted if they equal 0.

Signature

  • It accepts the following parameter(s):
    • $name (string) — The name of the numeric value, eg, 'Referrers_distinctKeywords'.
    • $value (float) — The numeric value.
  • It does not return anything or a mixed result.

insertBlobRecord()

Caches one or more blob records in the archive for this processor's site, period and segment.

Signature

  • It accepts the following parameter(s):
    • $name (string) — The name of the record, eg, 'Referrers_type'.
    • $values (string|array) — A blob string or an array of blob strings. If an array is used, the first element in the array will be inserted with the $name name. The others will be inserted with $name . '_' . $index as the record name (where $index is the index of the blob record in $values).
  • It does not return anything or a mixed result.