view CWEP-002.rst @ 18:3d5c05e7dc75

[CWEP002] migration section
author Laura Médioni <laura.medioni@logilab.fr>
date Mon, 16 Jun 2014 11:08:29 +0200
parents 2c4efa3428ca
children
line wrap: on
line source
CWEP-0002 - RQL rewriting
=========================

:champion: Léa Capgen, Vincent Michel, Sylvain Thénault
:reviewers: COPIL
:last update: 2014/05/15
.. draft / reviewed / implemented
:status: reviewed


Computed relations
------------------

Schema definition
~~~~~~~~~~~~~~~~~

.. sourcecode:: python

    class illustrator_of(ComputedRelation):
        rule  = ('C is Contribution, C contributor S, C manifestation O,'
                 'C role R, R name "illustrator"')

* define a virtual `illustrator_of` relation type ;

* possible (subject, object) are infered from the rule ;

* computed relation definition have empty 'add'/'delete' permissions, this
  should nicely drive the automatic UI

* 'read' permissions can be defined, permissions from the relations used in the
  rewrite rule **are not considered** ;

* nothing else may be defined on the `ComputedRelation` subclass beside
  permissions and rule (e.g. no cardinality, composite, etc.,).
  `BadSchemaDefinition` is raised on attempt to specify other attributes.

Alternatives:

* `ComputedRelation` is preferred over `ComputedRelation` because the
  type/definition concept remains obscur for most people and we don't want/need
  the discussion here. Also it's easier to read/remember.


Schema API
~~~~~~~~~~

Computed relations are represented by `ComputedRelation` holding the
rule attribute.


Cubicweb
~~~~~~~~

* computed relation can't be used in 'SET' and 'DELETE' rql queries (`BadQuery`
  exception raised)

* CWComputedRType is used for serialization

* computed relations are virtual, RQL is rewritten to handle them and nothing is
  stored in the database.


Computed attribute
------------------

Schema definition
~~~~~~~~~~~~~~~~~
.. sourcecode:: python:

    class Company(EntityType):
        name = String()
        total_salary = Int(formula=('Any SUM(SA) GROUPBY X WHERE P works_for X, P salary SA'))

* define a computed `total_salary` attribute on `Company`;

* actual type is checked from the formula;

* 'read' permissions can be defined, permissions from the relations used in the
  rewrite rule **are not considered**;

* `BadSchemaDefinition` is raised on attempt to set cardinality or 'add' / 'delete'
  permissions;

* every other attribute's property can be defined as for other attributes.


Schema API
~~~~~~~~~~

Computed attributes are represented by regular final type with a 'formula'
property set to a value.


Cubicweb
~~~~~~~~

* Similarly to computed relation, computed attribute can't be used in 'SET' and
  'DELETE' rql queries (`BadQuery` exception raised)

* computed attributes are materialized, hooks are generated to handle them and
  value is stored in the database. At some point you'll probably want to handle
  this using e.g.

Migration
---------

The migrations are handled as summarized in the array below.

+------------+---------------------------------------------------+---------------------------------------+
|            | Computer rtype                                    | Computed attribute                    |
+============+===================================================+=======================================+
| add        | * add_relation_type                               | * add_attribute                       |
|            | * add_relation_definition should trigger an error | * add_relation_definition             |
+------------+---------------------------------------------------+---------------------------------------+
| modify     | * sync_schema_prop_perms (check the rule is       | * sync_schema_prop_perms (empty the   |
| (rule or   |   synchronized with the database)                 |   cache, check formula, make sure all |
| formula)   |                                                   |   the values get updated)             |
+------------+---------------------------------------------------+---------------------------------------+
| del        | * drop_relation_type                              | * drop_attribute                      |
|            | * drop_relation_definition should trigger an error| * drop_relation_definition            |
+------------+---------------------------------------------------+---------------------------------------+

Restrictions
------------

This CWEP is on purpose not specifying materialized relations and rewritten
attributes. Materialized relations will probably be implemented using the work
done for materialized attribute. Rewritten attributes deserve more though,
integration of arbitrary rql being a tricky problem (GROUPBY and all).

Also, this leaves time to define yams annotations properly.