You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{+client-database+} only runs a query when you request the
64
+
results of that query. This lazy evaluation enables you to write
65
+
elegant, highly-performant code for handling large data sets and complex
66
+
queries.
67
+
68
+
.. _node-live-collections:
69
+
70
+
Collections are Live
71
+
--------------------
72
+
Like :ref:`live objects <node-live-objects>`, {+service-short+} collections
73
+
are usually **live**:
74
+
75
+
- Live results collections always reflect the current results of the associated query.
76
+
- Live lists always reflect the current state of the relationship on the {+realm+} instance.
77
+
78
+
A collection is **not** live when:
79
+
80
+
- it is a :ref:`results collection <node-realm-results>` that you are iterating through using a :mdn:`for..in <Web/JavaScript/Reference/Statements/for...in>` or :mdn:`for..of <Web/JavaScript/Reference/Statements/for...of>` statement. Both statements will continue to iterate through objects in the collection even if you have deleted or modified the collection's objects to exclude them from the filter that produced the results collection.
81
+
- the collection is a frozen :js-sdk:`Results.snapshot() <Realm.Collection.html#snapshot>`.
82
+
83
+
Combined with :ref:`collection notifications
84
+
<node-change-notifications>`, live collections enable
85
+
reactive code. For example, suppose your view displays the
86
+
results of a query. You can keep a reference to the results
87
+
collection in your view class, then read the results
88
+
collection as needed without having to refresh it or
89
+
validate that it is up-to-date.
90
+
91
+
.. important:: Indexes may change
92
+
93
+
Since results update themselves automatically, do not
94
+
store the positional index of an object in the collection
95
+
or the count of objects in a collection. The stored index
96
+
or count value could be outdated by the time you use
97
+
it.
98
+
99
+
.. _node-working-with-collections:
100
+
101
+
Working With Collections
102
+
------------------------
103
+
104
+
.. _node-limiting-query-results:
105
+
106
+
Limiting Query Results
107
+
~~~~~~~~~~~~~~~~~~~~~~
108
+
As a result of lazy evaluation, you do not need any special
109
+
mechanism to limit query results with {+client-database+}. For example, if
110
+
your query matches thousands of objects, but you only want
111
+
to load the first ten, access only the first ten
112
+
elements of the results collection.
113
+
114
+
.. _node-realm-result-pagination:
115
+
116
+
Pagination
117
+
~~~~~~~~~~
118
+
Thanks to lazy evaluation, the common task of pagination
119
+
becomes quite simple. For example, suppose you have a
120
+
results collection associated with a query that matches
121
+
thousands of objects in your {+realm+}. You display one hundred
122
+
objects per page. To advance to any page, simply access the
123
+
elements of the results collection starting at the index
124
+
that corresponds to the target page.
125
+
126
+
Summary
127
+
-------
128
+
- A {+service-short+} **collection** is a homogenous container of zero
129
+
or more instances of one
130
+
:ref:`{+service-short+} type <node-object-types>`.
131
+
- There are two main kinds of collection: **lists** and **results**.
132
+
Lists define the :ref:`to-many relationships <node-to-many-relationship>`
133
+
of your {+service-short+} types, while results represent the
134
+
lazily-loaded output of a :ref:`read operation <node-realm-database-reads>`.
135
+
- Lazy evaluation of results collections means there is no need to
136
+
design a special query to get limited or paginated results. Perform
137
+
the query and read from the results collection as needed.
138
+
- Data in {+service-short+} is *live*, which means that an object always reflects its most recent saved state.
0 commit comments