feat: CXL documentation

[patricebender]

TBD

[agoerler]

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

[Akatuoro]

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.

[renejeglinsky]

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

[agoerler]

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]

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]

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]

Suggested change

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

see above

[agoerler]

Suggested change

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

[agoerler]

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]

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)

[Akatuoro]

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]

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!

[Akatuoro]

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

[agoerler]

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

[Akatuoro]

@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]

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.

[Akatuoro]

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]

@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]

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.

[agoerler]

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

[Akatuoro]

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

[agoerler]

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.

[Akatuoro]

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]

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.

[danjoa]

👍👍👍

[agoerler]

The new shape looks much better :-)

[agoerler]

The vertical alignment of the text is off

[agoerler]

Suggested change

	Typically, this is done in a column of a query. CAP
	Typically, this is done on the select list of a query. CAP

[agoerler]

Suggested change

	Expressions can be used in various parts of a query, e.g., in the select list, in the where clause, in order by clauses, and more:
	Expressions can be used in various parts of a query, e.g., on the select list, in the where clause, in order by clauses, and more:

[agoerler]

Rather define the portable functions here (as they are DB-independent and also apply for to remote OData calls). Then link from the database guide to here.