README

AnalyticsDb is a component that enables you to store and query different time-series (numerical) data. Simple use-case would be tracking the number of visitors for your website inside the given date/time range, or tracking ecommerce revenue for a given quarter.

// get analytics instance
$mongo = new \Webiny\Component\Mongo\Mongo('127.0.0.1:27017', 'webiny');
$analytics = new \Webiny\AnalyticsDb\AnalyticsDb($mongo);

// store some visitor data
$analytics->log('visitor')->addDimension('browser', 'chrome')->addDimension('country', 'UK');

// store some revenue data
$analytics->log('revenue', 0, 120.00)
    ->addAttribute('brand', 'Foo')
    ->addDimension('product', 'hdd', 79.50)
    ->addDimension('product', 'mouse', 20.50)
    ->addDimension('tax', 'in-country', 20);

// save the data
$analytics->save();

// query data
$query = $a->query('revenue', 0, DateHelper::rangeLast30Days());

// get total number of visitors for the last 30 days, and group them by day
$result = $query->stats()->getResult();

// get total number of visitors for the last year, and group them by month
$query = $a->query('revenue', 0, DateHelper::rangeYear());
$result = $query->stats()->monthly()->groupByTimestamp()->sortByTimestamp(1)->getResult();

// get revenue for last quarter and group it by revenue type
$query = $a->query('revenue', 0, DateHelper::rangeQ1());
$result = $query->groupByDimensionName()->sortByCount(-1)->getResult();

Dependencies

The component requires an instance of \Webiny\Component\Mongo\Mongo to access your Mongo database where it will create several collections to store the data.

##Dimensions

Dimensions track different data which is still tied to your entity. For example say you have a product A, in 2 colors, red and blue. The product would be your entity, and colors would be your dimensions.

// track a view on the red product
$analytics->log('product', 'A')
  ->addDimension('color', 'red');

// track a view on the blue product
$analytics->log('product', 'A')
  ->addDimension('color', 'blue');

When tracking the dimensions, you can then get stats like "show me the views on all red version of my product".

$query = $a->query('product', 'A', DateHelper::rangeLast30Days());
$result = $query->dimension('color', 'red')->groupByDimensionValue()->sortByCount(-1)->getResult();

Attributes

Attributes are much simpler than dimensions. Attributes are just additional tags you can attach to an entity so you can group, sort and filter by them. A typical use-case for attributes is say you have a product, which has a certain brand and you want to be able to get a list of top 10 products for a certain brand.

$analytics->log('product', 'A')->addAttribute('brand', '10');

You can add multiple attributes to a product.

Now you can do something like this:

// show me top 10 products for brand "10" for last 30 days
$query = $a->query('product', null, DateHelper::rangeLast30Days());
$result = $query->stats()->addAttributeFilter('brand', 10)->sortByCount('-1')->limit(10);

Storing data

The data is stored using the log method. Note that data is not actually saved until you call the save method.

To assign attributes to your data, for example you wish to increment the number of visitors on your site, but you also want
to store some attributes, like what browser the user used, and from which country he came from; for that you can use dimensions. Dimensions are also counters which can be queried.

For example, for this use case:

$analytics->log('visitor')->addDimension('browser', 'chrome')->addDimension('country', 'UK');

You can know how many visitors you had for a given date range, and you can group that result either by day, or by month. Since you stored some data in dimensions, you can also know, how many users used chrome vs, for example firefox or ie, and then you can cross reference that to the total number of your visitors.

You can also assign a referral value to the log, for example, you can track per-page analytics like so:

$analytics->log('page', 123)->addDimension('browser', 'chrome')->addDimension('country', 'UK');

This will track a visitor for page with the id of 123. And then later you can query the analytics data for that page.

Some best practice is not to query data with a large set of different referrals. For example if you want to know how many visitors in total you had on your website, don't query and then sum the number of visitors of all your pages. Instead store 2 different analytics data, one for pages, and one for visitors in general.

By default the log method will increment the value by 1, but in some cases, for example when you wish to track revenue, you want to specify the increment value, and this is done by using the 3rd parameter, like so:

$analytics->log('revenue', 0, 120.00);

This will increase the revenue counter by 120.00 (float value is supported).

Querying data

To query the data, you need to get an instance of the query, like so:

$query = $a->query('revenue', 0, DateHelper::rangeLast30Days());

For the query you have to specify the entity name, referral, and the date range. There is a DateHelper class to help you in regards to some commonly used date ranges, but you can also specify your own custom range, it is just an array with two unix timestamps [dateFromTimestamp, dateToTimestamp].

Once you have the query instance, you can get the results for the given range. By default the data is grouped by day, but you can also get it in a per-month format.

$query = $a->query('revenue', 0, DateHelper::rangeLast30Days());

// get data by day
$result = $query->stats()->getResult();

// get data by month
$result = $query->stats()->monthly()->getResult();

To query dimensions, use the dimension method, like so:

$query = $a->query('revenue', 0, DateHelper::rangeYear());

// show me the revenue breakdown by item type (eg, product, tax)
$result = $query->dimension()->groupByDimensionName()->sortByCount(-1)->getResult();

// show me total revenue just from products
$result = $query->dimension('product')->getResult();

// show me total revenue breakdown by product type
$result = $query->dimension('product')->groupByDimensionValue()->sortByCount(-1)->getResult();

// show me revenue for `HDD` product by days
$result = $query->dimension('package', 'PAYG')->getResult();

// show me total revenue for `HDD` product
$result = $query->dimension('package', 'PAYG')->groupByDimensionName()->getResult();

License and Contributions

Contributing > Feel free to send PRs.

License > MIT

Resources

To run unit tests, you need to use the following command:

$ cd path/to/AnalyticsDb/
$ composer install
$ phpunit

webiny / analytics-db

Maintainers

Details