DJ Adams

Computing memories

2026-07-08T00:00:00Z

My good friend and colleague Antonio shared some thoughts today (also, see update below) about a post he'd just read: The Last People Who Know How It Works.

I was composing a reply to Antonio's thoughts on LinkedIn, but then thought better of it, and in the proper spirit of "owning (and being in control of) one's own content", harking back to the good old days of communication and community on the Web, I thought I'd write my reply here and then point to it via a URL. So here goes.

The post is a lovely read, and makes a great point that resonates with me, a point about the potential (or imminent) loss of knowing how things work, through having to make things work. I have many memories of building things from scratch, making computers do things (where in their default state they would do nothing).

For our SAP community readers, I also remember (in the early to mid 1990's) calculating which actual magnetic tracks across which cylinders (physical partitions on the DASD) to place different parts of the SAP R/2 document database and indices (ABEZ, ABIB, etc) for optimal head movement across the spinning platters. Most commonly we'd use IDCAMS to define VSAM Data Sets.

I'm sure that many of you dear readers have equivalent and equally fond memories.

One thing that stood out in the post was this wonderful image:

I went looking the other night for a recording of a modem connecting. People keep them around like pressed flowers.

Such sounds are indeed, at least in my mind, delicate artifacts, and worth preserving. And preserving with care.

One statement the post makes is:

A machine that cannot challenge you is a thing you cannot know. You can only use it.

I agree strongly with this. It summarises much of how I feel about using computers, and reminds me of the TEDx talk I gave back in 2012 titled Our Computational Future, on how we should not be raising generations of users, but generations of creators and builders.

Here's something else from the post:

The knowledge is not in danger, in fact, it has never been safer. The AI models have read every manual that no human reads.

Now this I cannot agree with, in fact strongly disagree (based on the way I read it, which may be incorrect). We have been down those roads of information being lost to time, either due to deterioration of physical media, or due to proprietary formats where there's no way of reincarnating a reader program. If we're relying on AI to remember stuff for us, that's very short sighted. Who owns the models, the systems, the processes? What format is that stored in, and how accessible is that to everyone and anyone who wants it?

That road is a road to pain and regret.

Anyway, I don't want this last thought to take anything away from the post - it's still a lovely read.

Update: Antonio has put his thoughts on his own post now too, kudos: A simple reflection on how things work, curiosity and friction.

Blogging in en-GB

2026-07-04T00:00:00Z

Terence Eden recently published a post titled This blog is written in en-GB. Before I even read the post, I knew what it was going to be about, and that I had to make that change myself too, for the same reasons as I'd guessed he was going to explain.

Terence expresses those reasons very well, so I won't try to reproduce them here. I'm in strong agreement with him and those reasons resonate with me. This is my blog, I string all the words together, in my own style, on the topics I choose, with or without bias, depending on what I think. That is called a voice. Everyone has one, this is mine.

To ask someone to change that (as a commenter did, to Terence), is not only poor judgement, it is also self-centred. It reminds me of how I sometimes feel about people who get "offended". Offence is taken, not given. Indeed, as Ricky Gervais famously said "just because someone is offended, it doesn't mean they're right".

I attribute much of my learning by coming across references or ideas that I didn't quite understand, and looking them up. Today, that's easier than ever. To ask someone to make their cultural references more "accessible" is asking to be spoon fed slop.

Talking of slop, one thing that gives me hope in today's world of generated content, is that the human experience as expressed by individuals is what will keep us sane. If you want more on that, I recommend the post The best response to AI slop, infinite advice, and online noise is from Robin Williams.

In turn, that post reminded me of the classic quote:

"The computer can't tell you the emotional story. It can give you the exact mathematical design, but what's missing is the eyebrows."

If you don't know who uttered that ... go and find out.

CAP service authentication at design time and in production

2026-06-19T00:00:00Z

Recently I wrote about mocking auth in CAP for a rapid local-first development loop that allows you to embrace auth design rather than defer it to later.

In development mode, unless otherwise stated (i.e. unless you add appropriate annotations such as @readonly, @requires or @restrict), all resources are accessible to everyone, even without authenticating. This is appropriate and fitting, helping to facilitate the tight feedback loop that folks love when developing with CAP.

What about production? Is it the same there, i.e. do we have to ensure we lock down access before moving to production? Of course not. Here's how things work.

Default auth settings for development

In development mode, the default auth strategy is "mocked", as we can see:

; cds env requires.auth
{
  restrict_all_services: false,
  kind: 'mocked',
  users: {
    alice: { tenant: 't1', roles: [ 'admin' ] },
    bob: { tenant: 't1', roles: [ 'cds.ExtensionDeveloper' ] },
    carol: { tenant: 't1', roles: [ 'admin', 'cds.ExtensionDeveloper' ] },
    ...
    yves: { roles: [ 'internal-user' ] },
    '*': true
  },
  tenants: { t1: { features: [ 'isbn' ] }, t2: { features: '*' } }
}

Notice also the restrict_all_services property, which is set to false by default in development mode too.

This property is at the core of the "failsafe" production auth mechanism that means that even if you do nothing with regards to auth for your services, they will be protected in production and only available to users who provide appropriate authentication.

Default auth settings for production

In the Authentication in Production section in Capire, we read, in the "Enforced by Default" subsection:

In a productive scenario with an authentication strategy configured, for example the default jwt, all CAP service endpoints are authenticated by default, regardless of the authorization model. That is, all services without @restrict or @requires implicitly get @requires: 'authenticated-user'.

This can be disabled via feature flag cds.requires.auth.restrict_all_services: false, or by using mocked authentication explicitly in production

We can check that the default auth strategy is jwt in production, like this:

; NODE_ENV=production cds env requires.auth
{ kind: 'jwt', vcap: { label: 'xsuaa' } }

Notice also here that restrict_all_services is not there, and will thus have an undefined value:

; NODE_ENV=production cds env requires.auth.restrict_all_services
undefined

Understanding the mechanism

Now we understand the background, let's dig in to see how this works, to understand things better.

In the runtime, there's @sap/cds/lib/srv/protocols/https.js, which contains:

const cds = require('../../index'), { decodeURI } = cds.utils
const express = require('express')
const PROD = process.env.NODE_ENV === 'production'
const restrict_all = cds.env.requires.auth?.restrict_all_services !== false
const authenticated = PROD && restrict_all ? ['authenticated-user'] : false

class HttpAdapter {

  // ...

  /**
   * Returns a handler to check required roles, or null if no check required.
   * @returns {express.RequestHandler|null}
   */
  get requires() {
    const d = this.service.definition; if (!d) return null
    const rr = d['@requires'] || d['@restrict']?.map(r => r.to).flat().filter(r => r)
    const roles = !rr?.length ? authenticated : Array.isArray(rr) ? rr : [rr]
    return super.requires = roles && function requires (req, res, next) {
      const user = cds.context.user
      if (roles.some(role => user.has(role))) return next() //> ok
      else if (user._is_anonymous) return next(401) //> request login
      else cds.error (403, `User '${user.id}' is lacking required roles: [${roles}]`)
    }
  }

  // ...
}

module.exports = HttpAdapter

This is from a @sap/cds runtime version 9.9.1 at the time of writing.

If we stare at this for a moment, we see that:

authenticated is set to the value ['authenticated-user'] if we're in production and the restrict_all_services value is NOT explicitly set to false
then, in the handler that gathers and checks for the specific roles required when a resource is requested, if there are no roles explicitly set as required for the service, then this authenticated-user role is used (remember, authenticated-user is a pseudo-role)

In other words, if you haven't set a value explicitly for restrict_all_services then this will "fail safely" in production.

Wrapping up

So there you have it. I mean, it's sort of obvious when you think about it, but I think it's always nice to "understand by reading" and spend a bit of time to dwell on the mechanism.

Book Overflow and two architectural patterns in CAP

2026-06-04T00:00:00Z

Book Overflow is "a long-form discussion podcast for software engineers" and one of the shows to which I'm subscribed.

The recent episode 118 is one in the series where Carter and Nathan discuss the book Learning Domain-Driven Design: Aligning Software Architecture and Business Strategy by Vlad Khononov.

I listened to this episode today and found that, as usual, the two go into great depth and draw on their thoughtfulness and experience to tease out details and connect the dots for us listeners.

Covered in their discussions were a couple of patterns that resonated with me:

Ports And Adapters
Transactional Outbox

Both these patterns live and breathe strongly within CAP, from a philosophical standpoint but also from a place that drives the fundamental design of the framework and how it manifests for us developers. So I thought it would be worth both highlighting this episode, series, and podcast, while also connecting the patterns and where they are in CAP.

Ports and adapters

The Ports And Adapters pattern is another name for Hexagonal Architecture, brought into this world and popularised by Alistair Cockburn. It's the ultimate approach to making agnosticism and abstraction first class players in system design.

(Nathan playfully observed that the hexagon isn't really used to the max, with only four sides used in the illustration. I may be misremembering, but I think Alistair might have picked the hexagon as it was different from other boxy shapes available in a classic software diagramming template he had to hand, plus the "extra" sides lend themselves to further expansion by folks using the diagram to express their own usage of the pattern.)

Of course, we know that Hexagonal Architecture is a core concept in CAP, one that supports CAP's agnostic-by-design approach to pretty much everything. It also is a fundamental enabler of the CAP developer experience - grow as you go for rapid prototyping with mocks followed by a seamless transition to production grade services when appropriate.

Transactional outbox

The Transactional Outbox pattern is one that we see reminders of while developing, with the built-in outbox table. This pattern allows the coordination of a typical enterprise scenario where data needs to be updated and an event needs to be sent to a remote system.

The requirement to have both (synchronous and asynchronous) parts as a transactional unit presents challenges, but by deferring the actual delivery of the event to a separate service, the two parts can coalesce and indeed be treated as a unit that collectively either works or doesn't.

Facilitating this is an "outbox" for events, which is at the heart of this pattern, and which CAP has had for a few years now.

Local-first dev with CAP Node.js - mocking messaging

2026-05-15T00:00:00Z

This post is one of a series on local-first development with CAP Node.js.

Everything is an event

In Five reasons to use CAP, we see that everything is an event. Whether synchronous, such as via HTTP requests and responses for OData operations, or asynchronous, where messages are emitted and received for decoupled service-to-service communications.

The Messaging topic in Capire has a great overview and an explanation of all the different message brokers that can be used. And there's one that is well suited for local-first development: File based messaging.

Working through an example

In this post, we'll work through an example of mocking messaging using the file-based facility, with content in the messaging/ directory of the repo set up for the related talk.

The setup is a little different to the other mock examples in this series. First, there are two CAP services that will be in play. Second, neither of them have any entity definitions; in fact, only one has a CDS model at all, and that only has a service definition with an action and an event defined within it.

The containing project definition

Usually in an asynchronous event scenario there is an emitter and a receiver, and that's what we have here. They're both found within the messaging/ directory, which is the containing project for this example, and has been set up to use the Node.js workspaces concept, with this as the definition in package.json:

{
  "name": "@qmacro/messaging",
  "workspaces": [
    "*"
  ]
}

Examining the emitter

Within the emitter/ subdirectory we have a CAP project which has been put together in the form of a package (like a plugin would be). The name declared in emitter/package.json is @qmacro/emitter and as well as the content in srv/ there's also a project root level emitter/index.js which acts as the package entry point and contains:

using from './srv/main';

The emitter service definition

This emitter is where the service definition is found, which looks like this, in emitter/srv/main.cds:

namespace org.qmacro.emitter;

@rest
service EmitterService {
  action greet(greeting: String) returns String;

  event Greeting.Received {
    info : String;
  }
}

The service defines:

an action endpoint greet
an event Greeting.Received

Note that while the term "action" has loaded meaning in the context of OData, it also serves to define a POST based "RPC" style target that is valid even in the context of the "REST" protocol, as declared here. The design of the event and also the signature of the action endpoint is deliberately as simple as possible for this example.

As we'll see shortly, to have an event be emitted in this example scenario, we need to make an HTTP POST request to the /greet endpoint, with a payload body containing the greeting data.

The emitter service implementation

Every action definition needs an implementation, and this is what we have in emitter/srv/main.js:

const cds = require('@sap/cds')
const log = cds.log('emitter')

module.exports = cds.service.impl(async function() {
  this.on('greet', async (req) => {
    const emitter = await cds.connect.to('org.qmacro.emitter.EmitterService')
    log(`emitting Greeting.Received (${req.data.greeting})`)
    await emitter.emit('Greeting.Received', { info: req.data.greeting })
    return 'OK'
  })
})

And that's pretty much it!

Messaging configuration

But upon what messaging mechanism are we relying here? Well, that's defined as a requirement in the emitter's emitter/package.json:

{
  "name": "@qmacro/emitter",
  ...
  "cds": {
    "requires": {
      ...
      "messaging": {
        "kind": "file-based-messaging"
      }
    }
  }
}

The value file-based-messaging is what we want here, as described in the corresponding Capire section where it tells us that a file is used as the message broker; that is, the emitter writes messages to the file, and the receiver reads (and then removes) messages from that file.

By default the file is ~/.cds-msg-box. This fits with the general approach of using hidden files in the developer's home directory (~/.cds-services.json is another example), emphasising the point that this is design-time only, i.e. only for used in a local development context.

Examining the receiver

The receiver in this setup is even simpler. It relies upon the emitter package, and defines it as a required service, in receiver/package.json:

{
  "name": "@qmacro/receiver",
  ...
  "dependencies": {
    "@qmacro/emitter": "*"
  },
  ...
  "cds": {
    "requires": {
      ...
      "EmitterService": {
        "service": "org.qmacro.emitter.EmitterService",
        "model": "@qmacro/emitter"
      },
      "messaging": {
        "kind": "file-based-messaging"
      }
    }
  }
}

Like the emitter, it also defines a requirement on file-based-messaging.

The receiver implementation

There's no CDS model in this simple receiver setup, just an implementation that is in the form of a custom server in receiver/server.js:

const cds = require('@sap/cds')
const log = cds.log('receiver')
const eventID = 'Greeting.Received'

cds.once('served', async () => {
  log(`Setting up listener for ${eventID}`)
  const EmitterService = await cds.connect.to('EmitterService')
  EmitterService.on(eventID, (msg) => {
    log('received:', msg.event, msg.data)
  })
})

Once the CAP server has started up, a connection to the emitter service is made and a handler is registered for the Greeting.Received event.

And that's all we need!

Trying it out

We can try the entire construct out step by step to see what's going on. All the following invocations are based on being in the messaging/ project root directory.

Before we start, we'll install the dependencies from the project root with:

npm install

Starting up the emitter

Now, let's start the emitter up, and we'll specify DEBUG level for the queue component(s) for a more detailed insight as to what happens:

DEBUG=queue cds watch emitter

We should see some familiar log output (some lines have been omitted for brevity):

[cds] - using bindings from: { registry: '~/.cds-services.json' }

[queue] - Using non-scheduling-based event queue processing
[cds] - connect to messaging > file-based-messaging
[cds] - serving org.qmacro.emitter.EmitterService {
  at: [ '/rest/emitter' ],
  decl: 'emitter/srv/main.cds:4',
  impl: 'emitter/srv/main.js'
}
[cds] - server listening on { url: 'http://localhost:4006' }

The file-based-messaging mechanism is brought into play, just before our emitter service is served.

Port 4006 is selected by means of the value in emitter/.env; it has no special significance, except that it's one of a few ports (4004-4006 and 9229) that I publish in my dev container in which I do all my work.

The service is registered in the local development binding registry ~/.cds-services.json:

{
  "cds": {
    "provides": {
      "org.qmacro.emitter.EmitterService": {
        "endpoints": {
          "rest": "/rest/emitter"
        },
        "server": 35678
      }
    },
    "servers": {
      "35678": {
        ...
      }
    }
  }
}

As we've seen in another blog post in this series, on mocking remote services, this registry serves to provide information on services provided and required.

Invoking the greet action

Normally at this point it would make sense to start up the receiver, to have the fully coordinated asynchronous setup. But we want to see things happen step by step, and if we were to start the receiver now, any message generated and emitted would be immediately consumed and we wouldn't see it "in transit".

So at this point we'll invoke the greet action that the emitter exposes, to have a message emitted.

curl \
  --url "localhost:4006/rest/emitter/greet" \
  --data '{"greeting":"Understanding is everything!"}'

From this, we get a simple OK, as we'd expect from the emitter service implementation. More interesting is what we see in the server log:

[rest] - POST /rest/emitter/greet
[emitter] - emitting Greeting.Received (Understanding is everything!)
[persistent-queue] - queue: Write message to queue
[persistent-queue] - queue: Fetch messages
[persistent-queue] - queue: Process 1 message
[persistent-queue] - queue: Messages modified (-1, ~0, +0)
[persistent-queue] - queue: Done

While the [rest] log record is just recording the incoming POST request, and the [emitter] log record was written by the emitter implementation (see above), most notably we see the core messaging mechanism in action, handling the queuing of the message. After all, queueing is a core part of everything that is asynchronous.

Looking at the message queue

As we know, the file based messaging uses ~/.cds-msg-box by default as the queue. And if we look at that right now:

cat ~/.cds-msg-box

we see the message, "in transit", as it were (formatted here for easier reading):

org.qmacro.emitter.EmitterService.Greeting.Received {
  "data": {
    "info": "Understanding is everything!"
  },
  "headers": {
    "x-correlation-id": "80f83122-ecb7-49aa-8cdd-c465e2588374"
  }
}

Half-way there!

Starting up the receiver

Now we've had a chance to examine the queue, we can start up the receiver:

cds watch receiver

[cds] - bootstrapping from { file: 'receiver/server.js' }
...
[queue] - Using non-scheduling-based event queue processing
[cds] - connect to messaging > file-based-messaging
...
[receiver] - Setting up listener for Greeting.Received
[cds] - server listening on { url: 'http://localhost:4005' }

And directly following this, we see:

[receiver] - received: Greeting.Received { info: 'Understanding is everything!' }

Not only that, but the queued message in ~/.cds-msg-box is now gone. Consumed!

Wrapping up

Asynchronous messaging is yet another fundamentally important aspect of real life service design, delivery and orchestration, and we have no reason to put off designing and building that in our projects, as we can incorporate local mocking from the very start.

By the way, for automated tests, you might even want to look at local messaging which takes place in-process, a little bit like in-process remote-service mocking, and is very useful for automated testing.

Local-first dev with CAP Node.js - mocking remote services

2026-05-13T00:00:00Z

This post is one of a series on local-first development with CAP Node.js.

Calesi and mocking remote services

In the context of CAP-Level Service Integration (aka "Calesi") we can mash up remote and local services, and in the full spirit of CAP generally, run everything in airplane mode, i.e. fully locally.

Working through an example

In this post, we'll work through an example of mocking a remote service, based on content in the remoteservice/ directory of the repo set up for the related talk.

We start with an almost empty project directory, save for a basic package.json file which we only really have at this point so we can check the changes in it that are introduced when we import a remote service API definition. All operations are done in the context of this project directory.

The other files in this directory in the repo are related to performing and resetting the demo during the talk version of this post.

Examining and importing the candidate remote service

At https://odd.cfapps.eu10.hana.ondemand.com/ there's the northbreeze OData V4 service with Products, Categories and Suppliers¹. The service's API is available as the metadata document so let's grab that:

curl \
  --url 'https://odd.cfapps.eu10.hana.ondemand.com/northbreeze/$metadata' \
> northbreeze.edmx

and use cds import to import it to our project:

cds import northbreeze.edmx

This emits:

[cds] - updated ./package.json

[cds] - imported API to srv/external/northbreeze
> use it in your CDS models through the likes of:

using { northbreeze as external } from './external/northbreeze';

and the EDMX API definition, along with the CAP-focused CSN equivalent that was created at import, are moved into an external/ directory within a standard srv/ directory (which itself is autovivified at this point):

./
├── package.json
└── srv/
    └── external/
        ├── northbreeze.csn
        └── northbreeze.edmx

Mocking is automatically and immediately initiated

At this point too, the CAP server restarts and shows:

[cds] - loaded model from 1 file(s):

  srv/external/northbreeze.csn

[cds] - using bindings from: { registry: '~/.cds-services.json' }
[cds] - connect to db > sqlite { url: ':memory:' }
/> successfully deployed to in-memory database.

[cds] - mocking northbreeze {
  at: [ '/odata/v4/northbreeze' ],
  decl: 'srv/external/northbreeze.csn:170'
}
[cds] - server listening on { url: 'http://localhost:4004' }

This is because cds watch is actually shorthand for:

cds serve all --with-mocks --in-memory?

and if we read the help for --with-mocks we see this:

Use this in combination with the variants serving multiple services.

It starts in-process mock services for all required services configured in package.json#cds.requires, which don't have external bindings in the current process environment.

Note that by default, this feature is disabled in production and must be enabled with configuration 'features.mocked_bindings=true'.

That's right - mocking is already being done for our imported remote service! It's in-process, i.e. within the same CAP server process that we started with cds watch.

The package.json file is extended

As part of the import process, package.json was modified in two key areas:

--- a/remoteservice/package.json
+++ b/remoteservice/package.json
@@ -4,7 +4,10 @@
   "description": "Demonstrating local-first support for remote services",
   "dependencies": {
     "@sap/cds": "^9",
-    "express": "^4"
+    "express": "^4",
+    "@sap-cloud-sdk/connectivity": "^4",
+    "@sap-cloud-sdk/http-client": "^4",
+    "@sap-cloud-sdk/resilience": "^4"
   },
   "devDependencies": {
     "@cap-js/sqlite": "^2"
@@ -12,5 +15,13 @@
   "scripts": {
     "start": "cds-serve"
   },
-  "private": true
-}
+  "private": true,
+  "cds": {
+    "requires": {
+      "northbreeze": {
+        "kind": "odata",
+        "model": "srv/external/northbreeze"
+      }
+    }
+  }
+}

the SAP Cloud SDK libraries were added - for marshalling of, connection to and communication with remote destinations²
the remote service is added as "required", with the name northbreeze

Reviewing the situation

This in-process mocking of the required remote service "northbreeze" means that in the CAP server context that exists for our project, we have that remote service as an endpoint available to us at http://localhost:4004:

But while the mocked remote service is already fully formed, even in this "in-process" mode, there's no data. Let's add some so we can better explore the service.

Add data for the mocked remote service

Using CAP's mock data facilities, we can easily come up with some mock data. Because of CAP's convention over configuration axiom, this works even for mocked remote services. As an erstwhile Perl programmer, I appreciate this DWIM-style approach.

To dig in more to the mock data facilities in CAP, see the mocking data blog post in this series.

Have some data generated

Let's first have CAP generate some data for us:

cds \
  add data \
  --filter Categories \
  --records 10

This creates a CSV file with an appropriate name and in the expected place for initial data:

./
├── db/
│   └── data/
│       └── northbreeze.Categories.csv
├── package.json
└── srv/
    └── external/
        ├── northbreeze.csn
        └── northbreeze.edmx

Retrieve data and use that too

Given this is about gathering some data to exercise the mocked remote service, it's likely that the actual remote service has data that we can perhaps use too.

Being an OData V4 service, the data available, in the form of, say, an entityset, is going to be in JSON format by default. But that's fine, the CAP server's data mechanism can deal with this too. So let's grab the Products data from the actual remote service and place it alongside the Categories data we have:

curl \
  --silent \
  --url 'https://odd.cfapps.eu10.hana.ondemand.com/northbreeze/Products' \
| jq .value \
> db/data/northbreeze.Products.json

We can mix CSV and JSON data with ease:

./
├── db/
│   └── data/
│       └── northbreeze.Categories.csv
:       └── northbreeze.Products.json

and it's picked up as we would hope:

[cds] - connect to db > sqlite { url: ':memory:' }
  > init from db/data/northbreeze.Products.json
  > init from db/data/northbreeze.Categories.csv
/> successfully deployed to in-memory database.

Move the data closer to the service

While the data for this mocked external required service is perfectly fine in db/data/ and is picked up as we'd expect, perhaps it makes more sense to keep it closer to the service definition, as a "bundle", as it were. That will work too, with respect to the automatic data loading mechanism, so let's do that:

mv db/data/ srv/external/

Now the external service is more self-contained:

./
├── db/
├── package.json
└── srv/
    └── external/
        ├── data/
        │   ├── northbreeze.Categories.csv
        │   └── northbreeze.Products.json
        ├── northbreeze.csn
        └── northbreeze.edmx

Switching to a more realistic scenario

There are a couple of aspects we should look at now, based on the very simple setup we have so far:

the required remote service has been mocked in-process; ideally we want a local development scenario that is closer to the eventual production situation
it is also entirely independent, unrelated to any local service definitions

Regarding the first aspect, we can also have a service mocked in a separate process, instead of being mocked in-process. One effect of this is that real wire API calls are made between your local service and the separately mocked (but still locally running) remote service.

Regarding the second aspect, we'll set up a local to remote proxy definition in our CDS model, for an entity. We'll do that first staying with in-process mocking, and then switch to separate process based mocking.

Set up a local to remote proxy definition

One of the simplest forms of service mashup is surfacing a remote entity as a local one. This may not be entirely useful, but it demonstrates the atomic structure of more involved scenarios, and is nice and simple so as not to get in the way of understanding here.

First, add the following service definition in srv/main.cds, remembering that the using directive here brings in the northbreeze scope from the imported remote service definition that was created with the cds import earlier:

using {northbreeze} from './external/northbreeze';

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

In the following sections, we'll see the difference between in-process and external process mocking.

Examine the CAP server logs now

Once the CAP server restarts, take a look at the log output:

[cds] - loaded model from 2 file(s):

  srv/main.cds
  srv/external/northbreeze.csn

[cds] - using bindings from: { registry: '~/.cds-services.json' }
[cds] - connect to db > sqlite { url: ':memory:' }
  > init from srv/external/data/northbreeze.Products.json
  > init from srv/external/data/northbreeze.Categories.csv
/> successfully deployed to in-memory database.

[cds] - serving Main {
  at: [ '/odata/v4/main' ],
  decl: 'srv/main.cds:3'
}
[cds] - mocking northbreeze {
  at: [ '/odata/v4/northbreeze' ],
  decl: 'srv/external/northbreeze.csn:170'
}

What we see is very useful and helps augment our understanding:

the overall CDS model is built from the local definition we've just created, plus the definitions from the remote service
initial data is being loaded from the CSV and JSON files
the local provided service Main is served
the remote required service northbreeze is also served, mocked in-process

Moreover, when we request a Products resource from the local Main service at /odata/v4/main, which as we know from our service definition is a projection onto the corresponding entity in the remote service definition:

curl --url 'localhost:4004/odata/v4/main/Products?$top=1'

we get a successful result:

{
  "@odata.context": "$metadata#Products",
  "value": [
    {
      "ProductID": 1,
      "ProductName": "Chai",
      "QuantityPerUnit": "10 boxes x 20 bags",
      "UnitPrice": 18,
      "Category_CategoryID": 1,
      "Supplier_SupplierID": 1,
      "UnitsInStock": 39,
      "UnitsOnOrder": 0,
      "ReorderLevel": 10,
      "Discontinued": false
    }
  ]
}

This is due to the in-process based connectivity available in the single CAP server process.

Let's stop the CAP server at this point.

Mock the remote service in a separate process

In a second terminal window, let's now start the standalone mocking of the required northbreeze service with the cds mock command³, like this:

cds mock northbreeze

We should see output like this:

[cds] - using bindings from: { registry: '~/.cds-services.json' }
[cds] - connect to db > sqlite { database: ':memory:' }
  > init from srv/external/data/northbreeze.Products.json
  > init from srv/external/data/northbreeze.Categories.csv
/> successfully deployed to in-memory database.

[cds] - mocking northbreeze {
  at: [ '/odata/v4/northbreeze' ],
  decl: 'srv/external/northbreeze.csn:170'
}
[cds] - server listening on { url: 'http://localhost:42623' }

The initial data is loaded as before, the northbreeze service is served, but crucially:

the provided Main service is not served (as we haven't asked it to be)
the required northbreeze service is available on a non-standard (in fact random) port 42623

We can successfully request resources in this mocked remote service at http://localhost:42623/odata/v4/northbreeze.

Start a normal CAP server process to have the local service served

Now in the first terminal window, let's restart the CAP server with cds watch, and we should now see:

[cds] - using bindings from: { registry: '~/.cds-services.json' }
[cds] - connect to db > sqlite { url: ':memory:' }
/> successfully deployed to in-memory database.

[cds] - serving Main {
  at: [ '/odata/v4/main' ],
  decl: 'srv/main.cds:3'
}
[cds] - server listening on { url: 'http://localhost:4004' }

Now, there's no initial data loaded, because that belongs to the required remote northbreeze service and thus not relevant here, because only the Main service is being served.

Why is only the provided Main service being served, and not the required remote northbreeze service, like before?

Get to know the binding registry

To answer that question, we need to recall that highlighted part of the help for the mocking option to cds serve earlier:

It starts in-process mock services for all required services configured in package.json#cds.requires, which don't have external bindings in the current process environment.

Here, in our local-first development context, our "current process environment" is effectively any (and all) CAP server process(es) running locally.

You might have noticed this line appearing in previous CAP server output samples in this post:

[cds] - using bindings from: { registry: '~/.cds-services.json' }

As they start up and shut down, local CAP server processes read and write to this registry file ~/.cds-services.json. They read it to see what services are available (that they might be requiring), and write to it to record the services they're providing (for other locally running CAP server processes).

When we started the separate CAP server to mock the northbreeze remote service with cds mock northbreeze, information was written to this file, recording the fact that this northbreeze service is "provided":

{
  "cds": {
    "provides": {
      "northbreeze": {
        "endpoints": {
          "odata": "/odata/v4/northbreeze"
        },
        "server": 17250
      }
    },
    "servers": {
      "17250": {
        "root": "file:///work/gh/github.com/qmacro/cap-nodejs-local-first-development/remoteservice",
        "url": "http://localhost:42623"
      }
    }
  }
}

As we can see, it also records where the provision is, in this case at http://localhost:42623, which is at the port that the mock server is listening on.

This is why a random port is not such a problem here.

Retry the local to remote proxy - part 1

Now that we have two CAP server processes running, one mocking the required remote service northbreeze, and the other serving the local service Main, let's retry that same request (to get the product data from the mocked remote service, proxied through the local service definition):

curl --url 'localhost:4004/odata/v4/main/Products?$top=1'

Oh dear:

{
  "error": {
    "message": "Entity \"Main.Products\" is annotated with \"@cds.persistence.skip\" and cannot be served generically.",
    "code": "501",
    "@Common.numericSeverity": 4
  }
}

The in-process connectivity available (provided for convenience) cannot be used here, and we have to implement some basic query and connectivity logic which is exactly what we will have to do in a productive scenario anyway.

So let's do that, using the simplest thing that could possibly work - adding this to a corresponding srv/main.js file:

const cds = require('@sap/cds')
module.exports = cds.service.impl(async function() {
  const northbreeze = await cds.connect.to('northbreeze')
  this.on('READ', 'Products', async (req) => {
    return await northbreeze.run(req.query)
  })
})

When a query arrives to read Products data, send it across to northbreeze and pass back whatever is returned.

Once the CAP server in the first terminal window restarts because of this change, note that there's a new log line in the output:

[cds] - connect to northbreeze > odata { url: 'http://localhost:42623/odata/v4/northbreeze' }

This is a direct result of the await cds.connect.to('northbreeze') line above.

Retry the local to remote proxy - part 2

With this simple implementation in place, retrying that same request again will result in some very satisfying log output in both CAP server processes.

Before we do, stop the CAP server in the first terminal window and restart it specifying DEBUG=remote like this, to get more log output detail for remote related activities:

DEBUG=remote cds watch

Now, after retrying the request for a final time, we see this log output in the first (Main) CAP server log output:

[remote] - GET http://localhost:42623/odata/v4/northbreeze/Products?$select=ProductID,ProductName,QuantityPerUnit,UnitPrice,Category_CategoryID,Supplier_SupplierID,UnitsInStock,UnitsOnOrder,ReorderLevel,Discontinued&$top=1 {
  headers: {
    accept: 'application/json,text/plain',
    'x-correlation-id': 'ff4da315-ec6e-4e89-97d4-85f96b270ed6',
    'x-correlationid': 'ff4da315-ec6e-4e89-97d4-85f96b270ed6'
  }
}
[remote] - Executing via native fetch.

We can see that there's an HTTP request, specifically an OData QUERY operation, that's been constructed and sent to the URL where the remote service is being provided⁴.

And in the CAP server process in the second terminal window, where we're separately mocking the northbreeze remote service on 42623, we see that OData QUERY operation arrive:

[odata] - GET /odata/v4/northbreeze/Products {
  '$select': 'ProductID,ProductName,QuantityPerUnit,UnitPrice,Category_CategoryID,Supplier_SupplierID,UnitsInStock,UnitsOnOrder,ReorderLevel,Discontinued',
  '$top': '1'
}

A true inter-process remote service call. All running locally, and orchestrated in the simplest way possible.

Wrapping up

This post has just scratched the surface of what's possible when it comes to working in local-first development mode, with remote services. For more information and stuff that you can practise yourself, we have the CAP Service Integration CodeJam exercises publicly available for you. Happy learning!

Footnotes

"odd" is short for OData Deep Dive, and the service is used in the corresponding SAP Tutorial Navigator mission that I'm rewriting currently - see OData Deep Dive rewrite in the open for details.
Note that since the CAP Apr 2026 release, the SAP Cloud SDK is no longer mandatory for remote communication in development scenarios.

cds mock servicename is actually just shorthand for

cds serve --mocked servicename --in-memory? --port 0

We can also see, via the "Executing via native fetch" line, that the Node-native Fetch API is in use here now, since Apr 2026.

Local-first dev with CAP Node.js - mocking auth

2026-05-12T00:00:00Z

This post is one of a series on local-first development with CAP Node.js.

The mocked authentication strategy

The Authentication Strategies section of the Node.js Security topic in Capire explains the different strategies available, and the "mocked" strategy comes with pre-defined users that can be used, with their various levels of authorisations, to explore, define and test security-related constructs. This mock user configuration can be modified and extended too, but what comes out of the box is definitely enough to get started.

Working through an example

In this post, we'll work through an example of mocking auth, based on content in the auth/ directory of the talk repository.

Note that what's absent here is any form of auth implementation - all declarations available are automatically enforced by CAP's generic service providers.

The service definition

In srv/main.cds there's a single service defined, with a couple of entities that are simple projections on to the entities in the data model:

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

service Main {

  entity Products   as projection on northwind.Products;
  entity Categories as projection on northwind.Categories;

}

Starting a CAP server in local development mode with cds watch shows us that the mocked authentication strategy is in play by default:

[cds] - using auth strategy { kind: 'mocked' }
[cds] - serving Main {
  at: [ '/main' ],
  decl: 'srv/main.cds:4'
}

As we haven't yet addressed any auth requirements in our CDS model, access is currently open to all, as we can see¹:

; curl \
  --include \
  --url 'localhost:4004/main/Products?$top=1'
HTTP/1.1 200 OK
OData-Version: 4.0
Content-Type: application/json; charset=utf-8
Content-Length: 105

{
  "@odata.context": "$metadata#BasicProducts",
  "value": [
    {
      "ID": 1,
      "name": "Chai",
      "supplier": "Exotic Liquids"
    }
  ]
}

Examine the pre-defined users and their authorisations

We can take a look at the pre-defined user data that is defined for the mocked authentication strategy, with:

cds env requires.auth.users

which will emit something like this:

{
  alice: { tenant: 't1', roles: [ 'admin' ] },
  bob: { tenant: 't1', roles: [ 'cds.ExtensionDeveloper' ] },
  carol: { tenant: 't1', roles: [ 'admin', 'cds.ExtensionDeveloper' ] },
  dave: { tenant: 't1', roles: [ 'admin' ], features: [] },
  erin: { tenant: 't2', roles: [ 'admin', 'cds.ExtensionDeveloper' ] },
  fred: { tenant: 't2', features: [ 'isbn' ] },
  me: { tenant: 't1', features: [ '*' ] },
  yves: { roles: [ 'internal-user' ] },
  '*': true
}

Restrict the service

Let's annotate the service with some basic role based access control (RBAC) requirements - that of needing to authenticate, via the pseudo-role authenticated-user. We can use the @requires annotation:

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

@requires: 'authenticated-user'
service Main {

  ...

}

The same curl request as before now fails with an appropriate HTTP 401 status code:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Basic realm="Users"
Content-Type: text/plain; charset=utf-8
Content-Length: 12

Unauthorized

Authenticate with a pre-defined user

We can re-try the request with one of the pre-defined users²; because the requirement is just for the pseudo-role authenticated-user, we don't need any particular actual role allocated to the user, we just need to be successfully authenticated (and so identified) in this case:

; curl \
  --user alice: \
  --include \
  --url 'localhost:4004/main/Products?$top=1'
HTTP/1.1 200 OK
OData-Version: 4.0
Content-Type: application/json; charset=utf-8
Content-Length: 105

{
  "@odata.context": "$metadata#BasicProducts",
  "value": [
    {
      "ID": 1,
      "name": "Chai",
      "supplier": "Exotic Liquids"
    }
  ]
}

Try some finer-grained access restrictions

With the @restrict we can define finer grained access requirements³ in privilege building blocks of this form:

{ grant:<events>, to:<roles>, where:<filter-condition> }

Let's now add privilege requirements for the Categories entity, like this:

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

@requires: 'authenticated-user'
service Main {

  entity Products   as projection on northwind.Products;

  @restrict: [
    {
      grant: 'WRITE',
      to   : 'buyer'
    },
    {
      grant: 'READ',
      to   : 'any'
    }
  ]
  entity Categories as projection on northwind.Categories;
}

This says that any (authenticated) user can read the categories, but only a user with the buyer role can perform "write"-semantic operations.

Confirm read operations are permitted

Let's check that "read"-semantic operations are allowed for authenticated users (remember that the entity access is also governed by the authenticated-user pseudo-role restriction on the service that contains it):

; curl \
  --user alice: \
  --include \
  --url 'localhost:4004/main/Categories?$top=1'
HTTP/1.1 200 OK
OData-Version: 4.0
Content-Type: application/json; charset=utf-8
Content-Length: 155

{
  "@odata.context": "$metadata#Categories",
  "value": [
    {
      "CategoryID": 1,
      "CategoryName": "Beverages",
      "Description": "Soft drinks, coffees, teas, beers, and ales"
    }
  ]
}

Looks OK.

Try a write operation

Now for a "write"-semantic operation. Let's go big and try DELETE:

; curl \
  --user alice: \
  --include \
  --request DELETE \
  --url 'localhost:4004/main/Categories/1'
HTTP/1.1 403 Forbidden
OData-Version: 4.0
Content-Type: application/json; charset=utf-8
Content-Length: 74

{
  "error": {
    "message": "Forbidden",
    "code": "403",
    "@Common.numericSeverity": 4
  }
}

Alice, with the admin role, is denied.

Give the user more access in the mocked strategy

We can also modify and add to the pre-defined user definitions for the mocked authentication strategy. Let's do that, adding a couple of extra roles for Alice in a separate .cdsrc.json file in the project:

{
  "cds": {
    "requires": {
      "auth": {
        "users": {
          "alice": {
            "roles": [
              "admin",
              "buyer",
              "head-office"
            ]
          }
        }
      }
    }
  }
}

One of the roles is buyer, so let's now retry the previous request:

; curl \
  --user alice: \
  --include \
  --request DELETE \
  --url 'localhost:4004/main/Categories/1'
HTTP/1.1 204 No Content
OData-Version: 4.0

Success!

Wrapping up

With the mocked authentication strategy, we can embrace and work on the important aspect of securing our app or service right from the very start. CAP makes it easy to do the right things here.

For more information, see the Authentication topic in Capire.

Footnotes

The JSON output in these examples has been pretty-printed for readability here.
The --user option for curl allows us to specify a username and password separated by a colon, so alice: here is just the username combined with an empty password (there are no passwords for these users). If we'd just specified --user alice without a colon, then curl would have prompted us for a password - we could have then just pressed Enter but this is one step we can avoid.
In fact, @requires is just a convenience shortcut for @restrict. The annotation
```
@requires: 'authenticated-user'
```
that we used earlier is equivalent to
```
@restrict: [ { grant: '*', to: 'authenticated-user' } ]
```

Local-first dev with CAP Node.js

2026-05-11T00:00:00Z

This series post is related to a talk I'm putting together:

Local-first development with CAP Node.js - mock all the things!

As developers we need to be free of distractions plus a tight and speedy development loop. But definitely not at the expense of ignoring or postponing important design decisions. CAP's mocking facilities abstracts us from much tedium and ceremony, allowing us to iterate fast on data, auth, messaging and remote services while we develop. This session shows you what, and how.

There's a repo for the themes and demos in this talk at https://github.com/qmacro/cap-nodejs-local-first-development/.

You can read more about the context of this talk in the section below.

The posts

More context

There are a couple of aspects of development that come together for the perfect (positive) storm of focused rapid iteration that results in a solid and complete foundation for a production offering, from the outset. They are:

a tight feedback loop within which we can iterate rapidly on design and implementation
local-first facilities for everything we need to get going, with minimum setup and configuration

As part of this second aspect, being able to easily fold in key design requirements and real world facilities from the very start means that we don't avoid them, or put them off until it's too late. Instead, we can embrace and address them right from the start of the iteration cycles, and avoid the build-up of design debt. The CAP development kit includes tools and affordances that make this easy for us to do, in the form of mocking.

Local-first dev with CAP Node.js - mocking data

2026-05-11T00:00:00Z

This post is one of a series on local-first development with CAP Node.js.

Initial, test and sample data - terminology

Mocking data is likely the most common and useful of the various local-first development mechanisms that provide mock facilities.

Before we start digging in, it's worth spending a minute on terminology used in the CAP development ecosphere in general and in Capire in particular.

There are three terms widely used in the context of mocking data: "initial", "test" and "sample".

Initial data

This is real data that is intended for use beyond development. In other words, it's data that will be deployed not only in development but also in production scenarios. Conventionally, initial data is placed in a data/ directory within the db/ directory.

Test data

This is data for development and testing only. It is data that is not intended for production. Conventionally, test data is placed in a data/ directory within a test/ directory in the project, and will not be deployed in non-development scenarios.

Sample data

Unlike "initial" or "test", "sample" is a looser term that is not specifically recognised in Capire. However, it's implicitly part of the local-first development approach in that it refers to data that is provided in the context of a sample application or service, which itself is not intended for production.

In other words, what we might refer to as sample data is normally found in the same place as initial data, i.e. typically in a db/data/ directory, but won't make it to production because the entire project will never be deployed there.

An example of sample data is the set of files in the db/data/ directory in the @capire/bookshop sample.

Understanding the mock data structure

Following CAP's strong convention over configuration approach, which is especially useful in development mode, mock data is, by default:

in CSV format
organised into files, one per entity

and the contents (of all types) are automatically deployed to the database in development mode.

The file names are normally based on the entity's scope and name. For example, given the db/schema.cds content in the aforementioned @capire/bookshop sample:

using { Currency, cuid, managed, sap } from '@sap/cds/common';
namespace sap.capire.bookshop;

entity Books : managed {

  ...

}

then the corresponding mock data file for this entity is:

db/data/sap.capire.bookshop-Books.csv

Its location suggests that it is initial data, but the fact that it's a sample app suggests that we can consider it sample data here.

Working through an example

In this post, we'll work through an example of mocking data, based on content in the data/ directory of the repo set up for the related talk.

This directory contains a simplified "Northwind" sample with three entities Products, Suppliers and Categories in a db/schema.cds file, exposed in a simple service in srv/main.cds:

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

@rest  @path: '/northbreeze'
service northbreeze {

  entity Products   as projection on northwind.Products;
  entity Suppliers  as projection on northwind.Suppliers;
  entity Categories as projection on northwind.Categories;

}

To keep things even simpler, this service has been annotated with @rest for a simpler HTTP API surface¹.

Starting the server

Starting a CAP server in development mode with cds watch, we see:

[cds] - connect to db > sqlite { url: ':memory:' }
/> successfully deployed to in-memory database.

This tells us that the Data Definition Language (DDL) statements for the tables and views have been deployed.

But by following the links via http://localhost:4004, such as http://localhost:4004/northbreeze/Products, we see there is no data.

Creating initial data files

We can add the "data" facet to the project to generate initial data files, which will have the right names, be put in the right place, and have CSV header lines that reflect the entity structures.

Let's do that now, with:

cds add data

This emits:

Adding facet: data
adding headers only, use --records to create random entries
  creating db/data/northwind-Categories.csv
  creating db/data/northwind-Products.csv
  creating db/data/northwind-Suppliers.csv

Successfully added features to your project

Let's check the CSV headers:

head db/data/*

This should show something like this:

==> db/data/northwind-Categories.csv <==
CategoryID,CategoryName,Description

==> db/data/northwind-Products.csv <==
ProductID,ProductName,QuantityPerUnit,UnitPrice,Category_CategoryID,Supplier_SupplierID,UnitsInStock,UnitsOnOrder,ReorderLevel,Discontinued

==> db/data/northwind-Suppliers.csv <==
SupplierID,CompanyName,ContactName,ContactTitle,Address,City,Region,PostalCode,Country,Phone,Fax,HomePage

It's a great starting point if we want to add our own data records manually.

Adding generated data

But what if we wanted to get started with mock data even quicker? With the --records option, we can have "random" records generated for us. Let's try that now, using also the --force option to ensure the CSV files are created anew:

cds \
  add data \
  --records 3 \
  --force

While the generated data is largely random (as the output above already mentioned), note that relationships are honoured, and foreign keys are generated appropriately for some (not all) entities so that we can immediately try following such relationships.

For example, we can explore the relationships with this OData style URL construct http://localhost:4004/northbreeze/Suppliers?$select=CompanyName&$expand=Products($select=ProductName;$expand=Category) which will produce something like this:

[
  {
    "CompanyName": "CompanyName-18484714",
    "Products": [
      {
        "Category": {
          "CategoryID": 13848306,
          "CategoryName": "CategoryName-13848306",
          "Description": "Description-13848306"
        },
        "ProductName": "ProductName-16110827"
      },
      {
        "Category": {
          "CategoryID": 13848306,
          "CategoryName": "CategoryName-13848306",
          "Description": "Description-13848306"
        },
        "ProductName": "ProductName-16110828"
      },
      {
        "Category": {
          "CategoryID": 13848306,
          "CategoryName": "CategoryName-13848306",
          "Description": "Description-13848306"
        },
        "ProductName": "ProductName-16110829"
      }
    ]
  },
  {
    "CompanyName": "CompanyName-20258347",
    "Products": []
  },
  {
    "CompanyName": "CompanyName-20258348",
    "Products": []
  }
]

Using more realistic data

If you already have some data that you can transform into the appropriate CSV shape, then you can use that directly. In the .csv/ directory of our example, there are CSV files for each of the entities, with some realistic data (from Northwind).

Let's copy those over into db/data/:

cp .csv/* db/data/

This enables us to move forward with our development alongside our domain expert, with more familiar business data to work with.

Using non-CSV data

It's not just CSV data that the mock data mechanism supports. If you have JSON in the right "shape", you can use this too.

And it just so happens (not by accident) that the "shape" is exactly that of an OData V4 entityset, specifically the contents of the value node (i.e. not including the @odata.context). Here's an example from a cut down version of Northwind:

https://odd.cfapps.eu10.hana.ondemand.com/northbreeze/Products

We can use this directly in a JSON file where we'd normally find a CSV file. Let's retrieve that category data and use it²:

rm db/data/northwind-Products.csv # we don't want duplicate data errors
curl \
  --silent \
  --url 'https://odd.cfapps.eu10.hana.ondemand.com/northbreeze/Products' \
| jq .value \
> db/data/northwind-Products.json

Check the data is surfaced

Let's use the cds REPL for a change, to check that this data is also valid and surfaced. We can already tell that it is very likely OK, given the log message emitted when the CAP server restarted:

[cds] - connect to db > sqlite { url: ':memory:' }
  > init from db/data/northwind-Suppliers.csv
  > init from db/data/northwind-Products.json
  > init from db/data/northwind-Categories.csv
/> successfully deployed to in-memory database.

Starting the cds REPL and getting it to load and run a server for the current project with cds repl --run ., we see:

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

from cds.entities: {
  Products,
  Categories,
  Suppliers,
}

from cds.services: {
  db,
  northbreeze,
}

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

We can use the relatively new query mode with the .ql command:

> .ql
cql>

Now, within the cql> prompt, we can try out a query like this:

select from Products[UnitsInStock = 0] \
{ ProductName as name, Supplier.CompanyName as supplier }

which should emit something like this:

[
  { name: "Chef Anton's Gumbo Mix", supplier: 'New Orleans Cajun Delights' },
  { name: 'Alice Mutton', supplier: 'Pavlova Ltd.' },
  { name: 'Thüringer Rostbratwurst', supplier: 'Plutzer Lebensmittelgroßmärkte AG' },
  { name: 'Gorgonzola Telino', supplier: 'Formaggi Fortini s.r.l.' },
  { name: 'Perth Pasties', supplier: "G'day Mate" }
]

This is the equivalent of http://localhost:4004/northbreeze/Products?$filter=UnitsInStock eq 0&$select=ProductName&$expand=Supplier($select=CompanyName) which produces:

[
  {
    "ProductName": "Chef Anton's Gumbo Mix",
    "Supplier": {
      "CompanyName": "New Orleans Cajun Delights"
    }
  },
  {
    "ProductName": "Alice Mutton",
    "Supplier": {
      "CompanyName": "Pavlova Ltd."
    }
  },
  {
    "ProductName": "Thüringer Rostbratwurst",
    "Supplier": {
      "CompanyName": "Plutzer Lebensmittelgroßmärkte AG"
    }
  },
  {
    "ProductName": "Gorgonzola Telino",
    "Supplier": {
      "CompanyName": "Formaggi Fortini s.r.l."
    }
  },
  {
    "ProductName": "Perth Pasties",
    "Supplier": {
      "CompanyName": "G'day Mate"
    }
  }
]

Wrapping up

Getting started on that local-first tight development loop is easy with CAP, and made easier with the data mocking facilities. By the way, there's another example of using JSON in this context in the mocking remote services post which is also in this series.

Footnotes

Although, surprisingly, or wonderfully, depending on your perspective, OData system query options like $filter, $select and $expand work perfectly fine too. The beauty of OData is the formalisation and standardisation, which is naturally and logically lacking in something (REST) that is mainly an architectural style.
It's the same data as in the equivalent CSV file, but that's not important, what's important is the different format.

CDS expressions in CAP - notes on Part 6

2026-05-04T00:00:00Z

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

Introduction

00:00 Introduction and recap.

05:47 Patrice takes over and looks at the syntax diagram in the CXL topic of Capire and the specific path expression diagram. He remarks that one of the cool things about path expressions is that you can chain navigations together, as is shown in one of the examples that follow the diagram:

assoc[filter].struct.assoc.element

Such navigation paths are materialised at some point (on use) into constructs such as:

an EXISTS subquery
a LEFT JOIN
a correlated subquery (for the expands)

These path expressions in particular (as well as CXL in general) can be used everywhere; Patrice gives examples:

in CDL models (when defining the schema or service projections)
in annotation expressions (when referring to a path or element)
in queries (written in CQL)

10:26 As good things come in threes, or so they say, here's a final three-bullet point list (making a total of three lists, too), where Patrice enumerates the different contexts in which we used the nonSeller association-like calculated element (nonSeller = books[ stock > 170 ]), in the previous episode:

12:29 We get a glimpse behind the scenes at the @cap-js/db-service mechanisms, where Patrice shows the function that is used to generate aliases, in the context of the new (to us in this series) style of aliases shown in the normalised, intermediate CAP-style SQL:

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

These $-prefixed short alias names are "technical" aliases. There's a function that Patrice dives into, specifically getImplicitAlias in @cap-js/db-service/lib/utils.js, that has a useTechnicalAlias parameter which defaults to true.

At this point we'll make the transition to having these technical aliases shown in our CAP-style SQL, as shown in this example, instead of the human-centric ones we've had so far.

Looking at the genres entity definition

16:02 Patrice takes some time to explain the reason for the technical aliases, using the recursively structured Genres entity definition as an example:

entity Genres : sap.common.CodeList {
  key ID       : Integer;
      parent   : Association to Genres;
      children : Composition of many Genres
                   on children.parent = $self;
}

Querying the genre information in Patrice's sample project we see the general idea:

> await cds.ql`
  SELECT from ${Genres}
  { name, parent { * } }
  `
[
  { name: 'Fiction', parent: null },
  { name: 'Drama', parent: { name: 'Fiction', descr: null, ID: 10, parent_ID: null } },
  { name: 'Poetry', parent: { name: 'Fiction', descr: null, ID: 10, parent_ID: null } },
  { name: 'Fantasy', parent: { name: 'Fiction', descr: null, ID: 10, parent_ID: null } },
  { name: 'Science Fiction', parent: { name: 'Fiction', descr: null, ID: 10, parent_ID: null } },
  { name: 'Romance', parent: { name: 'Fiction', descr: null, ID: 10, parent_ID: null } },
  { name: 'Mystery', parent: { name: 'Fiction', descr: null, ID: 10, parent_ID: null } },
  { name: 'Thriller', parent: { name: 'Fiction', descr: null, ID: 10, parent_ID: null } },
  { name: 'Dystopia', parent: { name: 'Fiction', descr: null, ID: 10, parent_ID: null } },
  { name: 'Fairy Tale', parent: { name: 'Fiction', descr: null, ID: 10, parent_ID: null } },
  { name: 'Non-Fiction', parent: null },
  { name: 'Biography', parent: { name: 'Non-Fiction', descr: null, ID: 20, parent_ID: null } },
  { name: 'Autobiography', parent: { name: 'Biography', descr: null, ID: 21, parent_ID: 20 } },
  { name: 'Essay', parent: { name: 'Non-Fiction', descr: null, ID: 20, parent_ID: null } },
  { name: 'Speech', parent: { name: 'Non-Fiction', descr: null, ID: 20, parent_ID: null } }
]

To help visualise the genre hierarchy, here it is represented in a tree structure:

/tmp/genres/
├── Fiction (10)
│   ├── Drama
│   ├── Dystopia
│   ├── Fairy Tale
│   ├── Fantasy
│   ├── Mystery
│   ├── Poetry
│   ├── Romance
│   ├── Science Fiction
│   └── Thriller
└── Non-Fiction (20)
    ├── Biography (21)
    │   └── Autobiography
    ├── Essay
    └── Speech

Because we'll be referring to them later in this post, the IDs for Fiction, Non-Fiction and Biography (genres that are "parents") are shown in brackets.

An introduction to scoped queries

16:44 At this point Patrice introduces us to "scoped queries", where we can traverse the FROM with a path expression like construct:

> await cds.ql`
  SELECT from ${Genres}:parent
  { name }
  `
[
  { name: 'Fiction' },
  { name: 'Non-Fiction' },
  { name: 'Biography' }
]

Here's another "wait, what's this and what's going on?!" moment in this series :-)

Let's have a look at the CQN:

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

The value for from looks very much like a path expression - a ref with a value that is an array of multiple elements [ 'sap.capire.bookshop.Books', 'parent' ].

Next, let's have a look at the CAP-style SQL:

> q.forSQL()
cds.ql {
  SELECT: {
    from: { ref: [ 'sap.capire.bookshop.Genres' ], as: '$p' },
    columns: [ { ref: [ '$p', 'name' ] } ],
    where: [
      'exists',
      {
        SELECT: {
          from: { ref: [ 'sap.capire.bookshop.Genres' ], as: '$G' },
          columns: [ { val: 1 } ],
          where: [
            { ref: [ '$G', 'parent_ID' ] },
            '=',
            { ref: [ '$p', 'ID' ] }
          ]
        }
      }
    ]
  }
}

Taking a moment to stare at this the mist starts to clear. Looking at this intermediate form, we see:

there's an EXISTS clause that's been materialised
the "lead" and "related" entities involved are the same, here (Genres)
the main query retrieves the genre name
the subquery returns something based on a condition that correlates a relationship within this single entity
that condition is that the ID of the genre whose name we're retrieving in the main query ... matches a parent ID value, at least once

In other words, "retrieve the genres that are parents" (i.e. that have children).

This can be stretched out to another path level, to retrieve genres that are "grandparents" (i.e. that are parents of parents):

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

This returns just a single result in the set:

> await q
[
  { name: 'Non-Fiction' }
]

This makes sense, as we can see in the tree structure earlier, Non-Fiction is the only genre that is a parent of a parent:

/tmp/genres/
...
└── Non-Fiction (20)
    ├── Biography (21)
    │   └── Autobiography
    ├── Essay
    └── Speech

Further examples of scoped queries

I initially struggled with this example. Illustrative as it was (especially with the parent.parent part), it was one that was a little complicated due to its self-referential nature.

So I used the power & utility of the cds REPL to explore more, and things started to make sense. For example, this query gives us the genres for books written by authors 40 years old or younger (Carpenter and the two Brontë sisters):

> q = cds.ql`
  SELECT from Authors[age <= 40]:books.genre
  { name }
  `
cds.ql {
  SELECT: {
    from: {
      ref: [
        {
          id: 'Authors',
          where: [ { ref: [ 'age' ] }, '<=', { val: 40 } ]
        },
        'books',
        'genre'
      ]
    },
    columns: [ { ref: [ 'name' ] } ]
  }
}
> await q
[
  { name: 'Drama' },
  { name: 'Romance' },
  { name: 'Mystery' }
]

Again we have a path expression traversal happening in the from part of the query, this time with an infix filter on the first part of the path. I used an infix filter here to make the example a little more interesting.

I then wondered to myself what it would look and feel like to use an infix filter on a different part of the path, and came up with this:

> q = cds.ql`
  SELECT from ${Authors}:books[title like 'The %'].genre
  { name }
  `
cds.ql {
  SELECT: {
    from: {
      ref: [
        'sap.capire.bookshop.Authors',
        {
          id: 'books',
          where: [ { ref: [ 'title' ] }, 'like', { val: 'The %' } ]
        },
        'genre'
      ]
    },
    columns: [ { ref: [ 'name' ] } ]
  }
}

This produces the names of the genres of books that begin with the definite article ("The ..."):

> q = cds.ql`
  SELECT from ${Authors}:books[title like 'The %'].genre
  { name }
  `
cds.ql {
  SELECT: {
    from: {
      ref: [
        'sap.capire.bookshop.Authors',
        {
          id: 'books',
          where: [ { ref: [ 'title' ] }, 'like', { val: 'The %' } ]
        },
        'genre'
      ]
    },
    columns: [ { ref: [ 'name' ] } ]
  }
}
> await q
[
  { name: 'Fantasy' },
  { name: 'Mystery' }
]

At first I thought the first part of the path in this query would now be redundant, assuming that I could have just written:

> q = cds.ql`
  SELECT from ${Books}[title like 'The %'].genre
  { name }
  `

But I was mistaken.

The key to thinking about this is remembering the term "scoped". To illustrate, let's adjust the postfix projection to have the book titles returned, and run the scoped query:

> await cds.ql`
  SELECT from ${Authors}:books[title like 'The %']
  { title }
  `
[
  { title: 'The Raven' },
  ... (12 rows removed for brevity)
  { title: 'The Fall of Gondolin' }
]

Running the unscoped query returns the same result set, yes:

> await cds.ql`
  SELECT from ${Books}[title like 'The %']
  { title }
  `
[
  { title: 'The Raven' },
  ... (12 rows removed for brevity)
  { title: 'The Fall of Gondolin' }
]

At this point let's add a book, but without a connection to an author, like this:

> await INSERT.into(Books,[{ID:999,title: 'The Book With No Author!'}])
InsertResult { results: [ { changes: 1, lastInsertRowid: 999 } ] }

Now re-running those queries gives us different result sets. First, the new book is included in the result set for the unscoped query:

> await cds.ql`
  SELECT from ${Books}[title like 'The %']
  { title }
  `
[
  { title: 'The Raven' },
  ... (12 rows removed for brevity)
  { title: 'The Fall of Gondolin' },
  { title: 'The Book With No Author!' }
]

But it is not included in the result set for the scoped query:

> await cds.ql`
  SELECT from ${Authors}:books[title like 'The %']
  { title }
  `
[
  { title: 'The Raven' },
  ... (12 rows removed for brevity)
  { title: 'The Fall of Gondolin' }
]

While both queries are materialised into SELECTs on sap.capire.bookshop.Books, the scoped query constrains the result set to those entries where there is an author, as we can see with the EXISTS in the intermediate SQL:

> cds.ql`
  SELECT from ${Authors}:books[title like 'The %']
  { title }
  `.forSQL()
cds.ql {
  SELECT: {
    from: { ref: [ 'sap.capire.bookshop.Books' ], as: '$b' },
    columns: [ { ref: [ '$b', 'title' ] } ],
    where: [
      'exists',
      {
        SELECT: {
          from: { ref: [ 'sap.capire.bookshop.Authors' ], as: '$A' },
          columns: [ { val: 1 } ],
          where: [
            { ref: [ '$A', 'ID' ] },
            '=',
            { ref: [ '$b', 'author_ID' ] }
          ]
        }
      },
      'and',
      { ref: [ '$b', 'title' ] },
      'like',
      { val: 'The %' }
    ]
  }
}

See the section Combining the scoped syntax with infix filters later on in these notes for more on this.

Back to looking at the technical aliases

At 18:40 Patrice steers us back to thinking about technical aliases by adding an explicit alias to the path expression in the query:

> q = cds.ql`
  SELECT from ${Genres}:parent as parent
  { name, parent.ID }
  `
cds.ql {
  SELECT: {
    from: { ref: [ 'sap.capire.bookshop.Genres', 'parent' ], as: 'parent' },
    columns: [ { ref: [ 'name' ] }, { ref: [ 'parent', 'ID' ] } ]
  }
}

Let's just see what this emits when executed:

> await q
[
  { name: 'Fiction', ID: 10 },
  { name: 'Non-Fiction', ID: 20 },
  { name: 'Biography', ID: 21 }
]

The alias is to the path expression in the query, and is an explicit one. It was also used explicitly in the parent.ID construct. There's also an implicit alias in that the referenced name element is really parent.name.

But things get confusing if we want to refer to elements in the parent genre's parent, as Patrice demonstrates:

> q = cds.ql`
  SELECT from ${Genres}:parent as parent
  { name, parent.parent.ID }
  `
cds.ql {
  SELECT: {
    from: { ref: [ 'sap.capire.bookshop.Genres', 'parent' ], as: 'parent' },
    columns: [ { ref: [ 'name' ] }, { ref: [ 'parent', 'parent', 'ID' ] } ]
  }
}

Note the three level path expression:

{ ref: [ 'parent', 'parent', 'ID' ] }

This returns:

> await q
[
  { name: 'Fiction', parent_ID: null },
  { name: 'Non-Fiction', parent_ID: null },
  { name: 'Biography', parent_ID: 20 }
]

which is what we should expect, in that Fiction and Non-Fiction are top level genres and have no parents.

Clearly there's a high degree of potential confusion and conflict, and so technical aliases make more sense in the runtime (i.e. implicitly) as they have far less chance of clashing.

At this point, it wouldn't be a bad idea to go and get a coffee and then come back for the rest of this write-up :-)

From nested expands to dot notation projections

23:02 At this point we revisit a nested expand from last week:

> await cds.ql`
  SELECT from ${Authors}
  { name, nonSeller { title, stock } }
  where exists nonSeller
  `
[
  {
    name: 'Richard Carpenter',
    nonSeller: [ { title: 'Catweazle', stock: 187 } ]
  },
  {
    name: '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 }
    ]
  }
]

Patrice reminds us that such an expand is "just another postfix projection", which leads to the possibility of using * and excluding clauses, as we saw in the previous episode on this topic:

{ name, nonSeller { * } excluding { ID } }

With such expands being "variants" of postfix projections, we are then introduced to another variant, which looks similar but does something different.

To illustrate, we move up to the service layer and go to the Books projection in the CatalogService, which currently looks like this, which includes a single element (the author name) from the author association:

entity Books       as
  projection on my.Books {
    *,
    author.name as author
  }
  excluding {
    createdBy,
    modifiedBy
  };

If we wanted to add another element from the author association, we could do this:

entity Books       as
  projection on my.Books {
    *,
    author.name as author,
    author.dateOfBirth
  }
  excluding {
    createdBy,
    modifiedBy
  };

At 26:27 Patrice shows what this resolves to at the database layer, by running a build for HANA:

cds build --profile production

This produces the HANA artifacts for deploying via the HDI container. One of these artifacts is the gen/db/src/gen/CatalogService.Books.hdbview file which contains the DDL statement to create the view that represents this projection:

VIEW CatalogService_Books AS SELECT
  Books_0.createdAt,
  Books_0.modifiedAt,
  Books_0.title,
  Books_0.ID,
  Books_0.descr,
  author_1.name AS author,
  Books_0.genre_ID,
  Books_0.stock,
  Books_0.price,
  Books_0.currency_code,
  author_1.dateOfBirth
FROM (
  sap_capire_bookshop_Books AS Books_0
  LEFT JOIN sap_capire_bookshop_Authors AS author_1
    ON Books_0.author_ID = author_1.ID
)

Doing this for the CDL is the rough equivalent to when we've been examining the corresponding SQL for our queries in CQL, using toSQL() in the cds REPL.

Here's what Patrice had to say about this DDL:

technical aliases (Books_0 and author_1) were used by the compiler, minimising ambiguities
both name and dateOfBirth use the same JOIN node

Now we have defined this and have confirmed at the DDL level what we expect to see, we can now explore the dot notation, which is essentially a little bit of syntactic sugar that is arguably easier on the eye:

entity Books       as
  projection on my.Books {
    *,
    author.{
      name,
      dateOfBirth
    }
  }
  excluding {
    createdBy,
    modifiedBy
  };

We can easily think of this as opening another projection (on the author association) because of the use of braces, but be aware that this is not a nested expand, it is a shortcut to, or a summarised version of, multiple path expressions with the same root.

A look at the compiled DDL for this variant shows that it's pretty much the same, i.e. still a flat list of elements, essentially:

VIEW CatalogService_Books AS SELECT
  Books_0.createdAt,
  Books_0.modifiedAt,
  Books_0.title,
  Books_0.ID,
  Books_0.descr,
  Books_0.author_ID,
  Books_0.genre_ID,
  Books_0.stock,
  Books_0.price,
  Books_0.currency_code,
  author_1.name AS name,
  author_1.dateOfBirth AS dateOfBirth
FROM (
  sap_capire_bookshop_Books AS Books_0
  LEFT JOIN sap_capire_bookshop_Authors AS author_1
    ON Books_0.author_ID = author_1.ID
)

We do get the Books_0.author_ID element additionally here, but that is of little consequence.

The power of infix filters

Patrice goes one step further at 30:45 to show how an infix filter might be added to this dot notation construct; the filter chosen isn't allowed in this context, but something like this is:

entity Books       as
  projection on my.Books {
    *,
    author[isAlive].{
      name as thename,
      dateOfBirth
    }
  }
  excluding {
    createdBy,
    modifiedBy
  };

In fact, Patrice uses this condition a little bit later on, albeit in a slightly longer form isAlive = true.

There is a wider range of possibilities here in the context of queries, which Patrice then demonstrates in the cds REPL with:

> await cds.ql`
  SELECT from ${Books}
  {
    title as book,
    author[exists books[genre.name = 'Fantasy']].{ name, age }
  }
  `
[
  { book: 'Wuthering Heights', author_name: null, author_age: null },
  { book: 'Jane Eyre', author_name: null, author_age: null },
  { book: 'The Raven', author_name: null, author_age: null },
  { book: 'Eleonora', author_name: null, author_age: null },
  {
    book: 'Catweazle',
    author_name: 'Richard Carpenter',
    author_age: 82
  },
  {
    book: 'Mistborn: The Final Empire',
    author_name: 'Brandon Sanderson',
    author_age: 50
  },
  {
    book: 'The Well of Ascension',
    author_name: 'Brandon Sanderson',
    author_age: 50
  },
  ...
]

Here we have a nested infix filter. Note that the condition construct only applies to the author data here, which explains why we have null values for some authors but not for others, within the books-led set.

Patrice highlights that one of the advantages of this dot notation approach, when used with infix filters, is that we can define our path conditions up front and then specify what we want when we follow that path, without having to repeat it.

This is also known as an inline nested projection.

Infix filter construction

At 36:36 Patrice shows us the syntax diagram that describes infix filters

and we talk a little about:

the where keyword, which is optional and often omitted, similar to other keywords in CDL such as define.
the main part which is an expression, which is thus essentially "anything"

This latter point means that, depending on the context used, infix filters will be materialised into different shapes.

Materialisation in DDL

To illustrate this somewhat, and to round this section out, at 38:18 Patrice modifies the infix filter condition in the CDL for the books projection to be dateOfBirth > 1900¹:

entity Books       as
  projection on my.Books {
    *,
    author[dateOfBirth > 1900].{
      name as thename,
      dateOfBirth
    }
  }
  excluding {
    createdBy,
    modifiedBy
  };

This has the effect that the DDL for the corresponding view in HANA is defined like this:

VIEW CatalogService_Books AS SELECT
  Books_0.createdAt,
  Books_0.modifiedAt,
  Books_0.title,
  Books_0.ID,
  Books_0.descr,
  Books_0.author_ID,
  Books_0.genre_ID,
  Books_0.stock,
  Books_0.price,
  Books_0.currency_code,
  author_1.name AS thename,
  author_1.dateOfBirth AS dateOfBirth
FROM (
  sap_capire_bookshop_Books AS Books_0
  LEFT JOIN sap_capire_bookshop_Authors AS author_1
    ON
      (Books_0.author_ID = author_1.ID)
      AND
      (author_1.dateOfBirth > 1900)
)

The infix filter is mixed in to the main foreign key matching part of the ON condition.

Infix filters in the FROM clause

Infix filters can also be used in the FROM clause in queries, as Patrice shows at 43:35:

> await cds.ql`
  SELECT from ${Books}[where stock between 50 and 100]
  { title, stock }
  `
[
  { title: 'Wuthering Heights', stock: 95 },
  { title: 'Jane Eyre', stock: 78 },
  { title: 'The Alloy of Law', stock: 67 },
  { title: 'Shadows of Self', stock: 89 },
  { title: 'Mistborn: Secret History', stock: 98 }
]

This is a nice syntactic sugar based variant, made even better by the use of the optional where, so we can read the entire construct (entity, infix filter condition and then the postfix projection) naturally, rather than e.g.:

> await cds.ql`
  SELECT from ${Books}
  { title, stock }
  where stock between 50 and 100
  `

These variants are the same, which we can see if we compare their intermediate SQL (via forSQL()):

cds.ql {
  SELECT: {
    from: { ref: [ 'sap.capire.bookshop.Books' ], as: '$B' },
    columns: [ { ref: [ '$B', 'title' ] }, { ref: [ '$B', 'stock' ] } ],
    where: [
      { ref: [ '$B', 'stock' ] },
      'between',
      { val: 50 },
      'and',
      { val: 100 }
    ]
  }
}

Combining the scoped syntax with infix filters

To drive home two of the key concepts we've looked at, Patrice now combines them, starting at 47:15. In other words, taking the scoped syntax variant of the FROM clause with a path expression constructed with a colon, and adding an infix filter.

To illustrate this and start simply, we first see this, which is just the scoped query part:

> q = cds.ql`SELECT from ${Books}:author { name }`
cds.ql {
  SELECT: {
    from: { ref: [ 'sap.capire.bookshop.Books', 'author' ] },
    columns: [ { ref: [ 'name' ] } ]
  }
}
> await q
[
  { name: 'Emily Brontë' },
  { name: 'Charlotte Brontë' },
  { name: 'Edgar Allen Poe' },
  { name: 'Richard Carpenter' },
  { name: 'Brandon Sanderson' },
  { name: 'J. R. R. Tolkien' }
]

This alone is worth dwelling on, when Patrice explains how he thinks about such constructs - reading from right to left: "select those authors for whom exist (at least one) book(s)". The selection is on the Authors entity, but it is constrained by the books-authors relationship.

If there was an author in the database for whom there were no corresponding book entries, this author would not be part of the result set. Rather than add an entry to show this, Patrice now adds on to this query an infix filter for the Books entity:

> q = cds.ql`
  SELECT from ${Books}[stock between 50 and 100]:author
  { name }
  `

Looking at the intermediate SQL, we can see that this stock based condition in the infix filter becomes part of the WHERE clause of the subquery used in the EXISTS:

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

This has the expected effect - a reduced result set:

> await q
[
  { name: 'Emily Brontë' },
  { name: 'Charlotte Brontë' },
  { name: 'Brandon Sanderson' }
]

And the possibilities don't end there, of course, which Patrice shows at this point by gratuitously adding another infix clause thus:

> await cds.ql`
  SELECT from ${Books}[stock between 50 and 100]:author[order by name asc]
  { name }
  `
[
  { name: 'Brandon Sanderson' },
  { name: 'Charlotte Brontë' },
  { name: 'Emily Brontë' }
]

At this point in this writeup, I wonder about the contents of this second infix clause, in that it's not really a filter in the simple way I understand filters so I wanted to try to add something that feels more like an actual "restrictive" filter², and that works too:

> await cds.ql`
  SELECT from ${Books}[stock between 50 and 100]:author[name like '%Brontë']
  { name }
  `
[
  { name: 'Emily Brontë' },
  { name: 'Charlotte Brontë' }
]

Disambiguating elements and their scoped named containers with colons

At 50:00 I ask Patrice to explain a little bit more about the use of the colon (:) when constructing a "fully qualified" element reference. Normally we would use a dot to express traversal through a relationship, such as author.name. But when it comes to including the "container" name, most commonly an entity, we must be precise and unambiguous, especially in the context of how the compiler will interpret what we express.

With the use of namespaces, defined with either the namespace or context directives, or even just expressed explicitly (e.g. entity Foo.Bar { ... }), a question arises: "Where does the name of the container end and the name of the element (path) start?". Sometimes, a colon is needed to facilitate the answer to that question.

Here's an example. Consider this simple model:

namespace a;

context b.c {

  entity D {
    e : String;
  }

}

If we wanted to annotate the element e with @readonly³, we might write:

annotate a.b.c.D.e with @readonly;

However, the compiler would emit a warning:

Artifact “a.b.c.D.e” has not been found

To disambiguate where the "join" is, we use a colon⁴:

annotate a.b.c.D : e with @readonly;

Summarising infix filters

At 52:58 Patrice gives a nice summary concerning infix filters, which can be employed in many places - everywhere that you can use paths, effectively - and are materialised differently depending on where and how they're used:

in a LEFT JOIN
in an EXISTS subquery
in a correlated subquery

Yes, it's not a coincidence that this is the same list that we considered at the start of this episode.

Here follows examples of each of those.

In a service projection (a JOIN example)

One of these places we saw was in the Books projection in the CatalogService (see the Materialisation in DDL section):

author[dateOfBirth > 1900].name as authorName

This infix filter is materialised in the JOIN

VIEW CatalogService_Books AS SELECT
  ...
  Books_0.author_ID,
  ...
  author_1.name AS authorName,
  author_1.dateOfBirth AS dateOfBirth
FROM (
  sap_capire_bookshop_Books AS Books_0
  LEFT JOIN sap_capire_bookshop_Authors AS author_1
    ON (Books_0.author_ID = author_1.ID)
    AND (author_1.dateOfBirth > 1900)
)

In a scoped query (an EXISTS example)

The infix filter in the scoped query we saw earlier (see the Combining the scoped syntax with infix filters section):

> q = cds.ql`
  SELECT from ${Books}[stock between 50 and 100]:author
  { name }
  `

is pushed down and added to the EXISTS subquery when the query is materialised; we can see this nicely even in the intermediate (CAP-style) SQL:

cds.ql {
  SELECT: {
    from: { ref: [ 'sap.capire.bookshop.Authors' ], as: '$a' },
    columns: [ { ref: [ '$a', 'name' ] } ],
    expand: 'root',
    orderBy: [ { ref: [ 'name' ], sort: 'asc' } ],
    where: [
      'exists',
      {
        SELECT: {
          from: { ref: [ 'sap.capire.bookshop.Books' ], as: '$B' },
          columns: [ { val: 1 } ],
          where: [
            { ref: [ '$B', 'author_ID' ] },
            '=',
            { ref: [ '$a', 'ID' ] },
            'and',
            { ref: [ '$B', 'stock' ] },
            'between',
            { val: 50 },
            'and',
            { val: 100 }
          ]
        }
      }
    ]
  }
}

In an expand construction (a correlated subquery example)

When the infix filter is used in the context of an expand (which will result in a nested result set) then the filter (stock > 10) is pushed down into the context of the subquery constructed for the expand, and added to the correlated subquery's conditions.

> cds.ql`
  SELECT from ${Authors}
  { books[stock > 10] { title } }
  `.forSQL()
cds.ql {
  SELECT: {
    from: { ref: [ 'sap.capire.bookshop.Authors' ], as: '$A' },
    columns: [
      {
        SELECT: {
          from: { ref: [ 'sap.capire.bookshop.Books' ], as: '$b' },
          columns: [ { ref: [ '$b', 'title' ] } ],
          expand: true,
          one: false,
          where: [
            { ref: [ '$A', 'ID' ] },
            '=',
            { ref: [ '$b', 'author_ID' ] },
            'and',
            { ref: [ '$b', 'stock' ] },
            '>',
            { val: 10 }
          ]
        },
        as: 'books'
      }
    ]
  }
}

Expressiveness in infix filters

Rounding off this episode at around 57:13 Patrice shows how expressive infix filters can be, with:

> cds.ql`
  SELECT from ${Books}[
    stock between 50 and 100
    and exists genre[name = 'Fantasy']
  ]:author
  { name }
  `.forSQL()
cds.ql {
  SELECT: {
    from: { ref: [ 'sap.capire.bookshop.Authors' ], as: '$a' },
    columns: [ { ref: [ '$a', 'name' ] } ],
    where: [
      'exists',
      {
        SELECT: {
          from: { ref: [ 'sap.capire.bookshop.Books' ], as: '$B' },
          columns: [ { val: 1 } ],
          where: [
            { ref: [ '$B', 'author_ID' ] },
            '=',
            { ref: [ '$a', 'ID' ] },
            'and',
            { ref: [ '$B', 'stock' ] },
            'between',
            { val: 50 },
            'and',
            { val: 100 },
            'and',
            'exists',
            {
              SELECT: {
                from: { ref: [ 'sap.capire.bookshop.Genres' ], as: '$g' },
                columns: [ { val: 1 } ],
                where: [
                  { ref: [ '$g', 'ID' ] },
                  '=',
                  { ref: [ '$B', 'genre_ID' ] },
                  'and',
                  { ref: [ '$g', 'name' ] },
                  '=',
                  { val: 'Fantasy' }
                ]
              }
            }
          ]
        }
      }
    ]
  }
}

We can see how the extended, chained set of conditions is materialised:

the stock condition becomes part of the EXISTS subquery's conditions
the genre condition becomes an additional correlated subquery which itself then becomes part of the EXISTS conditions too

That just about wraps it up for this episode, I hope you found some value in the video in these notes!

Further info

Genres, cuids and a bit of AWK

Footnotes

I find it interesting how we can use the > operator on dateOfBirth and supply only the first part of a value i.e. 1900, as if it were a string style comparison.
Later on in this episode at 54:48 I ask whether we can add such an order by in an infix filter at the schema level, and the answer helped me understand the difference between such "post-condition" filters and "restrictive". The answer was "no, not yet", but included an explanation which made a lot of sense - a restrictive filter (such as stock > 10) can be added to the WHERE condition in the subquery or JOIN, whereas a "post-condition" filter (such as order by name asc) cannot. The latter is only really possible right now at the query level.
Of course, this example assumes we do not want to, or cannot, add the annotation directly to the element where it occurs (@readonly e : String).
The language server based CDS formatter has inserted the spaces either side of the colon, which is a nice touch.

DJ Adams

Computing memories

Blogging in en-GB

CAP service authentication at design time and in production

Default auth settings for development

Default auth settings for production

Understanding the mechanism

Wrapping up

Book Overflow and two architectural patterns in CAP

Ports and adapters

Transactional outbox

Further reading

Local-first dev with CAP Node.js - mocking messaging

Everything is an event

Working through an example

The containing project definition

Examining the emitter

The emitter service definition

The emitter service implementation

Messaging configuration

Examining the receiver

The receiver implementation

Trying it out

Starting up the emitter

Invoking the greet action

Looking at the message queue

Starting up the receiver

Wrapping up

Local-first dev with CAP Node.js - mocking remote services

Calesi and mocking remote services

Working through an example

Examining and importing the candidate remote service

Mocking is automatically and immediately initiated

The package.json file is extended

Reviewing the situation

Add data for the mocked remote service

Have some data generated

Retrieve data and use that too

Move the data closer to the service

Switching to a more realistic scenario

Set up a local to remote proxy definition

Examine the CAP server logs now

Mock the remote service in a separate process

Start a normal CAP server process to have the local service served

Get to know the binding registry

Retry the local to remote proxy - part 1

Retry the local to remote proxy - part 2

Wrapping up

Footnotes

Local-first dev with CAP Node.js - mocking auth

The mocked authentication strategy

Working through an example

The service definition

Examine the pre-defined users and their authorisations

Restrict the service

Authenticate with a pre-defined user

Try some finer-grained access restrictions

Confirm read operations are permitted

Try a write operation

Give the user more access in the mocked strategy

Wrapping up

Footnotes

Local-first dev with CAP Node.js

The posts

More context

Local-first dev with CAP Node.js - mocking data

Initial, test and sample data - terminology

Initial data

Test data

Sample data

Understanding the mock data structure

Working through an example

Starting the server

Creating initial data files

Adding generated data

Using more realistic data

Using non-CSV data

Check the data is surfaced

Wrapping up

Footnotes