@@ -74,6 +74,9 @@ NS_SWIFT_NAME(SnapshotOptions)
7474 * A `FIRDocumentSnapshot` contains data read from a document in your Firestore database. The data
7575 * can be extracted with the `data` property or by using subscript syntax to access a specific
7676 * field.
77+ *
78+ * For a `FIRDocumentSnapshot` that points to non-existing document, any data access will return
79+ * `nil`. You can use the `exists` property to explicitly verify a documents existence.
7780 */
7881NS_SWIFT_NAME (DocumentSnapshot)
7982@interface FIRDocumentSnapshot : NSObject
@@ -95,50 +98,51 @@ NS_SWIFT_NAME(DocumentSnapshot)
9598@property(nonatomic, strong, readonly) FIRSnapshotMetadata *metadata;
9699
97100/* *
98- * Retrieves all fields in the document as an `NSDictionary`.
101+ * Retrieves all fields in the document as an `NSDictionary`. Returns `nil` if the document doesn't
102+ * exist.
99103 *
100- * Server-provided timestamps that have not yet been set to their final value
101- * will be returned as `NSNull`. You can use `dataWithOptions()` to configure this
102- * behavior.
104+ * Server-provided timestamps that have not yet been set to their final value will be returned as
105+ * `NSNull`. You can use `dataWithOptions()` to configure this behavior.
103106 *
104- * @return An `NSDictionary` containing all fields in the document.
107+ * @return An `NSDictionary` containing all fields in the document or `nil` if the document doesn't
108+ * exist.
105109 */
106- - (NSDictionary <NSString *, id > *)data;
110+ - (nullable NSDictionary <NSString *, id > *)data;
107111
108112/* *
109- * Retrieves all fields in the document as a `Dictionary`.
113+ * Retrieves all fields in the document as a `Dictionary`. Returns `nil` if the document doesn't
114+ * exist.
110115 *
111- * @param options `SnapshotOptions` to configure how data is returned from the
112- * snapshot (e.g. the desired behavior for server timestamps that have not
113- * yet been set to their final value).
114- * @return A `Dictionary` containing all fields in the document .
116+ * @param options `SnapshotOptions` to configure how data is returned from the snapshot (e.g. the
117+ * desired behavior for server timestamps that have not yet been set to their final value).
118+ * @return A `Dictionary` containing all fields in the document or `nil` if the document doesn't
119+ * exist .
115120 */
116- - (NSDictionary <NSString *, id > *)dataWithOptions:(FIRSnapshotOptions *)options;
121+ - (nullable NSDictionary <NSString *, id > *)dataWithOptions:(FIRSnapshotOptions *)options;
117122
118123/* *
119- * Retrieves a specific field from the document.
124+ * Retrieves a specific field from the document. Returns `nil` if the document or the field doesn't
125+ * exist.
120126 *
121- * The timestamps that have not yet been set to their final value
122- * will be returned as `NSNull`. The can use `get(_:options:)` to
123- * configure this behavior.
127+ * The timestamps that have not yet been set to their final value will be returned as `NSNull`. The
128+ * can use `get(_:options:)` to configure this behavior.
124129 *
125130 * @param field The field to retrieve.
126- * @return The value contained in the field or `nil` if the field doesn't exist.
131+ * @return The value contained in the field or `nil` if the document or field doesn't exist.
127132 */
128133- (nullable id )valueForField:(id )field NS_SWIFT_NAME (get(_:));
129134
130135/* *
131- * Retrieves a specific field from the document.
136+ * Retrieves a specific field from the document. Returns `nil` if the document or the field doesn't
137+ * exist.
132138 *
133- * The timestamps that have not yet been set to their final value
134- * will be returned as `NSNull`. The can use `get(_:options:)` to
135- * configure this behavior.
139+ * The timestamps that have not yet been set to their final value will be returned as `NSNull`. The
140+ * can use `get(_:options:)` to configure this behavior.
136141 *
137142 * @param field The field to retrieve.
138- * @param options `SnapshotOptions` to configure how data is returned from the
139- * snapshot (e.g. the desired behavior for server timestamps that have not
140- * yet been set to their final value).
141- * @return The value contained in the field or `nil` if the field doesn't exist.
143+ * @param options `SnapshotOptions` to configure how data is returned from the snapshot (e.g. the
144+ * desired behavior for server timestamps that have not yet been set to their final value).
145+ * @return The value contained in the field or `nil` if the document or field doesn't exist.
142146 */
143147// clang-format off
144148- (nullable id )valueForField:(id )field
@@ -151,10 +155,35 @@ NS_SWIFT_NAME(DocumentSnapshot)
151155 *
152156 * @param key The field to retrieve.
153157 *
154- * @return The value contained in the field or `nil` if the field doesn't exist.
158+ * @return The value contained in the field or `nil` if the document or field doesn't exist.
155159 */
156160- (nullable id )objectForKeyedSubscript:(id )key;
157161
158162@end
159163
164+ /* *
165+ * A `FIRQueryDocumentSnapshot` contains data read from a document in your Firestore database as
166+ * part of a query. The document is guaranteed to exist and its data can be extracted with the
167+ * `data` property or by using subscript syntax to access a specific field.
168+ *
169+ * A `FIRQueryDocumentSnapshot` offers the same API surface as a `FIRDocumentSnapshot`. As
170+ * deleted documents are not returned from queries, its `exists` property will always be true and
171+ * `data:` will never return `nil`.
172+ */
173+ NS_SWIFT_NAME (QueryDocumentSnapshot)
174+ @interface FIRQueryDocumentSnapshot : FIRDocumentSnapshot
175+
176+ /* * */
177+ - (instancetype )init
178+ __attribute__((unavailable(" FIRQueryDocumentSnapshot cannot be created directly."
179+
180+ /* *
181+ * Retrieves all fields in the document as an `NSDictionary`.
182+ *
183+ * @return An `NSDictionary` containing all fields in the document.
184+ */
185+ - (NSDictionary <NSString *, id > *)data;
186+
187+ @end
188+
160189NS_ASSUME_NONNULL_END
0 commit comments