cds-mongodb

MongoDB (Mongoose) persistence adapter for SAP Cloud Application Programming Model (CAP).

cds-mongodb enables CAP applications to use MongoDB as a native persistence layer, providing a developer experience consistent with official CAP database services such as @cap-js/sqlite and @cap-js/hana.

Why cds-mongodb

SAP CAP is traditionally optimized for relational databases.
However, modern enterprise scenarios increasingly require document-oriented storage, especially for:

• AI/ML workloads
• Event-driven systems
• Flexible schemas
• High-ingestion data models

cds-mongodb bridges this gap without changing how developers write CDS models or services.

Key Features

• Native CAP database service (no custom CRUD handlers required)
• Persists CDS entities to MongoDB using Mongoose
• Supports READ, CREATE, UPDATE, DELETE via CAP CQN
• Supports managed CDS associations using MongoDB ObjectId references
• Automatic association resolution via $expand (Mongoose populate)
• cds deploy --to mongoose support
• CSV seed data import from db/data/*.csv
• Reusable npm package
• Compatible with SAP BTP and local development

What This Is (and Is Not)

Supported

• Standard CRUD operations
• $expand for managed associations
• CAP service exposure without custom handlers
• Document-centric and AI-driven use cases

Not Supported (Current Version)

• Draft-enabled entities
• Complex CDS views and joins
• Transaction semantics
• Recursive or deep $expand
• Advanced CQN operators

Installation

npm install cds-mongodb

Configuration

{
  "cds": {
    "requires": {
      "db": {
        "kind": "mongoose",
        "impl": "cds-mongodb",
        "credentials": {
          "url": "mongodb://localhost:27017/cap"
        }
      }
    }
  }
}

Or via environment variable:

export MONGO_URL=mongodb://localhost:27017/cap

Usage

CDS Model (db/datamodel.cds)

entity Authors {
  key ID   : UUID;
  name     : String;
  books    : Association to many Books;
}

entity Books {
  key ID    : UUID;
  title     : String;
  author    : Association to Authors;
}

Service (srv/service.cds)

service CatalogService {
  entity Authors as projection on Authors;
  entity Books   as projection on Books;
}

No custom handlers required.

Running Locally

cds deploy --to mongoose
cds run

CSV Seed Data

Place CSV files under:

db/data/

File name must match CDS entity name.

Association Handling

• Stored as MongoDB ObjectId references
• $expand translated to Mongoose populate
• Expand depth limited to 1

Example:

GET /catalog/Authors?$expand=books

Compatibility Matrix

| Component | Version | |---------|---------| | Node.js | >= 18 | | @sap/cds | ^7.x | | MongoDB | 6.x, 7.x | | Mongoose | 8.x |

Logging & Errors

• Uses CAP logging (cds.log)
• Normalized CAP-style errors
• No MongoDB internals exposed

License

Apache License 2.0

Disclaimer

This is an independent, community-driven project and is not an official SAP product.