Actions

The ballerinax/mongodb package exposes the following clients:

Client	Purpose
Client	Top-level client for connecting to MongoDB, listing databases, and obtaining Database references.
Database	Represents a MongoDB database. Manage collections and drop the database.
Collection	Document CRUD, queries, aggregation pipelines, distinct values, and index management.

Error types

All operations return errors as mongodb:Error, a union of mongodb:DatabaseError, mongodb:ApplicationError, and Ballerina's built-in error. mongodb:DatabaseError carries an additional mongoDBExceptionType detail field for command-level failures.

---

Client

Top-level client for connecting to MongoDB, listing databases, and obtaining Database references.

Configuration

Field	Type	Default	Description
connection	ConnectionParameters|string	Required	Structured connection parameters or a MongoDB connection string URI.
options	ConnectionProperties?	()	Optional connection properties (read concern, write concern, pool settings, SSL, timeouts).

Initializing the client

import ballerinax/mongodb;

configurable string connectionUri = ?;

mongodb:Client mongoClient = check new ({
    connection: connectionUri
});

Operations

Database management

listDatabaseNames

Lists all database names in the MongoDB server.

Returns: string[]|mongodb:Error

Sample code:

string[] databases = check mongoClient->listDatabaseNames();

Sample response:

["admin", "local", "movies", "orders"]

getDatabase

Retrieves a Database object for the named database.

Parameters:

Name	Type	Required	Description
databaseName	string	Yes	Name of the database to retrieve.

Returns: mongodb:Database|mongodb:Error

Sample code:

mongodb:Database moviesDb = check mongoClient->getDatabase("movies");

close

Closes the MongoDB client connection. Use a single client instance for the application lifetime.

Returns: mongodb:Error?

Sample code:

check mongoClient->close();

---

Database

Represents a MongoDB database. Manage collections and drop the database.

Configuration

Database has no direct configuration. Instances are obtained through Client->getDatabase().

Initializing the client

import ballerinax/mongodb;

// Obtain a Database via Client->getDatabase()
mongodb:Client mongoClient = check new ({
    connection: "mongodb://localhost:27017"
});
mongodb:Database moviesDb = check mongoClient->getDatabase("movies");

Operations

Collection management

listCollectionNames

Lists all collection names in the database.

Returns: string[]|mongodb:Error

Sample code:

string[] collections = check moviesDb->listCollectionNames();

Sample response:

["movies", "directors", "reviews"]

createCollection

Creates a new collection in the database.

Parameters:

Name	Type	Required	Description
collectionName	string	Yes	Name of the collection to create.

Returns: mongodb:Error?

Sample code:

check moviesDb->createCollection("movies");

getCollection

Gets a Collection object for the named collection.

Parameters:

Name	Type	Required	Description
collectionName	string	Yes	Name of the collection to retrieve.

Returns: mongodb:Collection|mongodb:Error

Sample code:

mongodb:Collection moviesCollection = check moviesDb->getCollection("movies");

Database operations

drop

Drops the entire database and all its collections.

Returns: mongodb:Error?

Sample code:

check moviesDb->drop();

---

Collection

Document CRUD, queries, aggregation pipelines, distinct values, and index management.

Configuration

Collection has no direct configuration. Instances are obtained through Database->getCollection().

Initializing the client

import ballerinax/mongodb;

// Obtain a Collection via Database->getCollection()
mongodb:Client mongoClient = check new ({
    connection: "mongodb://localhost:27017"
});
mongodb:Database db = check mongoClient->getDatabase("movies");
mongodb:Collection moviesCollection = check db->getCollection("movies");

Operations

Insert operations

insertOne

Inserts a single document into the collection.

Parameters:

Name	Type	Required	Description
document	record {|anydata...;|}	Yes	The document to insert.
options	InsertOneOptions	No	Insert options (comment, bypassDocumentValidation).

Returns: mongodb:Error?

Sample code:

check moviesCollection->insertOne({
    title: "Inception",
    year: 2010,
    director: "Christopher Nolan"
});

insertMany

Inserts multiple documents into the collection. When ordered is true (default), insertion stops on the first error.

Parameters:

Name	Type	Required	Description
documents	record {|anydata...;|}[]	Yes	Array of documents to insert.
options	InsertManyOptions	No	Insert options (comment, bypassDocumentValidation, ordered).

Returns: mongodb:Error?

Sample code:

check moviesCollection->insertMany([
    {title: "The Dark Knight", year: 2008, director: "Christopher Nolan"},
    {title: "Interstellar", year: 2014, director: "Christopher Nolan"},
    {title: "Parasite", year: 2019, director: "Bong Joon-ho"}
]);

Query operations

find

Finds all documents matching the filter and returns a stream of typed records.

Parameters:

Name	Type	Required	Description
filter	map<json>	No	Query filter document. Defaults to {} (match all).
findOptions	FindOptions	No	Sort, limit, skip, and batchSize options.
projection	map<json>?	No	Projection document to include or exclude fields.
targetType	typedesc<record {|anydata...;|}>	No	Expected record type for results (inferred from context).

Returns: stream<targetType, error?>|mongodb:Error

Sample code:

type Movie record {|
    string title;
    int year;
    string director;
|};

stream<Movie, error?> result = check moviesCollection->find({year: 2010});
Movie[] movies = check from Movie m in result select m;

Sample response:

[{"title": "Inception", "year": 2010, "director": "Christopher Nolan"}]

findOne

Finds the first document matching the filter. Returns () if no match is found.

Parameters:

Name	Type	Required	Description
filter	map<json>	No	Query filter document.
findOptions	FindOptions	No	Sort, limit, skip, and batchSize options.
projection	map<json>?	No	Projection document to include or exclude fields.
targetType	typedesc<record {|anydata...;|}>	No	Expected record type (inferred from context).

Returns: targetType|mongodb:Error?

Sample code:

Movie? movie = check moviesCollection->findOne({title: "Inception"});

Sample response:

{"title": "Inception", "year": 2010, "director": "Christopher Nolan"}

countDocuments

Counts documents in the collection matching the filter.

Parameters:

Name	Type	Required	Description
filter	map<json>	No	Query filter document. Defaults to {} (count all).
options	CountOptions	No	Options for limit, skip, maxTimeMS, and hint.

Returns: int|mongodb:Error

Sample code:

int count = check moviesCollection->countDocuments({director: "Christopher Nolan"});

Sample response:

3

distinct

Returns distinct values for a given field across matching documents.

Parameters:

Name	Type	Required	Description
fieldName	string	Yes	The field name to get distinct values for.
filter	map<json>	No	Query filter document. Defaults to {} (all documents).
targetType	typedesc<anydata>	No	Type for distinct values (inferred from context).

Returns: stream<targetType, error?>|mongodb:Error

Sample code:

stream<string, error?> directors = check moviesCollection->'distinct("director", {});
string[] uniqueDirectors = check from string d in directors select d;

Sample response:

["Christopher Nolan", "Bong Joon-ho"]

Update operations

updateOne

Updates the first document matching the filter using MongoDB update operators.

Parameters:

Name	Type	Required	Description
filter	map<json>	Yes	Filter to match the document to update.
update	Update	Yes	Update operators record (set, unset, inc, mul, rename, etc.).
options	UpdateOptions	No	Options for upsert, bypassDocumentValidation, comment, hint, and hintString.

Returns: UpdateResult|mongodb:Error

Sample code:

mongodb:UpdateResult result = check moviesCollection->updateOne(
    {title: "Inception"},
    {set: {year: 2010, rating: 8.8}}
);

Sample response:

{"matchedCount": 1, "modifiedCount": 1}

note

The upsertedId field appears in the response only when the operation performs an upsert (upsert: true is set in UpdateOptions and a new document is inserted as a result). For non-upsert calls like the sample above, the field is omitted from the result entirely.

updateMany

Updates all documents matching the filter using MongoDB update operators.

Parameters:

Name	Type	Required	Description
filter	map<json>	Yes	Filter to match documents to update.
update	Update	Yes	Update operators record.
options	UpdateOptions	No	Options for upsert, bypassDocumentValidation, comment, hint, and hintString.

Returns: UpdateResult|mongodb:Error

Sample code:

mongodb:UpdateResult result = check moviesCollection->updateMany(
    {director: "Christopher Nolan"},
    {set: {genre: "Sci-Fi"}}
);

Sample response:

{"matchedCount": 3, "modifiedCount": 3}

note

The upsertedId field appears in the response only when the operation performs an upsert. For non-upsert calls like the sample above, the field is omitted from the result entirely.

Delete operations

deleteOne

Deletes the first document matching the filter.

Parameters:

Name	Type	Required	Description
filter	map<json>	Yes	Filter to match the document to delete.

Returns: DeleteResult|mongodb:Error

Sample code:

mongodb:DeleteResult result = check moviesCollection->deleteOne({title: "Inception"});

Sample response:

{"deletedCount": 1, "acknowledged": true}

deleteMany

Deletes all documents matching the filter.

Parameters:

Name	Type	Required	Description
filter	string|map<json>	Yes	Filter for documents to delete.

Returns: DeleteResult|mongodb:Error

Sample code:

mongodb:DeleteResult result = check moviesCollection->deleteMany({director: "Christopher Nolan"});

Sample response:

{"deletedCount": 3, "acknowledged": true}

Aggregation

aggregate

Runs an aggregation pipeline on the collection. Supports stages like $match, $group, $lookup, $sort, $project, $limit, and more.

Parameters:

Name	Type	Required	Description
pipeline	map<json>[]	Yes	Array of aggregation pipeline stage documents.
targetType	typedesc<anydata>	No	Expected result type (inferred from context).

Returns: stream<targetType, error?>|mongodb:Error

Sample code:

type DirectorSummary record {|
    string _id;
    int movieCount;
|};

stream<DirectorSummary, error?> result = check moviesCollection->aggregate([
    {"$group": {"_id": "$director", "movieCount": {"$sum": 1}}},
    {"$sort": {"movieCount": -1}}
]);
DirectorSummary[] summaries = check from DirectorSummary s in result select s;

Sample response:

[{"_id": "Christopher Nolan", "movieCount": 3}, {"_id": "Bong Joon-ho", "movieCount": 1}]

Index management

createIndex

Creates an index on the collection with the given key specification and options.

Parameters:

Name	Type	Required	Description
keys	map<json>	Yes	Index key specification (field name to direction, for example {"title": 1} for ascending).
options	CreateIndexOptions	No	Index options (unique, sparse, name, expireAfterSeconds, etc.).

Returns: mongodb:Error?

Sample code:

check moviesCollection->createIndex({"title": 1}, {unique: true, name: "title_unique_idx"});

listIndexes

Lists all indexes on the collection.

Returns: stream<Index, error?>|mongodb:Error

Sample code:

stream<mongodb:Index, error?> indexes = check moviesCollection->listIndexes();
mongodb:Index[] indexList = check from mongodb:Index idx in indexes select idx;

Sample response:

[{"ns": "movies.movies", "v": 2, "name": "_id_", "key": {"_id": 1}}, {"ns": "movies.movies", "v": 2, "name": "title_unique_idx", "key": {"title": 1}}]

dropIndex

Drops the named index from the collection.

Parameters:

Name	Type	Required	Description
indexName	string	Yes	Name of the index to drop.

Returns: mongodb:Error?

Sample code:

check moviesCollection->dropIndex("title_unique_idx");

dropIndexes

Drops all indexes on the collection except the default _id index.

Returns: mongodb:Error?

Sample code:

check moviesCollection->dropIndexes();

Collection operations

name

Returns the name of the collection. This is not a remote method, it does not invoke a network call.

Returns: string

Sample code:

string collectionName = moviesCollection.name();

drop

Drops the entire collection from the database.

Returns: mongodb:Error?

Sample code:

check moviesCollection->drop();

---

Supporting types

ConnectionParameters

Structured connection parameters used in ConnectionConfig.connection.

Field	Type	Default	Description
serverAddress	ServerAddress|ServerAddress[]	{}	A single server address, or an array for replica sets and sharded clusters.
auth	BasicAuthCredential|ScramSha1AuthCredential|ScramSha256AuthCredential|X509Credential|GssApiCredential	()	Optional. Authentication credentials: pick the record that matches your server's configured auth mechanism. See Authentication credentials below.

ServerAddress

Field	Type	Default	Description
host	string	"localhost"	MongoDB server hostname or IP.
port	int	27017	MongoDB server port.

Authentication credentials

The auth field of ConnectionParameters accepts one of five records, each tagged with a fixed authMechanism constant. Pick the record that matches the auth mechanism configured on your MongoDB server.

BasicAuthCredential: PLAIN

Field	Type	Default	Description
authMechanism	AUTH_PLAIN	AUTH_PLAIN	Always "PLAIN". Read-only.
username	string	Required	Username.
password	string	Required	Password.
database	string	Required	Authentication source database (typically "admin").

ScramSha1AuthCredential: SCRAM-SHA-1

Same field shape as BasicAuthCredential. The authMechanism is the constant AUTH_SCRAM_SHA_1 ("SCRAM_SHA_1").

ScramSha256AuthCredential: SCRAM-SHA-256

Same field shape as BasicAuthCredential. The authMechanism is the constant AUTH_SCRAM_SHA_256 ("SCRAM_SHA_256"). This is the default mechanism on modern MongoDB servers.

X509Credential: MongoDB X.509

Field	Type	Default	Description
authMechanism	AUTH_MONGODB_X509	AUTH_MONGODB_X509	Always "MONGODB_X509". Read-only.
username	string?	()	Optional username for client-certificate authentication. Omit to use the certificate subject.

GssApiCredential: GSSAPI / Kerberos

Field	Type	Default	Description
authMechanism	AUTH_GSSAPI	AUTH_GSSAPI	Always "GSSAPI". Read-only.
username	string	Required	Kerberos principal username.
serviceName	string?	()	Override the default service name ("mongodb").

ConnectionProperties

Optional connection-level settings passed via ConnectionConfig.options.

Field	Type	Default	Description
readConcern	ReadConcern?	()	Read concern level (see below).
writeConcern	string?	()	Write concern level (for example "majority").
readPreference	string?	()	Read preference for replica sets (for example "secondaryPreferred").
replicaSet	string?	()	Replica-set name. The driver uses it to validate that the cluster matches.
sslEnabled	boolean	false	Enable SSL/TLS. Set secureSocket together with this when a custom trust chain is needed.
invalidHostNameAllowed	boolean	false	Allow invalid hostnames in TLS handshakes.
secureSocket	SecureSocket?	()	TLS keystore and truststore configuration. Required when sslEnabled is true and you provide custom certificates.
retryWrites	boolean?	()	Retry writes on transient errors.
socketTimeout	int?	()	Socket timeout in milliseconds.
connectionTimeout	int?	()	Connection timeout in milliseconds.
maxPoolSize	int?	()	Maximum connections in the pool.
maxIdleTime	int?	()	Maximum idle time of a pooled connection (milliseconds).
maxLifeTime	int?	()	Maximum lifetime of a pooled connection (milliseconds).
minPoolSize	int?	()	Minimum pool size.
localThreshold	int?	()	Local-threshold latency for server selection (milliseconds).
heartbeatFrequency	int?	()	Frequency of cluster heartbeats (milliseconds).

SecureSocket

Field	Type	Default	Description
trustStore	crypto:TrustStore	Required	Truststore (JKS or PKCS12) holding the CA certificates the client trusts.
keyStore	crypto:KeyStore	Required	Keystore holding the client certificate (used for X.509 auth or mutual TLS).
protocol	string	Required	TLS protocol name (for example "TLS", "TLSv1.2", "TLSv1.3").

ReadConcern

A union of the supported read-concern levels:

Constant	Value	Description
LOCAL	"local"	Default. Returns data from the queried node without durability guarantees.
AVAILABLE	"available"	Like LOCAL but more permissive on sharded clusters.
MAJORITY	"majority"	Returns data acknowledged by a majority of replica-set members.
LINEARIZABLE	"linearizable"	Returns data reflecting all majority-acknowledged writes that completed before the read.
SNAPSHOT	"snapshot"	For use within multi-document transactions.

InsertOneOptions

Field	Type	Default	Description
comment	string?	()	Comment included with the operation in MongoDB logs.
bypassDocumentValidation	boolean	false	Skip server-side schema validation.

InsertManyOptions

Field	Type	Default	Description
comment	string?	()	Comment included with the operation.
bypassDocumentValidation	boolean	false	Skip server-side schema validation.
ordered	boolean	true	When true, insertion stops at the first error. When false, the connector attempts every document and reports per-document failures.

FindOptions

Field	Type	Default	Description
sort	map<json>	{}	Sort specification (for example {"year": -1}).
limit	int?	()	Maximum number of documents to return.
batchSize	int?	()	Cursor batch size.
skip	int?	()	Number of documents to skip.

CountOptions

Field	Type	Default	Description
limit	int?	()	Maximum number of documents to count.
skip	int?	()	Number of documents to skip before counting.
maxTimeMS	int?	()	Maximum time the operation can run, in milliseconds.
hint	string?	()	Hint as a JSON string indicating which index to use.

CreateIndexOptions

Field	Type	Default	Description
background	boolean?	()	Build the index in the background (legacy MongoDB).
unique	boolean?	()	Enforce uniqueness on the indexed fields.
name	string?	()	Custom index name.
sparse	boolean?	()	Index only documents where the indexed field exists.
expireAfterSeconds	int?	()	TTL on documents in the collection. Creates a TTL index.
version	int?	()	Index version number.
weights	map<json>?	()	Per-field weights for text indexes.
defaultLanguage	string?	()	Default language for text indexes.
languageOverride	string?	()	Field name that overrides the default language per document.
textVersion	int?	()	Text-index version.
sphereVersion	int?	()	2dsphere-index version.
bits	int?	()	2d-index geohash precision.
min	float?	()	2d-index minimum boundary.
max	float?	()	2d-index maximum boundary.
partialFilterExpression	map<json>	{}	Filter expression for partial indexes.
hidden	boolean?	()	Hide the index from the query planner.

UpdateOptions

Field	Type	Default	Description
upsert	boolean	false	Insert a new document if no match is found.
bypassDocumentValidation	boolean	false	Skip server-side schema validation.
comment	string?	()	Comment included with the operation.
hint	map<json>?	()	Hint as a document indicating which index to use.
hintString	string?	()	Hint as a string indicating which index to use.

Update

A record where each field corresponds to a MongoDB update operator. The connector adds the leading $ to each operator name automatically: writing set produces $set on the wire. All fields are optional. The record is open, so any additional MongoDB update operator can be passed and will likewise receive the $ prefix.

Field	MongoDB operator	Description
set	$set	Set field values.
unset	$unset	Remove fields.
inc	$inc	Increment numeric values.
mul	$mul	Multiply numeric values.
min	$min	Update only if the new value is less than the existing value.
max	$max	Update only if the new value is greater than the existing value.
rename	$rename	Rename a field.
currentDate	$currentDate	Set a field to the current date or timestamp.
setOnInsert	$setOnInsert	Set a field only when the operation results in an insert (used with upsert: true).

UpdateResult

Field	Type	Description
matchedCount	int	Number of documents matched by the filter.
modifiedCount	int	Number of documents whose contents actually changed.
upsertedId	string?	Optional. Set only when an upsert occurred and a new _id was assigned. Absent from the result otherwise.

DeleteResult

Field	Type	Description
deletedCount	int	Number of documents deleted.
acknowledged	boolean	Whether the operation was acknowledged by the server.

Index

Field	Type	Description
ns	string	Index namespace (<database>.<collection>).
v	int	Index version.
name	string	Index name.
key	map<json>	Index key specification.

Index is an open record. Servers may include additional fields (unique, sparse, weights, etc.) depending on the index type.