Skip to content

Commit b79ffbc

Browse files
Mohammad Hunan ChughtaiMohammad Hunan Chughtai
Mohammad Hunan Chughtai
and
Mohammad Hunan Chughtai
authored
(DOCSP-15613): Node.js embedded objects type (#1047)
* Added documentation of Node.js embedded objects under data types * clean up relationships and embedded objects * added CRUD examples for embedded obj * added bluehawked examples * fix rst syntax highlight + add description for deletes * Update source/sdk/node/data-types/embedded-objects.txt * Update source/sdk/node/data-types/embedded-objects.txt * Update source/sdk/node/data-types/embedded-objects.txt * Update source/sdk/node/data-types/embedded-objects.txt * Update source/sdk/node/data-types/embedded-objects.txt Co-authored-by: Mohammad Hunan Chughtai <[email protected]>
1 parent 2755206 commit b79ffbc

9 files changed

+310
-60
lines changed

‎examples/node/Examples/data-types.js

Lines changed: 125 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,128 @@
11
import Realm from "realm";
2+
import BSON from "bson";
23

4+
// :code-block-start: define-embedded-objects
5+
const AddressSchema = {
6+
name: "Address",
7+
embedded: true, // default: false
8+
properties: {
9+
street: "string?",
10+
city: "string?",
11+
country: "string?",
12+
postalCode: "string?",
13+
},
14+
};
15+
16+
const ContactSchema = {
17+
name: "Contact",
18+
primaryKey: "_id",
19+
properties: {
20+
_id: "objectId",
21+
name: "string",
22+
address: "Address", // Embed a single object
23+
},
24+
};
25+
26+
const BusinessSchema = {
27+
name: "Business",
28+
primaryKey: "_id",
29+
properties: {
30+
_id: "objectId",
31+
name: "string",
32+
addresses: { type: "list", objectType: "Address" }, // Embed an array of objects
33+
},
34+
};
35+
// :code-block-end:
336
describe("Node.js Data Types", () => {
4-
})
37+
test("should create and read and delete an embedded object", async () => {
38+
const realm = await Realm.open({
39+
schema: [AddressSchema, ContactSchema],
40+
});
41+
42+
// :code-block-start: create-an-embedded-object
43+
// create an embedded address object
44+
const sydneyOrthodontics = {
45+
street: "42 Wallaby Way",
46+
city: "Sydney",
47+
country: "Australia",
48+
postalCode: "2774",
49+
};
50+
realm.write(() => {
51+
// create a contact object
52+
realm.create("Contact", {
53+
_id: new BSON.ObjectId(),
54+
name: "Philip Sherman",
55+
address: sydneyOrthodontics, // embed the address in the contact object
56+
});
57+
});
58+
// :code-block-end:
59+
60+
// :code-block-start: query-an-embedded-object
61+
const philipShermanAddress = realm
62+
.objects("Contact")
63+
.filtered("name = 'Philip Sherman'")[0].address.street;
64+
console.log(`Philip Sherman's address is ${philipShermanAddress}`);
65+
// :code-block-end:
66+
expect(philipShermanAddress).toBe("42 Wallaby Way"); // this assertion tests both the 'query-an-embedded-object' and 'create-an-embedded-object' code blocks
67+
68+
// // :code-block-start: delete-an-embedded-object
69+
realm.write(() => {
70+
// Deleting the contact will delete the embedded address of that contact
71+
realm.delete(
72+
realm.objects("Contact").filtered("name = 'Philip Sherman'")
73+
);
74+
});
75+
// :code-block-end:
76+
77+
// close the realm
78+
realm.close();
79+
});
80+
// update and delete an embedded object
81+
test("should update and overwrite an embedded object", async () => {
82+
const realm = await Realm.open({
83+
schema: [AddressSchema, ContactSchema],
84+
});
85+
const harryAddress = {
86+
street: "4 Privet Drive",
87+
city: "Little Whinging, Surrey",
88+
country: "UK",
89+
postalCode: "WD4 8PN",
90+
};
91+
realm.write(() => {
92+
realm.create("Contact", {
93+
_id: new BSON.ObjectId(),
94+
name: "Harry Potter",
95+
address: harryAddress,
96+
});
97+
});
98+
99+
// :code-block-start: update-an-embedded-object
100+
// Find the contact with the address you want to update
101+
const harryPotter = realm
102+
.objects("Contact")
103+
.filtered("name = 'Harry Potter'")[0];
104+
// modify the property of the embedded object in a write transaction
105+
realm.write(() => {
106+
// update the embedded object directly through the contact
107+
harryPotter.address.street = "1 Hogwarts Ave";
108+
});
109+
// :code-block-end:
110+
expect(harryPotter.address.street).toBe("1 Hogwarts Ave");
111+
112+
// :code-block-start: overwrite-an-embedded-object
113+
// create a new address
114+
const harryNewAddress = {
115+
street: "12 Grimmauld Place",
116+
city: "London",
117+
country: "UK",
118+
postalCode: "E1 7AA",
119+
};
120+
realm.write(() => {
121+
// overwrite the embedded object with the new address within a write transaction
122+
harryPotter.address = harryNewAddress;
123+
});
124+
// :code-block-end:
125+
126+
expect(harryPotter.address.city).toBe("London");
127+
});
128+
});

‎source/examples/generated/node/data-types.codeblock.create-an-embedded-object.js

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
// create an embedded address object
2+
const sydneyOrthodontics = {
3+
street: "42 Wallaby Way",
4+
city: "Sydney",
5+
country: "Australia",
6+
postalCode: "2774",
7+
};
8+
realm.write(() => {
9+
// create a contact object
10+
realm.create("Contact", {
11+
_id: new BSON.ObjectId(),
12+
name: "Philip Sherman",
13+
address: sydneyOrthodontics, // embed the address in the contact object
14+
});
15+
});

‎source/examples/generated/node/data-types.codeblock.define-embedded-objects.js

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
const AddressSchema = {
2+
name: "Address",
3+
embedded: true, // default: false
4+
properties: {
5+
street: "string?",
6+
city: "string?",
7+
country: "string?",
8+
postalCode: "string?",
9+
},
10+
};
11+
12+
const ContactSchema = {
13+
name: "Contact",
14+
primaryKey: "_id",
15+
properties: {
16+
_id: "objectId",
17+
name: "string",
18+
address: "Address", // Embed a single object
19+
},
20+
};
21+
22+
const BusinessSchema = {
23+
name: "Business",
24+
primaryKey: "_id",
25+
properties: {
26+
_id: "objectId",
27+
name: "string",
28+
addresses: { type: "list", objectType: "Address" }, // Embed an array of objects
29+
},
30+
};

‎source/examples/generated/node/data-types.codeblock.delete-an-embedded-object.js

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
realm.write(() => {
2+
// Deleting the contact will delete the embedded address of that contact
3+
realm.delete(
4+
realm.objects("Contact").filtered("name = 'Philip Sherman'")
5+
);
6+
});

‎source/examples/generated/node/data-types.codeblock.overwrite-an-embedded-object.js

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
// create a new address
2+
const harryNewAddress = {
3+
street: "12 Grimmauld Place",
4+
city: "London",
5+
country: "UK",
6+
postalCode: "E1 7AA",
7+
};
8+
realm.write(() => {
9+
// overwrite the embedded object with the new address within a write transaction
10+
harryPotter.address = harryNewAddress;
11+
});

‎source/examples/generated/node/data-types.codeblock.query-an-embedded-object.js

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
const philipShermanAddress = realm
2+
.objects("Contact")
3+
.filtered("name = 'Philip Sherman'")[0].address.street;
4+
console.log(`Philip Sherman's address is ${philipShermanAddress}`);

‎source/examples/generated/node/data-types.codeblock.update-an-embedded-object.js

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
// Find the contact with the address you want to update
2+
const harryPotter = realm
3+
.objects("Contact")
4+
.filtered("name = 'Harry Potter'")[0];
5+
// modify the property of the embedded object in a write transaction
6+
realm.write(() => {
7+
// update the embedded object directly through the contact
8+
harryPotter.address.street = "1 Hogwarts Ave";
9+
});

‎source/sdk/node/data-types/embedded-objects.txt

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,3 +11,110 @@ Embedded Objects - Node.js SDK
1111
:backlinks: none
1212
:depth: 2
1313
:class: singlecol
14+
15+
Overview
16+
--------
17+
18+
An embedded object is a special type of :ref:`Realm object <node-object-schemas>`
19+
that models complex data about a specific object. Embedded objects are similar
20+
to :ref:`relationships <node-client-relationships>`, but they provide additional
21+
constraints and map more naturally to the denormalized :manual:`MongoDB document
22+
model </core/data-modeling-introduction/>`.
23+
24+
Realm enforces unique ownership constraints that treat each embedded object as
25+
nested data inside a single, specific parent object. An embedded object
26+
inherits the lifecycle of its parent object and cannot exist as an independent
27+
Realm object. This means that embedded objects cannot have a primary key and
28+
that Realm automatically deletes embedded objects if their parent object is
29+
deleted.
30+
31+
.. tip:: Embedded object types are reusable and composable
32+
33+
You can use the same embedded object type in multiple parent object types, and
34+
you can embed objects inside other embedded objects. You can even
35+
recursively reference an embedded object type as an optional property in its
36+
own definition.
37+
38+
.. note:: Realm Uses Cascading Deletes for Embedded Objects
39+
40+
When you delete a Realm object, Realm automatically deletes any
41+
embedded objects referenced by that object. Any objects that your
42+
application must persist after the deletion of their parent object
43+
should use :ref:`relationships <node-client-relationships>`
44+
instead.
45+
46+
Realm Object Models
47+
~~~~~~~~~~~~~~~~~~~
48+
49+
To define an embedded object, set ``embedded``
50+
to ``true``. You can reference an embedded object type from parent object types
51+
in the same way as you would define a relationship:
52+
53+
.. important::
54+
55+
Embedded objects cannot have a :ref:`primary key <node-primary-keys>`.
56+
57+
.. literalinclude:: /examples/generated/node/data-types.codeblock.define-embedded-objects.js
58+
:language: javascript
59+
:emphasize-lines: 3, 18, 28
60+
61+
62+
JSON Schema
63+
~~~~~~~~~~~
64+
65+
.. include:: /includes/embedded-object-json-schema.rst
66+
67+
68+
Read and Write Embedded Objects
69+
-------------------------------
70+
71+
Create an Embedded Object
72+
~~~~~~~~~~~~~~~~~~~~~~~~~
73+
74+
To create an embedded object, assign an instance of the embedded object
75+
to a parent object's property:
76+
77+
.. literalinclude:: /examples/generated/node/data-types.codeblock.create-an-embedded-object.js
78+
:language: javascript
79+
80+
Update an Embedded Object Property
81+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
82+
83+
To update a property in an embedded object, modify the property in a
84+
write transaction:
85+
86+
.. literalinclude:: /examples/generated/node/data-types.codeblock.update-an-embedded-object.js
87+
:language: javascript
88+
89+
90+
Overwrite an Embedded Object
91+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
92+
93+
To overwrite an embedded object, reassign the embedded object property
94+
of a party to a new instance in a write transaction:
95+
96+
.. literalinclude:: /examples/generated/node/data-types.codeblock.overwrite-an-embedded-object.js
97+
:language: javascript
98+
99+
100+
Query a Collection on Embedded Object Properties
101+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
102+
103+
Use dot notation to filter or sort a :ref:`collection
104+
<node-results-collections>` of objects based on an embedded object
105+
property value:
106+
107+
.. include:: /includes/directly-query-embedded-objects-note.rst
108+
109+
.. literalinclude:: /examples/generated/node/data-types.codeblock.query-an-embedded-object.js
110+
:language: javascript
111+
112+
113+
114+
Delete an Embedded Object
115+
~~~~~~~~~~~~~~~~~~~~~~~~~
116+
Realm Uses Cascading Deletes for Embedded Objects. To delete an embedded object,
117+
delete the embedded object's parent.
118+
119+
.. literalinclude:: /examples/generated/node/data-types.codeblock.delete-an-embedded-object.js
120+
:language: javascript

‎source/sdk/node/fundamentals/relationships-and-embedded-objects.txt

Lines changed: 3 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -175,62 +175,6 @@ to :ref:`relationships <node-client-relationships>`, but they provide additional
175175
constraints and map more naturally to the denormalized :manual:`MongoDB document
176176
model </core/data-modeling-introduction/>`.
177177

178-
Realm enforces unique ownership constraints that treat each embedded object as
179-
nested data inside of a single, specific parent object. An embedded object
180-
inherits the lifecycle of its parent object and cannot exist as an independent
181-
Realm object. This means that embedded objects cannot have a primary key and
182-
that Realm automatically deletes embedded objects if their parent object is
183-
deleted.
184-
185-
.. tip:: Embedded object types are reusable and composable
186-
187-
You can use the same embedded object type in multiple parent object types and
188-
you can embed objects inside of other embedded objects. You can even
189-
recursively reference an embedded object type as an optional property in its
190-
own definition.
191-
192-
Realm Object Models
193-
~~~~~~~~~~~~~~~~~~~
194-
195-
To specify that a Realm object model define an embedded object, set ``embedded``
196-
to ``true``. You can reference an embedded object type from parent object types
197-
in the same way as you would define a relationship:
198-
199-
.. code-block:: javascript
200-
:emphasize-lines: 3, 18, 28
201-
202-
const AddressSchema = {
203-
name: "Address",
204-
embedded: true, // default: false
205-
properties: {
206-
street: "string?",
207-
city: "string?",
208-
country: "string?",
209-
postalCode: "string?",
210-
},
211-
};
212-
213-
const ContactSchema = {
214-
name: "Contact",
215-
primaryKey: "_id",
216-
properties: {
217-
_id: "objectId",
218-
name: "string",
219-
address: "Address", // Embed a single object
220-
},
221-
};
222-
223-
const BusinessSchema = {
224-
name: "Business",
225-
primaryKey: "_id",
226-
properties: {
227-
_id: "objectId",
228-
name: "string",
229-
addresses: { type: "list", objectType: "Address" }, // Embed an array of objects
230-
},
231-
};
232-
233-
JSON Schema
234-
~~~~~~~~~~~
235-
236-
.. include:: /includes/embedded-object-json-schema.rst
178+
Learn more about :doc:`Embedded objects
179+
</sdk/node/data-types/embedded-objects>`, including how to read and write
180+
embedded objects.

0 commit comments

Comments
 (0)