diff -r 76ab3c71aff2 -r c67bcee93248 doc/book/annexes/rql/intro.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/annexes/rql/intro.rst Thu Jan 08 22:11:06 2015 +0100 @@ -0,0 +1,162 @@ + +.. _rql_intro: + +Introduction +------------ + +Goals of RQL +~~~~~~~~~~~~ + +The goal is to have a semantic language in order to: + +- query relations in a clear syntax +- empowers access to data repository manipulation +- making attributes/relations browsing easy + +As such, attributes will be regarded as cases of special relations (in +terms of usage, the user should see no syntactic difference between an +attribute and a relation). + +Comparison with existing languages +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +SQL +``` + +RQL may remind of SQL but works at a higher abstraction level (the *CubicWeb* +framework generates SQL from RQL to fetch data from relation databases). RQL is +focused on browsing relations. The user needs only to know about the *CubicWeb* +data model he is querying, but not about the underlying SQL model. + +Sparql +`````` + +The query language most similar to RQL is SPARQL_, defined by the W3C to serve +for the semantic web. + +Versa +````` + +We should look in more detail, but here are already some ideas for the moment +... Versa_ is the language most similar to what we wanted to do, but the model +underlying data being RDF, there are some things such as namespaces or +handling of the RDF types which does not interest us. On the functionality +level, Versa_ is very comprehensive including through many functions of +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 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Search (`Any`) + Extract entities and attributes of entities. + +Insert entities (`INSERT`) + Insert new entities or relations in the database. + It can also directly create relationships for the newly created entities. + +Update entities, create relations (`SET`) + Update existing entities in the database, + or create relations between existing entities. + +Delete entities or relationship (`DELETE`) + Remove entities or relations existing in the database. + + +RQL relation expressions +~~~~~~~~~~~~~~~~~~~~~~~~ + +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). + +An RQL relation expression contains three components: + +* 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 + +.. warning:: + + 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. + + 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:: + + P works_for C, P name N + +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. + +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. + +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. + +Adding another relation expression:: + + P works_for C, P name N, C name "logilab" + +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. + +.. 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) +