<commit_before>+++++++++++
OLAP Server
+++++++++++

Cubes framework provides easy to install web service WSGI server with API that 
covers most of the Cubes logical model metadata and aggregation browsing 
functionality.

For more information about how to run the server, please refer to the
:mod:`server` module.

Server Requests
===============

Version
-------

Request: ``GET /version``

Return a serve  r version.

.. code-block:: javascript

    {
        "version": "0.10.2"
    }

Model
=====

List of Cubes
-------------

Request: ``GET /cubes``

Get list of basic informatiob about served cubes. The cube description
dictionaries contain keys: `name`, `label`, `description` and `category`.

.. code-block:: javascript

    [
        {
            "name": "contracts",
            "label": "Contracts",
            "description": "...",
            "category": "..."
        }
    ]

Cube Model
----------

Request: ``GET /cube/<name>/model``

Get model of a cube `name`. Returned structure is a dictionary with keys:

* ``name`` – cube name – used as server-wide cube identifier
* ``label`` – human readable name of the cube – to be displayed to the users
  (localized)
* ``description`` – optional textual cube description (localized)
* ``dimensions`` – list of dimension description dictionaries (see below)
* ``aggregates`` – list of measures aggregates (mostly computed values) that
    can be computed. Each item is a dictionary. 
* ``measures`` – list of measure attributes (properties of facts). Each
    item is a dictionary. Example of a measure is: `amount`, `price`.
* ``details`` – list of attributes that contain fact details. Those attributes
  are provided only when getting a fact or a list of facts. 
* ``info`` – a dictionary with additional metadata that can be used in the
    front-end. The contents of this dictionary is defined by the model
    creator and interpretation of values is left to the consumer.
* ``features`` (advanced) – a dictionary with features of the browser, such as
  available actions for the cube ("is fact listing possible?")

Aggregate is the key numerical property of the cube from reporting
perspective. It is described as a dictionary with keys:

* ``name`` – aggregate identifier, such as: `amount_sum`, `price_avg`,
  `total`, `record_count`
* ``label`` – human readable label to be displayed (localized)
* ``measure`` – measure the aggregate is derived from, if it exists or it is
  known. Might be empty.
* ``function`` - name of an aggregate function applied to the `measure`, if
  known. For example: `sum`, `min`, `max`.
* ``info`` – additional custom information (unspecified)

Aggregate names are used in the ``aggregates`` parameter of the ``/aggregate``
request.

Measure dictionary contains:

* ``name`` – measure identifier
* ``label`` – human readable name to be displayed (localized)
* ``aggregates`` – list of aggregate functions that are provided for this
  measure
* ``info`` – additional custom information (unspecified)


.. note::

    Compared to previous versions of Cubes, the clients do not have to
    construct aggregate names (as it used to be ``amount``+``_sum``). Clients
    just get the aggrergate ``name`` property and use it right away.

See more information about measures and aggregates in the ``/aggregate``
request description.
    
Example cube:

.. code-block:: javascript

    {
        "name": "contracts", 
        "info": {}, 
        "label": "Contracts", 
        "aggregates": [
            {
                "name": "amount_sum", 
                "label": "Amount sum", 
                "info": {}, 
                "function": "sum"
            }, 
            {
                "name": "record_count", 
                "label": "Record count", 
                "info": {}, 
                "function": "count"
            }
        ], 

        "measures": [
            {
                "name": "amount", 
                "label": "Amount", 
                "info": {}, 
                "aggregates": [ "sum" ]
            }
        ], 
        
        "details": [...],

        "dimensions": [...]
    }

The dimension description dictionary:

* ``name`` – dimension identifier
* ``label`` – human readable dimension name (localized)
* ``is_flat`` – `True` if the dimension has only one level, otherwise `False`
* ``has_details`` – `True` if the dimension has more than one attribute
* ``default_hierarchy_name`` - name of default dimension hierarchy
* ``levels`` – list of level descriptions
* ``hierarchies`` – list of dimension hierarchies
* ``info`` – additional custom information (unspecified)

The level description:

* ``name`` – level identifier (within dimension context)
* ``label`` – human readable level name (localized)
* ``attributes`` – list of level's attributes
* ``key`` – name of level's key attribute (mostly the first attribute)
* ``label_attribute`` – name of an attribute that contains label for the
  level's members (mostly the second attribute, if present)
* ``order_attribute`` – name of an attribute that the level should be ordered
  by (optional)
* ``order`` – order direction ``asc``, ``desc`` or none.
* ``info`` – additional custom information (unspecified)

.. note::

    Use ``attribute["ref"]`` to access aggreegation result records.  Each
    level (dimension) attribute description contains two properties: `name`
    and `ref`.  `name` is identifier within the dimension context. The key
    reference `ref` is used for retrieving aggregation or browing results. 

    It is not recommended to create any dependency by parsing or constructing
    the `ref` property at the client's side.


Aggregation and Browsing
========================

The core data and analytical functionality is accessed through the following
requests:

* ``/cube/<name>/aggregate`` – aggregate measures, provide summary, generate
  drill-down, slice&dice, ...
* ``/cube/<name>/dimension/<dim>`` – list dimension members
* ``/cube/<name>/facts`` – list facts within a cell
* ``/cube/<name>/fact`` – return a single fact
* ``/cube/<name>/cell`` – describe the cell

If the model contains only one cube or default cube name is specified in the
configuration, then the ``/cube/<name>`` part might be omitted and you can
write only requests like ``/aggregate``.


Aggregate
---------

.. _serveraggregate:

Request: ``GET /cube/<cube>/aggregate``

Return aggregation result as JSON. The result will contain keys: `summary`
and `drilldown`. The summary contains one row and represents aggregation
of whole cell specified in the cut. The `drilldown` contains rows for each
value of drilled-down dimension.

If no arguments are given, then whole cube is aggregated.

Parameters:

* `cut` - specification of cell, for example:
  ``cut=date:2004,1|category:2|entity:12345``
* `drilldown` - dimension to be drilled down. For example ``drilldown=date``
  will give rows for each value of next level of dimension date. You can
  explicitly specify level to drill down in form: ``dimension:level``, such
  as: ``drilldown=date:month``. To specify a hierarchy use
  ``dimension@hierarchy`` as in ``drilldown=date@ywd`` for implicit level or
  ``drilldown=date@ywd:week`` to explicitly specify level.
* `aggregates` – list of aggregates to be computed, separated by ``|``, for
  example: ``aggergates=amount_sum|discount_avg|count``
* `measures` – list of measures for which their respecive aggregates will be
  computed (see below). Separated by ``|``, for
  example: ``aggergates=proce|discount``
* `page` - page number for paginated results
* `pagesize` - size of a page for paginated results
* `order` - list of attributes to be ordered by

.. note::

    You can specify either `aggregates` or `measures`. `aggregates` is a
    concrete list of computed values. `measures` yields their respective
    aggregates. For example: ``measures=amount`` might yield ``amount_sum``
    and ``amount_avg`` if defined in the model.
    
    Use of `aggregates` is preferred, as it is more explicit and the result
    is well defined.

..
    TODO: not implemented
    * `limit` - limit number of results in form
    `limit`[,`measure`[,`order_direction`]]: ``limit=5:received_amount_sum:asc``
    (this might not be implemented in all backends)

Response:

A dictionary with keys:

* ``summary`` - dictionary of fields/values for summary aggregation
* ``cells`` - list of drilled-down cells with aggregated results
* ``total_cell_count`` - number of total cells in drilldown (after `limit`,
  before pagination). This value might not be present if it is disabled for
  computation on the server side.
* ``aggregates`` – list of aggregate names that were considered in the
  aggragation query
* ``cell`` - list of dictionaries describing the cell cuts
* ``levels`` – a dictionary where keys are dimension names and values is a
  list of levels the dimension was drilled-down to

Example for request ``/aggregate?drilldown=date&cut=item:a``:

.. code-block:: javascript

    {
        "summary": {
            "count": 32, 
            "amount_sum": 558430
        }
        "cells": [
            {
                "count": 16, 
                "amount_sum": 275420, 
                "date.year": 2009
            }, 
            {
                "count": 16, 
                "amount_sum": 283010, 
                "date.year": 2010
            }
        ], 
        "aggregates": [
            "amount_sum", 
            "count"
        ], 
        "total_cell_count": 2, 
        "cell": [
            {
                "path": [ "a" ], 
                "type": "point", 
                "dimension": "item", 
                "invert": false,
                "level_depth": 1
            }
        ], 
        "levels": { "date": [ "year" ] }
    }


If pagination is used, then ``drilldown`` will not contain more than
``pagesize`` cells.

Note that not all backengs might implement ``total_cell_count`` or
providing this information can be configurable therefore might be disabled
(for example for performance reasons).
    

Facts
-----

Request: ``GET /cube/<cube>/facts``

Return all facts within a cell.

Parameters:

* `cut` - see ``/aggregate``
* `page`, `pagesize` - paginate results
* `order` - order results
* `format` - result format: ``json`` (default; see note below), ``csv``
* `fields` - comma separated list of fact fields, by default all fields are
  returned
* `headers` – specify what kind of headers should be present in the ``csv``
  output: ``names`` – raw field names (default), ``labels`` – human readable labels or<commit_msg>minor doc fix<commit_after>+++++++++++
OLAP Server
+++++++++++

Cubes framework provides easy to install web service WSGI server with API that 
covers most of the Cubes logical model metadata and aggregation browsing 
functionality.

For more information about how to run the server, please refer to the
:mod:`server` module.

Server Requests
===============

Version
-------

Request: ``GET /version``

Return a serve  r version.

.. code-block:: javascript

    {
        "version": "0.10.2"
    }

Model
=====

List of Cubes
-------------

Request: ``GET /cubes``

Get list of basic informatiob about served cubes. The cube description
dictionaries contain keys: `name`, `label`, `description` and `category`.

.. code-block:: javascript

    [
        {
            "name": "contracts",
            "label": "Contracts",
            "description": "...",
            "category": "..."
        }
    ]

Cube Model
----------

Request: ``GET /cube/<name>/model``

Get model of a cube `name`. Returned structure is a dictionary with keys:

* ``name`` – cube name – used as server-wide cube identifier
* ``label`` – human readable name of the cube – to be displayed to the users
  (localized)
* ``description`` – optional textual cube description (localized)
* ``dimensions`` – list of dimension description dictionaries (see below)
* ``aggregates`` – list of measures aggregates (mostly computed values) that
    can be computed. Each item is a dictionary. 
* ``measures`` – list of measure attributes (properties of facts). Each
    item is a dictionary. Example of a measure is: `amount`, `price`.
* ``details`` – list of attributes that contain fact details. Those attributes
  are provided only when getting a fact or a list of facts. 
* ``info`` – a dictionary with additional metadata that can be used in the
    front-end. The contents of this dictionary is defined by the model
    creator and interpretation of values is left to the consumer.
* ``features`` (advanced) – a dictionary with features of the browser, such as
  available actions for the cube ("is fact listing possible?")

Aggregate is the key numerical property of the cube from reporting
perspective. It is described as a dictionary with keys:

* ``name`` – aggregate identifier, such as: `amount_sum`, `price_avg`,
  `total`, `record_count`
* ``label`` – human readable label to be displayed (localized)
* ``measure`` – measure the aggregate is derived from, if it exists or it is
  known. Might be empty.
* ``function`` - name of an aggregate function applied to the `measure`, if
  known. For example: `sum`, `min`, `max`.
* ``info`` – additional custom information (unspecified)

Aggregate names are used in the ``aggregates`` parameter of the ``/aggregate``
request.

Measure dictionary contains:

* ``name`` – measure identifier
* ``label`` – human readable name to be displayed (localized)
* ``aggregates`` – list of aggregate functions that are provided for this
  measure
* ``info`` – additional custom information (unspecified)


.. note::

    Compared to previous versions of Cubes, the clients do not have to
    construct aggregate names (as it used to be ``amount``+``_sum``). Clients
    just get the aggrergate ``name`` property and use it right away.

See more information about measures and aggregates in the ``/aggregate``
request description.
    
Example cube:

.. code-block:: javascript

    {
        "name": "contracts", 
        "info": {}, 
        "label": "Contracts", 
        "aggregates": [
            {
                "name": "amount_sum", 
                "label": "Amount sum", 
                "info": {}, 
                "function": "sum"
            }, 
            {
                "name": "record_count", 
                "label": "Record count", 
                "info": {}, 
                "function": "count"
            }
        ], 

        "measures": [
            {
                "name": "amount", 
                "label": "Amount", 
                "info": {}, 
                "aggregates": [ "sum" ]
            }
        ], 
        
        "details": [...],

        "dimensions": [...]
    }

The dimension description dictionary:

* ``name`` – dimension identifier
* ``label`` – human readable dimension name (localized)
* ``is_flat`` – `True` if the dimension has only one level, otherwise `False`
* ``has_details`` – `True` if the dimension has more than one attribute
* ``default_hierarchy_name`` - name of default dimension hierarchy
* ``levels`` – list of level descriptions
* ``hierarchies`` – list of dimension hierarchies
* ``info`` – additional custom information (unspecified)

The level description:

* ``name`` – level identifier (within dimension context)
* ``label`` – human readable level name (localized)
* ``attributes`` – list of level's attributes
* ``key`` – name of level's key attribute (mostly the first attribute)
* ``label_attribute`` – name of an attribute that contains label for the
  level's members (mostly the second attribute, if present)
* ``order_attribute`` – name of an attribute that the level should be ordered
  by (optional)
* ``order`` – order direction ``asc``, ``desc`` or none.
* ``info`` – additional custom information (unspecified)

.. note::

    Use ``attribute["ref"]`` to access aggreegation result records.  Each
    level (dimension) attribute description contains two properties: `name`
    and `ref`.  `name` is identifier within the dimension context. The key
    reference `ref` is used for retrieving aggregation or browing results. 

    It is not recommended to create any dependency by parsing or constructing
    the `ref` property at the client's side.


Aggregation and Browsing
========================

The core data and analytical functionality is accessed through the following
requests:

* ``/cube/<name>/aggregate`` – aggregate measures, provide summary, generate
  drill-down, slice&dice, ...
* ``/cube/<name>/dimension/<dim>`` – list dimension members
* ``/cube/<name>/facts`` – list facts within a cell
* ``/cube/<name>/fact`` – return a single fact
* ``/cube/<name>/cell`` – describe the cell

If the model contains only one cube or default cube name is specified in the
configuration, then the ``/cube/<name>`` part might be omitted and you can
write only requests like ``/aggregate``.


Aggregate
---------

.. _serveraggregate:

Request: ``GET /cube/<cube>/aggregate``

Return aggregation result as JSON. The result will contain keys: `summary`
and `drilldown`. The summary contains one row and represents aggregation
of whole cell specified in the cut. The `drilldown` contains rows for each
value of drilled-down dimension.

If no arguments are given, then whole cube is aggregated.

Parameters:

* `cut` - specification of cell, for example:
  ``cut=date:2004,1|category:2|entity:12345``
* `drilldown` - dimension to be drilled down. For example ``drilldown=date``
  will give rows for each value of next level of dimension date. You can
  explicitly specify level to drill down in form: ``dimension:level``, such
  as: ``drilldown=date:month``. To specify a hierarchy use
  ``dimension@hierarchy`` as in ``drilldown=date@ywd`` for implicit level or
  ``drilldown=date@ywd:week`` to explicitly specify level.
* `aggregates` – list of aggregates to be computed, separated by ``|``, for
  example: ``aggergates=amount_sum|discount_avg|count``
* `measures` – list of measures for which their respecive aggregates will be
  computed (see below). Separated by ``|``, for
  example: ``aggergates=proce|discount``
* `page` - page number for paginated results
* `pagesize` - size of a page for paginated results
* `order` - list of attributes to be ordered by

.. note::

    You can specify either `aggregates` or `measures`. `aggregates` is a
    concrete list of computed values. `measures` yields their respective
    aggregates. For example: ``measures=amount`` might yield ``amount_sum``
    and ``amount_avg`` if defined in the model.
    
    Use of `aggregates` is preferred, as it is more explicit and the result
    is well defined.

..
    TODO: not implemented
    * `limit` - limit number of results in form
    `limit`[,`measure`[,`order_direction`]]: ``limit=5:received_amount_sum:asc``
    (this might not be implemented in all backends)

Response:

A dictionary with keys:

* ``summary`` - dictionary of fields/values for summary aggregation
* ``cells`` - list of drilled-down cells with aggregated results
* ``total_cell_count`` - number of total cells in drilldown (after `limit`,
  before pagination). This value might not be present if it is disabled for
  computation on the server side.
* ``aggregates`` – list of aggregate names that were considered in the
  aggragation query
* ``cell`` - list of dictionaries describing the cell cuts
* ``levels`` – a dictionary where keys are dimension names and values is a
  list of levels the dimension was drilled-down to

Example for request ``/aggregate?drilldown=date&cut=item:a``:

.. code-block:: javascript

    {
        "summary": {
            "count": 32, 
            "amount_sum": 558430
        }
        "cells": [
            {
                "count": 16, 
                "amount_sum": 275420, 
                "date.year": 2009
            }, 
            {
                "count": 16, 
                "amount_sum": 283010, 
                "date.year": 2010
            }
        ], 
        "aggregates": [
            "amount_sum", 
            "count"
        ], 
        "total_cell_count": 2, 
        "cell": [
            {
                "path": [ "a" ], 
                "type": "point", 
                "dimension": "item", 
                "invert": false,
                "level_depth": 1
            }
        ], 
        "levels": { "date": [ "year" ] }
    }


If pagination is used, then ``drilldown`` will not contain more than
``pagesize`` cells.

Note that not all backengs might implement ``total_cell_count`` or
providing this information can be configurable therefore might be disabled
(for example for performance reasons).
    

Facts
-----

Request: ``GET /cube/<cube>/facts``

Return all facts within a cell.

Parameters:

* `cut` - see ``/aggregate``
* `page`, `pagesize` - paginate results
* `order` - order results
* `format` - result format: ``json`` (default; see note below), ``csv``
* `fields` - comma separated list of fact fields, by default all fields are
  returned
* `header` – specify what kind of headers should be present in the ``csv``
  output: ``names`` – raw field names (default), ``labels`` – human readable labels or
{'fraction_non_alphanumeric': 0.12209549950309971, 'fraction_numerical': 0.004732383701670531, 'mean_word_length': 2.971433940988536, 'pattern_counts': {'":': 88, '<': 23, '<?xml version=': 0, '>': 23, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2303357', 'n_tokens_mistral': 6032, 'n_tokens_neox': 5608, 'n_words': 2465}