ClientEncryption.encryptExpression()

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
`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: NumberInt('100') } }, { val: { $lt: NumberInt('150') } }]
   },
   {
      algorithm: 'range',
      queryType: 'range',
      rangeOptions: { min: NumberInt('0'), max: NumberInt('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