CWEP-002.rst
author Rabah Meradi <rabah.meradi@logilab.fr>
Thu, 04 Jun 2015 09:28:35 +0200
changeset 28 2d1748aaa34b
parent 18 3d5c05e7dc75
permissions -rw-r--r--
updates about the pyramid bug
     1 CWEP-0002 - RQL rewriting
     2 =========================
     3 
     4 :champion: Léa Capgen, Vincent Michel, Sylvain Thénault
     5 :reviewers: COPIL
     6 :last update: 2014/05/15
     7 .. draft / reviewed / implemented
     8 :status: reviewed
     9 
    10 
    11 Computed relations
    12 ------------------
    13 
    14 Schema definition
    15 ~~~~~~~~~~~~~~~~~
    16 
    17 .. sourcecode:: python
    18 
    19     class illustrator_of(ComputedRelation):
    20         rule  = ('C is Contribution, C contributor S, C manifestation O,'
    21                  'C role R, R name "illustrator"')
    22 
    23 * define a virtual `illustrator_of` relation type ;
    24 
    25 * possible (subject, object) are infered from the rule ;
    26 
    27 * computed relation definition have empty 'add'/'delete' permissions, this
    28   should nicely drive the automatic UI
    29 
    30 * 'read' permissions can be defined, permissions from the relations used in the
    31   rewrite rule **are not considered** ;
    32 
    33 * nothing else may be defined on the `ComputedRelation` subclass beside
    34   permissions and rule (e.g. no cardinality, composite, etc.,).
    35   `BadSchemaDefinition` is raised on attempt to specify other attributes.
    36 
    37 Alternatives:
    38 
    39 * `ComputedRelation` is preferred over `ComputedRelation` because the
    40   type/definition concept remains obscur for most people and we don't want/need
    41   the discussion here. Also it's easier to read/remember.
    42 
    43 
    44 Schema API
    45 ~~~~~~~~~~
    46 
    47 Computed relations are represented by `ComputedRelation` holding the
    48 rule attribute.
    49 
    50 
    51 Cubicweb
    52 ~~~~~~~~
    53 
    54 * computed relation can't be used in 'SET' and 'DELETE' rql queries (`BadQuery`
    55   exception raised)
    56 
    57 * CWComputedRType is used for serialization
    58 
    59 * computed relations are virtual, RQL is rewritten to handle them and nothing is
    60   stored in the database.
    61 
    62 
    63 Computed attribute
    64 ------------------
    65 
    66 Schema definition
    67 ~~~~~~~~~~~~~~~~~
    68 .. sourcecode:: python:
    69 
    70     class Company(EntityType):
    71         name = String()
    72         total_salary = Int(formula=('Any SUM(SA) GROUPBY X WHERE P works_for X, P salary SA'))
    73 
    74 * define a computed `total_salary` attribute on `Company`;
    75 
    76 * actual type is checked from the formula;
    77 
    78 * 'read' permissions can be defined, permissions from the relations used in the
    79   rewrite rule **are not considered**;
    80 
    81 * `BadSchemaDefinition` is raised on attempt to set cardinality or 'add' / 'delete'
    82   permissions;
    83 
    84 * every other attribute's property can be defined as for other attributes.
    85 
    86 
    87 Schema API
    88 ~~~~~~~~~~
    89 
    90 Computed attributes are represented by regular final type with a 'formula'
    91 property set to a value.
    92 
    93 
    94 Cubicweb
    95 ~~~~~~~~
    96 
    97 * Similarly to computed relation, computed attribute can't be used in 'SET' and
    98   'DELETE' rql queries (`BadQuery` exception raised)
    99 
   100 * computed attributes are materialized, hooks are generated to handle them and
   101   value is stored in the database. At some point you'll probably want to handle
   102   this using e.g.
   103 
   104 Migration
   105 ---------
   106 
   107 The migrations are handled as summarized in the array below.
   108 
   109 +------------+---------------------------------------------------+---------------------------------------+
   110 |            | Computer rtype                                    | Computed attribute                    |
   111 +============+===================================================+=======================================+
   112 | add        | * add_relation_type                               | * add_attribute                       |
   113 |            | * add_relation_definition should trigger an error | * add_relation_definition             |
   114 +------------+---------------------------------------------------+---------------------------------------+
   115 | modify     | * sync_schema_prop_perms (check the rule is       | * sync_schema_prop_perms (empty the   |
   116 | (rule or   |   synchronized with the database)                 |   cache, check formula, make sure all |
   117 | formula)   |                                                   |   the values get updated)             |
   118 +------------+---------------------------------------------------+---------------------------------------+
   119 | del        | * drop_relation_type                              | * drop_attribute                      |
   120 |            | * drop_relation_definition should trigger an error| * drop_relation_definition            |
   121 +------------+---------------------------------------------------+---------------------------------------+
   122 
   123 Restrictions
   124 ------------
   125 
   126 This CWEP is on purpose not specifying materialized relations and rewritten
   127 attributes. Materialized relations will probably be implemented using the work
   128 done for materialized attribute. Rewritten attributes deserve more though,
   129 integration of arbitrary rql being a tricky problem (GROUPBY and all).
   130 
   131 Also, this leaves time to define yams annotations properly.