Database Manual / Reference / mongosh Methods / In-Use Encryption

ClientEncryption.encryptExpression() (mongosh method)

ClientEncryption.encryptExpression(keyId, expression, encOptions)

ClientEncryption.encryptExpression encrypts an MQL expression to query a range index, using the queried field's keyId and the query type and algorithm from the encOptions document. It returns the encrypted result of the query.

Returns:

The encrypted result of the query as a binary data object with subtype 6.

Compatibility

This command is available in deployments hosted in the following environments:

MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud

MongoDB Enterprise: The subscription-based, self-managed version of MongoDB
MongoDB Community: The source-available, free-to-use, and self-managed version of MongoDB

Syntax

clientEncryption = db.getMongo().getClientEncryption()

clientEncryption.encryptExpression(
   keyId,
   expression,
   encOptions
)

Parameter Type Description

Parameter	Type	Description
`keyId`	`UUID`	The data encryption key for the field queried in the expression. The UUID is a BSON `binary data` object with subtype `4` that identifies a specific data encryption key. If the data encryption key does not exist in the key vault configured for the database connection, `encryptExpression()` returns an error. See Key Vault Collections for more information on key vaults and data encryption keys.
`expression`	document	The range query expression to encrypt, as one of: a `$match` expression in the form: `{$and: [{<field>: {$gt: <value1>}}, {<field>: {$lt: <value2> }}]}` an `aggregate` expression in the form: `{$and: [{$gt: [<fieldpath>, <value1>]}, {$lt: [<fieldpath>, <value2>]}]}` Expressions can also use `$lte` or `$gte`
`encOptions`	document	A document with the fields: `algorithm`: The encryption algorithm to use for encrypting the `expression`. Must be set to `"range"`. `queryType`: The query type. Must be set to `"range"`. `rangeOptions`: A document with range query settings. Values must match those in the collection's encryption schema. `min`, `max`: Minimum and maximum values that match the field's BSON type. `precision`: The number of significant digits MongoDB accounts for when querying `double` and `decimal128` fields. `sparsity`: Affects how thoroughly MongoDB indexes range values. `trimFactor`: Controls the throughput of concurrent inserts and updates. `contentionFactor`: Related to the frequency of the values for fields in the expression. For details, see contention.

keyId

UUID

The data encryption key for the field queried in the expression.

The UUID is a BSON binary data object with subtype 4 that identifies a specific data encryption key. If the data encryption key does not exist in the key vault configured for the database connection, encryptExpression() returns an error. See Key Vault Collections for more information on key vaults and data encryption keys.

expression

document

The range query expression to encrypt, as one of:

a $match expression in the form: {$and: [{<field>: {$gt: <value1>}}, {<field>: {$lt: <value2> }}]}
an aggregate expression in the form: {$and: [{$gt: [<fieldpath>, <value1>]}, {$lt: [<fieldpath>, <value2>]}]}

Expressions can also use $lte or $gte

encOptions

document

A document with the fields:

algorithm: The encryption algorithm to use for encrypting the expression. Must be set to "range".
queryType: The query type. Must be set to "range".
rangeOptions: A document with range query settings. Values must match those in the collection's encryption schema.
- min, max: Minimum and maximum values that match the field's BSON type.
- precision: The number of significant digits MongoDB accounts for when querying double and decimal128 fields.
- sparsity: Affects how thoroughly MongoDB indexes range values.
- trimFactor: Controls the throughput of concurrent inserts and updates.
contentionFactor: Related to the frequency of the values for fields in the expression. For details, see contention.

Behavior

The mongosh client-side field level and queryable encryption methods require a database connection configured for client-side encryption. If the current database connection was not initiated with client-side field level encryption enabled, either:

Use the Mongo() constructor from the mongosh to establish a connection with the required client-side field level encryption options. The Mongo() method supports the following Key Management Service (KMS) providers for Customer Master Key (CMK) management:

Use the mongosh command line options to establish a connection with the required options. The command line options only support the Amazon Web Services KMS provider for CMK management.

Examples

clientEncryption.encryptExpression(
   UUID("64e2d87d-f168-493c-bbdf-a394535a2cb9"),
   {
      $and: [{ val: { $gt: Int32('100') } }, { val: { $lt: Int32('150') } }]
   },
   {
      algorithm: 'range',
      queryType: 'range',
      rangeOptions: { min: Int32('0'), max: Int32('200') },
      contentionFactor: 8
   })

If successful, ClientEncryption.encryptExpression returns the encrypted query result.

Learn More

For complete documentation on initiating MongoDB connections with Client-Side Field Level Encryption or Queryable Encryption enabled, see Mongo().

Back

ClientEncryption.encrypt

ClientEncryption.decrypt