API Reference

Segment

Piwik\

Segment

Limits the set of visits Matomo (formerly Piwik) uses when aggregating analytics data.

A segment is a condition used to filter visits. They can, for example, select visits that have a specific browser or come from a specific country, or both.

Plugins that aggregate data stored in Matomo can support segments by using this class when generating aggregation SQL queries.

Examples

Basic usage

$idSites = array(1,2,3);
$segmentStr = "browserCode==ff;countryCode==CA";
$segment = new Segment($segmentStr, $idSites);

$query = $segment->getSelectQuery(
    $select = "table.col1, table2.col2",
    $from = array("table", "table2"),
    $where = "table.col3 = ?",
    $bind = array(5),
    $orderBy = "table.col1 DESC",
    $groupBy = "table2.col2"
);

Db::fetchAll($query['sql'], $query['bind']);

Creating a null segment

$idSites = array(1,2,3);
$segment = new Segment('', $idSites);
// $segment->getSelectQuery will return a query that selects all visits

Methods

The class defines the following methods:

__construct()

Constructor.

When using segments that contain a != or !@ condition on a non visit dimension (e.g. action, conversion, ...) it is needed to use a subquery to get correct results. To avoid subqueries that fetch too many data it's required to set a startDate and/or an endDate in this case. That date will be used to limit the subquery (along with possibly given idSites). If no startDate and endDate is given for such a segment it will generate a query that directly joins the according tables, but trigger a php warning as results might be incorrect.

Signature

  • It accepts the following parameter(s):
    • $segmentCondition (string) — The segment condition, eg, 'browserCode=ff;countryCode=CA'.
    • $idSites (array) — The list of sites the segment will be used with. Some segments are dependent on the site, such as goal segments.
    • $startDate (Date|null) — start date used to limit subqueries
    • $endDate (Date|null) — end date used to limit subqueries
  • It throws one of the following exceptions:
    • ``

isAvailable()

Checks if the provided segmentCondition is valid and available for the given idSites

Signature

  • It accepts the following parameter(s):

    • $segmentCondition (string) —

    • $idSites (array) —

  • It returns a bool value.

getSegmentExpression()

Returns the segment expression.

Signature

  • It returns a Piwik\Segment\SegmentExpression value.

isEmpty()

Returns true if the segment is empty, false if otherwise.

Signature

  • It does not return anything or a mixed result.

willBeArchived()

Detects whether the Matomo instance is configured to be able to archive this segment. It checks whether the segment will be either archived via browser or cli archiving. It does not check if the segment has been archived. If you want to know whether the segment has been archived, the actual report data needs to be requested.

This method does not take any date/period into consideration. Meaning a Matomo instance might be able to archive this segment in general, but not for a certain period if eg the archiving of range dates is disabled.

Signature

  • It returns a bool value.

getString()

Returns the segment condition.

Signature

  • It returns a string value.

getHash()

Returns a hash of the segment condition, or the empty string if the segment condition is empty.

Signature

  • It returns a string value.

getSegmentHash()

Signature

  • It accepts the following parameter(s):

    • $definition

  • It does not return anything or a mixed result.

getSelectQuery()

Extend an SQL query that aggregates data over one of the 'log_' tables with segment expressions.

Signature

  • It accepts the following parameter(s):

    • $select (string) — The select clause. Should NOT include the SELECT just the columns, eg, 't1.col1 as col1, t2.col2 as col2'.
    • $from (array|string) — Array of table names (without prefix), eg, array('log_visit', 'log_conversion').
    • $where (false|string) — (optional) Where clause, eg, 't1.col1 = ? AND t2.col2 = ?'.
    • $bind (array|string) — (optional) Bind parameters, eg, array($col1Value, $col2Value).
    • $orderBy (false|string) — (optional) Order by clause, eg, "t1.col1 ASC".
    • $groupBy (false|string) — (optional) Group by clause, eg, "t2.col2".
    • $limit (int) — Limit number of result to $limit
    • $offset (int) — Specified the offset of the first row to return
    • $forceGroupBy (bool) — Force the group by and not using a subquery. Note: This may make the query slower see https://github.com/matomo-org/matomo/issues/9200#issuecomment-183641293 A $groupBy value needs to be set for this to work.
    • $withRollup (bool) — If set to value >= 1 then the Select query (and All inner queries) will be LIMIT'ed by this value. Use only when you're not aggregating or it will sample the data.

  • Returns: array — The entire select query.

__toString()

Returns the segment string.

Signature

  • It returns a string value.

combine()

Combines this segment with another segment condition, if the segment condition is not already in the segment.

The combination is naive in that it does not take order of operations into account.

Signature

  • It accepts the following parameter(s):

    • $segment (string) —

    • $operator (string) — The operator to use. Should be either SegmentExpression::AND_DELIMITER or SegmentExpression::OR_DELIMITER.

    • $segmentCondition (string) — The segment condition to add.
  • It returns a string value.
  • It throws one of the following exceptions:

getStoredSegmentName()

Signature

  • It accepts the following parameter(s):

    • $idSite

  • It does not return anything or a mixed result.

getOriginalString()

Signature

  • It does not return anything or a mixed result.