Skip to main content

mongodb functions: Interacting with a MongoDB database

The mongodb built-in functions allow you to interact with a MongoDB database.

info

Check out our tutorial on querying MongoDB.

You can also use the MongoDB data plugin to periodically push data from MongoDB directly into data..

Shared Parameters

All mongodb functions share several function parameters.

ParameterTypeRequiredDefaultDescription
uriStringYesThe URI of the database.
authObjectNoSee Auth
cacheBoolNofalseCache the results of queries.
cache_durationIntegerNo60Duration (in seconds) to keep cached query results.
canonicalBoolNofalseWhether to use Canonical mode or not for BSON encoding. More Details
raise_errorBoolNotrueSee Errors

Auth

ParameterTypeRequiredDefaultDescription
auth.auth_mechanismStringNoThe mechanism to use for authentication. Supported values include SCRAM-SHA-256, SCRAM-SHA-1, MONGODB-CR, PLAIN, GSSAPI, MONGODB-X509, and MONGODB-AWS. More details.
auth.auth_mechanism_propertiesObjectNoAdditional configuration options for certain mechanisms. More Details
auth.auth_sourceStringNoThe name of the database to use for authentication. More Details.
auth.usernameStringNoThe username for authentication.
auth.passwordStringNoThe password for authentication.
auth.password_setBoolNoFor GSSAPI, this must be true if a password is specified, even if the password is the empty string, and false if no password is specified, indicating that the password should be taken from the context of the running process. For other mechanisms, this field is ignored.

See links below to the MongoDB docs for more information on some of the options:

Errors

By default—and if raise_error is true—then an error returned will halt policy evaluation.

If raise_error is false, then the response object contains the error in an error key instead of its usual response.

{
"error": ...
}

mongodb.find

The mongodb.find function allows you to make a query against a MongoDB database, returning multiple objects.

Example usage

allowed_resources_query_response := mongodb.find({
"uri": "mongodb://localhost:27017",
"database": "permissions",
"collection": "resources",
"filter": {
operation_to_field[input.operation]: {
"$in": input.user.roles
},
},
"options": {"projection": {"_id": false}}
}) # => { "results": ... }

Parameters

ParameterTypeRequiredDefaultDescription
databaseStringYesThe name of the database.
collectionStringYesThe name of the collection in the database to fetch from.
filterObjectYesThe document describing query conditions for the operation. More Details
optionsObjectNoThe document describing extra query options. More Details

mongodb.find_one

The mongodb.find_one function allows you to make a query against a MongoDB database, returning a single object.

Example usage

resource_query_response := mongodb.find({
"uri": "mongodb://localhost:27017",
"database": "permissions",
"collection": "resources",
"filter": {
"endpoint": sprintf("/%s", [concat("/", input.request.path)]),
},
"options": {"projection": {"_id": false}},
}) # => { "results": ... }

Parameters

ParameterTypeRequiredDefaultDescription
databaseStringYesThe name of the database.
collectionStringYesThe name of the collection in the database to fetch from.
filterObjectYesThe document describing query conditions for the operation. More Details
optionsObjectNoThe document describing extra query options. More Details

Utility helpers

Enterprise OPA comes with helper methods for using this builtin together with vault.send: mongodb.find and mongodb.find_one.

Both of these methods are available in EOPA at data.system.eopa.utils.mongodb.v1.vault.

package example
import data.system.eopa.utils.mongodb.v1.vault as mongodb

example_1 := mongodb.find({"database": "database", "collection": "collection", "filter": {}})
) # => {"results": [ ... ]}

example_2 := mongodb.find_one({"database": "database", "collection": "collection", "filter": {}})
) # => {"result": [ ... ]}

The utility methods will lookup connection data from a map it expects to find in Vault, under the path secret/mongodb:

{
"host": "...",
"port": "...",
"user": "...",
"password": "...",
}

If host or port are not defined, they default to localhost and 27017 respectively.

To override the secret path within Vault, use:

package example
import data.system.eopa.utils.mongodb.v1.vault as mongodb

mongodb_find(req) := result {
result := mongodb.find(req)
with mongodb.override.secret_path as "secret/prod/eopa-mongodb"

example_3 := mongodb_find({"database": "database", "collection": "collection", "filter": {}})
) # => {"results": [ ... ]}

If you need to override the Vault address or token, you can use this:

package example
import data.system.eopa.utils.vault.v1.env as vault
import data.system.eopa.utils.mongodb.v1.vault as mongodb

mongodb_find(req) := result {
result := mongodb.find(req)
with mongodb.override.secret_path as "secret/prod/eopa-mongodb"
with vault.override.address as "localhost"
with vault.override.token as "dev-token-2"

example_4 := mongodb_find({"database": "database", "collection": "collection", "filter": {}})

The same mechanism applies to mongodb.find_one.

To control the caching and error raising behavior, cache, cache_duration, and raise_error can also be passed to find and find_one as keys of their request objects.