Parsing and Compiling Models

• cds. compile (...)
  • Compiling .cds files (async)
  • Single in-memory sources
  • Multiple in-memory sources
  • Additional Options
• cds. compile .to ...
  • .json()
  • .yaml()
  • .edm()
  • .edmx()
  • .hdbtable()
  • .hana() since @sap/cds 8.0.0
  • .sql()
  • .cdl()
  • .asyncapi()
• cds. load (files)
• cds. parse()
  • cds. parse. cdl()
  • cds. parse. cql()
  • cds. parse. expr()
  • cds. parse. xpr()
  • cds. parse. ref()
• cds. minify()
• cds. resolve()
• Lifecycle Events
  • compile.for.runtime
  • compile.to.dbx
  • compile.to.edmx

cds. compile (...)

function cds.compile (
  model :
  	'*', 'file:<filename>' | filenames[] |  // source files
    CDL string | { CDL strings }           // sources in memory
  ,
  options : CSN_flavor | {
    flavor?    : CSN_flavor,
    min?       : boolean,
    docs?      : boolean,
    locations? : boolean,
    messages?  : []
  }
)
type CSN_flavor = 'parsed' | 'inferred'

This is the central function to compile models from files or in-memory sources to CSN. It supports different variants based on the type of the first argument model as outlined below.

Depending on the variants, the method returns a Promise or a sync value.

Compiling .cds files (async)

If the first argument is either a string starting with "file:", or an array of filenames, these files are read and compiled to a single CSN asynchronously:

let csn = await cds.compile (['db','srv','app'])
let csn = await cds.compile ('*')
let csn = await cds.compile ('file:db')

The given filenames are resolved to effective absolute filenames using cds.resolve.

Use cds compile as CLI equivalent

The cds compile CLI is available as entry point to the functions described here. For example, cds compile --to hana maps to cds.compile.to.hana etc.

Single in-memory sources

If a single string, not starting with file: is passed as first argument, it is interpreted as a CDL source string and compiled to CSN synchronously:

let csn = cds.compile (`
  using {cuid} from '@sap/cds/common';
  entity Foo : cuid { foo:String }
  entity Bar as projection on Foo;
  extend Foo with { bar:String }
`)

Note: using from clauses are not resolved in this usage.

Multiple in-memory sources

Finally, you can pass an object with multiple named CDL or CSN sources, which allows to also resolve using from clauses:

let csn = cds.compile ({
  'db/schema.cds': `
    using {cuid} from '@sap/cds/common';
    entity Foo : cuid { foo:String }
  `,
  'srv/services.cds': `
    using {Foo} from '../db/schema';
    entity Bar as projection on Foo;
    extend Foo with { bar:String }
  `,
  '@sap/cds/common.csn': `
    {"definitions":{
      "cuid": { "kind": "aspect", "elements": {
        "ID": { "key":true, "type": "cds.UUID" }
      }}
    }}
  `,
})

Additional Options

You can pass additional options like so:

let csn = await cds.compile('*',{ min:true, docs:true })

Option	Description
flavor	By default the returned CSN is in 'inferred' flavor, which is an effective model, with all aspects, includes, extensions and redirects applied and all views and projections inferred. Specify 'parsed' to only have single models parsed.
min	Specify true to have cds.minify() applied after compiling the models.
docs	Specify true to have the all /** ... */ doc comments captured in the CSN.
locations	Specify true to have the all $location properties preserved in serialized CSN.
messages	Pass an empty array to get all compiler messages collected in there.

cds. compile .to ...

Following are a collection of model processors which take a CSN as input and compile it to a target output. They can be used in two API flavors:

let sql = cds.compile(csn).to.sql ({dialect:'sqlite'}) //> fluent
let sql = cds.compile.to.sql (csn,{dialect:'sqlite'}) //> direct

.json()

function cds.compile.to.json ( options: {
  indents : integer
})

Renders the given model to a formatted JSON string.

Option indents is the indent as passed to JSON.stringify.

.yaml()

Renders the given model to a formatted JSON or YAML string.

.edm()

.edmx()

Compiles and returns an OData v4 EDM, respectively EDMX model object for the passed in model, which is expected to contain at least one service definition.

Accepted options are the same as documented for cds.compile, with one addition: If the model contains more than one service definition, use {service:...} option parameter to:

• Either choose exactly one, for example, {service:'Catalog'}
• Choose to return EDM objects for all, that means, {service:'all'}

In case of the latter, a generator is returned that yields [ edm, {file, suffix} ] for each service. For example, use it as follows:

// for one service
let edm = cds.compile.to.edm (csn, {service:'Catalog'})
console.log (edm)

// for all services
let all = cds.compile.to.edm (csn, {service:'all'})
for (let [edm,{file,suffix}] of all)
  console.log (file,suffix,edm)

.hdbtable()

Use cds.compile.to.hana instead.

.hana() since @sap/cds 8.0.0

Generates hdbtable/hdbview output.

Returns a generator function that produces [ content, {file} ] for each artifact. The variable content contains the SQL DDL statements for the .hdb* artifacts, and file is the filename.

For example, use it as follows:

const all = cds.compile.to.hana(csn);
for (const [content, { file }] of all) {
  console.log(file, content);
}

Additional data for .hdbmigrationtable files is calculated if a beforeImage parameter is passed in. This is only relevant for build tools to determine the actual migration table changes.

.sql()

Generates SQL DDL statements for the given model. The default returns an array with the generated statements.

Accepted options are:

• dialect: 'plain' | 'sqlite' | 'postgres' | 'h2' → chooses the dialect to generate
• names: 'plain' | 'quoted' → allows to generate DDL using quoted names
• as: 'str' → returns a string with concatenated DDL statements.

Examples:

let ddls1 = cds.compile(csn).to.sql()
let ddls2 = cds.compile(csn).to.sql({dialect:'plain'})
let script = cds.compile(csn).to.sql({as:'str'})

.cdl()

Reconstructs CDL source code for the given csn model.

.asyncapi()

Convert the CSN file into an AsyncAPI document:

const doc = cds.compile.to.asyncapi(csn_file)

cds. load (files)

Loads and parses a model from one or more files into a single effective model. It's essentially a shortcut to cds.compile ([...]). In addition emits event cds 'loaded'.

Declaration:

function cds.load (
  files : filename || filenames[]
  options : {...} //> as in cds.compile
)

Usage examples:

// load a model from a single source
const csn = await cds.load('my-model')

// load a a model from several sources
const csn = await cds.load(['db','srv'])

The given filenames are resolved using cds.resolve().

Note: It's recommended to omit file suffixes to leverage automatic loading from precompiled CSN files instead of CDL sources.

cds. parse()

This is an API facade for a set of functions to parse whole CDL models, individual CQL queries, or CQL expressions. The three main methods are offered as classic functions, as well as tagged template string functions.

cds. parse. cdl()

Parses a source string in CDL syntax and returns it as a parsed model according to the CSN spec. Supports tagged template strings as well as plain string arguments. It's essentially a shortcut to cds.compile (..., {flavor:'parsed'}).

Examples:

let csn = cds.parse.cdl (`entity Foo{}`)
let csn = cds.parse.cdl `entity Foo{}`
let csn = cds.parse `entity Foo{}`  //> shortcut to the above

cds. parse. cql()

Parses a source string in CQL syntax and returns it as a parsed query according to the CQN spec. Supports tagged template strings as well as plain string arguments.

Examples:

let cqn = cds.parse.cql (`SELECT * from Foo`)
let cqn = cds.parse.cql `SELECT * from Foo`

cds. parse. expr()

Parses a source string in CQL expression syntax and returns it as a parsed expression according to the CQN Expressions spec. Supports tagged template strings as well as plain string arguments.

Examples:

[dev] cds repl
> let cxn = cds.parse.expr (`foo.bar > 9`)
> let cxn = cds.parse.expr `foo.bar > 9` //> both return:
{xpr:[ {ref:['foo', 'bar']}, '>', {val:9} ] }

cds. parse. xpr()

Convenience shortcut to cds.parse.expr(x).xpr

Example:

[dev] cds repl
> let xpr = cds.parse.xpr (`foo.bar > 9`) 
[ {ref:['foo', 'bar']}, '>', {val:9} ]

cds. parse. ref()

Convenience shortcut to cds.parse.expr(x).ref

Example:

[dev] cds repl
> let ref = cds.parse.ref (`foo.bar`) 
['foo', 'bar']

cds. minify()

Minifies a given CSN model by removing all unused¹ types and aspects, as well all entities tagged with @cds.persistence.skip:'if-unused'. Use it like that:

let csn = await cds.load('*').then(cds.minify)

Using cds.minify() is particularly relevant, when reuse models are in the game. For example, this applies to @sap/cds/common. In there, all code list entities like Countries, Currencies and Languages are tagged with @cds.persistence.skip:'if-unused'. For example, run this in cap/samples/bookshop:

[bookshop] DEBUG=minify cds -e "cds.load('*').then(cds.minify)"

... would generate this output, informing which definitions got skipped:

[minify] - skipping type Language
[minify] - skipping type Country
[minify] - skipping context sap.common
[minify] - skipping entity sap.common.Languages
[minify] - skipping entity sap.common.Countries
[minify] - skipping aspect cuid
[minify] - skipping aspect temporal
[minify] - skipping aspect extensible
[minify] - skipping entity sap.common.Languages.texts
[minify] - skipping entity sap.common.Countries.texts

¹ Unused in that context means, not reachable from roots services and — non-skipped — entities in the model.

cds. resolve()

Resolves the given source paths by fetching matching model source files, that is .cds or .csn files, including models for required services. In detail, it works as follows:

1. If paths is '*': paths = [ ...cds.env.roots, ...cds.requires.<srv>.model ]
2. If paths is a single string: paths = [ paths ]
3. For <each> in paths: ...

• if <each>.csn|cds exists → use it
• if <each>/index.csn|cds exists → use it
• if <each> is a folder → use all .csn|cds found in there

Learn more about cds.env

In effect, it resolves and returns an array with the absolute filenames of the root cds model files to be used to invoke the compiler.

If no files are found, undefined is returned.

Examples:

[dev] cds repl
> cds.env.folders           // = folders db, srv, app by default
> cds.env.roots             // + schema and services in cwd
> cds.resolve('*',false)    // + models in cds.env.requires
> cds.resolve('*')          // > the resolved existing files
> cds.resolve(['db'])       // > the resolved existing files
> cds.resolve(['db','srv']) // > the resolved existing files
> cds.resolve('none')       // > undefined

Try this in cds repl launched from your project root to see that in action.

Lifecycle Events

The following lifecycle events are emitted via the cds facade object during the server bootstrapping process. You can register event handlers using cds.on() like so:

const cds = require('@sap/cds')
cds.on('compile.for.runtime', ...)
cds.on('compile.to.dbx', ...)
cds.on('compile.to.edmx', ...)

WARNING

As we're using Node's standard EventEmitter, event handlers execute synchronously in the order they are registered.

Note that several of these events could be emitted for the same model, so ensure your handlers are idempotent.

compile.for.runtime

A one-time event, emitted before the model is compiled for usage in Node.js or Java runtime. This is the right place to, for example, add custom elements required at runtime.

compile.to.dbx

A one-time event, emitted before database-specific artifacts, i.e. SQL DDL scripts, are generated from the model. This is the right place to, for example, add custom elements required in your persistence.

compile.to.edmx

A one-time event, emitted immediately before the model is compiled to edmx. This is the right place to add custom transformations to the model, for example, to add custom Fiori annotations.