Docs Menu

Docs HomeNode.js Driver

Undefined Values

On this page

  • Overview
  • Ignore Undefined Values
  • Set the Scope for Serializing Undefined Values

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.

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.

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. The second operation inserts a document that has the salesTax field with a null value:

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
}

You can specify the ignoreUndefined setting at the following levels:

  • 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, as well as any other objects created from that instance.

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.

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:

const myDB = client.db("test", { ignoreUndefined: true });
// The collection inherits the ignoreUndefined setting
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.

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.

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 }
);
←  BSON SettingsUTF-8 Validation →