Docs Home / BSON

Undefined Values值

Overview概述

In this guide, you can learn to control how the driver serializes undefined values. By default, the driver serializes undefined values as null values during write operations.在本指南中，您可以学习控制驱动程序如何序列化undefined值。默认情况下，驱动程序在写入操作期间将undefined值序列化为null值。

Ignore Undefined Values忽略未定义的值

To make the driver ignore fields with undefined values during serialization, set the ignoreUndefined setting to true. When you specify this setting, the driver does not serialize fields with undefined values.要使驱动程序在序列化过程中忽略具有undefined值的字段，请将ignoreUndefined设置设置为true。指定此设置时，驱动程序不会序列化具有未定义值的字段。

The following example inserts two documents. 以下示例插入两个文档。The first insert operation has the ignoreUndefined setting set to true, so the driver does not serialize the salesTax field in that operation. 第一个插入操作将ignoreUndefined设置设置为true，因此驱动程序不会在该操作中序列化salesTax字段。The second operation inserts a document that has the salesTax field with a null value:第二个操作插入一个salesTax字段为null值的文档：

await myColl.insertOne(
  {
    state: "Montana",
    salesTax: undefined,
  },
  { ignoreUndefined: true }
);

await myColl.insertOne({
  state: "New Hampshire",
  salesTax: undefined,
});

The documents appear in the collection as follows:文档在集合中显示如下：

{
  _id: ...,
  state: "Montana",
},
{
  _id: ...,
  state: "New Hampshire",
  salesTax: null
}

Set the Scope for Serializing Undefined Values设置序列化未定义值的范围

You can specify the ignoreUndefined setting at the following levels:您可以在以下级别指定ignoreUndefined设置：

  • The client level客户层面
  • The database level数据库级别
  • The collection level集合级别
  • The operation level操作层面

The ignoreUndefined setting automatically applies to the scope of the object instance in which you specified it and any other objects created from that instance.ignoreUndefined设置会自动应用于您指定它的对象实例的范围以及从该实例创建的任何其他对象。

For example, if you set the ignoreUndefined setting when instantiating a database object, any collection instance created from that object inherits the setting. Furthermore, any operations that you call on that collection instance also inherit the setting.例如，如果在实例化数据库对象时设置ignoreUndefined设置，则从该对象创建的任何集合实例都会继承该设置。此外，您对该集合实例调用的任何操作也会继承该设置。

The following example performs an find-and-update operation that inherits the ignoreUndefined setting from the myDB database object. This operation does not produce any data changes because the driver ignores the gasTax field:以下示例执行查找和更新操作，该操作从myDB数据库对象继承ignoreUndefined设置。此操作不会产生任何数据更改，因为驱动程序忽略了gasTax字段：

const myDB = client.db("test", { ignoreUndefined: true });

// The collection inherits the ignoreUndefined setting该集合继承了ignoreUndefined设置
const myColl = myDB.collection("states");

// Any write operation will not serialize undefined values任何写入操作都不会序列化未定义的值
await myColl.findOneAndUpdate(
  { state: "Georgia" },
  { $set: { gasTax: undefined } }
);

You can specify the ignoreUndefined setting again at any level to override any inherited settings.您可以在任何级别再次指定ignoreUndefined设置，以覆盖任何继承的设置。

For example, if you set ignoreUndefined to true on your collection object, you can override the setting in individual write operations that you execute on that collection.例如，如果在集合对象上将ignoreUndefined设置为true，则可以在对该集合执行的单个写入操作中覆盖该设置。

const myColl = myDB.collection("states", { ignoreUndefined: true });

// The insert operation will not serialize undefined values插入操作不会序列化未定义的值
await myColl.insertOne({
  state: "South Dakota",
  capitalGainsTax: undefined,
});

// The insert operation will serialize undefined values插入操作将序列化未定义的值
await myColl.insertOne(
  { state: "Texas", capitalGainsTax: undefined },
  { ignoreUndefined: false }
);