Skip to content

Commit bda63c1

Browse files
rustagirrustagir
committed
undefined values page & reorganization
* DOCSP-29510: explain how driver handles undefined vals (#674) * DOCSP-29510: explain how driver handles undefined vals * make new subfolder for bson * tree fixes and redirect-- snooty stuff * fix version in redirect * fix highlight * JS PR fixes 1 * JS suggestion (cherry picked from commit 52daa59) * redirect file revert (cherry picked from commit 157f483) (cherry picked from commit f7c1609) (cherry picked from commit 82a8fff)
1 parent e1ee30a commit bda63c1

File tree

7 files changed

+159
-5
lines changed

7 files changed

+159
-5
lines changed

‎snooty.toml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ toc_landing_pages = [
1111
"/fundamentals",
1212
"/fundamentals/connection",
1313
"/fundamentals/crud",
14+
"/fundamentals/bson",
1415
"/usage-examples",
1516
]
1617
sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/"

‎source/fundamentals.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ Fundamentals
2020
/fundamentals/gridfs
2121
/fundamentals/time-series
2222
/fundamentals/typescript
23-
/fundamentals/utf8-validation
23+
/fundamentals/bson
2424
/fundamentals/encrypt-fields
2525

2626
.. include:: /includes/fundamentals-sections.rst

‎source/fundamentals/bson.txt

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
.. _node-bson-control:
2+
3+
=============
4+
BSON Settings
5+
=============
6+
7+
.. toctree::
8+
:caption: BSON settings
9+
10+
/fundamentals/bson/undefined-values
11+
/fundamentals/bson/utf8-validation
12+
13+
.. contents:: On this page
14+
:local:
15+
:backlinks: none
16+
:depth: 1
17+
:class: singlecol
18+
19+
Overview
20+
--------
21+
22+
Learn how to configure your application's BSON serialization settings.
23+
The guides in this section describe the following topics:
24+
25+
- :ref:`Undefined Values <node-undefined-values>`: Control how the
26+
driver serializes undefined values
27+
- :ref:`UTF-8 Validation <nodejs-utf-8-validation>`: Enable or disable
28+
the UTF-8 validation feature

‎source/fundamentals/bson/undefined-values.txt

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
.. _node-undefined-values:
2+
3+
================
4+
Undefined Values
5+
================
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
Overview
14+
--------
15+
16+
In this guide, you can learn to control how the driver serializes
17+
``undefined`` values. By default, the driver serializes ``undefined`` values
18+
as ``null`` values during write operations.
19+
20+
.. _nodejs-specify-ignoreundefined:
21+
22+
Ignore Undefined Values
23+
-----------------------
24+
25+
To make the driver ignore fields with
26+
``undefined`` values during serialization, set the
27+
``ignoreUndefined`` setting to ``true``. When you specify this setting,
28+
the driver *does not* serialize fields with ``undefined`` values.
29+
30+
The following example inserts two documents. The first insert operation has
31+
the ``ignoreUndefined`` setting set to ``true``, so the driver does not
32+
serialize the ``salesTax`` field in that operation. The second operation
33+
inserts a document that has the ``salesTax`` field with a ``null`` value:
34+
35+
.. code-block:: javascript
36+
:emphasize-lines: 6
37+
38+
await myColl.insertOne(
39+
{
40+
state: "Montana",
41+
salesTax: undefined,
42+
},
43+
{ ignoreUndefined: true }
44+
);
45+
46+
await myColl.insertOne({
47+
state: "New Hampshire",
48+
salesTax: undefined,
49+
});
50+
51+
The documents appear in the collection as follows:
52+
53+
.. code-block:: javascript
54+
:copyable: false
55+
56+
{
57+
_id: ...,
58+
state: "Montana",
59+
},
60+
{
61+
_id: ...,
62+
state: "New Hampshire",
63+
salesTax: null
64+
}
65+
66+
.. _nodejs-ignoreundefined-scope:
67+
68+
Set the Scope for Serializing Undefined Values
69+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
70+
71+
You can specify the ``ignoreUndefined`` setting at the following levels:
72+
73+
- The client level
74+
- The database level
75+
- The collection level
76+
- The operation level
77+
78+
The ``ignoreUndefined`` setting automatically applies to the scope of the
79+
object instance in which you specified it, as well as any other objects created
80+
from that instance.
81+
82+
For example, if you set the ``ignoreUndefined`` setting when
83+
instantiating a database object, any collection instance created from
84+
that object inherits the setting. Furthermore, any operations that you
85+
call on that collection instance also inherit the setting.
86+
87+
The following example performs an find-and-update operation that
88+
inherits the ``ignoreUndefined`` setting from the ``myDB`` database
89+
object. This operation does not produce any data changes because the
90+
driver ignores the ``gasTax`` field:
91+
92+
.. code-block:: javascript
93+
94+
const myDB = client.db("test", { ignoreUndefined: true });
95+
96+
// The collection inherits the ignoreUndefined setting
97+
const myColl = myDB.collection("states");
98+
99+
// Any write operation will not serialize undefined values
100+
await myColl.findOneAndUpdate(
101+
{ state: "Georgia" },
102+
{ $set: { gasTax: undefined } }
103+
);
104+
105+
You can specify the ``ignoreUndefined`` setting again at any level to
106+
override any inherited settings.
107+
108+
For example, if you set ``ignoreUndefined`` to ``true`` on your
109+
collection object, you can override the setting in individual write
110+
operations that you execute on that collection.
111+
112+
.. code-block:: javascript
113+
:emphasize-lines: 1, 12
114+
115+
const myColl = myDB.collection("states", { ignoreUndefined: true });
116+
117+
// The insert operation will not serialize undefined values
118+
await myColl.insertOne({
119+
state: "South Dakota",
120+
capitalGainsTax: undefined,
121+
});
122+
123+
// The insert operation will serialize undefined values
124+
await myColl.insertOne(
125+
{ state: "Texas", capitalGainsTax: undefined },
126+
{ ignoreUndefined: false }
127+
);

‎source/fundamentals/utf8-validation.txt renamed to ‎source/fundamentals/bson/utf8-validation.txt

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,6 @@
44
UTF-8 Validation
55
================
66

7-
.. default-domain:: mongodb
8-
97
.. contents:: On this page
108
:local:
119
:backlinks: none
@@ -117,4 +115,3 @@ collection.
117115

118116
// CRUD operation runs with UTF-8 validation disabled
119117
await collection.findOne({ title: 'Enola Holmes' });
120-

‎source/fundamentals/crud/write-operations/upsert.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -91,3 +91,4 @@ beforehand:
9191
{ name: "Deli Llama", address: "3 Nassau St" },
9292
...
9393
]
94+

‎source/includes/fundamentals-sections.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,4 +16,4 @@ Fundamentals section:
1616
- :doc:`Encrypt Fields from the Client </fundamentals/encrypt-fields>`
1717
- :doc:`Create and Query Time Series Collection </fundamentals/time-series>`
1818
- :doc:`Specify Type Parameters with TypeScript </fundamentals/typescript>`
19-
- :doc:`Specify UTF-8 Validation Settings </fundamentals/utf8-validation>`
19+
- :doc:`Specify BSON Serialization Settings </fundamentals/bson>`

0 commit comments

Comments
 (0)