How to use regular expressions in Piwik PRO?


A regular expression (regex) is a sequence of characters that defines a search pattern. It allows you to express complex search conditions. In this article, we’ll look at some examples of how to use regular expressions in Piwik PRO.

Before you start:

  • In the Analytics module, we use regular expressions in report filters, quick filters, custom dimension extractions, segments and automatic goal tracking.
  • Currently, we use the RE2 implementation of regular expression in all Piwik PRO search engines. RE2 is a regex implementation created and maintained by Google.

For developers: Our validation no longer accepts unnecessary escaping. For example,^https:\/\/ was considered correct, but it’s not anymore. The reason for this is the sequence \/ and the fact that slash characters have no meaning in regex syntax, so they don’t need to be escaped. That’s why the correct syntax should now look like ^https://.

Similarly, unnecessary escaping ASCI characters like \q is no longer accepted. Some of those expressions, like \w are valid regex patterns, so unnecessary escaping errors, in general, should lead to fewer mistakes.

Use regular expressions in filters in your reports

If the products on your website are tagged, you may want to filter your reports to see only customers who viewed specific items. After the client clicks on a tag, you will receive a page view event with a URL containing phrases like /tag/?t=green+shoes

When you want to filter your report to show only customers who were looking for green shoes, you can add a filter to your report and use a regular condition: contains

filters in reports

Now, if you want to see how many customers are looking for more than one color of shoes, you need to use a more complex condition, and that’s where regular expressions come in handy.

To add a filter with regex to your report, follow these steps:

  1. Go to Menu > Analytics.
  2. Navigate to Custom reports.
  3. Choose your report from the list.
  4. Click Edit.
    regex 1
  5. In Filter dimensions, drag and drop the data into the designing space. In our case, it’s Page URL.
  6. Choose matches regex from the list and enter the regular expression. For example, if you only want to see the visitors who searched for red, green or blue shoes, you can apply the following filter: Page URL matches regex (red|green|blue)\+shoes.
    regex 2

    Note: In this case, the condition will give you all the visitors that searched for red, green or blue shoes because | is equivalent to “or”. 
    Remember to enclose all the color options in brackets to tell the search engine that this + sign is not a part of regex language.

  7. Click Save.
  8. Done! Your filter with a regular expression is ready, and now your report shows only the visitors who searched for red, green or blue shoes.

Use regular expressions in custom dimensions

If you want to create a custom dimension that contains the color of searched shoes, you can also use a regex.

To create an event custom dimension, follow these steps:

  1. Go to Menu > Analytics.
  2. Navigate to Settings.
  3. On the left, click Custom dimensions.
  4. Click Add an event dimension.
    regex 3
  5. Name the dimension.
  6. Click Save.
  7. Now, it’s time to set up dimension values and data collection.
  8. In Set the value using extractions, click +Add extraction.
    regex 4
  9. Use a regex (regular expression) to extract values from the page URL or title. Or use a parameter to extract values from the page URL.

    Note: The following expression will treat bracketed content as a separate group. Added to custom dimension extraction, this particular group will be extracted.

  10. Click Save.
  11. Done! Your custom dimension for all the visitors who searched for red, green or blue shoe colors is ready.

    Note: As regular expression syntax is quite complicated, we recommend you to check regular expression documentation and use a regex online checking tool to test your expression.

Was this article helpful?

Technical support

If you still have any questions, visit our community.
There’s always someone happy to help!

Back to help center