++++++++
Backends
++++++++

Cubes backends provide ways of retrieving data and aggrgating them. The data
access is provided through `Store` subclasses and aggregation through
`AggregationBrowser` subclasses.

`Store` represents a connection to a database, caches metadata and knows how
to retrieve the physical data.

Browser provides the core aggregation functionality on top of a physical
schema. There might be multiple browsers in a backend, each handling different
schemas, for example: snowflake schema, denormalized table or pre-aggregated
star.

Implementing Backend
====================

To implement custom backend:

1. create a subclass of `Store`
2. create a subclass of `AggregationBrowser` and specify which store and
   physical schema the browser can handle.


Store
-----

The store type name will be derived from the class name. `SQLStore` will be
called `sql`, `MongoStore` as `mongo`, `SomeOtherStore` as `some_other`.

Methods that the custom store is expected to implement:

* `__init__(**options)` – initialize the store from `options` dictionary
* `close()` – release all resources associated with the store, close database
  connections

It is highly recommended that the store provides a class variable named
`parameters` which is a list of parameter description dictionaries. The list
is used for properly configuring the store from end-user tools, such as
Slicer. It also provides information about how to convert options into
appropriate data types. Example:

.. code-block:: python

    class SQLStore(object):
        parameters = [
            {
                "name": "schema",
                "type": "string",
                "description": "Database schema where tables are stored"
            },
            {
                "name": "fact_prefix",
                "type": "string",
                "description": "Prefix for fact tables."
            },
            {
                "name": "dimension_prefix",
                "type": "string",
                "description": "Prefix for dimension tables."
            },
            {
                "name": "safe_labels",
                "type": "bool",
                "description": "Use safe column labels for constructed SQL "
                               "queries."
            }
        }
        

.. note::

    Current use of the `Store` class is only as plug-in mechanism to find the
    store factory without need of explicit registration.

Aggregation Browser
-------------------

Methods to be implemented:

* `__init__(cube, store, locale)` – initialize the browser for `cube` stored
  in a `store` and use model and data `locale`.
* `aggregate()`, `facts()`, ... all basic browser methods that take a cell as
  first argument. See :class:`AggregationBrowser` for more information.

The browser class should provide two class variables:

* `store_type` – type of store that the browser operates on
* `schema_type` – type (name) of physical schema that the broser knows how to
  aggregate. It can be a list if the browser can handle multiple types of
  schema.

For example:

.. code-block:: python

    class SQLSnowflakeBrowser(AggregationBrowser):
        store_type = "sql"
        schema_type = ("snowflake", "star")

        def __init__(self, cube, store, locale=None):
            # browser initialization...

Backend Configuration
---------------------

Store is configured from one of:

* `[store]` section of the main configuration file (``slicer.ini``),
  considered as ``"default"`` store
* section with custom store name from stores configuration file
  (``stores.ini`` by default)

Browser is configured from ``[browser]`` section of the main configuration
file and from cube's `Cube.browser_options` (former `Cube.options`) attribute.