Field Encryption and Queryability字段加密和可查询性

Example实例

This example shows how to create a JSON schema that specifies which fields Queryable Encryption should automatically encrypt.此示例显示如何创建JSON模式，该模式指定可查询加密应自动加密哪些字段。

Consider the following document that contains personally identifiable information (PII), credit card information, and sensitive medical information:考虑以下包含个人身份信息（PII）、信用卡信息和敏感医疗信息的文档：

{
   "firstName": "Jon",
   "lastName": "Snow",
   "patientId": 12345187,
   "address": "123 Cherry Ave",
   "medications": [
      "Adderall",
      "Lipitor"
   ],
   "patientInfo": {
      "ssn": "921-12-1234",
      "billing": {
            "type": "visa",
            "number": "1234-1234-1234-1234"
      }
   }
}

To ensure the PII and sensitive medical information stays secure, create a JSON schema that configures those fields for automatic encryption. 为了确保PII和敏感医疗信息的安全，请创建一个JSON模式，配置这些字段进行自动加密。For example:例如：

const encryptedFieldsObject = {
   fields: [
      {
         path: "patientId",
         bsonType: "int"
      },
      {
         path: "patientInfo.ssn",
         bsonType: "string"
      },
      {
         path: "medications",
         bsonType: "array"
      },
      {
         path: "patientInfo.billing",
         bsonType: "object"
      }
   ]
}

MongoDB creates encryption keys for each field automatically. Configure AutoEncryptionSettings on the client, then use the createEncryptedCollection helper method to create your collections.MongoDB会自动为每个字段创建加密键。在客户端上配置AutoEncryptionSettings，然后使用createEncryptedCollection帮助程序方法创建集合。

If you are using explicit encryption, you must create a unique Data Encryption Key for each encrypted field in advance. Add a keyId field to each entry that includes the key:如果使用显式加密，则必须提前为每个加密字段创建一个唯一的数据加密键。向包含键的每个条目添加一个keyId字段：

const encryptedFieldsObject = {
   fields: [
      {
         path: "patientId",
         keyId: "<unique data encryption key>",
         bsonType: "int"
      },
      {
         path: "patientInfo.ssn",
         keyId: "<unique data encryption key>",
         bsonType: "string"
      },
      . . .
   ]
}

Example实例

Add the queries property to the previous example schema to make the patientId and patientInfo.ssn fields queryable.将queries属性添加到上一个示例架构中，使patientId和patientInfo.ssn字段可查询。

const encryptedFieldsObject = {
   fields: [
      {
         path: "patientId",
         bsonType: "int",
         queries: { queryType: "equality" }
      },
      {
         path: "patientInfo.ssn",
         bsonType: "string",
         queries: { queryType: "equality" }
      },
      {
         path: "medications",
         bsonType: "array"
      },
      {
         path: "patientInfo.billing",
         bsonType: "object"
      },
   ]
}

Configure Contention Factor配置争用系数

Include the contention property on queryable fields to prefer either find performance, or write and update performance.在可查询字段中包含contention属性，以便查找性能或写入和更新性能。

Inserting the same field/value pair into multiple documents in close succession can cause conflicts that delay insert operations.将同一字段/值对连续插入多个文档可能会导致冲突，从而延迟插入操作。

MongoDB tracks the occurrences of each field/value pair in an encrypted collection using an internal counter. MongoDB使用内部计数器跟踪加密集合中每个字段/值对的出现情况。The contention factor partitions this counter, similar to an array. 争用因子对该计数器进行分区，类似于数组。This minimizes issues with incrementing the counter when using insert, update, or findAndModify to add or modify an encrypted field with the same field/value pair in close succession. 当使用insert、update或findAndModify来连续添加或修改具有相同字段/值对的加密字段时，这可以最大限度地减少计数器递增的问题。contention = 0 creates an array with one element at index 0. 创建一个在索引0处有一个元素的数组。contention = 4 creates an array with 5 elements at indexes 0-4. MongoDB increments a random array element during insert. 创建一个在索引0-4处具有5个元素的数组。MongoDB在插入过程中增加一个随机数组元素。If unset, contention defaults to 8.如果未设置，contention默认为8。

High contention improves the performance of insert and update operations on low cardinality fields, but decreases find performance.高争用提高了对低基数字段的插入和更新操作的性能，但降低了查找性能。

Consider increasing contention above the default value of 8 only if:只有在以下情况下，才考虑将争用contention到默认值8以上：

• The field has low cardinality or low selectivity. 该字段具有低基数或低选择性。A state field may have 50 values, but if 99% of the data points use {state: NY}, that pair is likely to cause contention.一个state字段可能有50个值，但如果99%的数据点使用{state: NY}，则该对可能会引起争用。
• Write and update operations frequently modify the field. 写入和更新操作经常修改字段。Since high contention values sacrifice find performance in favor of write and update operations, the benefit of a high contention factor for a rarely updated field is unlikely to outweigh the drawback.由于高争用值牺牲了查找性能而有利于写入和更新操作，因此对于很少更新的字段，高争用因子的好处不太可能超过缺点。

Consider decreasing contention if:如果出现以下情况，请考虑减少contention：

• The field is high cardinality and contains entirely unique values, such as a credit card number.该字段具有很高的基数，并且包含完全唯一的值，例如信用卡号。
• The field is often queried, but never or rarely updated. In this case, find performance is preferable to write and update performance.该字段经常被查询，但从未更新或很少更新。在这种情况下，查找性能优于写入和更新性能。

const encryptedFieldsObject = {
   fields: [
      {
         path: "patientId",
         bsonType: "int",
         queries: { queryType: "equality",
                    contention: "0"}
      },
      {
         path: "patientInfo.ssn",
         bsonType: "string",
         queries: { queryType: "equality",
                    contention: "0"}
      },
      ...
   ]
}

Query Types查询类型

Passing a query type to the queries option in your encrypted fields object sets the allowed query types for the field. 将查询类型传递给加密字段对象中的queries选项将设置字段允许的查询类型。Querying non-encrypted fields or encrypted fields with a supported query type returns encrypted data that is then decrypted at the client.使用支持的查询类型查询非加密字段或加密字段会返回加密数据，然后在客户端对其进行解密。

Queryable Encryption currently supports none and equality query types. If the query type is unspecified, it defaults to none. 可查询加密当前支持none查询类型和equality查询类型。如果未指定查询类型，则默认为“无”。If the query type is none, the field is encrypted, but clients can't query it.如果查询类型为none，则字段是加密的，但客户端无法查询它。

The equality query type supports the following expressions:equality查询类型支持以下表达式：

• $eq
• $ne
• $in
• $nin
• $and
• $or
• $not
• $nor
• $expr

Queryable Encryption equality queries don't support read or write operations on a field when the operation compares the encrypted field to any of the following BSON types:当操作将加密字段与以下任何BSON类型进行比较时，可查询加密equality（相等）查询不支持对字段进行读取或写入操作：

• double
• decimal128
• object
• array
• javascriptWithScope (Deprecated in MongoDB 4.4)