@sap/cds 1.15.1 → 1.18.2

package/TUTORIAL.md

@@ -1,1236 +0,0 @@
-node-cds: Core Data Services for node.js
-========================================
-
-Important note: 
----------------
-    The node-cds library is now considered feature complete.  
-    It will remain fully supported but will not receive further 
-    enhancements in future releases.
-
-
-Entity Declarations
--------------------
-
-The data declaration part of your JavaScript file defines the entity
-types based on existing CDS and/or HANA tables and views:
-
-    cds.$importEntities([
-        // for CDS:
-        { $entity: "cds.namespace::cds_context.cds_entity" },
-        // for plain SQL:
-        { $schema: "SCHEMA", $table: "package::TABLE"), $name: "name" }
-    ], function (error, entities) { … });
-
-For single entity imports the `$importEntity` function may also be
-used.
-
-Both import methods pass a dictionary of imported entities indexed by
-entity name to the callback function.  This dictionary comprises both
-explicitly and implicitly imported entities, including previously
-imported entities if required.
-
-    cds.$importEntities([{
-        $entity: "sap.hana.xs2.cds.examples.data::bboard.post"
-    }], function (error, entities) {
-        var post = entities["sap.hana.xs2.cds.examples.data::bboard.post"];
-        var user = entities["sap.hana.xs2.cds.examples.data::bboard.user"];
-                   // automatically imported because of association from Post to User
-    });
-
-For most CDS data models and simple SQL data models this is all that
-is required to define an entity.
-
-Advanced options allow you to override certain properties of the
-columns to import.  In the simplest case, you simply want to rename a
-table column for your JavaScript object property:
-
-    cds.$importEntities([
-        { $entity: "sap.hana.xs2.cds.examples.data::bboard.post",
-            $fields: {
-                PostedOn: { $column: "Created" }
-            }
-        }
-    ], callback);
-
-Primary key information is automatically imported, but you may also
-add or change key information, e.g., for CDS entities defined with the
-`@nokey` attribute:
-
-    cds.$importEntities([{
-        $entity: "sap.hana.xs2.cds.examples.data::bboard.post",
-        $fields: {
-            pid: { $key: true }
-        }
-    }], callback);
-
-You may also provide an existing HDB sequence to generate keys
-automatically for you.  By using a sequence key fields may be
-populated automatically by the database.
-
-    cds.$importEntities([{
-        $entity: "sap.hana.xs2.cds.examples.data::bboard.user",
-        $fields: {
-            uid: { $key: "\"sap.hana.xs2.cds.examples.data::bb_keyid\"" }
-        }
-    }], callback);
-
-Note that node-cds does not apply any additional logic to key
-generation.  It is left to the application and the sequence to
-generate valid, unique keys for your entities.
-
-`$importEntities()` passes a dictionary of entity objects for the
-entity types defined to its callback.  If you need to access an entity
-in a different scope you can use the `$getEntity()` function to
-retrieve the entity object by entity name:
-
-    function foo() {
-        cds.$importEntity({ $entity: "cds_namespace::cds_context.cds_entity" }),
-                          callback);
-    }
-
-    function bar() {
-        cds.$getEntity("cds_namespace::cds_context.cds_entity"),
-                       function(err, entity) { … }
-    }
-
-The `$getEntity` function not only saves you from storing your
-entities in global variables but also offers flow control to ensure
-that the entity and all its dependencies have been imported
-completely.  Note that the callback of a `$getEntity` call for an
-entity that is not imported will never be called!
-
-There is also a synchronous version `$getEntitySync` that will return
-the entity immediately or null if the import has not been completed
-yet.
-
-    var someEntity = cds.$getEntitySync("cds_namespace::cds_context.cds_entity");
-    if (!someEntity)
-        console.warn("well, now what?!");
-
-Finally we would like to stress that node-cds is a consumption-only
-framework that will only import externally defined data models.  It is
-beyond the scope of node-cds to create tables and modify existing CDS
-data models permanently.  This scope definition will not change in the
-future.
-
-
-Associations
-------------
-
-One of the benefits of the semantically rich data models of CDS is the
-ability to handle associations conveniently.  node-cds supports plain
-one-to-one, one-to-many, and many-to-many CDS associations in all of
-their flavors.
-
-While the CDS core implementation for managed one-to-many and
-many-to-many associations is still incomplete node-cds already
-supports these types of associations in a way that makes it easy to
-migrate once they become available in CDS as well.
-
-CDS one-to-one (and one-to-zero-or-one) associations are imported
-automatically.  To define one-to-one associations manually you provide
-an `$association` property that specifies the associated entity type
-and the foreign key that links the parent entity to the associated
-target entity:
-
-    cds.$importEntity({
-        $entity: "sap.hana.xs2.cds.examples.data::bboard.post",
-        $fields: {
-            PostedBy: {
-                $association: { $entity: "sap.hana.xs2.cds.examples.data::bboard.user" },
-                uid: { $column: "Author" }
-            }
-        }
-    }, callback);
-
-In this example the link between Post and User is defined through the
-foreign key relation so that `USERS.uid = POSTS.Author` holds.  Note
-that the `Author` column of table `POSTS` is not mapped to a field of
-the `Post` entity; it’s used exclusively for following the
-association.  The foreign key may reference any number of columns of
-the underlying database table.
-
-Entities referenced by name are imported automatically with default
-options if no matching `$importEntities()` call can be found.
-
-
-### One-to-Many Associations
-
-The CDS specification defines one-to-many associations by using
-backlinks from the targets to the parent.  Assume for our example that
-each post may have any number of unique comments, where each comment
-contains a reference to its parent post:
-
-    entity comment {
-        key cid: Integer not null;
-        Text: text;
-        Author: association [1] to user;
-        Parent: association [1] to post;  // as backlink
-        Created: UTCDateTime;
-    };
-
-Since the CDS implementation does not support backlinks yet, we cannot
-add comments to our CDS definition of post, but we may augment the
-`Post` data model in our import:
-
-    cds.$importEntity({
-        $entity: "sap.hana.xs2.cds.examples.data::bboard.post",
-        $fields: {
-            Comments: {
-                $association: {
-                    $entity: "sap.hana.xs2.cds.examples.data::bboard.comment",
-                    $viaBacklink: "Parent"
-                }
-            }
-        }
-    }, callback);
-
-This is equivalent to importing the following, still unsupported CDS
-definition:
-
-    entity post {
-        key pid: Integer not null;
-        ...
-        Comments: association [0..*] to comment via backlink Parent;
-    };
-
-Once CDS support for backlinks is implemented, the node-cds import
-above simplifies to
-
-    cds.$importEntity({ $entity: "sap.hana.xs2.cds.examples.data::bboard.post" },
-        callback);
-
-Either way, the comments will appear as an array in our instances of
-the Post entity:
-
-    tx.$get(Post, { pid: 69 }, function(error, post) {
-        for (var i = 0; i < post.Comments.length; ++i) {
-            if (post.Comments[i].Author.Name === "Alice") { … }
-    });
-
-Note that the association array should be seen as a read-only array
-that gathers the association targets for convenience.  While
-individual array elements may be manipulated directly their membership
-to the association and thus the array is governed by their backlink
-property only.  This has some potentially unexpected consequences when
-saving instances with backlink associations that are further detailed
-in the section “Working with entities”.
-
-
-### Many-to-Many Associations
-
-The CDS specification defines many-to-many associations by using
-linking entities that connect parent and target instances.  Assume for
-our example that any number of tags may be attached to our posts:
-
-    entity tag {
-        key tid: Integer not null;
-        Name: String(63);
-    };
-
-The actual linkage data is stored in a separate table.  For plain SQL,
-this table may be specified directly, but for CDS we assume a
-corresponding entity definition:
-
-    @nokey entity tags_by_post {
-        lid: Integer;
-        LinkTag: association to tag;
-        LinkPost: association to post;
-    };
-
-Since the CDS implementation does not support linking entities yet, we
-can manually augment our data model in the import statement:
-
-    cds.$importEntity({
-        $entity: "sap.hana.xs2.cds.examples.data::bboard.post",
-        $fields: {
-            Tags: {
-                $association: {
-                    $entity: "sap.hana.xs2.cds.examples.data::bboard.tag",
-                    $viaEntity: "sap.hana.xs2.cds.examples.data::bboard.tags_by_post",
-                    $source: "LinkPost",
-                    $target: "LinkTag"
-                }
-            }
-        }
-    }, callback);
-
-The `$source` and `$target` properties indicate the direction of the
-association.  This is strictly required if source and target refer to
-the same entity; for simplicity, however, we enforce that these
-properties are always supplied.
-
-Above annotation is equivalent to importing the following, still
-unsupported CDS definition:
-
-    entity post {
-        key pid: Integer not null;
-        ...
-        Tags: association [0..*] to ds_comments via entity tags_by_post;
-    };
-
-Once CDS support for backlinks is implemented, the node-cds import
-simplifies to
-
-    cds.$importEntity({ $entity: "sap.hana.xs2.cds.examples.data::bboard.post" },
-        callback);
-
-Note again that an explicit import of `Tags` or `Tags_by_post` is not
-required.  The linking entities such as `Tags_by_post` may or may not
-have a key, and they could have additional fields besides the
-`$source` and `$target` fields.
-
-The tags will appear as a native JavaScript array in our instances of
-the `Post` entity:
-
-    tx.$get(Post, { pid: 69 }, function (error, post) {
-        tx.$find(Tag, { Text: "cool" }, function (error, tags) {
-            if (post.Tags.indexOf(tags[0]) < 0) {
-                // ...
-            }
-        }
-    });
-
-Via entity association arrays behave differently from via backlink
-association arrays in that element membership is controlled directly
-through the array.  In fact, direct manipulation of linking entities
-such as `Tags_by_post` is discouraged, although it is possible.  For
-further details see the section "Working with entities".
-
-
-### Unmanaged Associations
-
-The most general form of associations supported by CDS are unmanaged
-associations that define an arbitrary `JOIN ... ON` condition:
-
-    entity toppost {
-        key pid: Integer not null;
-        ...
-        TopReplies: association to Post on TopReplies.Parent.pid = pid and
-                                           TopReplies.Rating >= 3;
-    };
-
-Unmanaged associations are imported automatically and need not be
-supplied to the import call:
-
-    cds.$importEntity({ $entity: "sap.hana.xs2.cds.examples.data::bboard.topposts" },
-        callback);
-
-Similarly to backlink associations, unmanaged target instances are
-stored in a conceptually read-only array.  Due to the unmanaged nature
-of these associations the contents of the array cannot reflect unsaved
-changes to the relation and must be refreshed manually.
-
-
-Working With Managed Entities
------------------------------
-
-Once we have imported all our entities into our application we can use
-the resulting handles to work with their instances.
-
-For this node-cds provides two different modes to interact with the
-database: managed mode and unmanaged mode.  Managed mode works with
-entity instances, i.e., singleton objects with “personality” that
-correspond one-to-one to database records.  Unmanaged mode, on the
-other hand, works with plain values that are simple, flat JavaScript
-object values.
-
-In this tutorial we will start off with managed mode and cover
-unmanaged mode in the corresponding section below.
-
-To retrieve an existing entity instance in managed mode, we may query
-it by its key:
-
-    tx.$get(Post, { pid: 1 }, function (error, post) {
-        if (error)
-            console.error(error)
-        else
-            notify(post.Author.Email);
-    });
-
-This will retrieve the post with `pid == 1` if it exists, or null
-otherwise.  Note that specifying a non-existing key is not an error
-condition.  The $get() method requires that all key properties be
-supplied.
-
-The more general `$find()` method will search for instances that match
-the given property conditions:
-
-    tx.$find(User, { Name: "Alice" }, function (error, users) {
-        console.log("Number of users called Alice: " + users.length);
-    });
-
-The instance filter expression may be built using the following basic
-expression language that is valid for all JavaScript and SQL types:
-
-    <expr>  ::=  { <cond>, <cond>, … }
-    <cond>  ::=  prop: value | prop: { <op>: value, … }
-    <op>    ::=  $eq | $ne | $lt | $le | $gt | $ge | $like | $unlike | $null
-
-All conditions in an expression are joined by logical-AND.  The
-expression `{ prop: value }` is a shorthand for `{ prop: { $eq: value
-} }`.
-
-The comparison operators `$eq`, `$ne`, `$lt`, `$le`, `$gt`, `$ge`
-apply to all suitable types if the value is supplied in appropriate
-format:
-
-    tx.$find(E, { p: { $lt: 100 } });                // returns all instances where p < 100
-    tx.$find(E, { p: { $ge: 100, $le: 200 } });      // … p between 100 and 200
-    tx.$find(E, { p: "Bob", q: { $ne: "Jones" } });  // … p is Bob but q is not Jones
-
-The `$like` and `$unlike` operators can be used for SQL-like pattern
-matching:
-
-    tx.$find(User, { Name: { $like: "B%" } });     // returns all users whose name starts with B
-    tx.$find(User, { Name: { $unlike: "J.." } });  // returns Bill but not Jim
-
-The `$null` operator checks if a given property is `NULL` in the database:
-
-    tx.$find(Post, { Rating: { $null: true } });    // returns posts with unknown rating
-    tx.$find(Post, { Created: { $null: false } });  // returns posts with known authors
-
-The `$empty` operator checks if an association is missing or empty:
-
-    tx.$find(Post, { Parent: { $empty: true } });     // returns posts without parent
-    tx.$find(Post, { Comments: { $empty: false } });  // returns posts with comments
-
-Expressions are evaluated by the database but also by JavaScript when
-checking the entity cache for matching instances (see section on
-Entity Management below).  This works for simple types such as integers
-and strings, but requires user intervention for complex types, such as
-`DATE`, and for types that have no native JavaScript equivalent, such
-as `DECIMALS`.
-
-Handling those types meaningfully requires a comparison function
-with `$using` that matches the given implementation for non-native types.
-
-The `DATETIME` type, for example, is returned as string.  To retrieve
-instances relative to a certain date the following code could be used:
-
-    var datecomp = function(arg1, arg2) {
-        return (+(new Date(arg1))) - (+(new Date(arg2)))
-    };
-
-    tx.$find(Entity, {
-        datevalue: {
-            $le: "2012-02-29T01:02:03.000Z",
-            $using: datecomp }
-    }, callback);
-
-Note that HANA does not store timezone information, so passing JavaScript
-`Date` objects to the query (including `$query()`) is likely to cause
-issues.
-
-node-cds also supports batch retrieval to reduce the number of
-required callback functions:
-
-    tx.$getAll([
-        { $entity: Post, pid: 1 },
-        { $entity: User, uid: 2 }
-    ], function (error, instances) {
-        console.log("Post " + instances[0] + " was not made by user " + instances[1]);
-    });
-
-If you abhor the mixing of entity type and entity key the $prepare
-auxiliary function also provides the required entity type information
-to `$getAll()`:
-
-    tx.$getAll([
-        Post.$prepare({ pid: 1 }),
-        User.$prepare({ uid: 2 })
-    ], function (error, instances) { … });
-
-Note that there is no `$findAll()` method, as `$find()` already
-returns a list of instances.
-
-Managed queries are inherently limited in their expressiveness, as the
-node-cds runtime needs to check its instance cache against the filter
-condition provided to `$find()`.  Applications requiring advanced
-query capabilities should use unmanaged queries described in the next
-section.  Of course, both managed and unmanaged queries can be used
-side by side.
-
-
-### Updating Entities
-
-Entity instances are regular JavaScript objects and can be used and
-modified as one would expect:
-
-    post.Ranking++;
-    post.Author = users[0];
-    post.Author.Name = "Newt";
-
-All changes are made in memory only.  If we want to persist our
-changes for an instance we invoke the `$save()` method:
-
-    tx.$save(post, function (error, result) {
-        // post and its associated entity instances updated
-        // ...
-    });
-
-Calling `$save()` will flush our in-memory changes of that instance to
-the database, following all associations reachable from the root
-instance.  Note that all instances will be updated, including
-instances not actually modified.
-
-If auto commit is active, then all changes written to the database are
-automatically committed.  Without auto commit, you will have to call
-`tx.$commit()` and/or `tx.$rollback()` yourself in order to persist or
-undo your changes on the database.
-
-The result argument of the callback function receives the updated
-instance as written on the database.  It is identical to the instance
-argument the `$save()` method was called on.
-
-As instance keys must not be changed, all key properties are locked
-and cannot be modified; attempts to do are silently ignored:
-
-    var post = tx.$get(Post, { pid: 1 });
-    post.pid = 69;                       // silently ignored
-    console.log(JSON.stringigy(post));   // still pid == 1
-
-There is an additional batch persist for persisting multiple instances
-in one operation:
-
-    tx.$saveAll([ post1, user2 ]);   // persists post1 and user2 plus their dependencies
-
-Note that modified instances in memory always take precedence over
-their unmodified versions on the database.  For more details and
-further information on some of the resulting subtleties please refer
-to the section on Entity Management and Consistency below.
-
-
-### Creating new Entities
-
-New instances are created simply by saving new values with
-non-existing keys:
-
-    tx.$find(User, { Name: "Alice" }, function (error, users) {
-        var alice = users[0] || null;
-        var post = {
-            $entity: Post,
-            id: 101,
-            Title: "New Post", Text: "Hello BBoard!", Rating: 1, Created: new Date(),
-            Author: alice
-        };
-        tx.$save(post, function (error) { … });
-    });
-
-Since the original post object is not a `Post` instance yet, you’ll need
-to tell node-cds about its entity type by including a `$entity`
-property.  Alternatively, you could use the trivial $prepare helper
-function:
-
-    var post = { pid: … };  // no $entity: … property
-    tx.$save(Post.$prepare(post), function (error) { … });
-
-New and existing instances may be mixed, as in the example
-above.  node-cds tracks if an object represents an new or an existing
-instance and will use an `INSERT` or an `UPDATE` statements accordingly.
-Trying to save an existing instance with a value that was not
-retrieved from the database will yield a duplicate key exception from
-the database.
-
-    var user = { $entity: User, uid: 42, Name: "Newt" };
-    tx.$save(user, function(error) {
-        // user #42 created
-    });
-
-    var update = { $entity: User, uid: 42, Name: "Ann Newt" };  // must use $get instead
-    tx.$save(user, function(error) { … });     // duplicate key error
-
-Key properties for which an HDB sequence or an appropriate `$init`
-function has been supplied may be omitted from the entity call.
-
-
-### Discarding Entities
-
-Retrieved entity instances are stored in the entity manager cache and
-subject to general JavaScript garbage collection.  The `$discard()`
-method permanently deletes an instance from the database:
-
-    tx.$get(Post, { pid: 99 }, function (error, post) {
-        tx.$discard(post, function (error) { … });
-    });
-
-The `$discard()` callback has a single argument for potential errors.
-
-Note that after calling `$discard()` on an instance, the actual
-JavaScript object remains in memory as an unmanaged entity instance,
-i.e., `$find()` will no longer not return references to it.  It is up to
-the application to not use any remaining references to the object that
-may still be stored in some JavaScript variables.
-
-Note that `$discard()` cannot be used to delete instances based on a
-condition.  To delete multiple instances without instantiating them
-before use the `$delete()` method described below.
-
-The `$discardAll()` method for batch discards works analogous to
-the `$saveAll()` method:
-
-    tx.$discardAll([ post1, post2 ], function (error) {
-        // ...
-    });   // discards post1 and post2
-
-For the special use case of deleting instances on the database
-without instantiating them in memory first node-cds provides the
-`$delete()` operation for unmanaged deletes:
-
-    tx.$delete(Post, { Rating: { $lt: 3 } }, function (err) {
-        // deletes all posts where Rating < 3
-    });
-
-An unmanaged delete will delete all matching records on the database,
-ignoring the state of the entity cache.  Likewise, `$delete`s will not
-cascade to target instances.  Thus, the set of affected entity instances
-may differ from that of the sequence
-
-    tx.$findAll(Post, <cond>, function (error, posts) {
-        tx.$discardAll(posts, function (error) { … });
-    });
-
-In fact, `$delete()` is merely syntactic sugar for
-`$query().$matching().$delete()` (see below).  Please use `$delete()` with
-care.
-
-
-### Associations and Custom Types
-
-Both CDS types and CDS associations are supported and will yield
-nested structures in the resulting JavaScript entity.  For example,
-the import of the CDS definitions
-
-    entity user {
-        key uid: Integer not null;
-        Name: String(63) not null;
-    };
-
-    type text {
-        Text: String(255);
-        Lang: String(2);
-    };
-
-    entity post {
-        key pid: Integer not null;
-        Title: String(63) not null;
-        Text: text;
-        Author: association [1] to user;
-        Created: UTCDateTime;
-    };
-
-will yield a Post entity whose instances may look like
-
-    {
-        "pid": 102,
-        "Title": "Re: First Post!",
-        "Text": {
-            "Lang": "EN",
-            "Text": "You beat me to it."
-        },
-        "Author": {
-            "uid": 2,
-            "Name": "Bob"
-        },
-        "Created": "2014-04-25T09:11:30.000Z"
-    }
-
-Overriding properties in such structured CDS entities works analogous
-to the flat case:
-
-    cds.$importEntity({
-        $entity: "sap.hana.xs2.cds.examples.data::bboard.post",
-        $fields: {
-            Text: { Lang: { $init: "EN" } }
-        }
-    }, callback);
-
-
-### Lazy Navigation
-
-By default, all associations are eagerly resolved, i.e., their targets
-are included in the parent instance object.  For heavily connected
-data this may lead to very large data structures in memory.
-
-To control which associations are being followed associations may be
-declared `$lazy`:
-
-    cds.$importEntity({
-        $entity: "sap.hana.xs2.cds.examples.data::bboard.post",
-        $fields: {
-            Parent: { $association: { $lazy: true } }
-        },
-        $name: "LazyPost"
-    }, callback);
-
-A lazy association will delay the retrieval of the associated instance
-or instances until their property values are actually required:
-
-    tx.$get(LazyPost, { pid: 1 }, function (error, post) {
-        // retrieves single Post and Author from database
-        post.Rating++;
-        if (post.Author.Name === "Chris") {
-            // now retrieve parent post from database, if it exists
-            post.Parent.$load(function (error, parent) {
-                if (parent)
-                    parent.Rating++;
-            });
-        }
-    });
-
-The $load() function asynchronously retrieved that target instance or
-instances from the database and passes them to the callback function.
-Additionally, the target value is added to the association parent
-instance.
-
-Note that updates to an entity instance will not update
-associated lazy instances if they haven’t been followed yet!
-
-A lot may happen between the retrieval of some entity instance and the
-navigation to any of its lazy association targets.  It is left to the
-application to ensure the consistency of data.
-
-
-Unmanaged Queries
------------------
-
-In unmanaged mode we work with plain structured values retrieved from
-HANA by arbitrary queries.  Unlike in managed mode, these general
-queries support all of the advanced HANA functionality for retrieving
-data.
-
-A general query related to an entity is built by calling the `$query()`
-method of the entity function:
-
-    var qPosts = Post.$query();
-
-The resulting object returned by `$query()` represents an initial query
-for all of the fields of the underlying entity, but without any
-associated entities.
-
-Queries may be built from existing queries by chaining `$where`,
-`$matching`, `$project`, and further operators. With these operators,
-results can be constructed incrementally without accessing the
-database for intermediate results.  A typical query construction could
-look as follows:
-
-    var qInterestingPosts = Post.$query().$where(/* condition */)
-                                         .$where(/* further condition */)
-                                         .$project(/* projection paths */)
-                                         .$limit(5);
-
-The final query is executed by invoking its `$execute()` method, and is
-the only asynchronous operation in unmanaged mode:
-
-    qInterestingPosts.$execute(tx, function (error, result) { …  });
-
-It is important to note again that the result of the query is a plain
-value, not an entity instance managed by node-cds.
-
-
-### Projections
-
-The `$project()` method specifies the fields the query should return:
-
-    var qTitleAndComments = Post.$query().$project({
-        Title: true,
-        Comments: {
-            Author: {
-                Name: "CommentAuthorName"
-            },
-            Text: {
-                Text: true
-            }
-        }
-    });
-    qTitleAndComments.$execute(tx, function (error, result) { … });
-
-The list of projected fields is a JavaScript object, where desired
-fields are marked by either true or a String literal such as
-`CommentAuthorName` denoting an alias name.  Above query may thus
-yield the result:
-
-    {
-        Title: "First Post!",
-        Comments: {
-            Author: {
-                CommentAuthorName: "Bob"
-            },
-            Text: {
-                Text: "Can we prevent this by software?"
-            }
-        }
-    }
-
-Note that the actual database query automatically `JOIN`s all required
-tables based on the associations involved.  For above example, the
-generated SQL looks like (omitting the package prefix from the table
-name for readability):
-
-    SELECT          "t0"."Title" AS "t0.Title",
-                    "t0.Comments.Author"."Name" AS "t0.Comments.Author.Name",
-                    "t0.Comments"."Text.Text" AS "t0.Comments.Text,Text"
-    FROM            "bboard.post" "t0"
-    LEFT OUTER JOIN "bboard.comment" "t0.Comments" ON "t0"."pid"="t0.Comments"."Post.pid"
-    LEFT OUTER JOIN "bboard.user" "t0.Comments.Author" ON
-                     "t0.Comments"."Author.uid"="t0.Comments.Author"."uid"
-    LEFT OUTER JOIN "bboard.user" "t0.Author" ON "t0"."Author.uid"="t0.Author"."uid"
-
-
-### Selections using $where
-
-The `$where()` method filters the query result by some conditional
-expression.  For example, to select all posts which were commented by
-a person with the same name as the post author, we write:
-
-    var qStrangePosts = qTitleAndComments.$where(
-        Post.Comments.Author.Name.$eq(Post.Author.Name));
-
-References to fields and associations such as `Comments` are available
-as properties of the entity object, e.g., `Post.Comments`.  As in the
-case with projections, node-cds generates all required `JOIN`s for
-associations referenced by the conditions automatically, even if they
-are not part of the current projection.
-
-To build complex query expressions, the node-cds expression language
-provides a number of predefined operators that work on all data types:
-
- * `$eq`, `$ne` for SQL equality and inequality, resp.
- * `$gt`, `$lt`, `$gt`, `$le` for the SQL operators `>`, `<`, `<=`, `>=`, resp.
- * `$null` for the SQL operator `IS NULL`
- * `$like`, $unlike for the SQL operators `LIKE` and `NOT LIKE`
- * `$and`, $or for SQL junctors `AND` and `OR`
-
-A more complex selection statement could thus look like
-
-    Post.$query().$where(
-        Post.Tags.Name.$eq("+1").$and(Post.Rating.$lt(2).$or(Post.Rating.$gt(5))))
-
-yielding the following SQL query:
-
-    SELECT          "t0"."Created" AS "t0.Created",
-                    "t0"."Rating" AS "t0.Rating",
-                    "t0"."Parent.pid" AS "t0.Parent,pid",
-                    "t0"."Author.uid" AS "t0.Author,uid",
-                    "t0"."Text.Lang" AS "t0.Text,Lang",
-                    "t0"."Text.Text" AS "t0.Text,Text",
-                    "t0"."Title" AS "t0.Title",
-                    "t0"."pid" AS "t0.pid"
-    FROM            "bboard.post" "t0"
-    LEFT OUTER JOIN "bboard.tags_by_post" "t0.Tags$viaEntity"
-                 ON "t0.Tags$viaEntity"."Post.pid" = "t0"."pid"
-    LEFT OUTER JOIN "bboard.tag" "t0.Tags" ON "t0.Tags$viaEntity"."Tag.tid" = "t0.Tags"."tid"
-    WHERE           ("t0.Tags"."Name" = '+1') AND (("t0"."Rating" < 2) OR ("t0"."Rating" > 5))
-
-For other SQL operators not part of the node-cds expression language
-you may use generic operators such as $prefixOp
-
-    qStrangePosts = qStrangePosts.$where(Post.Rating.$prefixOp("SQRT").$gt(1));
-
-
-### Selections using $matching
-
-The `$matching()` method provides an alternative way to specify
-conditional expressions using the JSON-like syntax of the `$find()`
-method (see above).
-
-    var q1 = Posts.$query().$matching(
-        { Rating: { $gt: 2 });
-    var q2 = Posts.$query().$matching(
-        { Rating: { $ge: 1, $lt: 5 }, Parent: { $null: false } });
-
-The main difference between $matching() and $findAll() is that the
-former returns an unmanaged, plain value and ignores all unpersisted
-changes to any entity instances.
-
-We can think of the JSON-like conditional expression as a “template”
-that the result should match.  Compared to the node-cds expression
-language used by `$where()`, the matching syntax is more concise, but
-also less expressive.  Also note that the expression language does not
-apply to managed queries, e.g., to `$find()`.
-
-
-### Calculated Fields and Aggregations
-
-Arbitrary calculated values may be added to the result set by using
-the $addFields() method.  As an example, we return the square root of
-the post’s rating as an additional field `MyRating`:
-
-    var qRootedRatings = Posts.$query().$addFields(
-        { MyRating: Post.Rating.$prefixOp("SQRT") });
-
-Aggregations are a special case of calculated fields that combine the
-$addFields operator with an additional $aggregate() method.  For
-example, to retrieve the average rating per user, we would write:
-
-    var qUserRating = Post.$query()
-        .$aggregate({ Author: { uid: true, Name: true } })
-        .$addFields({ AverageRating: Post.Rating.$avg() });
-
-In SQL terms, the `$aggregate` operator creates a `GROUP BY` expression
-for the specified paths and automatically projects the result on
-those.  For an even more restrictive projection you may replace the
-true by a false in the `$aggregate` call:
-
-    var qUserRating = Post.$query()
-        .$aggregate({ Author: { uid: false, Name: true } })
-        .$addFields({ AverageRating: Post.Rating.$avg() });
-
-This will remove the users’ IDs from the in the result set.
-
-Currently, node-cds supports aggregation operators `$avg`, `$sum`, `$count`,
-`$max`, and `$min`.
-
-
-### Ordering, Size Limits, and Duplicate Elimination
-
-The order of the result set is defined by the `$order()` method.  Each
-order criteria contains a property by with an expression according
-which to order.  Optionally each criterion can contain a flag desc to
-require a descending order and a nullsLast flag.  The following
-example uses two criteria to first order descending by rating and then
-order ascending by author name:
-
-    var qOrderedPosts = Post.$query()
-                            .$order({ $by: Post.Rating, $desc: true },
-                                    { $by: Post.Author.Name });
-
-The $distinct operator removes duplicates from the result set.  To get
-the set of all ratings we can write:
-
-    var qAllRatings = Post.$query().$project({ Rating: true }).$distinct();
-
-The number of records returned may be specified by using the $limit
-operator, which introduces the `LIMIT` and `OFFSET` keywords into the SQL
-query:
-
-    // skip posts 1-3, return posts 4-8
-    var qNextFivePosts = qStrangePosts.$limit(5, 3);
-
-
-Entity Manegement and Consistency
----------------------------------
-
-Entities retrieved from the database are stored in the entity manager
-cache.  Any subsequent query for that entity will be served from the
-cache instead of the database.
-
-It is important to realize that if we modify an entity instance in
-memory, then all node-cds queries for that entity instance through
-`$get()` and `$find()` will return the modified, in-memory version of the
-entity, even if it hasn’t been persisted to the database yet.
-
-    // assume post #1 and post #2 share same author alice@sap.com
-    var post1 = tx.$get(Post, { pid: 1 });
-    post1.Author.Email = "alice@saphana.com";
-    var post2 = tx.$get(Post, { pid: 2 });
-
-In above example, the value of `post2.Author.Email` equals the new value
-`alice@saphana.com`, even though post1 has not been `$save()`ed yet.
-
-An unmanaged query, on the other hand, will ignore unpersisted changes
-to our data and return the database view instead, so continuing the
-example from above,
-
-    var post2_value = Post.$query().$matching({ pid: 2 }).$execute();
-
-will yield `post2_value.Author.Email === "alice@hana.com"`.
-
-You may use a transaction rollback to revert to the last committed
-state of your data, irrespective of whether data was persisted or not
-(see below).
-
-
-### Associations
-
-There are some additional subtleties about the consistency of
-CDS-based associations that impose certain restrictions on using
-backlinks and entity links in managed mode.
-
-For backlink associations, the associated instances are stored in an
-array in the parent instance:
-
-    tx.$get(Post, { pid: 1 }, function (error, post) {
-        post.Comments.forEach(function (comment) { … });
-    });
-
-For any given target instance `t` with backlink `b` there are two ways to
-express that `t` is a target of backlink association `a` of parent `p`:
-
- 1. `t` is a member of `p.a`
- 2. `t.b` equals `p`
-
-node-cds uses (2) exclusively to express the relationship between p
-and t.  Supporting association updates through the association array,
-i.e., option (1), would impose an unduly amount of runtime overhead
-on the application and may lead to conflicting membership states.
-
-For convenience, however, the `$save` function will set the backlink
-of newly created targets currently stored in `p.a` to `p`.  Thus,
-`p.a` may be used to add newly created instances, but it cannot be
-used to add or remove already existing instances.
-
-As a consequence of the above, updating an instance with backlinks
-may lead to situations where `p.a` contains elements that are not part of
-the association or where `p.a` misses elements that are part of the
-association.  To re-sync the association array `p.a` all backlink
-associations have a `$reload()` function that will update the
-current array:
-
-    tx.$get(Post, { pid: 1 }, function (error, post) {
-        var firstComment = post.Comments[0];
-        firstComment.Parent = 0;  // remove first comment
-        post.Comments.$reload(function (error, comments) {
-            // comments == post.Comments
-            // firstComment not in comments
-        });
-    });
-
-Saving an instance with backlinks will update all array members
-individually, but this will not change their backlinks.  Thus, simply
-adding and/or removing members from the association array and
-`$save()`ing the parent will not change the relationship between parent
-and target instances.
-
-    tx.$get(Post, { pid: 1 }, function (error, post) {
-        post.Comments.splice(1);  // incorrect: won’t remove comment
-        tx.$save(post, function (error, updatedPost) {
-            // $reload restores first comment back to post.Comments
-        });
-    });
-
-When saving an instance with backlink associations, the `$reload()`
-function will be invoked automatically.
-
-For many-to-many associations, on the other hand, the association
-array is the primary means to control the membership of individual
-target instances:
-
-    tx.$find(Tag, { Text: "cool" }, function (error, tag) {   // find certain tag
-        tx.$get(Post, { pid: 1 }, function (error, post) {    // get particular post
-            post.Tags.push(tag);                              // attach tag to post
-            tx.$save(post, callback);                         // update database
-        });
-    });
-
-This example attaches the tag “cool” to the first post without
-modifying any already existing tags.
-
-Note that the direct manipulation of linking entities is discouraged,
-as this may lead to inconsistencies between the views on the
-association arrays of the entities with many-to-many associations and
-their link tables:
-
-    post.Tags = [ tag1 ];                                     // post has one tag
-    tx.$save({ $entity: TagsByPost,
-               lid: 69, Tag: tag2, Post: post }, callback);   // don’t do this!
-
-Unmanaged associations are handled very similar to backlink
-associations in that the target association status cannot be
-controlled by array membership:
-
-    tx.$get(PostWithTopReplies, { pid: 101 }, function (error, thread) { … });
-
-But unlike managed associations such as those defined by
-backlinks, an unmanaged association is static and ignores both updates
-to the database and to the cache unless reloaded explicitly.
-
-    var reply = thread[0];
-    reply.Rating = 0;
-    tx.$save(reply);
-
-    // reply still contained in thread.TopReplies even
-    // though Rating >= 3 no longer holds
-    var i1 = thread.TopReplies.indexOf(reply);  // === 0
-
-    // explicit reload from database
-    thread.TopReplies.$reload(function (error, instance) {
-        // now reply is no longer contained in thread.TopReplies
-        var i2 = thread.TopReplies.indexOf(reply);  // === -1
-    });
-
-Saving the parent of an unmanaged association will also save all
-elements stored in the association array.  Finally, before invoking
-the callback function, the `$reload` function of the parent is
-called.
-
-Discarding an instance will delete the root instance, but not
-associated entities by default, even for one-to-one associations.  If
-you do want to delete associated entities as well, you can add a
-$cascadeDiscard property to your entity import statement:
-
-    cds.$importEntity({
-        $entity: "…",
-        $fields: {
-            MyAssoc: {
-                $association: {
-                    …
-                    $cascadeDiscard: true
-                }
-            }
-        }
-    }, callback);
-
-node-cds supports explicit cascading for deletion only at the moment.
-All other operations such as creation, tracking, and updates are
-always cascaded to all associated entities automatically.
-
-Note that node-cds currently doesn’t support orphan removal.  It is
-left to the application to maintain integrity of associations and
-references.  You can let HANA help you there by defining key
-constraints for your associations.
-
-
-Transactions
-------------
-
-All node-cds instance operations are tied to transactions.  To open a
-new transaction, call the corresponding node-cds function:
-
-    cds.$getTransaction(function (error, tx) { … });
-
-By default, all `$save()` and `$discard()` operations will auto
-commit upon completion.  To change this behavior you can set auto
-committing explicitly:
-
-    tx.$setAutoCommit(<boolean>);
-
-When not in auto commit mode, transactions can be explicitly committed
-or rolled back:
-
-    tx.$commit(callback);
-    tx.$rollback(callback);
-
-If you call `$rollback`, the instance cache for that transaction will be
-reset.  You need to make sure that you do not use any references pointing to
-obsolete instances predating the cache reset.
-
-Note that auto commit refers to node-cds operations, not database operations.
-In other words, if you `$save` an entity with a single target entity the two
-low-level `INSERT` statements are grouped into a single node-cds transaction
-that will `commit` or `rollback` together.
-
-When done, close and release the transaction by calling its `$close`
-method:
-
-    tx.$close();
-
-If your application is passed an existing database connection you can
-pass the connection to $getTransaction():
-
-    cds.$getTransaction(<dbconn>, function (error, tx) { … });
-
-This will reuse the existing connection instead of requesting a new
-connection from the pool.  If `dbconn` is in state disconnected node-cds
-will try to open the connection.  Note, however, that multiple calls
-using the same connection will also return the same transaction!
-
-Calling `$close()` on a transaction tied to an existing database
-connection will not have any effects.
-
-
-Support for geospatial HANA data types
---------------------------------------
-
-node-cds also provides handling of entities with spatial attributes:
-
-    entity attraction {
-        ...
-        position: hana.ST_GEOMETRY(4326);
-    };
-    
-For processing such entities node-cds uses an extension 'cds-queries-geo',
-which can be optinally be required and allows to seamlessly create/insert
-spatial objects and perform spatial functions with/on them in combination
-with normal node-cds query API. For example a query like
-
-    attractions.$query().$where( attractions.position.$distance( geo.stPoint([49.008981, 8.403897])).$le(1500))
-
-would result in:
-
-    [
-        {   "id":5 ,
-            "name":"SAP Karlsruhe" ,
-            "info":"SAP location Karlsruhe." ,
-            "year":1999 ,
-            "position": {"type":"Point","coordinates":[49.013143,8.424231]}
-        },
-        ...
-    ]
-
-The extension allows for converting the resulting spatial objects to
-[GeoJSON](http://geojson.org/) objects so that results can seamlessly
-be processed in JavaScript.
-
-
-XSJS Compatibility Mode
------------------------
-
-For code in the xsjs compatibility mode, an extension
-compatible with the XS Basic library XSDS can be used.
-
-Note, that it is intended to be used *only within the XSJS
-Compatibility Layer*.
-
-To initialize it from an xsjs file, it needs to be invoked as follows:
-
-    var conn = $.db.getConnection();
-    var cds = $.require("cds").xsjs(conn);
-
-Note, that the connection to the database is managed by the connection
-provided in the argument to the xsjs call. The connection object can
-be modified through the `cds.Transaction` object. E.g. you can close
-the connection by `cds.Transaction.$close();`.
-
-Like in plain node-cds, entities can then be imported following the
-syntax and the synchronous style of XSDS:
-
-    var Post = cds.$importEntity("sap.hana.xs2.cds.examples.data", "bboard.post");
-
-Note, that namespace and entity name are submitted as separate
-arguments. Moreover only one entity at a time is imported. In order to
-enhance the entity, a third argument can be passed, as demonstrated in
-the following example:
-
-    var Post = cds.$importEntity("sap.hana.xs2.cds.examples.data", "bboard.post", 
-        { Comments: 
-            { $association: 
-                { $entity:
-                    "sap.hana.xs2.cds.examples.data::bboard.user", 
-                    $viaBacklink: "Post" 
-                } 
-            } 
-        });
-
-Next, entities can be retrieved in managed or unmanaged mode, using
-the operations already known from plain node-cds, but in the
-synchronous approach of XSJS.
-
-For example, the $get method of an entity will retrieve an entity
-instance by its key:
-
-    var post = Post.$get({ pid: 101 });
-
-Creating a new instance is just as simple as invoking the 'new'
-operator and persisting the resulting object:
-
-    // create new post
-    var newpost = new Post({ pid: 102,
-                             Title: "New Post",
-                             Text: { Text: "Hello BBoard!", Text: "EN" },
-                             Author: post.Author,
-                             Rating: 1,
-                             Created: new Date() });
-    newpost.$save();
-
-For complex ad-hoc queries the same query builder as in plain node-cds
-can be used.  The $query method of the entity constructor returns a
-query object for the step-wise building of complex queries:
-
-    var results = Post.$query().$project({
-        Author: {
-            Name: true,
-            Email: true
-        },
-        Title: true
-    }).$execute();