# HG changeset patch # User Aurelien Campeas # Date 1278672483 -7200 # Node ID af48c527aea75c8a18f8fbbcee2e86658c8791c7 # Parent adb87a0752818df52a03beab501a76e459fbe3d6 [doc/book] fix & enhance rql intro chapter diff -r adb87a075281 -r af48c527aea7 doc/book/en/annexes/rql/intro.rst --- a/doc/book/en/annexes/rql/intro.rst Thu Jul 08 20:19:20 2010 +0200 +++ b/doc/book/en/annexes/rql/intro.rst Fri Jul 09 12:48:03 2010 +0200 @@ -45,6 +45,13 @@ conversion and basic types manipulation, which we may want to look at one time or another. Finally, the syntax is a little esoteric. +Datalog +``````` + +Datalog_ is a prolog derived query langage which applies to relational +databases. It is more expressive than RQL in that it accepts either +extensional_ and intensional_ predicates (or relations). As of now, +RQL only deals with intensional relations. The different types of queries ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -64,78 +71,91 @@ Remove entities or relations existing in the database. -Concepts -~~~~~~~~ - -Entity type -``````````` +RQL relation expressions +~~~~~~~~~~~~~~~~~~~~~~~~ -RQL manipulates variables that are instances of entities. -Each entity has its own type which are used in backend to improve the query -execution plan. +RQL expressions apply to a live database defined by a +:ref:`datamodel_definition`. Apart from the main type, or head, of the +expression (search, insert, etc.) the most common constituent of an +RQL expression is a (set of) relation expression(s). -Restrictions -```````````` +An RQL relation expression contains three components: -They are conditions used to limit the perimeter of the result set. - -Relations -````````` -A relation is a `3-expression` defined as follows: +* the subject, which is an entity type +* the predicate, which is a relation definition (an arc of the schema) +* the object, which is either an attribute or a relation to another entity .. image:: Graph-ex.gif :alt: :align: center -A RQL relation contains three components: +.. warning:: -* the subject, which is an entity type -* the predicate, which is an oriented graph -* the object, which is either an attribute or a relation to another entity + A relation is always expressed in the order: ``subject``, + ``predicate``, ``object``. -In cubicweb, the term `relation` is often found without ambiguity instead of `predicate`. -This predicate is also known as the `property` of the triple in `RDF concepts`_ - -A relation is always expressed in the order: subject, predicate, object. + It is important to determine if the entity type is subject or object + to construct a valid expression. Inverting the subject/object is an + error since the relation cannot be found in the schema. -It's important to determine if entity type is subject or object to construct a -valid expression. An inversion subject/object is equivalent to an RQL error -since the supposed relation cannot be found in schema. If you don't have access -to the code, you could find the order by looking at the schema image in manager -views (the subject is located at the beginning of the arrow). + If one does not have access to the code, one can find the order by + looking at the schema image in manager views (the subject is located + at the beginning of the arrow). + +An example of two related relation expressions:: -.. _SQL: http://www.firstsql.com/tutor5.htm -.. _RDF concepts: http://www.w3.org/TR/rdf-concepts/ + P works_for C, P name N -Cardinality -``````````` -XXX +RQL variables represent typed entities. The type of entities is +either automatically inferred (by looking at the possible relation +definitions, see :ref:`RelationDefinition`) or explicitely constrained +using the ``is`` meta relation. -Cardinality is an important concept to model your business rules. -They determine nu./tutorials/advanced/index.rst - -Please refer to the `datamodel definitions`_ for a deep understanding. +In the example above, we barely need to look at the schema. If +variable names (in the RQL expression) and relation type names (in the +schema) are expresssively designed, the human reader can infer as much +as the |cubicweb| querier. -`Relations`_ are always expressed by cardinality rules (`**` by default) +The ``P`` variable is used twice but it always represent the same set +of entities. Hence ``P works_for C`` and ``P name N`` must be +compatible in the sense that all the Ps (which *can* refer to +different entity types) must accept the ``works_for`` and ``name`` +relation types. This does restrict the set of possible values of P. -.. _datamodel definitions: ./devrepo/datamodel/definition.rst - -Transaction -``````````` +Adding another relation expression:: -RQL supports notion of **transactions**; i.e. sequences of RQL statements -without invoking security hooks of the instance's schema. - -When you're ready to make persistent the changes, you have to *commit* the -modification in calling `commit()`. + P works_for C, P name N, C name "logilab" -If an error is found (typically in raising a ValidationError), you have the -possibility to roll back the transaction in invoking `rollback()` function; i.e -to come back to the initial state of the transaction. +This further restricts the possible values of P through an indirect +constraint on the possible values of ``C``. The RQL-level unification_ +happening there is translated to one (or several) joins_ at the +database level. -Please, refer to the :ref:`Migration` chapter if you want more details. +.. note:: + + In |cubicweb|, the term `relation` is often found without ambiguity + instead of `predicate`. This predicate is also known as the + `property` of the triple in `RDF concepts`_ +RQL Operators +~~~~~~~~~~~~~ +An RQL expression's head can be completed using various operators such +as ``ORDERBY``, ``GROUPBY``, ``HAVING``, ``LIMIT`` etc. + +RQL relation expressions can be grouped with ``UNION`` or +``WITH``. Predicate oriented keywords such as ``EXISTS``, ``OR``, +``NOT`` are available. + +The complete zoo of RQL operators is described extensively in the +following chapter (:ref:`RQL`). + +.. _RDF concepts: http://www.w3.org/TR/rdf-concepts/ .. _Versa: http://wiki.xml3k.org/Versa .. _SPARQL: http://www.w3.org/TR/rdf-sparql-query/ +.. _unification: http://en.wikipedia.org/wiki/Unification_(computing) +.. _joins: http://en.wikipedia.org/wiki/Join_(SQL) +.. _Datalog: http://en.wikipedia.org/wiki/Datalog +.. _intensional: http://en.wikipedia.org/wiki/Intensional_definition +.. _extensional: http://en.wikipedia.org/wiki/Extension_(predicate_logic) diff -r adb87a075281 -r af48c527aea7 doc/book/en/devrepo/datamodel/definition.rst --- a/doc/book/en/devrepo/datamodel/definition.rst Thu Jul 08 20:19:20 2010 +0200 +++ b/doc/book/en/devrepo/datamodel/definition.rst Fri Jul 09 12:48:03 2010 +0200 @@ -1,5 +1,7 @@ .. -*- coding: utf-8 -*- +.. _datamodel_definition: + Yams *schema* ------------- @@ -11,6 +13,8 @@ .. _`Yams`: http://www.logilab.org/project/yams +.. _datamodel_overview: + Overview ~~~~~~~~ @@ -408,7 +412,7 @@ * special relations "has__permission" can not be used - +.. _yams_example: Defining your schema using yams ------------------------------- @@ -494,15 +498,15 @@ means that you need two separate entities that implement the `ITree` interface and get the result from `.children()` which ever entity is concerned. -Inheritance -``````````` -XXX feed me +.. Inheritance +.. ``````````` +.. XXX feed me Definition of relations ~~~~~~~~~~~~~~~~~~~~~~~ -XXX add note about defining relation type / definition +.. XXX add note about defining relation type / definition A relation is defined by a Python class heriting `RelationType`. The name of the class corresponds to the name of the type. The class then contains @@ -546,7 +550,7 @@ :Historical note: It has been historically possible to use `ObjectRelation` which - defines a relation in the opposite direction. This feature is soon to be + defines a relation in the opposite direction. This feature is deprecated and therefore should not be used in newly written code. :Future deprecation note: diff -r adb87a075281 -r af48c527aea7 doc/book/en/tutorials/base/maintemplate.rst --- a/doc/book/en/tutorials/base/maintemplate.rst Thu Jul 08 20:19:20 2010 +0200 +++ b/doc/book/en/tutorials/base/maintemplate.rst Fri Jul 09 12:48:03 2010 +0200 @@ -123,8 +123,8 @@ .. image:: ../../images/lax-book_06-simple-main-template_en.png -XXX -[WRITE ME] +.. XXX +.. [WRITE ME] * customize MainTemplate and show that everything in the user interface can be changed