Establishes a connection to MongoDB and returns a client id as string that identifies the opened connection.

The $uri string follows the MongoDB URI format. It must at least contain one host name, and it may be prefixed with the mongo scheme and suffixed with a port number. Multiple hosts, e.g. for a replica set, are separated with commas.

The format of the returned client id string is implementation-defined, but all returned ids must be unique during the evaluation of a query.

The following expression creates three connections to local MongoDB instances, using the default port, and returns the client ids as result: mongo:connect("localhost"), mongo:connect("localhost:27017"), mongo:connect("mongo://localhost:27017")

The following function call connects to a replica set with three members, and distributes reads to the secondary: mongo:connect("localhost,localhost:27018/?readPreference=secondary")

mongo:list-databases($client-id as xs:string) as xs:string*

Returns the names of all databases on the connected server.

The connection is identified by the supplied $client-id.

The following query lists all databases on localhost:

mongo:list-databases(mongo:connect("localhost"))

mongo:close($client-id as xs:string) as empty-sequence()

Closes an open database connection. The connection to be closed is identified by the supplied $client-id. When a database connection is closed, the associated id is discarded and invalidated. As a consequence, each database can be closed once.

A connection must be kept open as long as it has not explicitly been closed by the user, and as long as the query has not been fully evaluated. After query evaluation, an implementation must ensure that all remaining connections are automatically closed.

The following expression closes a connection that has just been opened:

mongo:close(mongo:connect("localhost"))

mongo:list-collections($client-id as xs:string, $database as xs:string) as xs:string*

Returns the names of all collections contained in a databases.

The connection is identified by the supplied $client-id, and the name of the database is supplied via $database.

mongo:command($client-id as xs:string, $database as xs:string, $command as map(*)) as map(*)

Executes a , supplied via $command, and returns the result as a map.

The connection is identified by the supplied $client-id, and the name of the database is supplied via $database.

The object returned by MongoDB contains the field ok, which must be parsed by the implementation to decide if command execution was successful (indicated by the integer value 1) or not (0). The field must be removed from the object before the result is returned as map. If execution failed, the field errmsg can be parsed to return a proper error message.

The following query clones a database from a remote MongoDB instance to the current host. The result will either be a map, which contains the result of the command execution, or an error: let $id := mongo:connect("localhost") return try { mongo:command($client-id, map { "clone", 1 }) } catch mongo:exec { "Command execution failed: " || $err:description, }

mongo:eval($client-id as xs:string, $database as xs:string, $code as xs:string) as item()*

mongo:eval($client-id as xs:string, $database as xs:string, $code as xs:string, $args as item()*) as item()*

Runs server-server JavaScript script code, supplied via $code. Function arguments can be supplied via $args. Arguments can be booleans, strings, numbers, arrays or maps. An error will be raised if any other type is supplied. Items of type xs:untypedAtomic are converted to strings.

The connection is identified by the supplied $client-id, and the name of the database is supplied via $database.

Due to the different type systems of XQuery and JavaScript, it is not possible to losslessly convert all values to one language and back. To ensure compatibility, an implementation must obey the following conversion rules:

Conversion of XQuery arguments to JavaScript:

A value of type xs:boolean is converted to a boolean.

Conversion of JavaScript results to XQuery:

A boolean is converted to xs:boolean.

The following query returns the result of an arithmetic expression:

let $id := mongo:connect("localhost") return mongo:eval($client-id, "db", 'function ( x, y ) { return x + y; }', (2, 5) )

mongo:drop-database($client-id as xs:string, $database as xs:string) as empty-sequence()

Drops a database. No operation will be performed if the database does not exist.

The connection is identified by the supplied $client-id, and the name of the database is supplied via $database.

The following query drops five databases (provided they exist):

let $id := mongo:connect("localhost") for $no in 1 to 5 return mongo:drop-database($client-id, "database-" || $no)

mongo:find($client-id as xs:string, $database as xs:string, $collection as xs:string) as map(*)*

mongo:find($client-id as xs:string, $database as xs:string, $collection as xs:string, $query as map(*)) as map(*)*

mongo:find($client-id as xs:string, $database as xs:string, $collection as xs:string, $query as map(*), $options as map(*)) as map(*)*

Returns documents of a collection. If a query is supplied via the $query argument, the documents are filtered by that query. The $options argument can have the following entries:

"fields": map(*): Restricts the returned fields. The field _id will always be returned.

The connection is identified by the supplied $client-id, and the name of the database and collection are supplied via $database and $collection.

The following expression queries an addressbook and selects all persons living in Tokyo. It sorts results by the names and returns the first 50 documents:

let $id := mongo:connect("localhost") return mongo:find($client-id, 'db', 'addressbook', map { "city": "Tokyo" }, map { "sort": map { "name": 1 }, "limit": 50 } )

mongo:find-one($client-id as xs:string, $database as xs:string, $collection as xs:string) as map(*)?

mongo:find-one($client-id as xs:string, $database as xs:string, $collection as xs:string, $query as map(*)) as map(*)?

mongo:find-one($client-id as xs:string, $database as xs:string, $collection as xs:string, $query as map(*), $options as map(*)) as map(*)?

Returns the first document of a database that optionally matches a supplied $query. The $options argument can have have the following entries:

"fields": map(*): Restricts the returned fields. The field _id will always be returned.

The connection is identified by the supplied $client-id, and the name of the database and collection are supplied via $database and $collection.

The following query returns the first document that matches the specified query:

let $id := mongo:connect("localhost") return mongo:find-one($client-id, 'db', 'addressbook', map { "name": "John Taylor" })

mongo:count($client-id as xs:string, $database as xs:string, $collection as xs:string) as xs:integer

mongo:count($client-id as xs:string, $database as xs:string, $collection as xs:string, $query as map(*)) as xs:integer

Counts documents in a collection. If a query is supplied via the $query argument, the documents are filtered by that query.

The connection is identified by the supplied $client-id, and the name of the database and collection are supplied via $database and $collection.

The following expression counts the number of documents in the "addressbook" collection:

mongo:count(mongo:connect("localhost"), 'db', 'addressbook')

mongo:aggregate($client-id as xs:string, $database as xs:string, $collection as xs:string, $pipeline as map(*)*) as map(*)*

Calculates aggregate values for the documents in a collection and returns the results. The operations to be performed are supplied via the $pipeline argument.

The connection is identified by the supplied $client-id, and the name of the database and collection are supplied via $database and $collection.

The following query selects all documents with "Tokyo" as city and returns their names:

let $id := mongo:connect("localhost") return mongo:aggregate($client-id, "db","addressbook", (map { "$match" : map { "city": "Tokyo" } }, map { "$project": map { "name": 1 } }) )

mongo:group($client-id as xs:string, $database as xs:string, $collection as xs:string, $fields as map(*), $reduce as xs:string, $initial as map(*)) as map(*)*

mongo:group($client-id as xs:string, $database as xs:string, $collection as xs:string, $fields as map(*), $reduce as xs:string, $initial as map(*), $options as map(*)) as map(*)*

Groups documents in a collection by the supplied $fields, aggregates the documents via the $reduce function, and returns the results. $initial provides an initial result document, which will be modified by the reduce function. The $options argument can have the following entries:

"cond": map(*): Filters the documents before being processed.

The connection is identified by the supplied $client-id, and the name of the database and collection are supplied via $database and $collection.

The following groups documents with age > 60 by the city field and returns the summed up orders field:

let $id := mongo:connect("localhost") return mongo:group($client-id, "db", "addressbook", map { "city": 1 }, "function (curr, result) { result.orders += curr.orders; }", map { "orders": 0 }, map { "cond": map { "age": map { "$gt": 60 } } } )

mongo:map-reduce($client-id as xs:string, $database as xs:string, $collection as xs:string, $map as xs:string, $reduce as xs:string) as map(*)*

mongo:map-reduce($client-id as xs:string, $database as xs:string, $collection as xs:string, $map as xs:string, $reduce as xs:string, $options as map(*)) as map(*)*

Runs a map-reduce aggregation operation over the documents of a collection. The map and reduce functions are supplied via the $map and $reduce arguments. The $options argument can have the following entries:

"query": map(*): Filters the documents before being processed.

The connection is identified by the supplied $client-id, and the name of the database and collection are supplied via $database and $collection.

The following query sums up the numbber of orders from all documents of the "addressbook" collection:

let $id := mongo:connect("localhost") return mongo:map-reduce($client-id, "db", "addressbook", 'function () { emit(this._id, this.orders) };', 'function (id, ordersArray) { return Array.sum(ordersArray); };' )

mongo:find-and-modify($client-id as xs:string, $database as xs:string, $collection as xs:string, $query as map(*), $update as map(*)) as map(*)?

mongo:find-and-modify($client-id as xs:string, $database as xs:string, $collection as xs:string, $query as map(*), $update as map(*), $options as map(*)) as map(*)?

Finds a document that has been selected via the $query argument, modifies it according to the $update argument, and returns the document as it was before the modifications. An empty sequence is returned if no document was found. The $options argument can have the following entries:

The connection is identified by the supplied $client-id, and the name of the database and collection are supplied via $database and $collection.

The following query modifies a document with the specified id:

let $id := mongo:connect("localhost") return mongo:find-and-modify($client-id, 'db', 'addressbook', map { "_id": 123 }, map { "name": "Naomi Matsuo", "city": "Tokyo", "country": "Japan" } )

mongo:find-and-remove($client-id as xs:string, $database as xs:string, $collection as xs:string, $query as map(*)) as map(*)?

Finds a document that has been selected via the $query argument and returns it after removing it from the database. An empty sequence is returned if no document was found.

The connection is identified by the supplied $client-id, and the name of the database and collection are supplied via $database and $collection.

The following query removes a document with the specified id:

let $id := mongo:connect("localhost") return mongo:find-and-remove($client-id, 'db', 'addressbook', map { "_id": 123 })

mongo:insert($client-id as xs:string, $database as xs:string, $collection as xs:string, $documents as map(*)*) as empty-sequence()

Inserts documents into a collection. If the collection does not exists on the server, it will be created. If the new document does not contain an _id field, it will be added.

The connection is identified by the supplied $client-id, and the name of the database and collection are supplied via $database and $collection.

The following expression inserts two new documents into a collection:

let $id := mongo:connect("localhost") let $docs := (map { 'name': 'John Daniels' }, map { 'name': 'Jack Walker' }) return mongo:insert($client-id, 'db', 'addressbook', $docs)

mongo:save($client-id as xs:string, $database as xs:string, $collection as xs:string, $document as map(*)) as empty-sequence()

Updates an existing document in a collection or inserts a new document. If the supplied document has no _id field, or if the id does not exist in the collection, the document will be inserted. Otherwise, the existing document will be replaced.

The connection is identified by the supplied $client-id, and the name of the database and collection are supplied via $database and $collection.

The following expression updates or inserts a single document:

let $id := mongo:connect("localhost") let $doc := map { '_id': 123, name': 'Hans Schmid' } return mongo:save($client-id, 'db', 'addressbook', $doc)

mongo:update($client-id as xs:string, $database as xs:string, $collection as xs:string, $query as map(*), $update as map(*)) as empty-sequence()

mongo:update($client-id as xs:string, $database as xs:string, $collection as xs:string, $query as map(*), $update as map(*), $options as map(*)) as empty-sequence()

Finds one or more document that have been selected via the $query argument and modifies them according to the $update argument. The $options argument can have have the following entries:

The connection is identified by the supplied $client-id, and the name of the database and collection are supplied via $database and $collection.

The following update applies to all documents in the addressed collection. It replaces the value of the info field with null, or adds a new name/value pair if the field does not exist:

let $id := mongo:connect("localhost") return mongo:update($client-id, 'db', 'addressbook', map { }, map { '$set': map { 'info': () } }, map { 'upsert': true(), 'multi': true() } )

mongo:remove($client-id as xs:string, $database as xs:string, $collection as xs:string, $query as map(*)) as empty-sequence()

Removes documents from a collection that are selected by the $query argument.

The connection is identified by the supplied $client-id, and the name of the database and collection are supplied via $database and $collection.

The following expression removes all documents from a collection:

mongo:remove(mongo:connect("localhost"), 'db', 'addressbook', map { })

mongo:drop-collection($client-id as xs:string, $database as xs:string, $collection as xs:string) as empty-sequence()

Drops a collection. No operation will be performed if the collection does not exist.

The connection is identified by the supplied $client-id, and the name of the database and collection are supplied via $database and $collection.

The following query drops five collections in a database:

let $id := mongo:connect("localhost") for $no in 1 to 5 return mongo:drop-collection($client-id, "database", "collection-" || $no)