feat: `CXL` documentation #2260

patricebender · 2025-12-09T15:04:17Z

TBD

cds/cxl.md

agoerler · 2025-12-10T07:42:46Z

cds/cxl.md

+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.


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

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/cxl.md

renejeglinsky · 2025-12-11T13:26:38Z

There's one example where it's not the text but the box that is clickable. Is that on purpose?

cds/cxl.md

assets/cxl/sets.drawio.svg

swaldmann · 2025-12-19T11:22:25Z

assets/cxl/sets-leftjoin.drawio.svg

Whenever I see Venn diagrams explaining JOINs I'm reminded of this article/rant, where the author makes the case that set theory is a false analogy as JOINs are rather a cross product filtered by a predicate with an optional UNION:
https://blog.jooq.org/say-no-to-venn-diagrams-when-explaining-joins/

Food for thought 🤔 The JOIN diagrams shown there could also come in helpful in some Capire guides.

Thanks for the link! This topic also came up when writing the theory section, because the inner join is indeed $\{ (a, b) \in \text{Authors} \times \text{Books} | a.\text{id} = b.\text{author\_id} \}$ -> a cross product with a filter.

Intersections (and thus Venn diagrams) are possible though if the sets are made union-compatible:

The key point of the blog entry in regards to why this can not be shown as a Venn diagram is that the sets (Authors and Books) are of a different type and are not union-compatible. So $\text{Authors} \cap \text{Books}$ is indeed not correct.
Rather, we implicitely look at the cross product
$$X = \{ \space (a_1, \dots, a_n, b_1, \dots, b_m) \in \{ \text{Authors} \cup \{(\omega, \dots, \omega)\} \} \times \{ \text{Books} \cup \{(\omega, \dots, \omega)\} \} - \{(\omega, \dots, \omega)\} \space \}$$
with each circle representing:
$$\text{Authors}' = \{ (a_1, \dots, a_n, b_1, \dots, b_m) \in X | a_\text{id} \ne \omega \}$$
$$\text{Books}' = \{ (a_1, \dots, a_n, b_1, \dots, b_m) \in X | b_\text{id} \ne \omega \}$$

Getting the actual authors back is now only an exercise of projection:
$$\{ (a_1, \dots, a_n) \} = \{ \pi_{a_1, \dots, a_n}(\text{Authors}') \} = \text{Authors}$$
-> Select distinct a.* from Authors a full join Books b on 1 = 1

Since the sets are independent of the projection (what we select), any join operations simply filter on the cross product, which imho can be nicely displayed using venn diagrams. So I do disagree with the author of the blog even though they have a point. I also think the join diagrams could come in helpful.

One of the key points in cql / cxl is that path navigation allows us to work on sets and only consider the select list (projection in relational algebra) at the end. When actually writing relational algebra, the tuple needs to be defined explicitely. CQL and SQL also handle null values nicely. When writing relational algebra, null values need to be explicitely included.

explaining JOINs

But we don't want to explain joins! We have sets of instances of some entity type that are associated with some other instances of in a different set. Sometimes our SQL backends use a JOIN in SQL to compute a cross product of these sets. But this is an implementation detail of the SQL backends.

Co-authored-by: Steffen Waldmann <[email protected]>

agoerler · 2025-12-19T15:11:15Z

cds/cxl.md

-???
+In this example, we select all books and order them by the date of birth of their authors.
+The table alias for the `author` association is used in the order by clause of the SQL query.
+


please add a hint that you should any path expression used in order by should also be on the select list

cds/cxl.md

agoerler · 2025-12-19T15:13:56Z

cds/cxl.md

+
+
+
+Every entity defines a set of all possible instances:


Suggested change

Every entity defines a set of all possible instances:

Every entity defines a set of all instances:

agoerler · 2025-12-19T15:14:22Z

cds/cxl.md

+Every entity defines a set of all possible instances:
+$${ b \in \text{Books} }$$
+
+A simple select query on Books returns the complete set → all books.


Suggested change

A simple select query on Books returns the complete set → all books.

A simple select from Books returns the complete set → all books.

agoerler · 2025-12-23T17:57:47Z

cds/cxl.md

+  group by genre
+  order by genre asc`


Suggested change

group by genre

order by genre asc`

group by genre.name

order by genre.name`

agoerler · 2025-12-23T18:00:15Z

cds/cxl.md

+Using the infix notation to specify the query modifiers is just
+syntactic sugar:


No. Using the infix notation to specify the query modifiers makes it really hard to understand (and explain) what the infix does. I think the plain infix filter is easy to understand though.

agoerler · 2025-12-23T18:00:28Z

cds/cxl.md

+syntactic sugar:
+
+```js
+await cds.ql`


this example is easy to understand

agoerler · 2025-12-23T18:02:19Z

cds/cxl.md

-  }
-  GROUP BY books.author.ID`

+## ordering term <Badge class="badge-inline" type="tip" text="💡 clickable diagram" /> { #ordering-term }


This is related to the query language and not to the expression language, I think. Move to CQL chapter?

agoerler · 2025-12-23T18:03:51Z

cds/cxl.md

+
+$$\text{books} = \{ (a,b) \in \text{Books} \times \text{Authors} \mid b.\text{author\_id} = a.\text{id} \}$$
+
+We can select this set using the path expression `Authors:books` in the [from clause](#in-from-clause).


why not Authors.books ?

agoerler · 2026-01-06T13:13:08Z

cds/cql-draft.md

+```
+:::
+
+TODO explanation


The path expression Books:author denotes the set of all author entities that can be reached by following the association author from any entity Books. I.e. the set of authors that have written a book.

agoerler · 2026-01-06T13:13:38Z

cds/cql-draft.md

+
+### in the where clause {#in-where-clause}
+
+A path expression can also be used as part of the where clause to filter based on elements of related entities:


Suggested change

A path expression can also be used as part of the where clause to filter based on elements of related entities:

A single-valued path expression can also be used as part of the where clause to filter based on elements of related entities:

agoerler · 2026-01-06T13:14:26Z

cds/cql-draft.md

+:::
+
+In this example, we select all books that belong to the `Fantasy` genre.
+The table alias for the `genre` association is used in the where clause of the SQL query.


Suggested change

The table alias for the `genre` association is used in the where clause of the SQL query.

This implementation detail does not apply to CAP Java. In CAP Java, we use table aliases T0, T1, ..., which is also an implementation detail not worth to mention.

agoerler · 2026-01-06T13:18:25Z

cds/cql-draft.md

+:::
+
+In this example, we select all books and order them by the date of birth of their authors.
+The table alias for the `author` association is used in the order by clause of the SQL query.


Suggested change

The table alias for the `author` association is used in the order by clause of the SQL query.

see above

agoerler · 2026-01-06T13:19:35Z

cds/cql-draft.md

+```js [CQL] {3}
+> await cds.ql`
+    SELECT from Authors { name,
+      books[ price < 19.99 ] as cheapBooks {


Suggested change

books[ price < 19.99 ] as cheapBooks {

books[ price < 20.00 ] as cheapBooks {

agoerler · 2026-01-06T13:28:39Z

cds/cql-draft.md

+
+TODO: This is database specific
+
+In this example, the runtime makes use of JSON functions to aggregate the related `books` into a JSON array.


Suggested change

In this example, the runtime makes use of JSON functions to aggregate the related `books` into a JSON array.

In this example, the CAP Node.js runtime makes use of JSON functions to aggregate the related `books` into a JSON array.

agoerler · 2026-01-06T13:45:45Z

cds/cql-draft.md

+In this example, the runtime makes use of JSON functions to aggregate the related `books` into a JSON array.
+This is because SQL databases do not have a native concept of nested result sets.
+
+> TODO: Link to guide about JSON functions, What about java?


What about java?

How CAP Java executes this depends the expand optimization mode used. We always do multiple queries:

join (default):

SELECT T0.name FROM Authors SELECT T1.title, T1.price FROM Authors T0 JOIN Books T1 ON T1.author_id = T0.ID AND T1.price < 20.00

parent-keys:

SELECT T0.ID, T0.name FROM Authors T0 -- yields <set of author IDs> SELECT T0.tile, T0.price FROM Books T0 WHERE T0.author_id IN (<set of author IDs>) AND T0.price < 20.00

load-single (legacy):

SELECT T0.ID, T0.name FROM Authors T0 -- yields <set of author IDs> for(id in <set of author IDs>): SELECT T0.tile, T0.price FROM Books T0 WHERE T0.author_id = id AND T0.price < 20.00

subquery

SELECT T0.ID, T0.name FROM Authors T0 -- yields <set of author IDs> SELECT T0.tile, T0.price FROM BOOKS T0 WHERE T0.ID IN (SELECT T1.ID FROM Authors T0 JOIN Books T1 ON T1.author_id = T0.ID AND T1.price < 20.00)

(Not 100% sure about subquery)

Thanks for listing these. Imho we should include the explanation around how expands are executed in a database specific section. While a developer should not need to interact with them or at most simply choose an optimization mode, it does help in the understanding of what is actually happening -> demystifying.

agoerler · 2026-01-06T13:57:24Z

cds/cxl.md

-### in the from clause {#in-from-clause}
-
-A path expression can also be used in the `from` clause of a query to navigate to a related entity:
+When navigating along a to-many association to a leaf element, the result is flattened:


is flattened

No. You create a cross product of the associated entities. This is nothing we should promote as it might have slipped in by accident. Also it might work only in the translation to SQL. The example below will result in a left outer join of books and authors. Also authors which have not written a book will be included.

Please either expand books from authors or start the selection from books:

Select from Authors { books { title } as title, name as author }

(gives a nested result)

or

Select from Books { title, author.name as author }

(will not include authors that have written no books)

The important point here is: the expression language CXL does not make any assumption that it is translated to SQL or how it's converted to SQL.

In your example below, the path expression books.title is just the set of titles of the books which are associated to a particular author via the Authors entity's books association. Hence the query

SELECT from Authors { books.title as title, name as author }

should return something like

[ { title: ['Wuthering Heights'], author: 'Emily Brontë' }, { title: ['Jane Eyre'], author: 'Charlotte Brontë' }, { title: ['Eleonora', 'The Raven'], author: 'Edgar Allen Poe' }, { title: ['Catweazle'], author: 'Richard Carpenter' } ]

which it doesn't. Instead it returns the "flattened" result which you mention. I think it does so by accident!

To make things worse think about:

SELECT FROM Authors { name, books.title book, addresses.{city, street} as address, phonenumbers.{country_code, area_code, extension} }

This would result in an unwanted, unexpected 4-way left outer join.

I think there is no valid use case for path expression involving to-many associations besides in expands and exists!

This was an ask by Daniel -> we should discuss this in our next review meeting

agoerler · 2026-01-06T14:14:49Z

cds/cxl.md

-### in the where clause {#in-where-clause}

-A path expression can also be used as part of the where clause to filter based on elements of related entities:
+::: info 💡 Associations are **forward-declared joins**


I still think we should sunset the phrase "forward-declared joins"

@danjoa the forward declaration terminology according to Wikipedia does not quite match the behavior of associations.

Let's discuss this in our next review meeting.
Earlier discussion: #2260 (comment)

agoerler · 2026-01-06T14:15:24Z

cds/cxl.md

-> await cds.ql`SELECT from Books { title } where genre.name = 'Fantasy'` // [!code focus]
-[ { title: 'Catweazle' } ]
-```
+The join condition is defined **ahead of time** as part of the association.


Suggested change

The join condition is defined **ahead of time** as part of the association.

The foreign-key relationship is defined **ahead of time** as part of the association.

I do think join condition is accurate as it does not need to be a foreign key relationship, although it pretty much always includes one. A join is the SQL terminology and well understood, even if cxl can also manifest in other ways.

Akatuoro · 2026-01-08T18:01:59Z

@danjoa the PR is now ready for an initial version.

CQL specific sections are moved out to a separate branch for a follow-up PR. We also moved the scientific background section as it still needs some work to be useful.

@agoerler I've gone through your feedback for the parts that are in scope for the merge, will go through the rest later.

agoerler

I still think this documentation is way to much focused on explaining how CQL is converted to SQL. Instead we should provide a documentation that explains the fundamentals of the expression language:

Values

literals
refs
- paths
  - filtered paths -> predicates
parameters
value functions
value expressions

Predicates

comparison predicates
connectives (AND, OR)
negation
Boolean functions

I would not know why you need SQL to explain any of this.

agoerler · 2026-01-09T12:31:25Z

cds/cxl.md

+
+```cds
+annotate AdminService.Authors:dateOfDeath with @assert: (case
+  when dateOfDeath > $now then 'Cannot be in the future'


dateOfDeath > $now

$now is a timestamp whereas dateOfDeath is a (local) date hence the types are incompatible.

We should introduce $today, which would be quite handy.

cds/cxl.md

agoerler · 2026-01-09T13:15:25Z

cds/cxl.md

 :::code-group
 ```js [CQL]
-> await cds.ql`SELECT from Books:author { name }` // [!code focus]
+> await cds.ql `SELECT from Authors { books.title as title, name as author }` // [!code focus]


please void the navigation over the to-many association books as it introduces the before mentioned join

As mentioned, it was requested by Daniel -> need to discuss this together. Until then, I'm keeping it in the PR

cds/cxl.md

agoerler · 2026-01-09T13:54:38Z

cds/cxl.md



-::: info 💡 A binary operator is an operator that operates on two operands.
+::: info A binary operator is an operator that operates on two operands.


Here would be the place to document which operators there are. That = does a three-valued comparison whereas == does a two-valued comparison. What's the precedence of operators. That we support || for string concatenation. This is all not documented so far. But it's very fundamental. We can't explain infix filters without explaining filter predicates.

Yes, we still need to document the operators (and also the literals) more.

Here's also some explanation for operators, but interestingly only for the node impl variant:
https://cap.cloud.sap/docs/guides/databases?impl-variant=node#standard-operators

Java then has its own explanation in the Java CQL docs:
https://cap.cloud.sap/docs/java/working-with-cql/query-api#comparison-operators

I like the way it is documented in Java, we can probably do something similar here. Do you want to contribute this?

Akatuoro · 2026-01-09T16:03:16Z

I still think this documentation is way to much focused on explaining how CQL is converted to SQL. Instead we should provide a documentation that explains the fundamentals of the expression language:

Values

literals

refs

paths

filtered paths -> predicates

parameters

value functions

value expressions

Predicates

comparison predicates

connectives (AND, OR)

negation

Boolean functions

I would not know why you need SQL to explain any of this.

The samples all have the corresponding SQL to make transparent what actually happens in the background. This is quite important for humans and especially for LLMs. The SQL is always hidden behind an extra tab, so it is not the focus.

If CQL (which CXL is a part of) was really its own language, it would make sense to describe and specify everything in detail from the ground up. Since it is based on SQL, we can use that fact to build on pre-existing knowledge.

To the structure of Value vs. Predicate... I don't agree. Predicates are also "values"... or rather, expressions... simply boolean expressions. There are some constructs which require that an expression returns a boolean (case when, ternary, filters, ...), but this boolean can also come from a literal, a ref etc.

Akatuoro and others added 24 commits November 26, 2025 16:54

initial cxl diagrams

e4fd59a

add some first drawings

f2b2611

more diagrams

06639e7

add links and clickable diagrams to CXL

589aa42

more diagrams

5f579bf

some text

db13438

Merge branch 'cxl' of https://github.com/cap-js/docs into cxl

6dd2daa

recangular entities

4522abf

Merge remote-tracking branch 'origin/cxl' into cxl

57a75dc

functions with method style

ca9858b

add intro and some samples for ref

45bf61b

spelling

784e99c

update

493b3ee

minor changes to diagram

ac6159e

small infix filter update

db644c2

adjustements

709f355

make imports relative

e9bec18

fix formatting -> disable word-wrap and text formatting

6e25e92

some more samples

c6fffef

Merge remote-tracking branch 'origin/cxl' into cxl

137166f

fix

1fe6bec

adjustements to drawings and more samples

8f56dd6

css

c22f480

more finetuning

925d0af

patricebender requested review from Akatuoro and agoerler December 9, 2025 15:04

patricebender requested a review from renejeglinsky as a code owner December 9, 2025 15:04

review notes

0038356

agoerler reviewed Dec 10, 2025

View reviewed changes

swaldmann reviewed Dec 19, 2025

View reviewed changes

cds/cxl.md Outdated Show resolved Hide resolved

swaldmann reviewed Dec 19, 2025

View reviewed changes

assets/cxl/sets.drawio.svg Outdated Show resolved Hide resolved

swaldmann reviewed Dec 19, 2025

View reviewed changes

Akatuoro and others added 7 commits December 19, 2025 16:10

remove duplicate diagram

5bd9e2d

Apply suggestions from code review

932c424

Co-authored-by: Steffen Waldmann <[email protected]>

fix

84632de

Merge branch 'cxl' of https://github.com/cap-js/docs into cxl

d2b337f

Merge remote-tracking branch 'origin/main' into cxl

87366e4

Books.title -> title

25c2fce

lower case null, true, false

395a800

agoerler reviewed Dec 23, 2025

View reviewed changes

Akatuoro added 3 commits January 5, 2026 13:49

Merge branch 'main' into cxl

c653408

add examples

34cb885

move to cql + learn-more links

1115e2c

agoerler reviewed Jan 6, 2026

View reviewed changes

Akatuoro added 9 commits January 8, 2026 15:43

todos + move parts out

ab2e0d1

Merge remote-tracking branch 'origin/main' into cxl

8a07425

fix

77b964c

.

768fac2

ready for merge

a73acf6

remove binding parameter for first version

d742c11

move diagrams

4f87d16

fix diagram whitespace

306f51a

apply review feedback

2994ffc

infix filter examples

f77f4a5

agoerler reviewed Jan 9, 2026

View reviewed changes

Akatuoro added 2 commits January 9, 2026 16:30

apply review comments

dc19472

apply review comment

d481bb9

	Every entity defines a set of all possible instances:
	Every entity defines a set of all instances:

	A simple select query on Books returns the complete set → all books.
	A simple select from Books returns the complete set → all books.

		Using the infix notation to specify the query modifiers is just
		syntactic sugar:


		$$\text{books} = \{ (a,b) \in \text{Books} \times \text{Authors} \mid b.\text{author\_id} = a.\text{id} \}$$

		We can select this set using the path expression `Authors:books` in the [from clause](#in-from-clause).


		### in the where clause {#in-where-clause}

		A path expression can also be used as part of the where clause to filter based on elements of related entities:

	A path expression can also be used as part of the where clause to filter based on elements of related entities:
	A single-valued path expression can also be used as part of the where clause to filter based on elements of related entities:

	books[ price < 19.99 ] as cheapBooks {
	books[ price < 20.00 ] as cheapBooks {


		TODO: This is database specific

		In this example, the runtime makes use of JSON functions to aggregate the related `books` into a JSON array.

	In this example, the runtime makes use of JSON functions to aggregate the related `books` into a JSON array.
	In this example, the CAP Node.js runtime makes use of JSON functions to aggregate the related `books` into a JSON array.

	The join condition is defined ahead of time as part of the association.
	The foreign-key relationship is defined ahead of time as part of the association.



		::: info 💡 A binary operator is an operator that operates on two operands.
		::: info A binary operator is an operator that operates on two operands.

feat: CXL documentation #2260

Are you sure you want to change the base?

feat: CXL documentation #2260

Uh oh!

Conversation

patricebender commented Dec 9, 2025

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Akatuoro Dec 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

renejeglinsky commented Dec 11, 2025

Uh oh!

Uh oh!

Uh oh!

swaldmann Dec 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Akatuoro Dec 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

join (default):

parent-keys:

load-single (legacy):

subquery

Uh oh!

Akatuoro Jan 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

I think there is no valid use case for path expression involving to-many associations besides in expands and exists!

Uh oh!

Choose a reason for hiding this comment

feat: `CXL` documentation #2260

feat: `CXL` documentation #2260

Akatuoro Dec 11, 2025 •

edited

Loading

swaldmann Dec 19, 2025 •

edited

Loading

Akatuoro Dec 19, 2025 •

edited

Loading

Akatuoro Jan 7, 2026 •

edited

Loading

I think there is no valid use case for path expression involving to-many associations besides in expands and `exists`!