MongoDB adapter

The MongoDB adapter works with:

• MongoDB 5.0+
• MongoDB Atlas (all tiers including M0 free)
• AWS DocumentDB (Mongo 5.0-compatible)
• Azure Cosmos DB for MongoDB (4.2+ API)
• Self-hosted MongoDB

Config shape

{
  "type": "mongodb",
  "config": {
    "uri": "mongodb+srv://spelo_ro:pass@cluster0.xxxxx.mongodb.net/?retryWrites=true",
    "database": "production",
    "tls": true
  },
  "collections": {
    "products": {
      "source": "products",
      "searchable_fields": ["name", "description", "sku"],
      "filterable_fields": ["category", "price", "in_stock", "tags"],
      "display_fields": ["_id", "name", "price", "sku"]
    }
  }
}

Setup

1. Create a read-only database user

   In Atlas: Database Access → Add New Database User → Built-in Role: Only read any database (or a custom role scoped to your DB).

   For self-hosted:

   use admin
   db.createUser({
     user: 'spelo_ro',
     pwd: 'StrongRandom123!',
     roles: [{ role: 'read', db: 'production' }]
   })

2. Whitelist Spelo’s IPs

   Atlas: Network Access → Add IP Address → paste Spelo’s egress CIDRs from spelo.ai/security/ips.

3. Enable TLS

   Atlas is TLS-always. Self-hosted: set up mongod with tls: requireTLS and set "tls": true in the config.

4. Paste the connection URI and database name in the dashboard

   Dashboard → Data → MongoDB → Test connection.

5. Map collections — the source is the Mongo collection name (case-sensitive).

Operator translation

SearchParams operator	MongoDB filter expression
eq	{ field: value }
neq	{ field: { $ne: value } }
gt	{ field: { $gt: value } }
gte	{ field: { $gte: value } }
lt	{ field: { $lt: value } }
lte	{ field: { $lte: value } }
contains (string column)	{ field: { $regex: escapedValue, $options: 'i' } }
contains (array column)	{ field: value } (matches if value ∈ array)
in	{ field: { $in: values } }
free-text query	$or across searchable_fields with case-insensitive regex

Caution

Free-text regex on large collections without indexes is slow. Either add a text index (db.products.createIndex({ name: 'text' })) or use a search service via the REST or Webhook adapter.

Security notes

• Collection names validated against ^[A-Za-z_][A-Za-z0-9_]*$ — no $ or . allowed in names (prevents operator injection).
• Regex values are escaped via \Q...\E-equivalent replacement so a filter value cannot inject regex metacharacters.
• Only find().filter().sort().limit() pipelines are emitted. No update, delete, aggregate with $out, $merge.

Atlas Data API

The Atlas Data API (HTTPS, no driver) is not used by this adapter. If you want to avoid managing a Mongo driver on our side, the REST adapter can call the Data API directly.

Troubleshooting

• Authentication failed → wrong user/password, or the user isn’t authorized on the target database.
• ENOTFOUND cluster0.xxxxx.mongodb.net → DNS issue; make sure the URI is correct (Atlas uses mongodb+srv://).
• Server selection timed out → IP not whitelisted in Atlas Network Access.
• MongoNotConnectedError → TLS config mismatch. Atlas requires tls: true.
• Regex-based search is slow → add a text index or use a real search service.

More: Database connection errors.

Connect a different data source

Overview Postgres MySQL MS SQL Supabase Firebase OAuth setup Airtable Google Sheets Shopify WooCommerce REST API Webhook TS adapter Schema introspection