DJ Adams

CDS expressions in CAP - notes on Part 5

2026-04-07T00:00:00Z

See the series post for an overview of all the episodes.

Introduction

00:00 Introduction and recap from last time.

06:55 Patrice jumps back in and visits the CXL documentation in Capire, which already by this point has even been updated and improved. He also briefly runs over some of the expressions and concepts we've covered thus far, including the CASE statement, predicates, association-like calculated elements (derived from existing associations) and more.

Combining CASE and concatenation operators

11:33 Revisiting my question last time about element references, Patrice expands the fullName example to combine some of the concepts with which we're now familiar:

the ternary operator (syntactic sugar for the CASE construct)
string concatenation (||)

fullName = academicTitle is not null
  ? academicTitle || ' ' || name
  : name;

This allows us to take Tolkien's "Professor" title into account 👍.

To show the result of this expression, Patrice runs a query¹ in the cds REPL:

> await SELECT
    .from(Authors)
    .columns('name', 'academicTitle', 'fullName')
[
  ...,
  {
    name: 'Brandon Sanderson',
    academicTitle: null,
    fullName: 'Brandon Sanderson'
  },
  {
    name: 'J. R. R. Tolkien',
    academicTitle: 'Prof.',
    fullName: 'Prof. J. R. R. Tolkien'
  }
]

If you want to copy this to try it out yourself, you can use the cds REPL's .editor feature to enter the multi-line construct (shown like this for better readability here).

Explicit and default types for calculated elements

14:01 I ask a question relating to the type declarations (or lack thereof) for the calculated elements. I came up with a very fanciful theory, only to be told that types are declared when the type is not String. In other words, if a type is not declared, then String is the default (for fullName here):

entity Authors : managed {
  key ID            : Integer;
      name          : String(111) @mandatory;
      address       : Association to Addresses;
      academicTitle : String(111);
      ...

      fullName = academicTitle is not null
        ? academicTitle || ' ' || name
        : name;

      isAlive       : Boolean = dateOfDeath is null ? true : false;
      age           : Integer = years_between(
        dateOfBirth, coalesce(dateOfDeath, current_date)
      );
}

Keep services simple

16:25 Then comes a great question from Neil, on hints, tips and best practices for complex models in the context of large data volumes.

In response, Patrice talks about how caution is needed when constructing definitions with large numbers of associations, especially when querying views that result from such definitions, where the queries are only to retrieve a small subset of data. To satisfy any query, a complex and possibly costly FROM clause needs to be processed by the underlying database, which when compared to the small query surface area, is then costly in comparison.

It's much better to keep service definitions simple and granular; think of services as reflectors of single domain problems, rather than representing the entire domain.

See also AXI004 Services are cheap.

This is also why it's always important to not only know about the power that we are able to wield, but also to know what happens behind the scenes. Two key reasons for this series!

Additionally, another member of the CAP team in the chat, Johannes Vogt, suggests employing DEBUG=sql as another way to see what's going on. At around 21:33 Patrice demonstrates this (with DEBUG=sql cds repl --run .).

Always consider EXISTS for checks across to-many relationships

24:10 Patrice concludes his wrap up by emphasising the importance of the EXISTS predicate. Not using this predicate results in likely unwanted duplicate records in the result set due to the LEFT JOIN that is used:

> await cds.ql`
  SELECT from Authors { fullName }
  where books.title like '%Mistborn%'
  `
[
  { fullName: 'Brandon Sanderson' },
  { fullName: 'Brandon Sanderson' }
]

Reformulating the above to use EXISTS plus an infix filter solves that, as a subquery (a "subselect") is used instead:

> await cds.ql`
  SELECT from Authors { fullName }
  where exists books[title like '%Mistborn%']
  `
[
  { fullName: 'Brandon Sanderson' }
]

See the section A look at the EXISTS predicate in the notes to the previous episode for more detail.

Simplicity from shifting left

27:00 Revisiting the association-like calculated element from last time, we get to meditate a bit more² on how shifting left brings about simplicity.

It would not be out of the ordinary to construct and execute a query like this:

> await cds.ql`
  SELECT from Authors { fullName }
  where exists books[stock > 170]
  `
[
  { fullName: 'Richard Carpenter' },
  { fullName: 'Prof. J. R. R. Tolkien' }
]

This is already an "accomplished" query, using the very constructions we looked at just earlier. However, if we shift this condition left, moving it from the query to our CDS model:

entity Authors : managed {
  key ID            : Integer;
      name          : String(111) @mandatory;
      ...

      books         : Association to many Books
                        on books.author = $self;

      nonSeller = books[ stock > 170 ];
      ...
}

then we define it once, can identify and test it once, and consumers have a convenient semantic shortcut to what the domain modelling process has defined.

Moreover, let's just take a second to boggle at the simplicity of the expression that is then available to us in query construction:

> await cds.ql`
  SELECT from Authors { fullName }
  where exists nonSeller
  `
[
  { fullName: 'Richard Carpenter' },
  { fullName: 'Prof. J. R. R. Tolkien' }
]

Digging into the condition

Here it is: where exists nonSeller. Now that is simple. How exactly are we checking for existence here? And what exactly are we checking anyway? An association? Well, yes, but this is where the term "association-like calculated element" fits much better.

At 28:31 Patrice takes a moment to look under the hood at this, so we can understand better what is going on.

First, the CQN shows us that the the target of the EXISTS is an expression { ref: [ 'nonSeller' ] }:

> q = cds.ql`
  SELECT from ${Authors} { fullName }
  where exists nonSeller
  `
cds.ql {
  SELECT: {
    from: { ref: [ 'sap.capire.bookshop.Authors' ] },
    columns: [ { ref: [ 'fullName' ] } ],
    where: [ 'exists', { ref: [ 'nonSeller' ] } ]
  }
}

Moving to the normalised "CAP-style SQL", with forSQL()³, we see somewhat of an explosion:

> q.forSQL()
cds.ql {
  SELECT: {
    from: { ref: [ 'sap.capire.bookshop.Authors' ], as: 'Authors' },
    columns: [
      {
        xpr: [
          'case',
          'when',
          { ref: [ 'Authors', 'academicTitle' ] },
          'is',
          'not',
          'null',
          'then',
          { ref: [ 'Authors', 'academicTitle' ] },
          '||',
          { val: ' ' },
          '||',
          { ref: [ 'Authors', 'name' ] },
          'else',
          { ref: [ 'Authors', 'name' ] },
          'end'
        ],
        as: 'fullName'
      }
    ],
    where: [
      'exists',
      {
        SELECT: {
          from: { ref: [ 'sap.capire.bookshop.Books' ], as: 'nonSeller' },
          columns: [ { val: 1 } ],
          where: [
            {
              xpr: [
                { ref: [ 'nonSeller', 'author_ID' ] },
                '=',
                { ref: [ 'Authors', 'ID' ] }
              ]
            },
            'and',
            { xpr: [ { ref: [ 'nonSeller', 'stock' ] }, '>', { val: 170 } ] }
          ]
        }
      }
    ]
  }
}

For the sake of this discussion, we can ignore the first part, specifically the value of columns, as that is for the fullName element. It's the WHERE clause that is of interest, and where the answers to the questions earlier start to appear.

You may wish to refer to the section A look at the EXISTS predicate from the notes to the previous episode for a detailed analysis, but revisiting this allows us to stare at the construct a little more, and see how it fits together - the subquery includes both conditions:

one from the nonSeller definition
one from the "donor" books definition

and either returns something (1)⁴ or nothing, which is why we can treat it almost like a Boolean.

31:30 Patrice makes a point about the SQL that is ultimately produced here, in that it's perfectly possible to construct that SQL yourself, manually. But who would want to do that, also taking into account the nuances of different database SQL dialects?

Moreover, one could consider taking one step back and writing the CAP-style SQL manually instead, using cds.ql facilities⁵. But for everyday development, this is extra effort that is not required, when compared to the power & expressiveness of CQL combined with CXL.

Using a path expression in the column list

At 32:36 Patrice continues the exploration of the nonSeller association-like calculated element, adding a couple of path expressions (nonSeller.stock and nonSeller.title) to the column list of the query:

> q = cds.ql`
  SELECT from ${Authors}
  { fullName, nonSeller.stock, nonSeller.title }
  where exists nonSeller
  `
cds.ql {
  SELECT: {
    from: { ref: [ 'sap.capire.bookshop.Authors' ] },
    columns: [
      { ref: [ 'fullName' ] },
      { ref: [ 'nonSeller', 'stock' ] },
      { ref: [ 'nonSeller', 'title' ] }
    ],
    where: [ 'exists', { ref: [ 'nonSeller' ] } ]
  }
}

The challenge here is that the introduction of the path expression into this query causes a flat list to be produced, with multiple entries for the authors involved:

> await q
[
  {
    fullName: 'Richard Carpenter',
    nonSeller_stock: 187,
    nonSeller_title: 'Catweazle'
  },
  {
    fullName: 'Prof. J. R. R. Tolkien',
    nonSeller_stock: 178,
    nonSeller_title: 'Beren and Lúthien'
  },
  {
    fullName: 'Prof. J. R. R. Tolkien',
    nonSeller_stock: 203,
    nonSeller_title: 'The Children of Húrin'
  },
  {
    fullName: 'Prof. J. R. R. Tolkien',
    nonSeller_stock: 195,
    nonSeller_title: 'The Fall of Gondolin'
  },
  {
    fullName: 'Prof. J. R. R. Tolkien',
    nonSeller_stock: 189,
    nonSeller_title: 'Unfinished Tales'
  }
]

Now we know about forSQL() and toSQL(), we can comfortably look behind the scenes, as Patrice does at 34:17, to understand why:

> q.forSQL()
cds.ql {
  SELECT: {
    from: {
      join: 'left',
      args: [
        { ref: [ 'sap.capire.bookshop.Authors' ], as: 'Authors' },
        { ref: [ 'sap.capire.bookshop.Books' ], as: 'nonSeller' }
      ],
      on: [
        {
          xpr: [
            { ref: [ 'nonSeller', 'author_ID' ] },
            '=',
            { ref: [ 'Authors', 'ID' ] }
          ]
        },
        'and',
        {
          xpr: [ { ref: [ 'nonSeller', 'stock' ] }, '>', { val: 170 } ]
        }
      ]
    },
    columns: [
      {
        xpr: [
          'case',
          'when',
          { ref: [ 'Authors', 'academicTitle' ] },
          'is',
          'not',
          'null',
          'then',
          { ref: [ 'Authors', 'academicTitle' ] },
          '||',
          { val: ' ' },
          '||',
          { ref: [ 'Authors', 'name' ] },
          'else',
          { ref: [ 'Authors', 'name' ] },
          'end'
        ],
        as: 'fullName'
      },
      { ref: [ 'nonSeller', 'stock' ], as: 'nonSeller_stock' },
      { ref: [ 'nonSeller', 'title' ], as: 'nonSeller_title' }
    ],
    where: [
      'exists',
      {
        SELECT: {
          from: { ref: [ 'sap.capire.bookshop.Books' ], as: 'nonSeller2' },
          columns: [ { val: 1 } ],
          where: [
            {
              xpr: [
                { ref: [ 'nonSeller2', 'author_ID' ] },
                '=',
                { ref: [ 'Authors', 'ID' ] }
              ]
            },
            'and',
            { xpr: [ { ref: [ 'nonSeller2', 'stock' ] }, '>', { val: 170 } ] }
          ]
        }
      }
    ],
    expand: 'root'
  }
}

Patrice points out the alias nonSeller2 - the term nonSeller has already been used for the alias for Books in the LEFT JOIN constructed due to the path expressions we added to the column list.

37:35 In answering a question I asked about this, Patrice explains the query plan here, which is to:

Filter the entire set of authors down to those satisfying the non-seller predicate condition
For that subset of authors, a LEFT JOIN is made to the books

The duplicate author names in the result set are because of this LEFT JOIN which brings about a flattening, essentially a consequence of the implicit requirement for a LEFT JOIN contradicting or invalidating the point of the subquery.

One could have just as well constructed the query like this, which Patrice shows at 38:33:

> q = cds.ql`
  SELECT from ${Authors}
  { fullName, nonSeller.stock, nonSeller.title }
  where nonSeller.title is not null
  `
cds.ql {
  SELECT: {
    from: { ref: [ 'sap.capire.bookshop.Authors' ] },
    columns: [
      { ref: [ 'fullName' ] },
      { ref: [ 'nonSeller', 'stock' ] },
      { ref: [ 'nonSeller', 'title' ] }
    ],
    where: [ { ref: [ 'nonSeller', 'title' ] }, 'is', 'not', 'null' ]
  }
}

The result set is the same as before.

Nested expands

39:50 However, there's more to life than flattened lists! Returning to the original query with the EXISTS predicate, we can avoid the flattening and repetition (which we now know is caused by the LEFT JOIN, due in turn to the path expression traversal requirements).

How? By using the power of nested expands:

> q = cds.ql`
  SELECT from ${Authors}
  { fullName, nonSeller { title, stock } }
  where exists nonSeller
  `
cds.ql {
  SELECT: {
    from: { ref: [ 'sap.capire.bookshop.Authors' ] },
    columns: [
      { ref: [ 'fullName' ] },
      {
        ref: [ 'nonSeller' ],
        expand: [ { ref: [ 'title' ] }, { ref: [ 'stock' ] } ]
      }
    ],
    where: [ 'exists', { ref: [ 'nonSeller' ] } ]
  }
}

This brings back a result set that is definitely not flattened:

> await q
[
  {
    fullName: 'Richard Carpenter',
    nonSeller: [ { title: 'Catweazle', stock: 187 } ]
  },
  {
    fullName: 'Prof. J. R. R. Tolkien',
    nonSeller: [
      { title: 'Unfinished Tales', stock: 189 },
      { title: 'The Children of Húrin', stock: 203 },
      { title: 'Beren and Lúthien', stock: 178 },
      { title: 'The Fall of Gondolin', stock: 195 }
    ]
  }
]

... it's structured!

This seems a little extraordinary, given the nature of SQL generally, and the native inability to store an entire set of data into a single column in particular. This extraordinariness is made possible due to the modern database adapters, re-written and introduced in CAP major version 8.

42:50 Patrice explains how this was achieved before those new database adapters: such queries were realised by a combination of SQL and also runtime logic, perhaps a bit like we approached similar query tasks in ABAP by using internal tables and custom logic controlled execution of various SELECT statements, back in the day.

Looking back at the Release Notes for Jun 2024, introducing CAP 8, we can see exactly what this is about in the New Database Services (GA) section, in particular:

Various optimizations like using database-native JSON functions for deep queries in single roundtrips, user-defined functions and more, to push data-processing tasks down to the database (→ improves utilization).

What do these "database-native JSON functions" look like? Well, we've seen them in passing before, but we can work our way towards them by following the now-familiar path, going from the CQN, to the CAP-style SQL, and ultimately to the native SQL.

First, the CAP-style SQL (with the expression for the fullName construction and the subquery for the exists nonSeller both elided for brevity):

> q.forSQL()
cds.ql {
  SELECT: {
    from: { ref: [ 'sap.capire.bookshop.Authors' ], as: 'Authors' },
    columns: [
      {
        xpr: [
          ...
        ],
        as: 'fullName'
      },
      {
        SELECT: {
          from: { ref: [ 'sap.capire.bookshop.Books' ], as: 'nonSeller2' },
          columns: [
            { ref: [ 'nonSeller2', 'stock' ] },
            { ref: [ 'nonSeller2', 'title' ] }
          ],
          expand: true,
          one: false,
          where: [
            {
              xpr: [
                { ref: [ 'Authors', 'ID' ] },
                '=',
                { ref: [ 'nonSeller2', 'author_ID' ] }
              ]
            },
            'and',
            { xpr: [ { ref: [ 'nonSeller2', 'stock' ] }, '>', { val: 170 } ] }
          ]
        },
        as: 'nonSeller'
      }
    ],
    where: [
      'exists',
      {
        ...
      }
    ]
  }
}

Note that there's no LEFT JOIN that we've seen employed previously (before we introduced the nested expand). Instead, alongside the fullName column, there's now a second column in the outermost (main) query, which is a subquery, specifically a SELECT on Books.

The WHERE clause in this subquery should look familiar, and serves to correlate the IDs of the Authors from the main query as well as restricting the result set according to the stock values.

48:16 In answer to my question at this point, Patrice tells us that these expands are similar to postfix projections and the concepts are shared.

Here follows an example, which shows:

the smart * selector
a couple of alias declarations (one for the actual association, and one for one of the structure elements)
omission of elements via an excluding clause

> await cds.ql`
  SELECT from ${Authors}
  {
    fullName,
    nonSeller as booksNotSellingWell
      { *, title as bookName }
      excluding { createdBy, modifiedBy, ID, descr }
  }
  where exists nonSeller
  `
[
  {
    fullName: 'Richard Carpenter',
    nonSeller: [
      {
        createdAt: '2026-04-04T10:29:20.859Z',
        modifiedAt: '2026-04-04T10:29:20.859Z',
        title: 'Catweazle',
        author_ID: 170,
        genre_ID: 13,
        stock: 187,
        price: 150,
        currency_code: 'JPY',
        bookName: 'Catweazle'
      }
    ]
  },
  {
    fullName: 'Prof. J. R. R. Tolkien',
    nonSeller: [
      {
        createdAt: '2026-04-04T10:29:20.859Z',
        modifiedAt: '2026-04-04T10:29:20.859Z',
        title: 'Unfinished Tales',
        author_ID: 201,
        genre_ID: 13,
        stock: 189,
        price: 13.99,
        currency_code: 'GBP',
        bookName: 'Unfinished Tales'
      },
      {
        createdAt: '2026-04-04T10:29:20.859Z',
        modifiedAt: '2026-04-04T10:29:20.859Z',
        title: 'The Children of Húrin',
        author_ID: 201,
        genre_ID: 13,
        stock: 203,
        price: 13.99,
        currency_code: 'GBP',
        bookName: 'The Children of Húrin'
      },
      ...
    ]
  }
]

At 50:12 I make an observation about nesting depth, to which Patrice responds by extending the example to add genre information, which I will do here to this example:

> await cds.ql`
  SELECT from ${Authors}
  {
    fullName,
    nonSeller as booksNotSellingWell
      { *, title as bookName, genre { * } }
      excluding { createdBy, modifiedBy, ID, descr }
  }
  where exists nonSeller
  `

The result set is suitably extended, here's what a typical book structure looks like now:

{
  createdAt: '2026-04-04T10:29:20.859Z',
  modifiedAt: '2026-04-04T10:29:20.859Z',
  title: 'The Fall of Gondolin',
  author_ID: 201,
  genre_ID: 13,
  stock: 195,
  price: 13.99,
  currency_code: 'GBP',
  bookName: 'The Fall of Gondolin',
  genre: {
    name: 'Fantasy',
    descr: null,
    ID: 13,
    parent_ID: 10
  }
}

Note also, as Patrice points out, that before CAP 8, this would have been realised by multiple (three, in fact) separate calls to the database layer, coordinated by logic in the runtime, and then the results stitched together before being returned as a contiguous set. These three calls can be seen as three nested SELECT statements in the query's intermediate format⁶.

With the new database adapters, there's only a single call to the database layer, and no coordination or combination logic required at runtime.

JSON functions in SQL

53:18 Based on this query that Patrice was working with:

> q = cds.ql`
  SELECT from ${Authors}
  {
    fullName,
    nonSeller
    {
      title as book,
      stock,
      genre
      {
        *
      }
    }
  }
  where exists nonSeller
  `

here's what the actual database native (SQLite in this particular example) SQL looks like⁷:

SELECT
  case
    when Authors.academicTitle is not null then Authors.academicTitle || ? || Authors.name
    else Authors.name
  end as fullName,
  (
    SELECT
      jsonb_group_array (
        jsonb_insert (
          '{}',
          '$."book"',
          book,
          '$."stock"',
          stock,
          '$."genre"',
          genre - > '$'
        )
      ) as _json_
    FROM
      (
        SELECT
          nonSeller2.title as book,
          nonSeller2.stock,
          (
            SELECT
              json_insert (
                '{}',
                '$."name"',
                name,
                '$."descr"',
                descr,
                '$."ID"',
                ID,
                '$."parent_ID"',
                parent_ID
              ) as _json_
            FROM
              (
                SELECT
                  genre.name,
                  genre.descr,
                  genre.ID,
                  genre.parent_ID
                FROM
                  sap_capire_bookshop_Genres as genre
                WHERE
                  "nonSeller2".genre_ID = genre.ID
                LIMIT
                  ?
              )
          ) as genre
        FROM
          sap_capire_bookshop_Books as "nonSeller2"
        WHERE
          (Authors.ID = "nonSeller2".author_ID)
          and ("nonSeller2".stock > ?)
      )
  ) as nonSeller
FROM
  sap_capire_bookshop_Authors as Authors
WHERE
  exists (
    SELECT
      1 as "1"
    FROM
      sap_capire_bookshop_Books as nonSeller
    WHERE
      (nonSeller.author_ID = Authors.ID)
      and (nonSeller.stock > ?)
  )

Here are some initial notes on this (single!) SQL statement:

the outermost SELECT is on the Authors
it is constrained by the WHERE clause that represents the non-seller subquery with which we are familiar
the construction of the fullName in SQL here is extremely similar to the CXL CASE expression

Then come the nested subqueries. But wait, that's a lot more SELECTs that we expected! That's because of the interleaving of JSON functions, from which comes the power and ability to push down such complex queries directly and solely to the database layer.

Essentially, we see the use here of:

the aggregate function jsonb_group_array
the function json_insert to construct JSON objects (to be aggregated)

The juxtaposition (pairing, almost) of the JSON functions and the corresponding subquery SELECT statements is not accidental. They have been generated exactly like this to be able to build the deeply nested structure required, otherwise impossible in SQL without such JSON facilities ... combined with the ability to stringify complex JSON structures into scalar values (large strings!).

Further info

Patrice also has some great notes for this part.

Footnotes

The query is constructed using the fluent API style, rather than what we've mostly employed, which has been by writing queries in tagged template literals. See the Constructing Queries section of the Querying in JavaScript topic in Capire for more information. Additionally, I used the columns() method to restrict the data set returned.
We considered this briefly in part 3 of this series - see Adding a calculated element in the notes.
It's for the benefit of this method that we're using ${Authors} rather than Authors in the query template string, so that the transformation function will work properly.

Note that this value of 1 is not the SQLite Boolean value for true. This is the normalised neutral SQL (from forSQL()) rather than the database specific SQL. If we were to ask for the database specific SQL when connected to HANA (instead of SQLite here):

echo 'cds.ql`select from ${Authors} { fullName } where exists nonSeller`.toSQL().sql'
| cds bind --exec --profile hybrid -- cds repl --run .

we'd see this 1 value too:

SELECT
  case
    when Authors.academicTitle is not null then Authors.academicTitle || ? || Authors.name
    else Authors.name
  end as "fullName"
FROM
  sap_capire_bookshop_Authors as Authors
WHERE
  exists (
    SELECT
      1 as "1"
    FROM
      sap_capire_bookshop_Books as nonSeller
    WHERE
      (nonSeller.author_ID = Authors.ID)
      and (nonSeller.stock > ?)
  )

cds.ql contains a whole host of facilities for this:

> Object.keys(cds.ql)
[
  'Query',   'SELECT', 'INSERT',
  'UPSERT',  'UPDATE', 'DELETE',
  'CREATE',  'DROP',   'predicate',
  'columns', 'ref',    'val',
  'xpr',     'expr',   'list',
  'func',    'nested', 'expand',
  'inline',  'where',  'orderBy',
  'orders',  'limit',  'clone'
]

Here's the intermediate format for this query, showing the SELECT statements nested as columns:

cds.ql {
  SELECT: {
    from: { ref: [ 'sap.capire.bookshop.Authors' ], as: 'Authors' },
    columns: [
      {
        xpr: [
          ...
        ],
        as: 'fullName'
      },
      {
        SELECT: {
          excluding: [ 'createdBy', 'modifiedBy', 'ID', 'descr' ],
          from: { ref: [ 'sap.capire.bookshop.Books' ], as: 'nonSeller2' },
          columns: [
            { ref: [ 'nonSeller2', 'createdAt' ] },
            { ref: [ 'nonSeller2', 'modifiedAt' ] },
            { ref: [ 'nonSeller2', 'title' ] },
            { ref: [ 'nonSeller2', 'author_ID' ] },
            { ref: [ 'nonSeller2', 'genre_ID' ] },
            { ref: [ 'nonSeller2', 'stock' ] },
            { ref: [ 'nonSeller2', 'price' ] },
            { ref: [ 'nonSeller2', 'currency_code' ] },
            { ref: [ 'nonSeller2', 'title' ], as: 'bookName' },
            {
              SELECT: {
                from: { ref: [ 'sap.capire.bookshop.Genres' ], as: 'genre' },
                columns: [
                  { ref: [ 'genre', 'name' ] },
                  { ref: [ 'genre', 'descr' ] },
                  { ref: [ 'genre', 'ID' ] },
                  { ref: [ 'genre', 'parent_ID' ] }
                ],
                expand: true,
                one: true,
                where: [
                  { ref: [ 'nonSeller2', 'genre_ID' ] },
                  '=',
                  { ref: [ 'genre', 'ID' ] }
                ]
              },
              as: 'genre'
            }
          ],
          expand: true,
          one: false,
          where: [
            {
              xpr: [
                { ref: [ 'Authors', 'ID' ] },
                '=',
                { ref: [ 'nonSeller2', 'author_ID' ] }
              ]
            },
            'and',
            { xpr: [ { ref: [ 'nonSeller2', 'stock' ] }, '>', { val: 170 } ] }
          ]
        },
        as: 'nonSeller'
      }
    ],
    where: [
      'exists',
      {
        SELECT: {
          from: { ref: [ 'sap.capire.bookshop.Books' ], as: 'nonSeller' },
          columns: [ { val: 1 } ],
          where: [
            {
              xpr: [
                { ref: [ 'nonSeller', 'author_ID' ] },
                '=',
                { ref: [ 'Authors', 'ID' ] }
              ]
            },
            'and',
            { xpr: [ { ref: [ 'nonSeller', 'stock' ] }, '>', { val: 170 } ] }
          ]
        }
      }
    ]
  }
}

The outermost JSON function has been omitted here, as it is less important to stare at right now.

CDS expressions in CAP - notes on Part 4

2026-03-27T00:00:00Z

See the series post for an overview of all the episodes.

Introduction

00:00 Introduction and recap from last time.

07:00 Patrice revisits the syntax diagram and starts to explain the insignificant-looking but very significant (in terms of power and utility) "ref" box in that diagram, which is the start of our journey to understand path expressions.

In fact, the box label "ref" at the time this episode was being broadcast has now been replaced with "path expression" in the latest incarnation of the syntax diagram in Capire:

Selecting this box leads to the Path Expressions (ref) section of the CXL topic.

Some syntactic sugar for the case-when-then-else-end expression

10:08 Patrice revisits the CASE ... WHEN ... THEN ... ELSE ... END expression, which we looked at first in part 2 but for which there's some nice syntactic sugar.

He starts with passing a simple CXL example to the context-free parser (cds.parse.expr), which emits the corresponding CXN:

> cds.parse.expr`
  case when stock > 10 then 'non-seller' else 'sells quickly' end
  `
{
  xpr: [
    'case',
    'when',
    { ref: [ 'stock' ] },
    '>',
    { val: 10 },
    'then',
    { val: 'non-seller' },
    'else',
    { val: 'sells quickly' },
    'end'
  ]
}

Using the syntactic sugar, Patrice then shows us that we can write the same expression using a construct familiar in JavaScript and other languages:

> cds.parse.expr`
  stock > 10 ? 'non seller' : 'sells quickly'
  `
{
  xpr: [
    'case',
    'when',
    { ref: [ 'stock' ] },
    '>',
    { val: 10 },
    'then',
    { val: 'non seller' },
    'else',
    { val: 'sells quickly' },
    'end'
  ]
}

This version of the CXL expression is actually exactly the same in the internal (CXN) machine-readable form. Not only that, but this ? : is nestable too:

> cds.parse.expr`
  stock > 10
  ? (price > 50 ? 'expensive non seller' : 'cheap non seller')
  : 'sells quickly'
  `
{
  xpr: [
    'case',
    'when',
    { ref: [ 'stock' ] },
    '>',
    { val: 10 },
    'then',
    {
      xpr: [
        'case',
        'when',
        { ref: [ 'price' ] },
        '>',
        { val: 50 },
        'then',
        { val: 'expensive non seller' },
        'else',
        { val: 'cheap non seller' },
        'end'
      ]
    },
    'else',
    { val: 'sells quickly' },
    'end'
  ]
}

A closer look at the predicate expressions

15:15 The last thing that Patrice talks about before jumping into path expressions is the collection of predicates, which we very briefly noted in the previous episode.

First, we look at the BETWEEN predicate, by first considering an compound expression that describes a closed interval, to check for stock between 10 and 30:

> cds.parse.expr`
  stock >= 10 and stock <= 30
  `
{
  xpr: [
    { ref: [ 'stock' ] },
    '>=',
    { val: 10 },
    'and',
    { ref: [ 'stock' ] },
    '<=',
    { val: 30 }
  ]
}

Here we have two binary operator based expressions (with the comparison operators >= and <=) that are joined with (and become the operands for) another binary operator, the logical operator and.

In contrast, there's the range checking operator between, which we can use instead:

> cds.parse.expr`
  stock between 12 and 34
  `
{
  xpr: [ { ref: [ 'stock' ] }, 'between', { val: 12 }, 'and', { val: 34 } ]
}

Not only is this a single expression, it is also much neater and (arguably) easier to read as well as write.

Here's that expression in action, in a query:

> await cds.ql`
  select from Books { title, stock } where stock between 12 and 34
  `
[
  { title: 'Mistborn: The Final Empire', stock: 12 },
  { title: 'The Two Towers', stock: 14 }
]

There's also the not variant which is also available.

20:30 Next up is IN, which Patrice first demonstrates in an abstract way with:

> cds.parse.expr` (1, 2, 3) in (select ID from Books)`
{
  xpr: [
    { list: [ { val: 1 }, { val: 2 }, { val: 3 } ] },
    'in',
    {
      SELECT: {
        from: { ref: [ 'Books' ] },
        columns: [ { ref: [ 'ID' ] } ]
      }
    }
  ]
}

but then goes on to show the operator employed in a more practical example:

> q = cds.ql`
  select from ${Books} { title, stock }
  where (author.ID) in
    (select ID from ${Authors} where dateOfDeath is null)
  `
cds.ql {
  SELECT: {
    from: { ref: [ 'sap.capire.bookshop.Books' ] },
    columns: [ { ref: [ 'title' ] }, { ref: [ 'stock' ] } ],
    where: [
      { ref: [ 'author', 'ID' ] },
      'in',
      {
        SELECT: {
          from: { ref: [ 'sap.capire.bookshop.Authors' ] },
          columns: [ { ref: [ 'ID' ] } ],
          where: [ { ref: [ 'dateOfDeath' ] }, 'is', 'null' ]
        }
      }
    ]
  }
}

Here, the ID of the author association (via author_ID, effectively) is matched to the set of values from the (select ID from ...) subquery:

> await q
[
  { title: 'Mistborn: The Final Empire', stock: 12 },
  { title: 'The Well of Ascension', stock: 8 },
  { title: 'The Hero of Ages', stock: 5 },
  { title: 'The Alloy of Law', stock: 67 },
  { title: 'Shadows of Self', stock: 89 },
  { title: 'The Bands of Mourning', stock: 134 },
  { title: 'The Lost Metal', stock: 156 },
  { title: 'Mistborn: Secret History', stock: 98 },
  { title: 'The Way of Kings', stock: 7 },
  { title: 'Words of Radiance', stock: 4 },
  { title: 'Edgedancer', stock: 125 },
  { title: 'Oathbringer', stock: 3 },
  { title: 'Dawnshard', stock: 142 },
  { title: 'Rhythm of War', stock: 6 },
  { title: 'Wind and Truth', stock: 2 }
]

Moreover, the expression (author.ID) could have been written as author.ID i.e. as a path expression, rather than a path expression within a list context, which Patrice explains at 24:45, and also clarifies at 27:59 that the subquery is indeed an expression (it is, according to the syntax diagram) - a "query expression".

A first look at path expressions

There's also the EXISTS predicate which we will want to take a look at, but because this is most often found in use with path expressions, Patrice takes us on our first excursion to explore their power and utility, starting at 29:30, with a simple example (some results omitted for brevity here):

> q = cds.ql`SELECT from ${Authors} {name as author, books.title }`
cds.ql {
  SELECT: {
    from: { ref: [ 'sap.capire.bookshop.Authors' ] },
    columns: [
      { ref: [ 'name' ], as: 'author' },
      { ref: [ 'books', 'title' ] }
    ]
  }
}
> await q
[
  { author: 'Emily Brontë', books_title: 'Wuthering Heights' },
  { author: 'Charlotte Brontë', books_title: 'Jane Eyre' },
  { author: 'Edgar Allen Poe', books_title: 'Eleonora' },
  { author: 'Edgar Allen Poe', books_title: 'The Raven' },
  { author: 'Richard Carpenter', books_title: 'Catweazle' },
  { author: 'Brandon Sanderson', books_title: 'Dawnshard' },
  { author: 'Brandon Sanderson', books_title: '...' },
  { author: 'Brandon Sanderson', books_title: 'Words of Radiance' },
  { author: 'J. R. R. Tolkien', books_title: 'Beren and Lúthien' },
  { author: 'J. R. R. Tolkien', books_title: '...' },
  { author: 'J. R. R. Tolkien', books_title: 'Unfinished Tales' }
]

This is a "flat" list, i.e. all of the authors + book combinations.

To help our understanding, Patrice then highlights the diagram specifically for path expressions, which looks like this:

A brief digression on the term "forward declared join"

At this point (32:30) I'm unable to resist surfacing a phrase that is also used in this context, and that is "forward declared join", which Daniel Hutzel and I touched upon in part 9 of The Art and Science of CAP. Patrice nicely explains what this term is, and how the concept it represents, is present in the model that we're using, for example in the definition of the Authors entity (some elements omitted here for brevity):

entity Authors : managed {
  key ID            : Integer;
      name          : String(111) @mandatory;
      books         : Association to many Books
                        on books.author = $self;
}

The "on condition" for the books element definition is a sign that some correlation is going to be involved (as Patrice rightly points out, correlation is at the heart of any RDBMS); what's more, that correlation connecting Authors to Books is defined ahead of time, before any actual manifestation of the JOIN mechanism that will be required to realise the correlation.

Digging deeper into path expressions

Turning back to the path expression we had in SELECT from ${Authors} {name as author, books.title }, Patrice had pointed out that this query is not directly possible (in its current, simple form) in SQL, as books.title traverses a path from one entity to another.

Indeed, at 36:07 we see what this query is going to become by using the forSQL() method on the query object, where we see a LEFT JOIN is planned in the SELECT specification, in this SQL-style CQN version of the query:

> q.forSQL()
cds.ql {
  SELECT: {
    from: {
      join: 'left',
      args: [
        { ref: [ 'sap.capire.bookshop.Authors' ], as: 'Authors' },
        { ref: [ 'sap.capire.bookshop.Books' ], as: 'books' }
      ],
      on: [
        { ref: [ 'books', 'author_ID' ] },
        '=',
        { ref: [ 'Authors' , 'ID' ] }
      ]
    },
    columns: [
      { ref: [ 'Authors' , 'name' ], as: 'author' },
      { ref: [ 'books', 'title' ], as: 'books_title' }
    ]
  }
}

Note that the name of the association element books becomes the alias for the target of the traversal.

So here we're seeing the time element of a forward declared join i.e. a path expression, in that the join is manifested "just in time". By the way, with toSQL() we can see that the actual database engine specific SQL (SQLite in this case) looks like this (with the json_insert removed):

SELECT
  Authors.name as author,
  books.title as books_title
FROM
  sap_capire_bookshop_Authors as Authors
  left JOIN sap_capire_bookshop_Books as books
    ON books.author_ID = Authors.ID

Association-like calculated element

40:16 Building on this knowledge and what we learned last week, Patrice now adds a further element to the Authors entity definition, called nonSeller. And what a remarkable one! Here it is (again, with other elements removed for brevity):

entity Authors : managed {
  key ID            : Integer;
      name          : String(111) @mandatory;
      books         : Association to many Books
                        on books.author = $self;

      nonSeller = books[ stock > 100 ];

      isAlive       : Boolean = dateOfDeath is null ? true : false;
      age           : Integer = years_between(
        dateOfBirth, coalesce(
          dateOfDeath, current_date
        )
      );
}

This nonSeller element builds upon an existing association (books), and adds a condition in an infix filter ([stock > 100]). The syntax used for this definition basically follows the calculated element pattern. Patrice and I discussed the type, which is derived from the referenced element (books).

Additionally, the "on" condition in that referenced element is, for nonSeller, enhanced by the infix filter. This is exactly what's shown in the bottom part of the path expression syntax diagram shown earlier.

Essentially this new element nonSeller is still an association, and can therefore be used in path expressions just like books, as Patrice demonstrates at 43:46:

> q = cds.ql`SELECT from ${Authors} { name, nonSeller.title } `
cds.ql {
  SELECT: {
    from: { ref: [ 'sap.capire.bookshop.Authors' ] },
    columns: [ { ref: [ 'name' ] }, { ref: [ 'nonSeller', 'title' ] } ]
  }
}

Transforming the query into the normalised (intermediate) format, we see:

> q.forSQL()
cds.ql {
  SELECT: {
    from: {
      join: 'left',
      args: [
        { ref: [ 'sap.capire.bookshop.Authors' ], as: 'Authors' },
        { ref: [ 'sap.capire.bookshop.Books' ], as: 'nonSeller' }
      ],
      on: [
        {
          xpr: [
            { ref: [ 'nonSeller', 'author_ID' ] },
            '=',
            { ref: [ 'Authors', 'ID' ] }
          ]
        },
        'and',
        {
          xpr: [ { ref: [ 'nonSeller', 'stock' ] }, '>', { val: 100 } ]
        }
      ]
    },
    columns: [
      { ref: [ 'Authors', 'name' ] },
      { ref: [ 'nonSeller', 'title' ], as: 'nonSeller_title' }
    ]
  }
}

We can see that there's a left join planned, and there is a set of "on" conditions in an array, two expressions:

a correlation of the author ID across the two entities
a comparison operator based condition on the stock value

In both cases the entities are referred to by their aliases.

48:00 The dataset returned from this query looks like this:

  { name: 'Emily Brontë', nonSeller_title: null },
  { name: 'Charlotte Brontë', nonSeller_title: null },
  { name: 'Edgar Allen Poe', nonSeller_title: 'Eleonora' },
  { name: 'Edgar Allen Poe', nonSeller_title: 'The Raven' },
  { name: 'Richard Carpenter', nonSeller_title: 'Catweazle' },
  { name: 'Brandon Sanderson', nonSeller_title: 'Dawnshard' },
  { name: 'Brandon Sanderson', nonSeller_title: 'Edgedancer' },
  { name: 'Brandon Sanderson', nonSeller_title: 'The Bands of Mourning' },
  { name: 'Brandon Sanderson', nonSeller_title: 'The Lost Metal' },
  { name: 'J. R. R. Tolkien', nonSeller_title: 'Beren and Lúthien' },
  { name: 'J. R. R. Tolkien', nonSeller_title: 'The Children of Húrin' },
  { name: 'J. R. R. Tolkien', nonSeller_title: 'The Fall of Gondolin' },
  { name: 'J. R. R. Tolkien', nonSeller_title: 'The Silmarillion' },
  { name: 'J. R. R. Tolkien', nonSeller_title: 'Unfinished Tales' }
]

We're driving this query from the Authors, with a(n implicit) LEFT JOIN, which means that we are going to get all of the authors, including those (two of the Brontë sisters!) for which there are no "non sellers", i.e. no books with more than 100 in stock. We can deal with this in various ways, see the next section.

Element reference expressions

51:02 Based on a question from me going back to the CDL definition of nonSeller, and how it is basically a reference to an existing element (books), Patrice shows that this is a pattern that works generally. For example, we add an origin element that just points to placeOfBirth:

entity Authors : managed {
  key ID            : Integer;
      name          : String(111) @mandatory;
      address       : Association to Addresses;
      academicTitle : String(111);
      dateOfBirth   : Date;
      dateOfDeath   : Date;
      placeOfBirth  : String;
      placeOfDeath  : String;
      books         : Association to many Books
                        on books.author = $self;

      nonSeller = books[stock > 100];

      origin = placeOfBirth;

      isAlive       : Boolean = dateOfDeath is null ? true : false;
      age           : Integer = years_between(
        dateOfBirth, coalesce(
          dateOfDeath, current_date
        )
      );
}

Essentially this is just another calculated element, albeit a very simple one! Patrice gives another example:

name          : String(111) @mandatory;
academicTitle : String(10);
fullName = academicTitle || ' ' || name;

The type of fullName here is implicit but we can make it explicit:

fullName : String = academicTitle || ' ' || name;

like we have done for the isAlive and age elements.

A look at the EXISTS predicate

54:54 At this point we go back to the dataset that was produced from the query SELECT from ${Authors} { name, nonSeller.title }, in particular with the two author records with null for nonSeller_title. What if we wanted to exclude such authors, i.e. only include authors with non-sellers?

Patrice first shows us an option that is available to us, but one which we probably want to avoid, as it is a little clumsy, involves a somewhat technical approach:

> await cds.ql`select from ${Authors} { name } where nonSeller.ID is not null`
[
  { name: 'Edgar Allen Poe' },
  { name: 'Edgar Allen Poe' },
  { name: 'Richard Carpenter' },
  { name: 'Brandon Sanderson' },
  { name: 'Brandon Sanderson' },
  { name: 'Brandon Sanderson' },
  { name: 'Brandon Sanderson' },
  { name: 'J. R. R. Tolkien' },
  { name: 'J. R. R. Tolkien' },
  { name: 'J. R. R. Tolkien' },
  { name: 'J. R. R. Tolkien' },
  { name: 'J. R. R. Tolkien' }
]

Moreover, there is still an issue with the authors that do have non-sellers - there are duplicate records returned. This is a natural consequence of the to-many relationship:

entity Authors : managed {
  key ID            : Integer;
      name          : String(111) @mandatory;

      ...

      books         : Association to many Books
                        on books.author = $self;

      nonSeller = books[stock > 100];

      ...
}

and is essentially the result of a LEFT JOIN that traverses it.

A much better approach is to use the prefix operator EXISTS:

> await cds.ql`select from ${Authors} { name } where exists nonSeller`
[
  { name: 'Edgar Allen Poe' },
  { name: 'Richard Carpenter' },
  { name: 'Brandon Sanderson' },
  { name: 'J. R. R. Tolkien' }
]

This is almost magic! The expression used as the operand here is simply nonSeller, i.e. a reference to the association, to the relationship. It's the closest we can get to how we'd say it in English.

By now, we know how to look under the hood for this - we can trace the steps from this CQL and CXL ... through the various stages. First, here's what the "CAP style CQN" looks like:

> q = cds.ql`select from ${Authors} { name } where exists nonSeller`
cds.ql {
  SELECT: {
    from: { ref: [ 'sap.capire.bookshop.Authors' ] },
    columns: [ { ref: [ 'name' ] } ],
    where: [ 'exists', { ref: [ 'nonSeller' ] } ]
  }
}

Notice that the simple association name nonSeller here (as the target of exists, i.e. { ref: [ 'nonSeller' ]}) is perfectly valid according to the syntax diagram we looked at earlier in our first look at path expressions.

Next, we can see the normalised "CAP style SQL":

> q.forSQL()
cds.ql {
  SELECT: {
    from: { ref: [ 'sap.capire.bookshop.Authors' ], as: 'Authors' },
    columns: [ { ref: [ 'Authors', 'name' ] } ],
    where: [
      'exists',
      {
        SELECT: {
          from: { ref: [ 'sap.capire.bookshop.Books' ], as: 'nonSeller' },
          columns: [ { val: 1 } ],
          where: [
            {
              xpr: [
                { ref: [ 'nonSeller', 'author_ID' ] },
                '=',
                { ref: [ 'Authors', 'ID' ] }
              ]
            },
            'and',
            { xpr: [ { ref: [ 'nonSeller', 'stock' ] }, '>', { val: 100 } ] }
          ]
        }
      }
    ]
  }
}

Here are some observations on this:

the SELECT is on the Authors entity, as we expect
the WHERE clause is essentially the EXISTS predicate
the predicate's target (or focus) is a complete subquery
this subquery represents the association and is on the Books
a Boolean value is expected from this subquery
that value is represented by the dummy literal value { val: 1 }

What's not changed subquery's WHERE clause is exactly the same as what was in the on clause in the earlier query in the previous association-like calculated element section, representing the combined conditions of books.author = $self and stock > 100.

So moving from a LEFT JOIN to an EXISTS with a subquery ... moves us from duplicate data from the left part of the relationship, to unique values, as what's returned from this subquery is either something ({ val: 1 }) or nothing.

01:01:16 To underline the power and utility of this predicate, Patrice rounds the episode off with another example, contrasting the two approaches and result sets, based on the books from Brandon Sanderson, two of which include the word "Mistborn":

> await cds.ql`
  select title from ${Books} where author.name like '%Sanderson'
  `
[
  { title: 'Mistborn: The Final Empire' },
  { title: 'The Well of Ascension' },
  { title: 'The Lost Metal' },
  { title: 'Mistborn: Secret History' },
  { title: 'The Way of Kings' },
  { title: '...' },
  { title: 'Wind and Truth' }
]

First, the less convenient approach:

> q = cds.ql`
  select from ${Authors} { name }
  where books.title like '%Mistborn%'
  `
cds.ql {
  SELECT: {
    from: { ref: [ 'sap.capire.bookshop.Authors' ] },
    columns: [ { ref: [ 'name' ] } ],
    where: [ { ref: [ 'books', 'title' ] }, 'like', { val: '%Mistborn%' } ]
  }
}
> await q
[
  { name: 'Brandon Sanderson' },
  { name: 'Brandon Sanderson' }
]

And then the approach using EXISTS:

> q = cds.ql`
  select from ${Authors} { name }
  where exists books[title like '%Mistborn%']
  `
cds.ql {
  SELECT: {
    from: { ref: [ 'sap.capire.bookshop.Authors' ] },
    columns: [ { ref: [ 'name' ] } ],
    where: [
      'exists',
      {
        ref: [
          {
            id: 'books',
            where: [ { ref: [ 'title' ] }, 'like', { val: '%Mistborn%' } ]
          }
        ]
      }
    ]
  }
}
> await q
[
  { name: 'Brandon Sanderson' }
]

The EXISTS predicate is an essential item in your expression toolkit for checking across to-many relationships.

Further info

Patrice also has some great notes for this part.

CDS expressions in CAP - notes on Part 3

2026-03-23T00:00:00Z

See the series post for an overview of all the episodes.

Introduction

00:00 Introduction.

03:12 Patrice confirms that the constraints that we looked at in the previous part are checked in an "after" phase handler.

Revisiting core CXL building blocks

05:55 Patrice jumps into the cds REPL to revisit some of the CXL building blocks, such as literals:

> cds.parse.expr` 1 `
{ val: 1 }
> cds.parse.expr` true `
{ val: true }

unary operators:

> cds.parse.expr` +1 `
{ xpr: [ '+', { val: 1 } ] }

binary operators, including some that are common in programming languages, such as != which is translated to IS NOT in SQL:

> cds.ql`SELECT title from ${Books} where stock != null`.toSQL()
{
  sql: 'SELECT title AS "title" FROM (
    SELECT "$B".title
    FROM sap_capire_bookshop_Books as "$B"
    WHERE "$B".stock is not NULL
  )',
  values: []
}

This is simplified SQL without JSON, in a cds REPL session invoked thus:
CDS_FEATURES_SQL__SIMPLE__QUERIES=2 cds r -r .

Functions, CAST and predicates

09:58 Next up is a look at the function syntax, which Patrice shows with an example in the cds REPL, emphasising that the arguments are just expressions:

> cds.parse.expr` someFunction( (1+1), true ) `
{
  func: 'someFunction',
  args: [ { xpr: [ { val: 1 }, '+', { val: 1 } ] }, { val: true } ]
}

17:25 We take a brief look at CAST, a special function:

> cds.parse.expr` cast( 1 as String ) `
{ val: 1, cast: { type: 'String' } }

19:06 And then we look at the family of predicates available, such as [NOT] LIKE, IS [NOT] NULL, [NOT] BETWEEN ... AND ..., [NOT] IN ( ... ) and [NOT] EXISTS ....

Adding a calculated element

21:50 Patrice shows an example at the "db" level in the db/schema.cds file, by adding a calculated element (the sort that we might alternatively find in queries, i.e. in CQL) to the CDL definition of the Authors entity which currently looks like this:

entity Authors : managed {
  key ID            : Integer;
      name          : String(111) @mandatory;
      address       : Association to Addresses;
      academicTitle : String(111);
      dateOfBirth   : Date;
      dateOfDeath   : Date;
      placeOfBirth  : String;
      placeOfDeath  : String;
      books         : Association to many Books
                        on books.author = $self;
}

Adding a Boolean element isAlive can be done via an expression, in various ways, such as:

isAlive : Boolean = case
  when dateOfDeath is null then true
  else false
end;

Or with the concise ternary expression beloved of JavaScript (and other) programmers:

isAlive : Boolean = dateOfDeath is null ? true : false

Of course, this was purely to illustrate the ? : syntax; an even less verbose version would be:
isAlive : Boolean = dateOfDeath is null;

24:00 This calculated element is virtual, i.e. not manifested in the underlying table definition, which Patrice shows with:

cds compile -2 sql db/schema.cds

which emits this DDL, with no sign of the isAlive field:

CREATE TABLE sap_capire_bookshop_Authors (
  createdAt TIMESTAMP_TEXT,
  createdBy NVARCHAR(255),
  modifiedAt TIMESTAMP_TEXT,
  modifiedBy NVARCHAR(255),
  ID INTEGER NOT NULL,
  name NVARCHAR(111),
  address_ID INTEGER,
  academicTitle NVARCHAR(111),
  dateOfBirth DATE_TEXT,
  dateOfDeath DATE_TEXT,
  placeOfBirth NVARCHAR(255),
  placeOfDeath NVARCHAR(255),
  PRIMARY KEY(ID)
);

The calculated element only plays a role in queries, and in the context of views or projections. And we have one of those, in the form of the AdminService which looks like this:

using {sap.capire.bookshop as my} from '../db/schema';

service AdminService {
  entity Books   as projection on my.Books;
  entity Authors as projection on my.Authors;
}

// ...

Compiling srv/admin-service.cds:

cds compile -2 sql srv/admin-service.cds

shows us where this manifests, in the DDL for this Authors projection:

CREATE VIEW AdminService_Authors AS SELECT
  Authors_0.createdAt,
  Authors_0.createdBy,
  Authors_0.modifiedAt,
  Authors_0.modifiedBy,
  Authors_0.ID,
  Authors_0.name,
  Authors_0.address_ID,
  Authors_0.academicTitle,
  Authors_0.dateOfBirth,
  Authors_0.dateOfDeath,
  Authors_0.placeOfBirth,
  Authors_0.placeOfDeath,
  CASE WHEN Authors_0.dateOfDeath IS NULL THEN TRUE ELSE FALSE END AS isAlive
FROM sap_capire_bookshop_Authors AS Authors_0;

This, incidentally, is a great example of both shifting left and down, where the convenience mechanism that results in an isAlive Boolean value is not calculated by any requester (based on the dateOfDeath value that is available, once the dataset has been retrieved), or added to any transient dynamic queries, or even added as adornments to one or more service definitions that have projections on the authors data.

Instead, it is defined once, quietly and gently, at the "db" level, and reified where appropriate, and available automatically. As Patrice puts it a bit later on, this is "centralising our common expressions into one place - our domain model".

See the Further info section for links to more reading on this.

26:40 In the context of a question asked by VishalK, Patrice notes that there are two forms of calculated elements, on-read (as here) and also on-write.

28:20 Patrice illustrates the expression that has been constructed (in CXN) for this isAlive calculated element by looking directly at it in the cds REPL:

> Authors.elements['isAlive']
Boolean {
  '@Core.Computed': true,
  type: 'cds.Boolean',
  value: {
    xpr: [
      'case',
      'when',
      { ref: [ 'dateOfDeath' ] },
      'is',
      'null',
      'then',
      { val: true },
      'else',
      { val: false },
      'end'
    ]
  }
}

Using the calculated element in queries

29:26 Having looked at how the calculated element at the "db" level is manifested in the DDL for the AdminService's projection, Patrice now shows how it comes into play in a query, in the cds REPL:

> await cds.ql`
  SELECT from ${Books} { title, author.name }
  where author.isAlive = true
  `
[
  { title: 'Mistborn: The Final Empire', author_name: 'Brandon Sanderson' },
  { title: 'The Well of Ascension', author_name: 'Brandon Sanderson' },
  ...
  { title: 'Wind and Truth', author_name: 'Brandon Sanderson' }
]

The condition could be written more simply as where author.isAlive here too.

An illustration of the opposite might look like this (again, using terser condition syntax, instead of, say, where isAlive = false):

> await cds.ql`
  SELECT from ${Authors} { name, books.title }
  where isAlive = false
  `
[
  { name: 'Emily Brontë', books_title: 'Wuthering Heights' },
  { name: 'Charlotte Brontë', books_title: 'Jane Eyre' },
  { name: 'Edgar Allen Poe', books_title: 'Eleonora' },
  { name: 'Edgar Allen Poe', books_title: 'The Raven' },
  { name: 'Richard Carpenter', books_title: 'Catweazle' },
  { name: 'J. R. R. Tolkien', books_title: 'Beren and Lúthien' },
  { name: 'J. R. R. Tolkien', books_title: 'The Children of Húrin' },
  ...
  { name: 'J. R. R. Tolkien', books_title: 'Unfinished Tales' }
]

Here also the condition could be written more simply as where not isAlive.

Target references

33:11 There was a brief discussion about the "Books" reference in the previous query, which looked like this:

SELECT from ${Books}

This is the more precise approach to specifying the target of the query - the entity represented by (contained in) the Books variable injected into the cds REPL session, which resolves thus:

> Books.name
sap.capire.bookshop.Books

When we use a literal value instead, like this:

SELECT from Books

then CAP can often resolve the reference, but caution must be used here in case there are other entities, in different scopes, but with the same name; in this case using the template string interpolation (${ ... }) will allow us to be specific.

Query details and the phased translation to native SQL

35:05 At this point Patrice digs in a little deeper to the query. First, from the CQL (which was then modified at 36:25, so that the from reference is to sap.capire.bookshop.Books rather than just Books), we see the CQN representation which includes an expression notation for the isAlive check:

> q = cds.ql`
  SELECT from ${Books} { title, author.name }
  where author.isAlive = false
  `
cds.ql {
  SELECT: {
    from: { ref: [ 'sap.capire.bookshop.Books' ] },
    columns: [ { ref: [ 'title' ] }, { ref: [ 'author', 'name' ] } ],
    where: [ { ref: [ 'author', 'isAlive' ] }, '=', { val: false } ]
  }
}

Using the toSQL() method on the query object, we see the SQL¹ and the injectable values:

> q.toSQL()
{
  sql: `SELECT json_insert('{}','$."title"',title,'$."author_name"',author_name) as _json_ FROM (SELECT Books.title,author.name as author_name FROM sap_capire_bookshop_Books as Books left JOIN sap_capire_bookshop_Authors as author ON author.ID = Books.author_ID WHERE (case when author.dateOfDeath is null then ? else ? end) = ?)`,
  values: [ 1, 0, 0 ]
}

And the SQL, when formatted nicely, looks like this:

SELECT
  json_insert(
    '{}', '$."title"', title, '$."author_name"', author_name
  ) as _json_
FROM
  (
    SELECT
      Books.title,
      author.name as author_name
    FROM sap_capire_bookshop_Books as Books
      left JOIN sap_capire_bookshop_Authors as author
      ON author.ID = Books.author_ID
    WHERE
      (
        case
          when author.dateOfDeath is null then ?
          else ?
        end
      ) = ?
  )

38:30 We've jumped from CQL almost directly to the (SQLite dialect² of) SQL here, but Patrice now explains the multi-step process here.

Between the CQL (and CXL), and its machine-readable CQN (and CXN) equivalents, and the ultimate persistence-layer-specific SQL, there's an intermediate "normalised" format. This is often referred to as "CAP-style SQL", or the "SQL variant of CQL". Using the forSQL() method on the query object (as opposed to the toSQL() we used just now), we can get this intermediate format:

> q.forSQL()
cds.ql {
  SELECT: {
    from: {
      join: 'left',
      args: [
        { ref: [ 'sap.capire.bookshop.Books' ], as: 'Books' },
        { ref: [ 'sap.capire.bookshop.Authors' ], as: 'author' }
      ],
      on: [
        { ref: [ 'author', 'ID' ] },
        '=',
        { ref: [ 'Books', 'author_ID' ] }
      ]
    },
    columns: [
      { ref: [ 'Books', 'title' ] },
      { ref: [ 'author', 'name' ], as: 'author_name' }
    ],
    where: [
      {
        xpr: [
          'case',
          'when',
          { ref: [ 'author', 'dateOfDeath' ] },
          'is',
          'null',
          'then',
          { val: true },
          'else',
          { val: false },
          'end'
        ]
      },
      '=',
      { val: false }
    ]
  }
}

As we can see, we can recognise both CXL (CXN) style expressions, as well as SQL-style constructions such as JOINs. At this point this is is still in a form that is not SQL database system specific (i.e. not SQLite, Postgres or HANA specific SQL).

And as opposed to this neutral "normalised" format from forSQL(), we get the database-specific dialect with toSQL().

A question on WITH ASSOCIATIONS and the previous db adapters

41:20 At this point ArtlessSoul asks a question to which Patrice responds by explaining the difference between how path expressions were handled (translated to SQL) in the now-legacy database services which were in play before the current major CAP version.

It had not been possible at the time to transform all path expressions to the required JOINs that would be needed to represent them at a SQL level. One way to address this at the time, specifically for HANA, had been to push down such associations to the database, which supported them with a WITH ASSOCIATIONS native feature (see the Native Associations section of the SAP HANA topic in Capire).

While HANA would be the typical target database runtime for production, it had thus not been previously possible to test associations in development, i.e. outside the HANA context.

But thanks to the new database adapters with the current major release, all associations are possible for all supported databases due to improvements in how they're managed and translated by the CAP runtime, and therefore a much higher development and testing confidence can be achieved.

Exploring function expressions

45:01 Patrice starts to round off this episode with a nice example to illustrate function expressions. The example is another calculated element on the Authors entity, for the author's age:

age : Integer = years_between(dateOfBirth, coalesce(dateOfDeath, current_date));

46:38 But before continuing, he connects and deploys to the HANA Cloud service he has already set up in his account, following the same connection and deployment to HANA procedure from part 2, and then at 48:20 he starts the cds REPL using the hybrid profile, also following the same procedure from part 2 (see the Going hybrid section of part 2's notes for details).

49:10 At this point we take a look at what happens under the hood -- in HANA -- for this new age element, step by step.

First, step 1, from CQL to CQN and the query object:

> q = cds.ql`SELECT from ${Authors} { name, age }`
cds.ql {
  SELECT: {
    from: { ref: [ 'sap.capire.bookshop.Authors' ] },
    columns: [ { ref: [ 'name' ] }, { ref: [ 'age' ] } ]
  }
}

Next, step 2, taking a look at the intermediate "normalised" version of the query, using forSQL():

> q.forSQL()
cds.ql {
  SELECT: {
    from: { ref: [ 'sap.capire.bookshop.Authors' ], as: 'Authors' },
    columns: [
      { ref: [ 'Authors', 'name' ] },
      {
        args: [
          { ref: [ 'Authors', 'dateOfBirth' ] },
          {
            func: 'coalesce',
            args: [
              { ref: [ 'Authors', 'dateOfDeath' ] },
              { func: 'current_date' }
            ]
          }
        ],
        func: 'years_between',
        as: 'age'
      }
    ]
  }
}

From a column perspective, there are two:

a reference to the name element in sap.capire.bookshop.Authors
the evaluation of a function years_between, the arguments to which are
- a reference to the dateOfBirth element
- the evaluation of another function coalesce, the arguments to which are
  - a reference to the dateOfDeath element
  - the evaluation of yet another function current_date

Running this query gives us what we expect:

> await q
[
  { age: 30, name: 'Emily Brontë' },
  { age: 36, name: 'Charlotte Brontë' },
  { age: 40, name: 'Edgar Allen Poe' },
  { age: 82, name: 'Richard Carpenter' },
  { age: 50, name: 'Brandon Sanderson' },
  { age: 81, name: 'J. R. R. Tolkien' }
]

51:05 After adding the isAlive element back into the query, Patrice now takes a look at the actual SQL resolved for this query ... in the context of the hybrid profile, which means in the context of a HANA database:

> cds.ql`SELECT from ${Authors} {name, age, isAlive }`.toSQL().sql

This results in SQL that, when formatted, looks like this:

SELECT
  Authors.name as "name",
  years_between (
    Authors.dateOfBirth,
    coalesce(Authors.dateOfDeath, current_utcdate)
  ) as "age",
  case
    when Authors.dateOfDeath is null then true
    else false
  end as "isAlive"
FROM
  sap_capire_bookshop_Authors as Authors

There's pretty much a 1-to-1 correlation between the CDL we have used to define our Authors entity, and the HANA-flavoured SQL here.

Portable functions

And that's because HANA implements the years_between function natively. Unlike SQLite, for which more heavy lifting is done by the compiler team, to essentially provide us with "a set of portable functions (and also operators) which are automatically translated for us to the best-possible database-specific native SQL equivalents". That quote is from Capire's CAP-Level Database Support topic which is well worth a read.

52:47 To illustrate this, Patrice starts a new cds REPL session in the context of the default (development) profile which implies SQLite:

cds repl --run .

This time, the same query (SELECT from ${Authors} { name, age }) results in the same CQN of course, as well as the same normalised CAP-style SQL (via forSQL()) as before, but the resulting database-specific SQL(via toSQL().sql) is quite different³:

SELECT
  json_insert ('{}', '$."name"', name, '$."age"', age) as _json_
FROM
  (
    SELECT
      "Authors".name,
      floor(
        (
          (
            (
              cast(
                strftime ('%Y', coalesce("Authors".dateOfDeath, current_date)) as Integer
              ) - cast(strftime ('%Y', "Authors".dateOfBirth) as Integer)
            ) * 12
          ) + (
            cast(
              strftime ('%m', coalesce("Authors".dateOfDeath, current_date)) as Integer
            ) - cast(strftime ('%m', "Authors".dateOfBirth) as Integer)
          ) + (
            (
              case
                when (
                  cast(
                    strftime ('%Y%m', coalesce("Authors".dateOfDeath, current_date)) as Integer
                  ) < cast(strftime ('%Y%m', "Authors".dateOfBirth) as Integer)
                ) then (
                  cast(
                    strftime (
                      '%d%H%M%S%f0000',
                      coalesce("Authors".dateOfDeath, current_date)
                    ) as Integer
                  ) > cast(
                    strftime ('%d%H%M%S%f0000', "Authors".dateOfBirth) as Integer
                  )
                )
                else (
                  cast(
                    strftime (
                      '%d%H%M%S%f0000',
                      coalesce("Authors".dateOfDeath, current_date)
                    ) as Integer
                  ) < cast(
                    strftime ('%d%H%M%S%f0000', "Authors".dateOfBirth) as Integer
                  )
                ) * -1
              end
            )
          )
        ) / 12
      ) as age
    FROM
      sap_capire_bookshop_Authors as "Authors"
  )

As Patrice reminds us, this is another example of AXI001 What not how in action.

56:45 To wrap this section up, Patrice adds back in the isAlive element to the query before executing it, to show that this works too, albeit resulting in a different⁴ representation of true and false, as SQLite has no Boolean data type:

> await cds.ql`SELECT from ${Authors} {name, age, isAlive }`
[
  { name: 'Emily Brontë', age: 30, isAlive: 0 },
  { name: 'Charlotte Brontë', age: 36, isAlive: 0 },
  { name: 'Edgar Allen Poe', age: 40, isAlive: 0 },
  { name: 'Richard Carpenter', age: 82, isAlive: 0 },
  { name: 'Brandon Sanderson', age: 50, isAlive: 1 },
  { name: 'J. R. R. Tolkien', age: 81, isAlive: 0 }
]

Support in CDL as well as CQL

58:25 Wrapping up, Patrice makes the very good point that this portability afforded by CAP to support different database runtimes is not only at the "runtime" level, i.e. in queries (as we've seen in these examples), but also at the persistence, or data definition level (in particular for views). To illustrate this, Patrice shows us that the view DDL is constructed appropriately, first in the production profile context, i.e. for HANA:

; cds build --production
building project with {
  versions: { cds: '9.8.0', compiler: '6.8.0', dk: '9.4.3' },
  target: 'gen',
  tasks: [
    { src: 'db', for: 'hana', options: { model: [ 'db', 'srv', '@sap/cds/srv/outbox' ] } },
    { src: 'srv', for: 'nodejs', options: { model: [ 'db', 'srv', '@sap/cds/srv/outbox' ] } }
  ]
}
done > wrote output to:
   gen/db/package.json
   gen/db/src/.hdiconfig
   gen/db/src/gen/.hdiconfig
   gen/db/src/gen/.hdinamespace
   gen/db/src/gen/AdminService.Authors.hdbview
   gen/db/src/gen/AdminService.Books.hdbview
   ... more. Run with DEBUG=build to show all files.

build completed in 2438 ms

The DDL for the Authors projection in the AdminService (in gen/db/src/gen/AdminService.Authors.hdbview) looks like this, where the HANA native years_between function is available:

VIEW AdminService_Authors AS SELECT
  Authors_0.createdAt,
  Authors_0.createdBy,
  Authors_0.modifiedAt,
  Authors_0.modifiedBy,
  Authors_0.ID,
  Authors_0.name,
  Authors_0.address_ID,
  Authors_0.academicTitle,
  Authors_0.dateOfBirth,
  Authors_0.dateOfDeath,
  Authors_0.placeOfBirth,
  Authors_0.placeOfDeath,
  CASE WHEN Authors_0.dateOfDeath IS NULL THEN TRUE ELSE FALSE END AS isAlive,
  years_between(Authors_0.dateOfBirth, coalesce(Authors_0.dateOfDeath, current_date)) AS age
FROM sap_capire_bookshop_Authors AS Authors_0

In contrast, when, like earlier, we compile the AdminService definitions in the default development profile context i.e. for SQLite:

cds compile -2 sql srv/admin-service.cds

we get this for the Authors projection:

CREATE VIEW AdminService_Authors AS
SELECT
  Authors_0.createdAt,
  Authors_0.createdBy,
  Authors_0.modifiedAt,
  Authors_0.modifiedBy,
  Authors_0.ID,
  Authors_0.name,
  Authors_0.address_ID,
  Authors_0.academicTitle,
  Authors_0.dateOfBirth,
  Authors_0.dateOfDeath,
  Authors_0.placeOfBirth,
  Authors_0.placeOfDeath,
  CASE
    WHEN Authors_0.dateOfDeath IS NULL THEN TRUE
    ELSE FALSE
  END AS isAlive,
  floor(
    (
      (
        (
          (
            CAST(
              strftime (
                '%Y',
                coalesce(Authors_0.dateOfDeath, current_date)
              ) AS Integer
            ) - CAST(strftime ('%Y', Authors_0.dateOfBirth) AS Integer)
          ) * 12
        ) + (
          CAST(
            strftime (
              '%m',
              coalesce(Authors_0.dateOfDeath, current_date)
            ) AS Integer
          ) - CAST(strftime ('%m', Authors_0.dateOfBirth) AS Integer)
        ) + (
          CASE /* For backward intervals: if the composite (day + time) of y is greater than x, add 1. */
            WHEN CAST(
              strftime (
                '%Y%m',
                coalesce(Authors_0.dateOfDeath, current_date)
              ) AS Integer
            ) < CAST(
              strftime ('%Y%m', Authors_0.dateOfBirth) AS Integer
            ) THEN (
              CAST(
                strftime (
                  '%d%H%M%S%f0000',
                  coalesce(Authors_0.dateOfDeath, current_date)
                ) AS Integer
              ) > CAST(
                strftime ('%d%H%M%S%f0000', Authors_0.dateOfBirth) AS Integer
              )
            ) /* For forward intervals: if the composite of y is less than x, subtract 1. */
            ELSE (
              CAST(
                strftime (
                  '%d%H%M%S%f0000',
                  coalesce(Authors_0.dateOfDeath, current_date)
                ) AS Integer
              ) < CAST(
                strftime ('%d%H%M%S%f0000', Authors_0.dateOfBirth) AS Integer
              )
            ) * -1
          END
        )
      )
    ) / 12
  ) AS age
FROM
  sap_capire_bookshop_Authors AS Authors_0;

Phew!

Further info

Footnotes

This is what was show on Patrice's screen; what you will likely get instead is SQL that is almost the same, except that a technical alias name is used for the FROM target, i.e. you will likely see "$B" instead of Books, like this:

SELECT
  json_insert(
    '{}', '$."title"', title, '$."author_name"', author_name
  ) as _json_
FROM
  (
    SELECT
      "$B".title,
      author.name as author_name
    FROM sap_capire_bookshop_Books as "$B"
      left JOIN sap_capire_bookshop_Authors as author
      ON author.ID = "$B".author_ID
    WHERE
      (
        case
          when author.dateOfDeath is null then ?
          else ?
        end
      ) = ?
  )

Technical aliases are discussed in a later episode in this series.

The SQL that we see here is the SQLite dialect as we're running in development mode by default.
Notice that the coalesce function is available natively not only in HANA but also in SQLite.

When using the hybrid profile and connected to HANA, this is how the query runs:

> await cds.ql`SELECT from ${Authors} {name, age, isAlive }`
[
  { age: 30, isAlive: false, name: 'Emily Brontë' },
  { age: 36, isAlive: false, name: 'Charlotte Brontë' },
  { age: 40, isAlive: false, name: 'Edgar Allen Poe' },
  { age: 82, isAlive: false, name: 'Richard Carpenter' },
  { age: 50, isAlive: true, name: 'Brandon Sanderson' },
  { age: 81, isAlive: false, name: 'J. R. R. Tolkien' }
]

CDS expressions in CAP - notes on Part 2

2026-03-09T00:00:00Z

See the series post for an overview of all the episodes.

Introduction

00:00 A rather lengthy introduction and recap (sorry Patrice!).

The case-when-then-else-end expression

09:30 Patrice reviews and re-explains the CASE ... WHEN ... THEN ... ELSE ... END expression in the @assert annotation, noting that if neither of the conditions match then the expression evaluates to null:

annotate AdminService.Books:stock with @assert: (
  case
    when stock < 0 then 'stock must not be negative'
    when stock > 1000 then 'stock exceeds maximum limit of 1000'
  end
);

13:15 Starting the cds REPL with DEBUG=sql to see what happens under the hood:

DEBUG=sql cds r --run .

Immediately we see many SQL statements being executed due to the automatic deployment to the in-memory SQLite database that's used:

DROP VIEW IF EXISTS ...
DROP TABLE IF EXISTS ...
CREATE TABLE ...
INSERT INTO ...

15:15 Patrice explains what we missed in the previous part - the db service does not have the hook for the assertion, it's the AdminService that does, and that's because it lives not in the DB service but in the Application Service.

22:00 At this point Patrice explains what actually happened, by following the detail emitted in the SQL debug output. There's also a dedicated blog post on this detail: Constraints, expressions and axioms in action.

The key SQL statement that we focused on was this one:

SELECT
  Books.ID,
  case
      when Books.stock < ? then ?
      when Books.stock > ? then >
  end as "@assert:stock"
FROM AdminService_Books as Books
WHERE (Books.ID) in ((?), (?))

This is executed within the transaction, straight after the record insertion, and, in the @assert:stock alias, surfaces either nothing or an error string (from the expression in the @assert annotation above); the selection is restricted to the two records specifically just inserted. If something (i.e. an error string) is surfaced from this, then the entire transaction is aborted and rolled back.

31:20 While some checks are done implicitly in the "before" phase, such as in the built-in validate_input here:

> AdminService.handlers
EventHandlers {
  _initial: [
    {
      before: '*',
      handler: [Function: check_service_level_restrictions]
    },
    { before: '*', handler: [Function: check_auth_privileges] },
    { before: '*', handler: [Function: check_readonly] },
    { before: '*', handler: [Function: check_insertonly] },
    { before: '*', handler: [Function: check_odata_constraints] },
    { before: '*', handler: [Function: check_autoexposed] },
    { before: '*', handler: [AsyncFunction: enforce_auth] },
    { before: 'READ', handler: [Function: restrict_expand] },
    { before: 'CREATE', handler: [AsyncFunction: validate_input] },
    { before: 'UPDATE', handler: [AsyncFunction: validate_input] },
    { before: 'NEW', handler: [AsyncFunction: validate_input] },
    { before: 'READ', handler: [Function: handle_paging] },
    { before: 'READ', handler: [Function: handle_sorting] }
  ],
  ...
}

... such declarative constraints are checked in an "after" phase handler - see the notes to part 3 of this series for a clarification.

A question on reusable expressions

31:30 At this point we start to look at one of the two questions that were asked at the very end of part 1 by Ben: "Would it be possible to build an expression and then re-use it for different assertions?".

Patrice's answer was based on CAP's embrace of aspect orientation, specifically at the "db" level, in db/schema.cds. First, an aspect defined thus:

aspect ConstrainedTitle {
  @assert: (
    case
      when length(title) < 2 then 'title must be at least 2 characters long'
    end
  )
  title : String @mandatory;
}

and employed like this (where the basic Books entity definition does not now have its own title element):

entity Books : managed, ConstrainedTitle {
  key ID    : Integer;
  descr     : localized String(1111);
  ...
}

Looking at the CSN, we see that this constraint is included in the AdminService as we'd expect:

; echo 'AdminService.entities.Books.elements.title' | cds r -r .
...
String {
  '@assert': {
    '=': "case when length(title) < 2 then 'title must be at least 2 characters long' end",
    xpr: [
      'case',
      'when',
      {
        func: 'length',
        args: [ { ref: [ 'title' ] } ]
      },
      '<',
      { val: 2 },
      'then',
      { val: 'title must be at least 2 characters long' },
      'end'
    ]
  },
  '@mandatory': true,
  type: 'cds.String',
  '@Common.FieldControl': { '#': 'Mandatory' }
}

36:56 This constraint annotation is propagated up to the "service" level where there's a projection on the Books entity. Patrice also points out here something that we might not expect, but happens anyway thanks to the compiler ... even if we change the name of the element, say from title to mytitle in the projection, the expression is modified accordingly!

To see this in action, here's a temporary modification to the Books projection in the AdminService, renaming the title element to mytitle:

using {sap.capire.bookshop as my} from '../db/schema';

service AdminService {
  entity Books   as
    projection on my.Books {
      *,
      title as mytitle
    }
    excluding { title }

  ...
}

The change is effected not only at the element level, but within the expression too:

; echo 'AdminService.entities.Books.elements.mytitle' | cds r -r .
String {
  '@assert': {
    '=': true,
    xpr: [
      'case',
      'when',
      {
        func: 'length',
        args: [ { ref: [ 'mytitle' ] } ]
      },                     ^
      '<',                   |
      { val: 2 },            +--- modified within the expression
      'then',
      { val: 'title must be at least 2 characters long' },
      'end'
    ]
  },
  '@mandatory': true,
  type: 'cds.String',
  '@Common.FieldControl': { '#': 'Mandatory' }
}

This constraint works as expected, as we can see from this cds REPL session:

> { Books } = AdminService.entities
[object Function]
> insert = INSERT.into(Books).entries({ID:567,author_ID:180,title:"X",stock:1})
cds.ql {
  INSERT: {
    into: { ref: [ 'AdminService.Books' ] },
    entries: [ { ID: 567, author_ID: 180, title: 'X', stock: 1 } ]
  }
}
> await AdminService.run(insert)
Uncaught:
{
  status: 400,
  code: 'ASSERT',
  target: 'title',
  message: 'title must be at least 2 characters long'
}

Connection and deployment to HANA

39:52 To show that this entire approach is portable across, and abstract from the underlying database systms supported by CAP, Patrice proceeds at this point to show the same thing but with HANA.

First, adding database support for HANA via the facet:

; cds add hana

Adding facet: hana

Successfully added features to your project

Amongst other things (such as creating db/undeploy.json), this adds @cap-js/hana as a dependency:

--- a/package.json
+++ b/package.json
@@ -3,6 +3,7 @@
   "version": "1.0.0",
   "description": "A simple CAP project.",
   "dependencies": {
+    "@cap-js/hana": "^2",
     "@sap/cds": "^9",
     "express": "^4"
   },

Which, when installed (with npm install), adds HANA specific DB parameters to the production profile, which we can see with:

; cds env requires.db --profile production
{
  impl: '@cap-js/hana',
  data: [ 'db/data', 'db/csv' ],
  pool: {
    min: 0,
    max: 10,
    acquireTimeoutMillis: 1000,
    idleTimeoutMillis: 60000,
    evictionRunIntervalMillis: 100000,
    numTestsPerEvictionRun: 10,
    testOnBorrow: true,
    fifo: false
  },
  kind: 'hana'
}

42:49 Now everything is ready for a deployment to HANA, which Patrice does at this point:

; cds deploy --to hana
building project with {
  versions: { cds: '9.8.0', compiler: '6.8.0', dk: '9.7.2' },
  target: 'gen',
  tasks: [
    { for: 'hana', src: 'db', options: { model: [ 'db', 'srv', '@sap/cds/srv/outbox' ] } }
  ]
}
done > wrote output to:
   gen/db/package.json
   gen/db/src/gen/.hdiconfig
   gen/db/src/gen/.hdinamespace
   gen/db/src/gen/AdminService.Authors.hdbview
   gen/db/src/gen/AdminService.Books.hdbview
   ...

build completed in 332 ms

using container cxl-bookshop-db
creating service cxl-bookshop-db - please be patient...
creating service key cxl-bookshop-db-key - please be patient...
starting deployment to SAP HANA ...
deploying to HANA from /work/gh/github.com/patricebender/cxl-bookshop/gen/db/
HDI deployer path: /home/dj/.npm-packages/lib/node_modules/@sap/cds-dk/node_modules/@sap/hdi-deploy/library.js
HDI deployer version: 5.6.1
VCAP_SERVICES:

{
  "hana": [
    {
      "name": "cxl-bookshop-db",
      "label": "hana",
      "credentials": {
        "schema": "4DCBA6B626C745E29947D848D3CCEE38",
        "database_id": "442316b0-3ec9-469c-b3ab-2d333c2ecf8f",
        "user": "4DCBA6B626C745E29947D848D3CCEE38_BROA7XLTTVAJ193W0CETRKJF2_RT",
        "hdi_user": "4DCBA6B626C745E29947D848D3CCEE38_BROA7XLTTVAJ193W0CETRKJF2_DT"
      },
      "tags": [
        "hana"
      ]
    }
  ]
}

...

Deployment started ...

   ... (lots of log output deleted)

   Processing work list... ok (2s 70ms)
   Finalizing... ok (0s 126ms)
   Make succeeded (0 warnings): 51 files deployed (effective 58), 0 files undeployed (effective 0), 0 dependent files redeployed
  Making... ok (4s 497ms)
  Enabling table replication for the container schema "4DCBA6B626C745E29947D848D3CCEE38"...
  Enabling table replication for the container schema "4DCBA6B626C745E29947D848D3CCEE38"... ok (0s 17ms)
 Starting make in the container "4DCBA6B626C745E29947D848D3CCEE38" with 51 files to deploy, 0 files to undeploy... ok (4s 586ms)

Deploying to the container "4DCBA6B626C745E29947D848D3CCEE38"... ok (10s 853ms)
...
Deployment ended ...
...
retrieving data from Cloud Foundry...
binding db to Cloud Foundry managed service cxl-bookshop-db:cxl-bookshop-db-key with kind hana
saving bindings to .cdsrc-private.json in profile hybrid
successfully finished deployment

Going hybrid

Right at the end we can see the bindings saved in a project-local .cdsrc-private.json file, under the "hybrid" profile name (see the Hybrid Testing topic in Capire); the binding information looks similar to this:

{
  "requires": {
    "[hybrid]": {
      "db": {
        "binding": {
          "type": "cf",
          "apiEndpoint": "https://api.cf.us10-001.hana.ondemand.com",
          "org": "38b4ec42trial",
          "space": "dev",
          "instance": "cxl-bookshop-db",
          "key": "cxl-bookshop-db-key"
        },
        "kind": "hana",
        "vcap": {
          "name": "db"
        }
      }
    }
  }
}

This binding information is then used to start a cds REPL session ... but in the context of the remote HANA database system¹:

; cds bind --exec --profile hybrid -- cds repl --run .
resolving cloud service bindings...
bound db to cf managed service cxl-bookshop-db:cxl-bookshop-db-key
Welcome to cds repl v 9.8.0
[cds] - using bindings from: { registry: '~/.cds-services.json' }
[cds] - loaded model from 4 file(s):

  srv/cat-service.cds
  srv/admin-service.cds
  db/schema.cds
  node_modules/@sap/cds/common.cds

[cds] - connect to db > hana {
  database_id: '442316b0-3ec9-469c-b3ab-2d333c2ecf8f',
  host: '442316b0-3ec9-469c-b3ab-2d333c2ecf8f.hna1.prod-us10.hanacloud.ondemand.com',
  port: '443',
  driver: 'com.sap.db.jdbc.Driver',
  url: 'jdbc:sap://442316b0-3ec9-469c-b3ab-2d333c2ecf8f.hna1.prod-us10.hanacloud.ondemand.com:443?encrypt=true&validateCertificate=true&currentschema=4DCBA6B626C745E29947D848D3CCEE38',
  schema: '4DCBA6B626C745E29947D848D3CCEE38',
  certificate: '...',
  hdi_user: '4DCBA6B626C745E29947D848D3CCEE38_BROA7XLTTVAJ193W0CETRKJF2_DT',
  hdi_password: '...',
  user: '4DCBA6B626C745E29947D848D3CCEE38_BROA7XLTTVAJ193W0CETRKJF2_RT',
  password: '...'
}
[cds] - using auth strategy { kind: 'mocked' }
[cds] - serving AdminService {
  at: [ '/odata/v4/admin' ],
  decl: 'srv/admin-service.cds:3'
}
[cds] - serving CatalogService {
  at: [ '/odata/v4/catalog' ],
  decl: 'srv/cat-service.cds:3'
}
[cds] - server listening on { url: 'http://localhost:45699' }
[cds] - server v9.8.0 launched in 555 ms
[cds] - [ terminate with ^C ]


------------------------------------------------------------------------
Following variables are made available in your repl's global context:

from cds.entities: {
  Books,
  Authors,
  Addresses,
  Cities,
  Genres,
  Orders,
  OrderItems,
}

from cds.services: {
  db,
  AdminService,
  CatalogService,
}

Simply type e.g. CatalogService in the prompt to use the respective objects.

This setup is now complete and we can see that the constraint works here on HANA just the same, too:

> { Books } = AdminService.entities
[object Function]
> await AdminService.run(INSERT.into(Books).entries({ ID:567, author_ID:180, title:"X", stock:1 }))
Uncaught:
{
  status: 400,
  code: 'ASSERT',
  target: 'title',
  message: 'title must be at least 2 characters long'
}

A question on iteration and aggregation in expressions

46:27 Next, Patrice turns to the second of the two questions asked in the previous episode, this time one from Stubbs: "Can we iterate over composition items with expressions? Example calculate order total amount using line item amounts?". I've written about the answer to this question in great detail in the post Path expressions, nested projections, aggregations and expressions in queries with CQL and CXL in CAP, so won't dwell any more on it in these notes here.

Exploring with cds.parse.expr

54:32 Rounding off this episode, Patrice explores some of the brand new documentation in Capire for CXL, and emphasises how easy it is to try things out in the cds REPL.

Starting out as simple as possible with just a literal:

> cds.parse.expr` 42 `
{ val: 42 }

Then with one of the unary operators not:

> cds.parse.expr` not foo `
{
  xpr: [ 'not', { ref: [ 'foo' ] } ]
}

And with the binary operator +, producing an expression made up of a literal ({ val: 1 }) followed by the binary operator '+' followed by another literal ({ val: 1}):

> cds.parse.expr` 1 + 1 `
{ xpr: [ { val: 1 }, '+', { val: 1 } ] }

With growing confidence we can now construct larger expressions, this time a predicate (based on the > binary operator):

> cds.parse.expr` (1 + 1) > (1 + 2) `
{
  xpr: [
    { xpr: [ { val: 1 }, '+', { val: 1 } ] },
    '>',
    { xpr: [ { val: 1 }, '+', { val: 2 } ] }
  ]
}

Definitely worth trying a few out yourself!

Further info

Patrice also has some great notes for this part.

Footnotes

The "hybrid" profile is used as default by cds bind so we can omit the --profile hybrid here:
```
cds bind --exec -- cds repl --run .
```

CDS expressions in CAP - notes on Part 1

2026-03-05T00:00:00Z

See the series post for an overview of all the episodes.

Introduction

00:00 Introductions.

05:00 A first look at expressions in the context of the new Declarative Constraints feature.

The family of CDS languages

06:00 An overview of CDS and the languages within the CDS family (CDL & CSN, CQL & CQN and CXL & CXN).

07:05 A first look at the "cxl-bookshop" project, specifically the entities and service definition. Patrice compiled (with cds compile db/schema.cds) the schema level definitions to show the relationship between the human-first CDL (Conceptual Definition Language) and the corresponding machine-first CSN (Core Schema Notation).

11:38 Next in the CDS language family overview is the human-first CQL (CDS Query Language) and corresponding machine-first equivalent CQN (CDS Query Notation). An example was given in the context of a cds REPL session (started with cds repl --run .). The example uses a postfix projection to specify the desired column (element), instead of the more SQL-like SELECT title from Books (the resulting query is the same):

> q = cds.ql` SELECT from Books { title }`
cds.ql {
  SELECT: {
    from: { ref: [ 'Books' ] },
    columns: [ { ref: [ 'title' ] } ]
  }
}

This shows the CQL and the corresponding CQN.

19:58 The final language pair, the human-first CXL (CDS Expression Language) and the corresponding machine-first CXN (CDS Expression Notation) (at this point the CXL documentation in Capire was still under construction, but exists now).

A first look at expressions

27:23 Looking at very simple expressions, trying out the (context-free) expression parser cds.parse.expr to parse a CXL expression to the internal CXN representation:

> cds.parse.expr` 1 `
{ val: 1 }

Here's one with a binary operator (+), taking two operands:

> cds.parse.expr` 1 + 1 `
{ xpr: [ { val: 1 }, '+', { val: 1 } ] }

29:01 An example in the context of declarative constraints, where validation is added to a service entity (which makes sense as they act as functional facets to the underlying persistence layer), in particular, to the stock element of the Books entity:

using {sap.capire.bookshop as my} from '../db/schema';

service AdminService {
  entity Books   as projection on my.Books;
  entity Authors as projection on my.Authors;
}

annotate AdminService.Books:stock with @assert: (
  case
    when stock < 0 then 'stock must not be negative'
    when stock > 1000 then 'stock exceeds maximum limit of 1000'
  end
);

Note that here we have:

the annotate directive (CDL)
the @assert annotation (also CDL)
the case ... when ... then ... end expression (CXL)

There was a brief discussion on how expressions in annotations should be enclosed in parentheses (as used in this annotation example), which also allows full compiler support and also code completion.

Exercising the constraint in the cds REPL

34:58 First, an overview of the entities:

> Object.keys(AdminService.entities)
[
  'Books',
  'Authors',
  'Genres',
  'Genres.texts',
  'Currencies',
  'Currencies.texts',
  'Books.texts'
]

and then some destructuring to get the Books entity from the AdminService:

{ Books } = AdminService.entities
[object Function]

Next, the construction of an INSERT query via the fluent API (the statement is split across multiple lines for readability; use the REPL's .editor command to paste in these multiple lines if you're playing along):

> insert = INSERT
.into(Books)
.entries(
  { ID:567, author_ID: 180, title: 'Foo', stock: -1 },
  { ID: 568, author_ID: 180, title: 'Foo 2', stock: 1001 }
)

which gives:

cds.ql {
  INSERT: {
    into: { ref: [ 'AdminService.Books' ] },
    entries: [
      { ID: 567, author_ID: 180, title: 'Foo', stock: -1 },
      { ID: 568, author_ID: 180, title: 'Foo 2', stock: 1001 }
    ]
  }
}

At this point, this query was awaited, with an unexpected result. That's because using await on a query object will by default invoke db.run(), sending that query object as an argument (i.e. db.run(insert) here). However, this db service is the "wrong" one - it's the persistence-layer database service, rather than the AdminService at which level we have our declarative constraint. This is why the insertion of the two new book records was successful (at 39:50).

Sending this to the AdminService to be executed:

> AdminService.run(insert)

shows us the result of the constraint:

> Uncaught [Error: MULTIPLE_ERRORS] {
  details: [
    {
      status: 400,
      code: 'ASSERT',
      target: 'stock',
      numericSeverity: 4,
      '@Common.numericSeverity': 4,
      message: 'stock must not be negative'
    },
    {
      status: 400,
      code: 'ASSERT',
      target: 'stock',
      numericSeverity: 4,
      '@Common.numericSeverity': 4,
      message: 'stock exceeds maximum limit of 1000'
    }
  ]
}

Comparing entity definitions at different layers

46:25 A brief comparison between the Books definition at the persistence ("db") level from cds.entities and the Books definition in the AdminService at the service ("srv") level. This is effectively the difference between A and B where:

using {sap.capire.bookshop as my} from '../db/schema';

service AdminService {
  entity Books as projection on my.Books;
           ^                       ^
           |                       |
           B                       A

A my.Books is from sap.capire.bookshop in db/schema
B Books is the entity defined in AdminService as a projection on my.Books in A

Comparing the artifacts and their CSN shows differences that all make sense (each of these comparisons shows A first, then B):

the artifacts' name properties (Books.name) are different: sap.capire.bookshop.Books vs AdminService.Books

reflecting this, the scope name prefixes are different in each reference, with A being sap.capire.bookshop and B being AdminService, for example:

author: Association {
  ...
  target: 'sap.capire.bookshop.Authors'
}

author: Association {
  ...
  target: 'AdminService.Authors'
}

each association in the service level CSN has an additional annotation @Common.ValueList.viaAssociation, for example (although we didn't dwell on this at all):

  genre: Association {
    type: 'cds.Association',
    target: 'AdminService.Genres',
    keys: [ { ref: [ 'ID' ], '$generatedFieldName': 'genre_ID' } ],
    '@Common.ValueList.viaAssociation': { '=': 'genre' }
  }

as pointed out in the conversation, the service level CSN has an extra projection property, which makes sense given how this is defined:
```
projection: { from: { ref: [ 'sap.capire.bookshop.Books' ] } }
```

And perhaps most significantly:

while the stock element at the persistence level is defined like this:

stock: Integer { type: 'cds.Integer' }

the projected version, thanks to the annotation applied specifically to AdminService.Books:stock, is defined like this (where can see the expression in CXN form):

stock: Integer {
  '@assert': {
    '=': "case when stock < 0 then 'stock must not be negative' when stock > 1000 then 'stock exceeds maximum limit of 1000' end",
    xpr: [
      'case',
      'when',
      { ref: [ 'stock' ] },
      '<',
      { val: 0 },
      'then',
      { val: 'stock must not be negative' },
      'when',
      { ref: [ 'stock' ] },
      '>',
      { val: 1000 },
      'then',
      { val: 'stock exceeds maximum limit of 1000' },
      'end'
    ]
  },
  type: 'cds.Integer'
}

57:44 Patrice describes the relationship between CXL, CQL and CDL in terms of "passenger" and "vehicle", in that CXL expressions are "passengers" carried in the "vehicles" of CQL queries and / or CDL definitions (such as annotations and element definitions); Patrice illustrates this further by showing what a simple expression in CXL is parsed to:

> cds.parse.expr` author.books.genre.name `
{ ref: [ 'author', 'books', 'genre', 'name' ] }

and also notes that the value of the ref is interpreted depending on the "vehicle" in which it is being carried.

Further info

Patrice also has some great notes for this part.

Genres, cuids and a bit of AWK

2026-03-03T00:00:00Z

One of my goals this year is to learn more about the AWK programming language. I'm interested in not only the beauty of the language itself and the Unix history that surrounded it, but in how AWK shaped one of my favourite languages of all time, Perl.

In some ways AWK and CAP are similar, in that there's beauty, power and simplicity built in. These three attributes come about not least because it's about the code that you don't have to write; the language (AWK) and the framework (CAP) take care of much of the ceremony, allowing you to focus on the heart of the task at hand, and to write the smallest amount of code necessary to get the job done and minimise the maintenance burden for yourself.

Challenge

It's from the CAP context that a small challenge arose. The initial data supplied with the "bookshop" sample contains Books, Authors and Genres. But I don't like the aesthetics of the Genre IDs; they're GUIDs, as defined by the cuid aspect in the schema:

using {
  cuid,
  sap
} from '@sap/cds/common';

namespace sap.capire.bookshop;

/** Hierarchically organized Code List for Genres */
entity Genres : cuid, sap.common.CodeList {
  parent   : Association to Genres;
  children : Composition of many Genres
               on children.parent = $self;
}

The corresponding initial data (in db/data/sap.capire.bookshop.Genres.csv) looks like this (many records have been omitted for brevity):

ID,parent_ID,name
10aaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa,,Fiction
11aaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa,10aaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa,Drama
12aaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa,10aaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa,Poetry
13aaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa,10aaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa,Fantasy
131aaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa,13aaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa,Fairy Tale
132aaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa,13aaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa,Epic Fantasy
133aaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa,13aaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa,High Fantasy
134aaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa,13aaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa,Gothic
14aaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa,10aaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa,Science Fiction
141aaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa,14aaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa,Utopian and Dystopian
1411aaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa,141aaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa,Utopian
1412aaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa,141aaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa,Dystopian
14121aaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa,1412aaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa,Cyberpunk
141211aa-aaaa-aaaa-aaaa-aaaaaaaaaaaa,14121aaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa,Steampunk
...
18aaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa,10aaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa,Short Story
19aaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa,10aaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa,Graphic Novel
20aaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa,,Non-Fiction
21aaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa,20aaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa,Biography
22aaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa,21aaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa,Autobiography
23aaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa,20aaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa,Essay
24aaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa,20aaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa,Speech

This hurts my eyes, and I wanted to rebuild this dataset with integer IDs, while keeping the same hierarchy¹. As a bonus, I wanted to be able to visualise that hierarchy too.

Exploration

While I was on a similar journey to learn more about jq, I built an interactive jq REPL style data explorer, using tools in my personal development environment (i.e. my Unix shell). I described that explorer (called jqte) in the blog post A simple jq REPL with tmux, bash, vim and entr.

I found jqte so useful that I thought a similar AWK REPL style data explorer would be useful too, so I created one, called ate (AWK terminal explorer, I guess).

It's great, because:

I can see the original data (top right)
I get immediate feedback and output (left) ...
... as soon as I modify any of my AWK incantations (bottom right)

Solution

Here's the AWK script I came up with, bearing in mind that I've not written very much AWK at all, and probably most of what I have written has been very simple, in one-liners. I have written some notes below on how the script works.

#!/usr/bin/awk -f

# - Reads in a CSV file of genres
# - Emits a version with "clean(er)" IDs
# - Creates a directory tree (in /tmp/genres/) representing the hierarchy

function getparent(sid) {
  if (! parent[sid]) return ""
  return getparent(parent[sid]) "/" name[parent[sid]]
}

BEGIN {
  OFS = FS = ",";
  DIR = "genres";
  system("rm -rf /tmp/" DIR);
}

NR == 1

NR > 1 {
  sid = NR - 1
  id[$1] = sid
  name[sid] = $3
  parent[sid] = id[$2]
  print sid, parent[sid], $3
  system("mkdir -p '/tmp/" DIR getparent(sid) "/" $3 "'")
}

This script turns the above CSV records into ones that have (to me) much more pleasant identifiers:

ID,parent_ID,name
1,,Fiction
2,1,Drama
3,1,Poetry
4,1,Fantasy
5,4,Fairy Tale
6,4,Epic Fantasy
7,4,High Fantasy
8,4,Gothic
9,1,Science Fiction
10,9,Utopian and Dystopian
11,10,Utopian
12,10,Dystopian
13,12,Cyberpunk
14,13,Steampunk
...
36,1,Short Story
37,1,Graphic Novel
38,,Non-Fiction
39,38,Biography
40,39,Autobiography
41,38,Essay
42,38,Speech

You may have noticed the system( ... ) call in the script. This is related to the visualisation part of the challenge.

To address this part, I had decided not to reinvent any wheels and use the venerable tree facility available almost everywhere, which is designed to show files and directories in a hierarchical view. So all I needed was to create a hierarchy of directories, where each directory was a genre, with optional parent and children, and then display it with tree. The result looks like this:

/tmp/genres/
├── Fiction
│   ├── Adventure
│   ├── Drama
│   ├── Fantasy
│   │   ├── Epic Fantasy
│   │   ├── Fairy Tale
│   │   ├── Gothic
│   │   └── High Fantasy
│   ├── Graphic Novel
│   ├── Mystery
│   │   ├── Cozy Mystery
│   │   ├── Crime
│   │   │   ├── Detective
│   │   │   ├── Suspense
│   │   │   └── Thriller
│   │   │       ├── Legal Thriller
│   │   │       ├── Medical Thriller
│   │   │       ├── Police Procedural
│   │   │       └── Spy Thriller
│   │   └── Noir
│   │       ├── Nordic Noir
│   │       └── Tart Noir
│   ├── Poetry
│   ├── Romance
│   │   ├── Contemporary Romance
│   │   ├── Historical Romance
│   │   └── Romantic Suspense
│   ├── Science Fiction
│   │   ├── Space Opera
│   │   ├── Tech Noir
│   │   ├── Time Travel
│   │   └── Utopian and Dystopian
│   │       ├── Dystopian
│   │       │   └── Cyberpunk
│   │       │       └── Steampunk
│   │       └── Utopian
│   └── Short Story
└── Non-Fiction
    ├── Biography
    │   └── Autobiography
    ├── Essay
    └── Speech

Notes

Here are some notes on the content of the script, the small size of which is a testament to the power, beauty and simplicity of AWK and the Unix toolset, rather than any skill of mine.

Records, which contain fields, are processed one by one in AWK.
There's a PATTERN - ACTION pair approach to thinking about what you want to happen for each record.
In each pair's case, the pattern come first, then the corresponding action is defined in a { ... } block.
If the pattern matches, then the action is carried out.
There are special patterns, one of which, BEGIN, I use here to set a few things up.
There are many built-in variables; in the BEGIN section I'm setting the (input) field separator FS and the output field separator OFS; also used in this script is NR which is the number of the record being currently processed.
As well as these built-in "system" variables, the variables $1, $2, $3 and so on refer to the individual fields in a record (and $0 refers to the entire record)
AWK can make system calls, as you can also see here where I remove any previously created directory hierarchy in /tmp/genres/ at the start.
The default action is to print the entire record, which I use for the first record (pattern NR == 1) to pass through the CSV header line to the output untouched
Processing is done for each of the actual CSV records (where the pattern NR > 1 holds true, basically), where I derive a simple (integer) ID in sid and then create lookups (using AWK's array structure which is associative) for the IDs, genre names, and genre parents (where appropriate).
Variables (including arrays) benefit from autovivification ², which means I don't need to worry about declaring or initialising anything.
The print statement is where I output the CSV records each with their (and their parent's) simpler IDs.
I also invoke a mkdir command to create a directory within /tmp/genres/ to represent the current genre.
The core of this relies on the getparent function defined at the top, which recursively backtracks to derive the complete parent path.

Wrapping up

I am still fascinated by the simplicity of command line tools, flat file data processing and little languages like AWK, whose size belies its power and utility.

If you want to learn a little more about AWK, I would definitely recommend the paper Awk - A Pattern Scanning and Processing Language, concise and compact, just like AWK.

Footnotes

Yes I know there's also a corresponding .texts.csv file that I should also convert, but I would rather just delete this file, as it's just initial data for testing in all cases, anyway. I may also want to change the type of the Genres:ID element to Integer itself. But basically, this excursion was more about AWK than genre data.
It's fascinating that the linked Wikipedia page entry on autovivification specifically refers to Perl which as I've mentioned was heavily influenced by AWK as well as other contemporary languages and tools.

Improving the SAP Community together, one comment at a time

2026-02-17T00:00:00Z

As a Developer Advocate, I have the privilege of working with some amazing colleagues in that team, but also in the wider Developer and Community Relations organisation. For the size of the community, it's a small group, and the folks are working hard to keep the wheels on the bus and rolling in the right direction. But they can only do so much. In this post, I want to highlight a challenge for us all, and how we can, again, collectively, tackle it together.

The challenge

I'm talking about content quality, which to a greater or lesser degree has for a long time been a topic of debate both in the questions area and also the blog post area. My relationship with the SAP Community platform goes back to day 1, with SDN.

Actually, it goes back to well before that - creating and running the first online SAP community in 1995, and co-creating the SAP Developer Network has caused me to never stop caring for and worrying about those platforms, the people, and the content.

Blog post quality

The quality of some blog posts on the SAP Community platform could be better. I know it. You know it. We all know it. The number of people like you and me who worry about this sort of thing is far outweighed by the larger number of folks that make up the entire community.

Over time various folks have attempted to help educate folks so that they create better content. Here are some posts from me on this topic:

Help us to help you - share your code (2014)
Help us to help you - good questions beget good answers (2019)
Monday morning thoughts: a good blog post (2018)
Monday morning thoughts: on starting blogging (2018)

These attempts have worked, but only to a certain extent. Not only that, but we have AI content generation to contend with too. While used appropriately, and with thought, this approach can produce great results. But it can also produce poor content, especially when the human component in this equation is not entirely engaged with the purpose and process. Moreover, the ease with which poor content can be produced is astounding. And so the problem has got worse over time, and I can only see that progression accelerating.

The SAP Community belongs to us

Like you, seeing blog posts that don't belong makes me sad and frustrated. So, what should we do in this situation?

Report important issues to the moderators

Well, first, there's a decision to be made. Does the blog post break the important parts of the Rules Of Engagement? What are the important parts? Well, a bit of common sense will help. Does it defame, injure or harass? Is the content illegal? Report it to the moderators.

Feel empowered to call other issues out yourself

In other cases, don't report it. Use your voice publicly, by attaching a comment to the post, explaining briefly what you consider inappropriate, or just plain incorrect. Encourage your fellow SAP Community members to upvote your comment if they agree.

Use the power of the collective, the power of the shared heart, to highlight, educate, and yes, if you want to think of it in this way, to shame the author into adjusting or removing the post and changing their ways.

This is how society works. And the SAP Community platform is an online society. So feel empowered to treat it as one. Call the person out. Gently, politely, firmly, however you see fit. You be the judge - we're all adults here. Don't treat it as a kindergarten and go to the teacher whenever you dislike something.

Why? Because the teachers are in short supply. The moderators behind the scenes are working flat out on an ever increasing load of reports. Some that I would definitely class as important, but many, many others that I'd class as trivial and inappropriate.

Celebrate good posts

Calling out bad posts like this is important. Upvoting such call-out comments is also important.

But as well as calling out bad posts, remember to celebrate good ones by adding comments of praise or encouragement. Or just upvote them. That is the least you can do, it only takes a second.

The power of filtering and natural selection

Calling out poor content by leaving a comment helps educate, even gently admonish, if needed. But upvoting and adding multiple positive comments helps even more, not only to highlight good content, but also to feed the filter mechanisms that can surface content that you want to see, controlled in part by you.

Final thoughts

Thanks for reading this far. Here's a TL;DR (yes, I know it should go at the top, but think of it as the call to action instead).

Stop reporting poor quality content, and similar transgressions. Call the authors out yourself. Everyone is a member, and everyone is a moderator. And if we moderate ourselves with respect, honesty and firmness, we just might turn this giant sea-going cargo ship towards a better quality future for the community platform that belongs to all of us.

Also posted on the SAP Community platform.

Shift left with CAP

2026-02-09T00:00:00Z

The traditional "shift left" strategy in software is about how we move testing, security considerations and quality assurance to an earlier stage in the architecture and development process. This strategy is a useful one which can be adapted to what we code, and where we code.

Something that's always been the case -- but which is gaining increasing focus and attention thanks to AI -- is how more lines of code is worse, not better.

Less code, more solid-state

Why worse? Well, more code means a larger surface area for bugs to manifest, higher efforts in comprehension & maintenance and a greater likelihood of technical debt¹.

Moreover, in traditional languages (such as JavaScript, Java, et al.) the code written often contains moving parts, writhing and mutating ... requiring effort to contain, control and reason about.

Today, there's another problem with more code, and that's the lack of concision when it comes to being the subject of training, in LLM situations. We want our AI models to be trained on, and producing, reliable and concise code.

Whether it's us, or future LLMs that will be maintaining and extending that generated code, we owe it to ourselves (and our future AI overlords) to make it as precise and with a small a footprint as possible.

I sometimes use the term "solid-state" in my talks when describing what functional programming brings, such as in Learning by Doing - Beginning Clojure by Solving Puzzles. The term, for me, captures the idea of code that doesn't move, and therefore is far less prone to changing or breaking².

Alongside functional programming languages in which this state (pun intended) can be found, there's also the class of declarative languages. Guess what? CAP has a wealth of declarative languages right there for us to embrace, in the CDS language family: CDL, CQL and CXL.

One way of working towards this goal of writing less code, and having as much of that code in solid-state form, is by shifting our development left.

An example

To illustrate what I mean by shifting left from a code perspective in CAP, I want to work through a deliberately simple example. Consider a typical CAP scenario, where we have an entity model, a service on top of that³ which is made available via some protocol, consumed in some frontend app.

+---------+     +---------+     +---------+     +---------+
| Entity  |     | Service |     |  OData  |     |         |
| Model   +-----+ Defn    +-----+  Proto  +-----|Frontend |
|         |     |         |     |         |     |         |
+---------+     +----+----+     +---------+     +---------+
                     |
                +----+----+
                | Service |
                | Impl    |
                |         |
                +---------+

The setup

Our starting position is a basic CDS model with a single entity, Products, and a single service making that entire entity available.

In db/schema.cds we have:

namespace northbreath;

entity Products {
  key ID    : Integer;
      name  : String;
      price : Decimal;
      stock : Integer;
}

and in srv/main.cds we have:

using northbreath from '../db/schema';

service Main {
  entity Products as projection on northbreath.Products;
}

If Northbreeze is a cut down version of the original Northwind, then Northbreath is an extremely cut down version. Geddit? Ok, I'll get me coat.

For completion and illustration's sake, we also have a skeleton implementation for this Main service in srv/main.js, which does nothing at the moment:

const cds = require('@sap/cds')

module.exports = class Main extends cds.ApplicationService {
  init() {
    return super.init()
  }
}

There are just a few initial data records in test/data/northbreath-Products.csv:

ID,name,price,stock
1,Chai,18.00,39
2,Chang,19.00,17
3,Aniseed Syrup,10.00,13

That's all we need for this scenario. Unless otherwise stated, assume that we're now running a CAP server for this project, with cds watch. We'll request single entities in examples henceforth, mostly to keep things brief.

Albeit simple, this scenario comprises a fully formed model and a service provided via OData. Properties available for each entity (e.g. at localhost:4004/odata/v4/main/Products/1) are what the frontend is built around:

{
  "@odata.context": "$metadata#Products/$entity",
  "ID": 1,
  "name": "Chai",
  "price": 18,
  "stock": 39
}

The requirement

Let's say the frontend now also needs to calculate the in-stock value for each of the products (again, deliberately simple, but this idea holds for more complex requirements too).

In other words, the value is the price multiplied by the number of units in stock. For this Chai product, that would be 18 * 39 i.e. 702.

Addressing the requirement

How should the developer go about this? There are many approaches, which I'll enumerate in right to left order, with respect to the diagram earlier, i.e. shifting further and further left and towards declarative solutions each time.

Computation at the frontend

+---------+  +---------+  +---------+  ///////////
| Entity  |  | Service |  |  OData  |  /         /
| Model   +--+ Defn    +--+  Proto  +--/Frontend /
|         |  |         |  |         |  /         /
+---------+  +----+----+  +---------+  ///////////
                  |
             +----+----+
             | Service |
             | Impl    |
             |         |
             +---------+

Naturally one might be tempted to make the calculation in the frontend, on the far right, once the entity data is available.

That would work, but why put extra effort where it's least wanted, transferring extra business logic (in the form of JavaScript, typically for a Web-based application) and requiring a small amount of extra compute nearest to the user? This pushes more complexity at the rightmost end of the spectrum where moving parts and calculations are least appropriate.

Computation via the URL in the OData operation

                                SHIFT LEFT
                               <==================

+---------+  +---------+  ///////////  +---------+
| Entity  |  | Service |  /  OData  /  |         |
| Model   +--+ Defn    +--/  Proto  /--|Frontend |
|         |  |         |  /         /  |         |
+---------+  +----+----+  ///////////  +---------+
                  |
             +----+----+
             | Service |
             | Impl    |
             |         |
             +---------+

Moving slightly further left, this requirement could be satisfied using OData facilities⁴, specifically with the system query option $compute.

The in-stock value calculation can be effectively shifted left by using $compute to return the value as a computed property:

curl \
  --silent \
  --url 'localhost:4004/odata/v4/main/Products/1?$compute=price%20mul%20stock%20as%20instockvalue_odata' `
  | jq .

Written out in decoded form, the query string of the URL looks like this:

$compute=price mul stock as instockvalue_odata

The entity returned looks like this:

{
  "@odata.context": "$metadata#Products/$entity",
  "ID": 1,
  "name": "Chai",
  "price": 18,
  "stock": 39,
  "instockvalue_odata": 702
}

The calculation is specified in the frontend but provided by the backend and thus available without any extra custom code on the far right hand side.

However, we've only slightly deferred the work burning execution cycles in the browser's JavaScript engine, changing it into a requirement to customise the OData URLs. We can do better.

Using a custom event handler

                   SHIFT LEFT
                  <===============================

+---------+  +---------+  +---------+  +---------+
| Entity  |  | Service |  |  OData  |  |         |
| Model   +--+ Defn    +--+  Proto  +--|Frontend |
|         |  |         |  |         |  |         |
+---------+  +----+----+  +---------+  +---------+
                  |
             ///////////
             / Service /
             / Impl    /
             /         /
             ///////////

Shifting further left, while still in "imperative" mode, given all that JavaScript that's in our heads from thinking all things frontend, we have the chance to jump into the built-in request/response handling cycle that the CAP server provides, and modify the payload of a response before it's sent back.

We can do this in an event handler, specifically in the "after" phase. Such "after" phase handlers run after the "on" handlers, and get the result set as input. What might that look like? Well, in its simplest form, like this, in our srv/main.js:

const cds = require('@sap/cds')

module.exports = class Main extends cds.ApplicationService {
  init() {
    this.after('each', 'Products', p => {
      p.instockvalue_after = p.price * p.stock
    })
    return super.init()
  }
}

In the init we've now defined an anonymous function for the "after" phase, a function that adds a new property instockvalue_after to the entity objects.

This means that the computation of price * stock is now pushed back further left, and we can now remove the $compute system query option from the URL in the OData request:

curl \
  --silent \
  --url 'localhost:4004/odata/v4/main/Products/1`
  | jq .

but still get what we need:

{
  "@odata.context": "$metadata#Products/$entity",
  "ID": 1,
  "name": "Chai",
  "price": 18,
  "stock": 39,
  "instockval_after": 702
}

Calculated element in the service definition

From the diagram's perspective, we're not shifting much further left with this next option, as service definition and implementation go together.

                   SHIFT LEFT
                  <===============================

+---------+  ///////////  +---------+  +---------+
| Entity  |  / Service /  |  OData  |  |         |
| Model   +--/ Defn    /--+  Proto  +--|Frontend |
|         |  /         /  |         |  |         |
+---------+  ///////////  +---------+  +---------+
                  |
             +----+----+
             | Service |
             | Impl    |
             |         |
             +---------+

However, I'd argue that a shift from the custom code, a move away from the ceremony and imperative nature of a custom handler in the implementation of a service, to a calm, declarative and solid-state addition in the definition of a service is what we should strive for.

This is effectively a "push up", as described in the What not how, less is more section of the Constraints, expressions and axioms in action post.

One of my five main reasons to use CAP is that the code is in the framework, not outside of it. That gives us a massive step up as developers and allows us to focus on the important stuff, such as domain modelling. The phrase "the code is in the framework" is also a subtle clue that we should try to keep it that way, too.

So instead of a custom handler, let's remove the srv/main.js service implementation file entirely, and use the power of CDL and CXL to declare a calculated element in the Products projection definition in our Main service, like this:

using northbreath from '../db/schema';

service Main {
  entity Products as
    projection on northbreath.Products {
      *,
      price * stock as instockval_service
    }
}

Now we can request the "bare" entity URL again:

curl \
  --silent \
  --url 'localhost:4004/odata/v4/main/Products/1`
  | jq .

and get what we need, with no moving parts, and no custom code at all to maintain:

{
  "@odata.context": "$metadata#Products/$entity",
  "ID": 1,
  "name": "Chai",
  "price": 18,
  "stock": 39,
  "instockval_service": 702
}

Calculated element at the schema layer

      SHIFT LEFT
     <============================================

///////////  +---------+  +---------+  +---------+
/ Entity  /  | Service |  |  OData  |  |         |
/ Model   /--+ Defn    +--+  Proto  +--|Frontend |
/         /  |         |  |         |  |         |
///////////  +----+----+  +---------+  +---------+
                  |
             +----+----+
             | Service |
             | Impl    |
             |         |
             +---------+

It is not by chance that there is a distinct separation of CDS model and service layers. The Services as Facades section of the Define Provided Services tells us that rather than having a single service to serve all consumers, they should be plentiful, facades encapsulating different views on domain data constellations, exposing different aspects tailored to the use cases as required.

So while it can make a lot of sense to place a calculated element at the service definition layer, it can sometimes make sense to place it at the schema layer, directly in the CDS model. You and your domain experts & business owners are best placed to decide this.

Defining a calculated element at this level is just as simple. Instead of making any changes to the projection definition in srv/main.cds, we can add an element to Products directly in db/schema.cds:

namespace northbreath;

entity Products {
  key ID                  : Integer;
      name                : String;
      price               : Decimal;
      stock               : Integer;
      instockvalue_schema : Decimal = price * stock;
}

With the definition at this level, all Products projections at the service layer will benefit from this extra element, without you having to do anything special.

If there was a particular service where you didn't want this element in a projection on Products, you could use an excluding clause like this:
using northbreath from '../db/schema';

service Secondary {
  entity Products as
    projection on northbreath.Products
    excluding {
      instockvalue_schema
    }
}

Wrapping up

Shifting left in CAP results in less code. It also means that the smaller amount of code that we do end up writing is also more solid-state.

Shifting left also surfaces solutions to business requirements at the level that the domain expert can more easily collaborate on; the construction of solutions become part of the design document set, rather than being a write-once and write-only part of the solution at the imperative and brittle code level.

CAP supports us with the built-in philosophies and the languages we can use to do the right thing, and I'm reminded of how it also strongly lives up to one of Perl's taglines, to which I alluded in the notes to The Art and Science of CAP Part 9, especially the first part:

Makes easy things easy and hard things possible.

CAP makes it easy for us to do the easy things, the right things. Let's do that.

Further info

For a great deal of amazing insight into expressions, in CXL, within CDL and also CQL, don't miss the current Hands-on SAP Dev live stream series "CDS expressions in CAP - under the hood" with me and expert Patrice Bender. You can find all the info, including links to replays and upcoming episodes, in the post A new Hands-on SAP Dev mini-series on the core expression language in CDS.

Birgit Selbach's post Declarative Programming in CAP: Less Code, More Value has also some great thoughts in this area.

The blog post Constraints, expressions and axioms in action also talks about driving custom code upwards, downwards and out of a project.

Footnotes

See AXI002 Less is more.
This is strongly linked with the functional programming idea that we should avoid mutating data, making things difficult to track, and instead use higher level mechanisms that provide us with chainable functions at the what, not how level.
See AXI004 Services are cheap.
If you want to learn more about OData, and influence the new series of tutorials I'm writing, see OData Deep Dive rewrite in the open. See also the Serving OData APIs topic in Capire for what facilities like this are available.

Series of "Did You Know" videos

2026-02-06T00:00:00Z

In the run up to SAP TechEd 2025, the Developer Advocates put together a series of short videos on tech topics, in a "Did You Know" series. A bit like our collection of YouTube Shorts "Good To Know" series (on CAP Node.js and on ABAP Cloud), but in landscape mode with a bit more detail.

The series

Here's an overview of that "Did You Know" series; this list will be updated over the coming weeks as we add them one by one to upcoming SAP Developer News episodes. Use the 📺 link to jump directly to the section in the news episode.

1 The cds REPL

📺 Did you know: that the cds REPL is great for exploring your CAP services? More info: A reCAP intro to the cds REPL (SAP Developer News 29 Jan 2026, with DJ).

2 Mocking auth in CAP

📺 Did you know: that CAP has a "mocked" authentication strategy you can use in local development so you don't have to put off this important part of your domain design? More info: Authentication Strategies (SAP Developer News 05 Feb 2026, with DJ).

3 Debugging apps on CF

📺 Did you know: that it's easy to debug your CAP Node.js apps running on Cloud Foundry? More info: The Debugging with cds debug section of the CLI topic in Capire (SAP Developer News 12 Feb 2026, with DJ).

4 Released Objects in ADT

📺 Did you know: that the released objects that are available for developer extensibility are displayed in the Project Explorer of ABAP Development Tools? More info: The Released Development Objects section of the Developer Extensibility documentation in the SAP Help Portal (SAP Developer News 19 Feb 2026, with Shilpa).

5 Search ABAP CDS objects using Annotations

📺 Did you know: that you can search the CDS View entity by the annotations used? More info: The guide to the ABAP Development Tools for Eclipse in the SAP Help Portal (SAP Developer News 26 Feb 2026, with Shilpa).

6 Privileged access in ADT

📺 Did you know: that you can check if your data model can access the relevant data without using an access control? More info: The guide to the ABAP Development Tools for Eclipse in the SAP Help Portal (SAP Developer News 05 Mar 2026, with Shilpa).

7 AI Launchpad Model Library

📺 Did you know: that you can use the Model Library in Generative AI Hub on SAP AI Launchpad to explore the LLMs SAP is offering managed, hosted or provided remotely? More info: The SAP AI Launchpad Model Library documentation in the SAP Help Portal (SAP Developer News 12 Mar 2026, with Kevin).

8 Orchestration Client in SAP Cloud SDK for AI

📺 Did you know: that you can use the orchestration client from the SAP Cloud SDK for AI to create a full AI orchestration flow in CAP? More info: The SAP Cloud SDK for AI – Chat Completion documentation (SAP Developer News 19 Mar 2026, with Kevin).

9 Orchestration Client configuration

📺 Did you know: that you can configure an AI orchestration in AI Launchpad and use it to configure the orchestration client from the SAP Cloud SDK for AI? More info: Orchestration Workflow AI in the SAP Help Portal (SAP Developer News 26 Mar 2026, with Kevin).

10 Test Orchestration configuration

📺 Did you know: that you can test the orchestration configuration directly in AI Launchpad against various LLMs? More info: Test Your Orchestration Workflow in the SAP Help Portal (SAP Developer News 02 Apr 2026, with Kevin).

11 AI agents (Generative AI Hub & LangGraph)

📺 Did you know: that you can build AI agents using LangGraph and Generative AI Hub? More info: CrewAI example connecting to SAP Generative AI Hub via LiteLLM (SAP Developer News 09 Apr 2026, with Nora). 👈 LATEST

Modifying queries, replacing the WHERE clause

2026-02-04T00:00:00Z

The result of modifying existing queries can be a little unexpected at first. For example, you might have a query object where you want to replace the WHERE clause before you execute it. Here's how not to do it, and then how to do it.

Setup

To illustrate, we can use my cdsnano script to set up a tiny project with a services.cds file containing:

context qmacro {
  entity Books {
    key ID    : Integer;
        title : String;
  }
}

service Bookshop {
  entity Books as projection on qmacro.Books;
}

Let's add a couple of sample books in test/data/qmacro-Books.csv:

ID,title
1,Book 1
2,Book 2

Now we can start up the cds REPL and ask for a CAP server to be started for this project:

cds repl --run .

Creating the query

Let's create a query object with a WHERE condition:

> q1 = cds.ql `
  SELECT from ${Bookshop.entities.Books} where title = 'Book 1'
`
cds.ql {
  SELECT: {
    from: { ref: [ 'Bookshop.Books' ] },
    where: [ { ref: [ 'title' ] }, '=', { val: 'Book 1' } ]
  }
}

This works as expected:

> await db.run(q1)
[ { ID: 1, title: 'Book 1' } ]

Modifying the query (wrong)

Let's say we want to change the WHERE condition, to retrieve any book with a title starting with "Book".

What happens when we do this:

> q1.where(`title like 'Book%'`)
cds.ql {
  SELECT: {
    from: { ref: [ 'Bookshop.Books' ] },
    where: [
      { ref: [ 'title' ] },
      '=',
      { val: 'Book 1' },
      'and',
      { ref: [ 'title' ] },
      'like',
      { val: 'Book%' }
    ]
  }
}

The .where(...) does not replace, but append - notice that both predicates:

title = 'Book 1'
title like 'Book%'

are present, and joined with a logical and.

The result of this query is not what we want:

> await db.run(q1)
[ { ID: 1, title: 'Book 1' } ]

Modifying the query (right)

We can replace the WHERE clause completely, supplying a new predicate, like this:

> q1.SELECT.where = cds.ql.predicate `title like 'Book%'`
[ { ref: [ 'title' ] }, 'like', { val: 'Book%' } ]

And indeed, this is what the entire query object looks like now:

> q1
cds.ql {
  SELECT: {
    from: { ref: [ 'Bookshop.Books' ] },
    where: [ { ref: [ 'title' ] }, 'like', { val: 'Book%' } ]
  }
}

This does what we want:

> await db.run(q1)
[
  { ID: 1, title: 'Book 1' },
  { ID: 2, title: 'Book 2' }
]

Modifying a copy of the query

It's probably a good idea to think about modifying a copy of the query, so you always have the original. We can use cds.ql.clone() for that. Here's how it would work, in this example context:

> q2 = cds.ql.clone(q1)

then we can operate on q2 and keep q1 intact.

Wrapping up

Nice!

For more info, check out the Querying in JavaScript topic in Capire, which, in the upcoming January 2026 release (that should be out in the next few days) will be expanded and fully constructed.