MongoDB

To use FrogBot with MongoDB, install the package @frogbotai/db-mongodb. It will come with everything you need to store your FrogBot data in MongoDB. Then from there, pass it to your FrogBot Config as follows:

import { mongooseAdapter } from '@frogbotai/db-mongodb'

export default buildConfig({
  // Your config goes here
  collections: [
    // Collections go here
  ],
  // Configure the Mongoose adapter here
  db: mongooseAdapter({
    // Mongoose-specific arguments go here.
    // URL is required.
    url: process.env.DATABASE_URL,
  }),
})

Collection search

The adapter implements collection search with MongoDB Search and MongoDB Vector Search. Lexical queries run as a $search stage, vector queries as a $vectorSearch stage, and hybrid queries fuse both in one aggregation. Ranking happens inside the database after access, where, draft, and locale filters are applied.

import { mongooseAdapter } from '@frogbotai/db-mongodb'
import { buildConfig } from 'frogbot'

export default buildConfig({
  secret: process.env.FROGBOT_SECRET!,
  db: mongooseAdapter({ url: process.env.DATABASE_URL! }),
  collections: [
    {
      slug: 'articles',
      fields: [
        { name: 'title', type: 'text', required: true },
        { name: 'body', type: 'textarea' },
        { name: 'embedding', type: 'vector', dimensions: 1536 },
      ],
      search: {
        content: {
          lexical: { fields: ['title', 'body'], language: 'english' },
          vector: { field: 'embedding' },
        },
      },
    },
  ],
})

Prerequisites

Vector fields store plain number arrays and work on any MongoDB deployment. Search indexes need a deployment with MongoDB’s search process, mongot:

MongoDB Atlas.
A self-managed deployment that runs mongot alongside mongod. For local development, the mongodb/mongodb-atlas-local Docker image includes both.

The database user also needs permission to list, create, and update search indexes on the collections you search. When the adapter connects, it creates and updates the search indexes. If that fails, it closes the connection and stops setup with SearchCapabilityError. The message names the collection, index, mode, and reason:

Reason	Cause
`missing-prerequisite`	The deployment has no search process, for example a plain replica set or standalone `mongod`.
`permission-denied`	The database user cannot list, create, or update search indexes.
`setup-failed`	The server rejected an index definition, or an index failed to build.

Collections without a search index connect as usual on any deployment. Before connecting, setup reports engine-gap for configurations that MongoDB cannot index:

A vector field with more than 8,192 dimensions.
A lexical.language without a built-in MongoDB language analyzer. Supported names include english, french, german, spanish, italian, portuguese, dutch, russian, chinese, japanese, korean, arabic, and the other lucene.<language> analyzers. Without language, text uses the standard analyzer.

Search indexes

Each named index becomes up to two MongoDB search indexes on the collection:

Index component	MongoDB index name	Type
`lexical`	`<name>_lexical`	`search`
`vector`	`<name>_vector`	`vectorSearch`

MongoDB needs the vectorSearch index for exact vector search as well, so an index with vector.approximate: false still creates it. Collections with drafts get the same indexes on their versions collection, so draft: true queries rank the latest draft of each document. Each index counts toward your deployment’s search index limit: one named index with both components on a collection with drafts uses four MongoDB search indexes. The adapter creates missing indexes and updates an index in place when its definition differs from your configuration, for example after you add a filterable field or someone edits the index by hand. It never drops a search index. If the server rejects an in-place update, setup fails with setup-failed and the server’s message. Drop the index yourself, and the adapter recreates it on the next connection. An index that MongoDB reports as failed to build also stops setup with setup-failed; fix the cause, then drop it so it is recreated. Search configuration is read once at startup, so restart the app, including the development server, after changing a collection’s search indexes. MongoDB builds search indexes asynchronously, so a new or rebuilt index is not usable right away. Every search checks the indexes it needs first. A missing index, or one that is not queryable yet, returns SearchReadinessError (HTTP 503) rather than an empty result. Ordinary reads and writes are never blocked while an index builds.

Filters

MongoDB can only filter search results on paths that the search index maps, so the adapter maps every eligible filterable field: IDs and single relationships, dates, numbers, checkboxes, and text-like values (text, textarea, email, select, and radio). Use filters.fields or filters.exclude on the index to narrow the list. Text fields that are both searched and filtered are indexed as searchable text and as exact-match tokens. Fields with hasMany, and fields inside arrays or blocks, cannot be filtered. Your where filter, collection read access, trash visibility, and draft status run inside the $search or $vectorSearch stage, before the result limit, so hidden documents never take up result slots. Filters on unmapped paths, or operators such as like and contains, fail with SearchFilterUnsupportedError. Exact-match tokens are case-sensitive, and very long text values may not be indexed as tokens, so filter on short, exact values.

Ranking

Mode	`ranking.method`	Score
Lexical	`mongodb-search`	The `$search` relevance score (BM25). Higher is better.
Vector	`mongodb-hnsw` or `mongodb-exact`	Cosine similarity, Euclidean distance (lower is better), or dot product.
Hybrid	`rrf`	Weighted reciprocal rank fusion, `weight / (60 + rank)` summed over both components. Higher is better.

MongoDB reports vector scores normalized to the 0–1 range. The adapter converts them back in the database, so vector scores use the same scale as on the other adapters. The dotProduct metric expects unit-length vectors; use cosine if yours aren’t normalized. Approximate vector queries report approximate: true and pass the resolved candidate count to $vectorSearch as numCandidates, capped at MongoDB’s maximum of 10,000. Your filters run inside the vector index scan, so they don’t reduce the number of hits. Indexes with vector.approximate: false search exactly, and so does any query whose limit exceeds 10,000, because numCandidates cannot be lower than the limit. Hybrid search takes up to the resolved candidate count from each component and returns the top limit by fused score. A record that matches only one component still ranks, with the other component reported as null. Documents with equal component scores share a rank. On servers that support $rankFusion, the adapter uses it; otherwise, for example on MongoDB 8.0, it computes the same fusion with $unionWith. Both paths run entirely in the database.

Limits

Localized fields are indexed once per locale and ranked on the requested locale’s stored value. Fallback-locale values are not ranked.
Search indexes update shortly after a write, not in the same transaction, so a new or changed document can take a moment to appear in results. A deleted document can stay in the index briefly, but ranked documents are read back before they are returned, so deleted and no-longer-readable documents are left out and hits may be shorter than limit.
Search does not read uncommitted writes from the request’s transaction.

Options

Option	Type	Default	Description
`url`	`string \| false`	Required	MongoDB connection string. `false` starts FrogBot without connecting to a database.
`connectOptions`	`ConnectOptions`	`{ autoIndex: true }`	Mongoose connection options, merged over the defaults. A deprecated `useFacet` key is accepted and ignored.
`afterCreateConnection`	`(adapter: MongooseAdapter) => void \| Promise<void>`	—	Runs once, after the connection is first created.
`afterOpenConnection`	`(adapter: MongooseAdapter) => void \| Promise<void>`	—	Runs after each connection opens.
`transactionOptions`	`TransactionOptions \| false`	`{}`	Options for transactions, or `false` to disable them. Transactions are disabled automatically when the server isn’t a replica set.
`bulkOperationsSingleTransaction`	`boolean`	`false`	Processes bulk updates and deletes one document at a time, each in its own transaction, instead of all in one. Useful for transaction limits on large datasets in DocumentDB and Cosmos DB.
`migrationDir`	`string`	First of `src/migrations`, `dist/migrations`, or `migrations` that exists	Directory migrations are written to and read from. See Migrations.
`prodMigrations`	`{ name: string; up: Function; down: Function }[]`	—	Migrations to run on connect when `NODE_ENV` is `production`. See Running migrations in production.
`ensureIndexes`	`boolean`	`false`	Waits for every collection’s indexes to build before finishing the connection. Slows startup, so it isn’t recommended in production.
`autoPluralization`	`boolean`	`true`	Lets Mongoose pluralize collection names when a collection `slug` is a singular word.
`collectionsSchemaOptions`	`Record<CollectionSlug, SchemaOptions>`	`{}`	Mongoose schema options, per collection.
`collation`	`Omit<CollationOptions, 'locale'>`	—	Enables language-aware string comparison, such as `{ strength: 3 }`. The locale comes from the request and defaults to `en`. Available on MongoDB 3.4 and later. See Using collation and the MongoDB documentation.
`allowAdditionalKeys`	`boolean`	`false`	Keeps keys in stored documents that your collection config doesn’t define, instead of stripping them. FrogBot access control doesn’t apply to that data.
`allowIDOnCreate`	`boolean`	`false`	Uses an `id` passed in create data, without a custom ID field.
`disableFallbackSort`	`boolean`	`false`	Stops adding a secondary `createdAt` sort when sorting by a non-unique field. The fallback keeps result order consistent but can slow queries on very large collections.
`disableIndexHints`	`boolean`	`false`	Stops hinting MongoDB to use the `id` index when counting documents for pagination. Disabling the hint may fix problems with AWS DocumentDB.
`useJoinAggregations`	`boolean`	`true`	Set `false` to populate join fields with separate `find` queries instead of join aggregations that use correlated subqueries.
`usePipelineInSortLookup`	`boolean`	`true`	Set `false` to stop using `pipeline` in the `$lookup` stage used for sorting.
`useBigIntForNumberIDs`	`boolean`	`false`	Stores custom `number` ID fields as `BigInt`, for databases that don’t support `double` or `int32` IDs.
`useAlternativeDropDatabase`	`boolean`	`false`	Drops the database by calling `deleteMany({})` on every collection instead of sending `dropDatabase`. FrogBot drops the database only in tests.
`mongoMemoryServer`	`MongoMemoryReplSet`	—	An in-memory replica set, for tests. The adapter waits for it to elect a primary before continuing.

Access to Mongoose models

After FrogBot is initialized, this adapter exposes all of your Mongoose models and they are available for you to work with directly. You can access Mongoose models as follows:

Collection models - frogbot.db.collections[myCollectionSlug]
Versions model - frogbot.db.versions[myEntitySlug]

Using other MongoDB implementations

You can import the compatibilityOptions object to get the recommended settings for other MongoDB implementations. Since these databases aren’t officially supported by frogbot, you may still encounter issues even with these settings (please create an issue or PR if you believe these options should be updated):

import { mongooseAdapter, compatibilityOptions } from '@frogbotai/db-mongodb'

export default buildConfig({
  db: mongooseAdapter({
    url: process.env.DATABASE_URL,
    // For example, if you're using firestore:
    ...compatibilityOptions.firestore,
  }),
})

We export compatibility options for DocumentDB, Azure Cosmos DB and Firestore. Known limitations:

Azure Cosmos DB does not support transactions that update two or more documents in different collections, which is a common case when using FrogBot (via hooks).
Azure Cosmos DB requires the root config property indexSortableFields to be set to true.

Using collation

There are situations where you may want to use language-specific string comparison, for example when sorting strings with accents or in different languages. MongoDB supports this via collation. We thread your locale automatically through to the MongoDB queries when collation is enabled in the adapter, so that when you sort by a field, it uses the correct language rules for that locale. To enable collation, set the collation option in the adapter configuration:

import { mongooseAdapter } from '@frogbotai/db-mongodb'

export default buildConfig({
  // Your config goes here
  collections: [
    // Collections go here
  ],
  // Configure the Mongoose adapter here
  db: mongooseAdapter({
    // Mongoose-specific arguments go here.
    // URL is required.
    url: process.env.DATABASE_URL,
    collation: {
      // Set any MongoDB collation options here.
      // The locale will be set automatically based on the request locale.
      strength: 1, // Example option
    },
  }),
})

Start here

Basics

Managing Data

Features

Ecosystem

Deployment

Collection search

Prerequisites

Search indexes

Filters

Ranking

Limits

Options

Access to Mongoose models

Using other MongoDB implementations

Using collation

​Collection search

​Prerequisites

​Search indexes

​Filters

​Ranking

​Limits

​Options

​Access to Mongoose models

​Using other MongoDB implementations

​Using collation

Collection search

Prerequisites

Search indexes

Filters

Ranking

Limits

Options

Access to Mongoose models

Using other MongoDB implementations

Using collation