API Reference

Archive

Piwik\

Archive

The Archive class is used to query cached analytics statistics (termed "archive data").

You can use Archive instances to get data that was archived for one or more sites, for one or more periods and one optional segment.

If archive data is not found, this class will initiate the archiving process. 1

Archive instances must be created using the build() factory method; they cannot be constructed.

You can search for metrics (such as nb_visits) using the getNumeric() and getDataTableFromNumeric() methods. You can search for reports using the getBlob(), getDataTable() and getDataTableExpanded() methods.

If you're creating an API that returns report data, you may want to use the createDataTableFromArchive() helper function.

Learn more

Learn more about archiving here.

Limitations

  • You cannot get data for multiple range periods in a single query.
  • You cannot get data for periods of different types in a single query.

Examples

Querying metrics for an API method

// one site and one period
$archive = Archive::build($idSite = 1, $period = 'week', $date = '2013-03-08');
return $archive->getDataTableFromNumeric(array('nb_visits', 'nb_actions'));

// all sites and multiple dates
$archive = Archive::build($idSite = 'all', $period = 'month', $date = '2013-01-02,2013-03-08');
return $archive->getDataTableFromNumeric(array('nb_visits', 'nb_actions'));

Querying and using metrics immediately

// one site and one period
$archive = Archive::build($idSite = 1, $period = 'week', $date = '2013-03-08');
$data = $archive->getNumeric(array('nb_visits', 'nb_actions'));

$visits = $data['nb_visits'];
$actions = $data['nb_actions'];

// ... do something w/ metric data ...

// multiple sites and multiple dates
$archive = Archive::build($idSite = '1,2,3', $period = 'month', $date = '2013-01-02,2013-03-08');
$data = $archive->getNumeric('nb_visits');

$janSite1Visits = $data['1']['2013-01-01,2013-01-31']['nb_visits'];
$febSite1Visits = $data['1']['2013-02-01,2013-02-28']['nb_visits'];
// ... etc.

Querying for reports

$archive = Archive::build($idSite = 1, $period = 'week', $date = '2013-03-08');
$dataTable = $archive->getDataTable('MyPlugin_MyReport');
// ... manipulate $dataTable ...
return $dataTable;

Querying a report for an API method

public function getMyReport($idSite, $period, $date, $segment = false, $expanded = false)
{
    $dataTable = Archive::createDataTableFromArchive('MyPlugin_MyReport', $idSite, $period, $date, $segment, $expanded);
    return $dataTable;
}

Querying data for multiple range periods

// get data for first range
$archive = Archive::build($idSite = 1, $period = 'range', $date = '2013-03-08,2013-03-12');
$dataTable = $archive->getDataTableFromNumeric(array('nb_visits', 'nb_actions'));

// get data for second range
$archive = Archive::build($idSite = 1, $period = 'range', $date = '2013-03-15,2013-03-20');
$dataTable = $archive->getDataTableFromNumeric(array('nb_visits', 'nb_actions'));

[1]: The archiving process will not be launched if browser archiving is disabled and the current request came from a browser.

Methods

The class defines the following methods:

__construct()

Signature

  • It accepts the following parameter(s):

    • $params (Piwik\Archive\Parameters) —

    • $forceIndexedBySite (bool) — Whether to force index the result of a query by site ID.

    • $forceIndexedByDate (bool) — Whether to force index the result of a query by period.

build()

Returns a new Archive instance that will query archive data for the given set of sites and periods, using an optional Segment.

This method uses data that is found in query parameters, so the parameters to this function can be string values.

If you want to create an Archive instance with an array of Period instances, use Archive::factory().

Signature

  • It accepts the following parameter(s):
    • $idSites (string|int|array) — A single ID (eg, '1'), multiple IDs (eg, '1,2,3' or array(1, 2, 3)), or 'all'.
    • $period (string) — 'day', 'week', 'month', 'year' or 'range'
    • $strDate (Date|string) — 'YYYY-MM-DD', magic keywords (ie, 'today'; Date::factory() or date range (ie, 'YYYY-MM-DD,YYYY-MM-DD').
    • $segment (bool|false|string) — Segment definition or false if no segment should be used. Segment
    • $_restrictSitesToLogin (bool|false|string) — Used only when running as a scheduled task.
  • It returns a Piwik\Archive\ArchiveQuery value.

factory()

Returns a new Archive instance that will query archive data for the given set of sites and periods, using an optional segment.

This method uses an array of Period instances and a Segment instance, instead of strings like build().

If you want to create an Archive instance using data found in query parameters, use build().

Signature

  • It accepts the following parameter(s):
    • $segment (Segment) — The segment to use. For no segment, use new Segment('', $idSites).
    • $periods (array) — An array of Period instances.
    • $idSites (array) — An array of site IDs (eg, array(1, 2, 3)).
    • $idSiteIsAll (bool) — Whether 'all' sites are being queried or not. If true, then the result of querying functions will be indexed by site, regardless of whether count($idSites) == 1.
    • $isMultipleDate (bool) — Whether multiple dates are being queried or not. If true, then the result of querying functions will be indexed by period, regardless of whether count($periods) == 1.
  • It returns a Piwik\Archive\ArchiveQuery value.

shouldSkipArchiveIfSkippingSegmentArchiveForToday()

Signature

  • It accepts the following parameter(s):

  • It does not return anything or a mixed result.

getNumeric()

Queries and returns metric data in an array.

If multiple sites were requested in build() or factory() the result will be indexed by site ID.

If multiple periods were requested in build() or factory() the result will be indexed by period.

The site ID index is always first, so if multiple sites & periods were requested, the result will be indexed by site ID first, then period.

Signature

  • It accepts the following parameter(s):

    • $names (string|array) — One or more archive names, eg, 'nb_visits', 'Referrers_distinctKeywords', etc.

  • Returns: false|integer|array — false if there is no data to return, a single numeric value if we're not querying for multiple sites/periods, or an array if multiple sites, periods or names are queried for.

getBlob()

Queries and returns blob records without turning them into DataTables.

Unlike other methods, this returns a DataCollection instance directly. Use it to directly access and process blob data.

Signature

  • It accepts the following parameter(s):

    • $names

    • $idSubtable

  • Returns: Piwik\Archive\DataCollection — the queried data.

getDataTableFromNumeric()

Queries and returns metric data in a DataTable instance.

If multiple sites were requested in build() or factory() the result will be a DataTable\Map that is indexed by site ID.

If multiple periods were requested in build() or factory() the result will be a Map that is indexed by period.

The site ID index is always first, so if multiple sites & periods were requested, the result will be a Map indexed by site ID which contains Map instances that are indexed by period.

Note: Every DataTable instance returned will have at most one row in it. The contents of each row will be the requested metrics for the appropriate site and period.

Signature

  • It accepts the following parameter(s):

    • $names (string|array) — One or more archive names, eg, 'nb_visits', 'Referrers_distinctKeywords', etc.

  • Returns: DataTable|Map — A DataTable if multiple sites and periods were not requested. An appropriately indexed DataTable\Map if otherwise.

getDataTable()

Queries and returns one or more reports as DataTable instances.

This method will query blob data that is a serialized array of of Row's and unserialize it.

If multiple sites were requested in build() or factory() the result will be a Map that is indexed by site ID.

If multiple periods were requested in build() or factory() the result will be a DataTable\Map that is indexed by period.

The site ID index is always first, so if multiple sites & periods were requested, the result will be a Map indexed by site ID which contains Map instances that are indexed by period.

Signature

  • It accepts the following parameter(s):

    • $name (string) — The name of the record to get. This method can only query one record at a time.
    • $idSubtable (int|string|null) — The ID of the subtable to get (if any).

  • Returns: DataTable|Map — A DataTable if multiple sites and periods were not requested. An appropriately indexed Map if otherwise.

getDataTableExpanded()

Queries and returns one report with all of its subtables loaded.

If multiple sites were requested in build() or factory() the result will be a DataTable\Map that is indexed by site ID.

If multiple periods were requested in build() or factory() the result will be a DataTable\Map that is indexed by period.

The site ID index is always first, so if multiple sites & periods were requested, the result will be a indexed by site ID which contains Map instances that are indexed by period.

Signature

  • It accepts the following parameter(s):

    • $name (string) — The name of the record to get.
    • $idSubtable (int|string|null) — The ID of the subtable to get (if any). The subtable will be expanded.
    • $depth (int|null) — The maximum number of subtable levels to load. If null, all levels are loaded. For example, if 1 is supplied, then the DataTable returned will have its subtables loaded. Those subtables, however, will NOT have their subtables loaded.
    • $addMetadataSubtableId (bool) — Whether to add the database subtable ID as metadata to each datatable, or not.

  • Returns: DataTable|Map —

getParams()

Returns an object describing the set of sites, the set of periods and the segment this Archive will query data for.

Signature

  • It returns a Piwik\Archive\Parameters value.

createDataTableFromArchive()

Helper function that creates an Archive instance and queries for report data using query parameter data. API methods can use this method to reduce code redundancy.

Signature

  • It accepts the following parameter(s):

    • $recordName (string) — The name of the report to return.
    • $idSite (int|string|array) — @see build()
    • $period (string) — @see build()
    • $date (string) — @see build()
    • $segment (string) — @see build()
    • $expanded (bool) — If true, loads all subtables. See getDataTableExpanded()
    • $flat (bool) — If true, loads all subtables and disabled all recursive filters.
    • $idSubtable (int|null|string) — See getDataTableExpanded()
    • $depth (int|null) — See getDataTableExpanded()

  • Returns: DataTable|Map —

getPluginForReport()

Returns the name of the plugin that archives a given report.

Signature

  • It accepts the following parameter(s):

    • $report (string) — Archive data name, eg, 'nb_visits', 'DevicesDetection_...', etc.

  • Returns: string — Plugin name.

  • It throws one of the following exceptions:
    • Exception — If a plugin cannot be found or if the plugin for the report isn't activated.

forceFetchingWithoutLaunchingArchiving()

Signature

  • It does not return anything or a mixed result.