firebase.database. DataSnapshot
A DataSnapshot
contains data from a Database location.
Any time you read data from the Database, you receive the data as a
DataSnapshot
. A DataSnapshot
is passed to the event callbacks you attach with on()
or once()
. You can extract the contents of the snapshot as a JavaScript object by calling the val()
method. Alternatively, you can traverse into the snapshot by calling child()
to return child snapshots (which you could then call val()
on).
A DataSnapshot
is an efficiently generated, immutable copy of the data at a Database location. It cannot be modified and will never change (to modify data, you always call the set()
method on a Reference
directly).
Properties
key
(string or null)
The key (last part of the path) of the location of this DataSnapshot
.
The last token in a Database location is considered its key. For example, "ada" is the key for the /users/ada/ node. Accessing the key on any
DataSnapshot
will return the key for the location that generated it. However, accessing the key on the root URL of a Database will return null
.
Examples
// Assume we have the following data in the Database:
{
"name": {
"first": "Ada",
"last": "Lovelace"
}
}
var ref = firebase.database().ref("users/ada");
ref.once("value")
.then(function(snapshot) {
var key = snapshot.key; // "ada"
var childKey = snapshot.child("name/last").key; // "last"
});
var rootRef = firebase.database().ref();
rootRef.once("value")
.then(function(snapshot) {
var key = snapshot.key; // null
var childKey = snapshot.child("users/ada").key; // "ada"
});
ref
non-null firebase.database.Reference
The Reference
for the location that generated this DataSnapshot
.
Methods
child
child(path) returns firebase.database.DataSnapshot
Gets another DataSnapshot
for the location at the specified relative path.
Passing a relative path to the child()
method of a DataSnapshot returns another DataSnapshot
for the location at the specified relative path. The relative path can either be a simple child name (for example, "ada")
or a deeper, slash-separated path (for example, "ada/name/first"). If the child location has no data, an empty DataSnapshot
(that is, a DataSnapshot
whose value is null
) is returned.
Parameter |
|
---|---|
path |
string A relative path to the location of child data. |
- Returns
-
non-null firebase.database.DataSnapshot
Example
// Assume we have the following data in the Database:
{
"name": {
"first": "Ada",
"last": "Lovelace"
}
}
// Test for the existence of certain keys within a DataSnapshot
var ref = firebase.database().ref("users/ada");
ref.once("value")
.then(function(snapshot) {
var name = snapshot.child("name").val(); // {first:"Ada",last:"Lovelace"}
var firstName = snapshot.child("name/first").val(); // "Ada"
var lastName = snapshot.child("name").child("last").val(); // "Lovelace"
var age = snapshot.child("age").val(); // null
});
exists
exists() returns boolean
Returns true if this DataSnapshot
contains any data. It is slightly more efficient than using snapshot.val() !== null
.
- Returns
-
boolean
Example
// Assume we have the following data in the Database:
{
"name": {
"first": "Ada",
"last": "Lovelace"
}
}
// Test for the existence of certain keys within a DataSnapshot
var ref = firebase.database().ref("users/ada");
ref.once("value")
.then(function(snapshot) {
var a = snapshot.exists(); // true
var b = snapshot.child("name").exists(); // true
var c = snapshot.child("name/first").exists(); // true
var d = snapshot.child("name/middle").exists(); // false
});
exportVal
exportVal() returns any type
Exports the entire contents of the DataSnapshot as a JavaScript object.
The exportVal()
method is similar to val()
, except priority information is included (if available), making it suitable for backing up your data.
- Returns
-
any type
The DataSnapshot's contents as a JavaScript value (Object, Array, string, number, boolean, ornull
).
forEach
forEach(action) returns boolean
Enumerates the top-level children in the DataSnapshot
.
Because of the way JavaScript objects work, the ordering of data in the JavaScript object returned by val()
is not guaranteed to match the ordering on the server nor the ordering of child_added
events. That is where
forEach()
comes in handy. It guarantees the children of a DataSnapshot
will be iterated in their query order.
If no explicit orderBy*()
method is used, results are returned ordered by key (unless priorities are used, in which case, results are returned by priority).
Parameter |
|
---|---|
action |
function(non-null firebase.database.DataSnapshot) A function that will be called for each child DataSnapshot. The callback can return true to cancel further enumeration. |
- Returns
-
boolean
true if enumeration was canceled due to your callback returning true.
Examples
// Assume we have the following data in the Database:
{
"users": {
"ada": {
"first": "Ada",
"last": "Lovelace"
},
"alan": {
"first": "Alan",
"last": "Turing"
}
}
}
// Loop through users in order with the forEach() method. The callback
// provided to forEach() will be called synchronously with a DataSnapshot
// for each child:
var query = firebase.database().ref("users").orderByKey();
query.once("value")
.then(function(snapshot) {
snapshot.forEach(function(childSnapshot) {
// key will be "ada" the first time and "alan" the second time
var key = childSnapshot.key;
// childData will be the actual contents of the child
var childData = childSnapshot.val();
});
});
// You can cancel the enumeration at any point by having your callback
// function return true. For example, the following code sample will only
// fire the callback function one time:
var query = firebase.database().ref("users").orderByKey();
query.once("value")
.then(function(snapshot) {
snapshot.forEach(function(childSnapshot) {
var key = childSnapshot.key; // "ada"
// Cancel enumeration
return true;
});
});
getPriority
getPriority() returns (string, number, or null)
Gets the priority value of the data in this DataSnapshot
.
Applications need not use priority but can order collections by ordinary properties (see Sorting and filtering data).
- Returns
-
(string, number, or null)
hasChild
hasChild(path) returns boolean
Returns true if the specified child path has (non-null) data.
Parameter |
|
---|---|
path |
string A relative path to the location of a potential child. |
- Returns
-
boolean
true
if data exists at the specified child path; elsefalse
.
Example
// Assume we have the following data in the Database:
{
"name": {
"first": "Ada",
"last": "Lovelace"
}
}
// Determine which child keys in DataSnapshot have data.
var ref = firebase.database().ref("users/ada");
ref.once("value")
.then(function(snapshot) {
var hasName = snapshot.hasChild("name"); // true
var hasAge = snapshot.hasChild("age"); // false
});
hasChildren
hasChildren() returns boolean
Returns whether or not the DataSnapshot
has any non-null
child properties.
You can use hasChildren()
to determine if a DataSnapshot
has any children. If it does, you can enumerate them using forEach()
. If it doesn't, then either this snapshot contains a primitive value (which
can be retrieved with val()
) or it is empty (in which case, val()
will return
null
).
- Returns
-
boolean
true if this snapshot has any children; else false.
Example
// Assume we have the following data in the Database:
{
"name": {
"first": "Ada",
"last": "Lovelace"
}
}
var ref = firebase.database().ref("users/ada");
ref.once("value")
.then(function(snapshot) {
var a = snapshot.hasChildren(); // true
var b = snapshot.child("name").hasChildren(); // true
var c = snapshot.child("name/first").hasChildren(); // false
});
numChildren
numChildren() returns number
Returns the number of child properties of this DataSnapshot
.
- Returns
-
number
Example
// Assume we have the following data in the Database:
{
"name": {
"first": "Ada",
"last": "Lovelace"
}
}
var ref = firebase.database().ref("users/ada");
ref.once("value")
.then(function(snapshot) {
var a = snapshot.numChildren(); // 1 ("name")
var b = snapshot.child("name").numChildren(); // 2 ("first", "last")
var c = snapshot.child("name/first").numChildren(); // 0
});
toJSON
toJSON() returns Object
Returns a JSON-serializable representation of this object.
- Returns
-
nullable Object
A JSON-serializable representation of this object.
val
val() returns any type
Extracts a JavaScript value from a DataSnapshot
.
Depending on the data in a DataSnapshot
, the val()
method may return a scalar type (string, number, or boolean), an array, or an object. It may also return null, indicating that the DataSnapshot
is
empty (contains no data).
- Returns
-
any type
The DataSnapshot's contents as a JavaScript value (Object, Array, string, number, boolean, ornull
).
Examples
// Write and then read back a string from the Database.
ref.set("hello")
.then(function() {
return ref.once("value");
})
.then(function(snapshot) {
var data = snapshot.val(); // data === "hello"
});
// Write and then read back a JavaScript object from the Database.
ref.set({ name: "Ada", age: 36 })
.then(function() {
return ref.once("value");
})
.then(function(snapshot) {
var data = snapshot.val();
// data is { "name": "Ada", "age": 36 }
// data.name === "Ada"
// data.age === 36
});