CWEP-002.rst
author Nicolas Chauvat <nicolas.chauvat@logilab.fr>
Thu, 13 Feb 2014 17:11:45 +0100
changeset 6 f00e0e8cdeaf
parent 0 c628b3e8a6f1
child 1 0de3fa52f5a5
permissions -rw-r--r--
CWEP-003: proof-reading
     1 CWEP-0002 RQL rewriting
     2 =======================
     3 
     4 :champion: Lea Capgen
     5 :reviewers: COPIL
     6 :last update: 2014/01/10
     7 :status: draft
     8 
     9 
    10 Computed relations
    11 ------------------
    12 
    13 Schema definition
    14 ~~~~~~~~~~~~~~~~~
    15 
    16 .. sourcecode:: python
    17 
    18     class illustrator_of(ComputedRelationType):
    19 	rule  = ('C is Contribution, C contributor S, C manifestation O,'
    20 		 'C role R, R name "illustrator"')
    21 
    22 * define a virtual `illustrator_of` relation type
    23 
    24 * XXX alternative proposition `ComputedRelation`
    25 
    26 * possible (subject, object) are infered from the rule
    27 
    28 * cardinality can't be specifed and is forced '**'
    29 
    30 * nothing else may be defined on the `ComputedRelationType` subclass (e.g. no
    31   permissions, cardinality, etc., `BadSchema` raised on attempt to specify those
    32   attributes)
    33 
    34 
    35 Schema API
    36 ~~~~~~~~~~
    37 
    38 Computed relation type are represented by `ComputedRelationSchema` holding the
    39 special logic.
    40 
    41 XXX implementation will tell if we want `ComputedRDef` class for associated
    42 generated relation definitions.
    43 
    44 * computed relation definition have empty 'add'/'delete' permissions, this
    45   should nicely drive the automatic ui
    46 
    47 
    48 Cubicweb
    49 ~~~~~~~~
    50 
    51 * computed relation can't be used in SET / DELETE (`BadQuery` exception raised)
    52 
    53 * need new entity type for serialization
    54 
    55 * computed relations are virtual, RQL is rewritten to handle them and nothing is
    56   stored in the database. At some point you'll probably want to handle this
    57   using e.g.
    58 
    59   .. sourcecode::
    60 
    61     class illustrator_of(ComputedRelationType):
    62 	rule  = ('C is Contribution, C contributor S, C manifestation O,'
    63 		 'C role R, R name "illustrator"')
    64 	__annotations__ = {'materialized': True}
    65 
    66 See CWEP-XXXX regarding the annotation syntax.
    67 
    68 XXX explain why those restrictions
    69 
    70 
    71 Computed attribute
    72 ------------------
    73 
    74 Schema definition
    75 ~~~~~~~~~~~~~~~~~
    76 .. sourcecode:: python:
    77 
    78     class Company(EntityType):
    79 	name = String()
    80 	total_salary = Int(formula=('Any SUM(SA) GROUPBY X WHERE P works_for X, P salary SA'))
    81 
    82 * define a computed `total_salary` attribute on `Company`
    83 
    84 * XXX alternative proposition: `ComputedAttribute(formula=<rql>)`, actual type
    85   being infered from the formula.
    86 
    87 * every other attribute's property should/could be defined, including
    88   permissions.
    89 
    90 * cardinality can't be specifed and is forced '?*'
    91 
    92 Schema API
    93 ~~~~~~~~~~
    94 
    95 XXX alternative:
    96 
    97   Computed attributes are represented by `ComputedAttribute` holding the special
    98   logic.
    99 
   100 vs
   101 
   102   Computed attributes are represented by regular type with a 'formula' property
   103   set to a value.
   104 
   105 
   106 Similarly to computed relation:
   107 
   108 * computed attribute can't be used in SET / DELETE (`BadQuery` exception raised)
   109 
   110 * computed attribute have empty 'add'/'update' permissions
   111 
   112 
   113 Cubicweb
   114 ~~~~~~~~
   115 
   116 * computed attributes are materialized, hooks are generated to handle them and
   117   value is stored in the database. At some point you'll probably want to handle
   118   this using e.g.
   119 
   120   .. sourcecode::
   121 
   122 
   123     class Company(EntityType):
   124 	name = String()
   125 	total_salary = Int(formula=('Any SUM(SA) GROUPBY X WHERE P works_for X, P salary SA'))
   126 	total_salary.__annotations__ = {'materialized': False}
   127