feat: CXL documentation
#2260
feat: CXL documentation
#2260
Conversation
| No matter where `CXL` is used, it always manifests in queries. | ||
| For example, [a calculated element](./cdl/#calculated-elements) defined in an entity will be resolved | ||
| to the respective calculation in the generated query when the entity is queried. |
There was a problem hiding this comment.
You can use expressions in various other places
- translated to EDMX-expressions
- to define projections between types
- projections can be resolved at runtime (runtime views)
- expressions can be evaluated in memory
There was a problem hiding this comment.
Query does not mean that it is a database query. There can be multiple vehicles for an expression. Conceptually though, it can be understood as part of a query - whether it is either sent to the database, converted to edmx (and then sent to the backend again), or evaluated in memory.
This is an important point though. Expressions are not only meant for database queries.
Keeping this open -> happy for suggestions on how to formulate this.
| ```cds | ||
| select from Books { | ||
| 42 as answer, // literal | ||
| title, // ref |
There was a problem hiding this comment.
| title, // ref | |
| title, // reference ("ref") |
| ( | ||
| (CAST(STRFTIME('%Y', author.dateOfDeath) AS INTEGER) - CAST(STRFTIME('%Y', author.dateOfBirth) AS INTEGER)) * 12 | ||
| ) + ( | ||
| CAST(STRFTIME('%m', author.dateOfDeath) AS INTEGER) - CAST(STRFTIME('%m', author.dateOfBirth) AS INTEGER) | ||
| ) + ( | ||
| CASE | ||
| WHEN (CAST(STRFTIME('%Y%m', author.dateOfDeath) AS INTEGER) < CAST(STRFTIME('%Y%m', author.dateOfBirth) AS INTEGER)) THEN | ||
| (CAST(STRFTIME('%d%H%M%S%f0000', author.dateOfDeath) AS INTEGER) > CAST(STRFTIME('%d%H%M%S%f0000', author.dateOfBirth) AS INTEGER)) | ||
| ELSE | ||
| (CAST(STRFTIME('%d%H%M%S%f0000', author.dateOfDeath) AS INTEGER) < CAST(STRFTIME('%d%H%M%S%f0000', author.dateOfBirth) AS INTEGER)) * -1 | ||
| END | ||
| ) | ||
| ) / 12 | ||
| ) < ? |
There was a problem hiding this comment.
I think this is way to complicated to illustrate path expressions. Why not use something like
address[kind = 'home'].street
this would result in SQL, which readers can actually understand
|
|
||
|
|
||
| ### use an infix-filter to make an association more specific | ||
|
|
There was a problem hiding this comment.
make an association more specific
i.e. to navigate to a subset of the associated entities
| E.g. in the expression `price * quantity`, the `*` operator is a binary operator | ||
| that operates on the two operands `price` and `quantity`. |
There was a problem hiding this comment.
| E.g. in the expression `price * quantity`, the `*` operator is a binary operator | |
| that operates on the two operands `price` and `quantity`. | |
| E.g. in the expression `price * quantity`, the `*` operator is a binary operator | |
| that multiplies the two factors `price` and `quantity`. |
| <div v-html="literalValue"></div> | ||
| </div> | ||
|
|
||
| TODO |
There was a problem hiding this comment.
don't forget to specify the literal formats for
- Date
- Time
- Timestamp
- Binary
| ### aggregate function with [ordering term](#ordering-term) | ||
|
|
||
| ::: code-group | ||
| ```js [CAP Style] | ||
| > await cds.ql` | ||
| SELECT from Authors { | ||
| name, | ||
| string_agg(books.title, ', ' ORDER BY books.title DESC) as titles | ||
| } | ||
| GROUP BY books.author.ID` | ||
|
|
||
| [ | ||
| { name: 'Emily Brontë', titles: 'Wuthering Heights' }, | ||
| { name: 'Charlotte Brontë', titles: 'Jane Eyre' }, | ||
| { name: 'Edgar Allen Poe', titles: 'The Raven, Eleonora' }, | ||
| { name: 'Richard Carpenter', titles: 'Catweazle' } | ||
| ] | ||
| ``` | ||
|
|
||
| ```js [SQL Style] | ||
| await cds.ql` | ||
| SELECT | ||
| name, | ||
| string_agg(books.title, ', ' ORDER BY books.title DESC) as titles | ||
| from ${Authors} as A | ||
| left join ${Books} as books on books.author_ID = A.ID | ||
| GROUP BY books.author_ID | ||
| ``` | ||
|
|
||
| ```sql [SQL output] | ||
| SELECT | ||
| "$A".name, | ||
| string_agg(books.title, ? ORDER BY books.title DESC) AS titles | ||
| FROM sap_capire_bookshop_Authors AS "$A" | ||
| LEFT JOIN sap_capire_bookshop_Books AS books | ||
| ON books.author_ID = "$A".ID | ||
| GROUP BY books.author_ID; | ||
| ``` | ||
| ::: | ||
|
|
||
| ## ordering term <Badge class="badge-inline" type="tip" text="💡 clickable diagram" /> { #ordering-term } | ||
|
|
||
| <div class="diagram" v-html="orderingTerm"></div> | ||
|
|
||
| TODO: some text | ||
|
|
||
| ## over-clause <Badge class="badge-inline" type="tip" text="💡 clickable diagram" /> { #over-clause } | ||
|
|
||
| <div class="diagram" v-html="overClause"></div> | ||
|
|
||
| ## type-ref <Badge class="badge-inline" type="tip" text="💡 clickable diagram" /> { #type-ref } | ||
|
|
||
| TODO | ||
|
|
There was a problem hiding this comment.
I think this is too specialized for the CXL docu
|
There's one example where it's not the text but the box that is clickable. Is that on purpose? |
TBD