Interface DataSnapshot

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.

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 = admin.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
  });

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 = admin.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
  });

The exportVal() method is similar to val(), except priority information is included (if available), making it suitable for backing up your data.

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).

example

// 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 = admin.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();
  });
});

example

// 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 = admin.database().ref("users").orderByKey();
query.once("value")
  .then(function(snapshot) {
    snapshot.forEach(function(childSnapshot) {
      var key = childSnapshot.key; // "ada"

      // Cancel enumeration
      return true;
  });
});

Applications need not use priority but can order collections by ordinary properties (see Sorting and filtering data).

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 = admin.database().ref("users/ada");
ref.once("value")
  .then(function(snapshot) {
    var hasName = snapshot.hasChild("name"); // true
    var hasAge = snapshot.hasChild("age"); // false
  });

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).

example

// Assume we have the following data in the Database:
{
  "name": {
    "first": "Ada",
    "last": "Lovelace"
  }
}

var ref = admin.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
  });

example

// Assume we have the following data in the Database:
{
  "name": {
    "first": "Ada",
    "last": "Lovelace"
  }
}

var ref = admin.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
  });

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).

example

// 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"
  });

example

// 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
  });