You're viewing the legacy docs. They are deprecated as of May 18, 2016.
These docs are for version 2.4.2 and below of the Javascript SDK. Go to our current docs, or see our Web migration guide.

Version 2.4.2Changelog

DataSnapshot

A DataSnapshot contains data from a Firebase database location. Any time you read data from a Firebase 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 its 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. They cannot be modified and will never change. To modify data, you always use a Firebase reference directly.

Tutorial

A DataSnapshot is passed to your event callbacks attached with on() and once():

var fredRef = new Firebase("https://docs-examples.firebaseio.com/samplechat/users/fred");
fredRef.once("value", function(snapshot) {
  // ...
});

Let's say that your database contains the following data:

{
  "users": {
    "fred" {
      "name": {
        "first": "Fred",
        "last": "Flintstone"
      },
      "age": 53
    }
  }
}

Once you have a snapshot, you can extract its entire contents as a JavaScript object with val():

var fredRef = new Firebase("https://docs-examples.firebaseio.com/samplechat/users/fred");
fredRef.once("value", function(snapshot) {
  var data = snapshot.val();
  // data equals { "name": { "first": "Fred", "last": "Flintstone" }, "age": 53 }
  console.log(data.name.first);  // "Fred"
  console.log(data.age);  // 53
});

To include priority information in the extracted data, you can use exportVal(). For example, say the /users/fred/ node above has a priority of 500. We can grab that priority with the following code:

var fredRef = new Firebase("https://docs-examples.firebaseio.com/samplechat/users/fred");
fredRef.once("value", function(snapshot) {
  var data = snapshot.exportVal();
  // data equals { "name": { "first": "Fred", "last": "Flintstone" }, "age": 53, ".priority": 500 }
  console.log(data[".priority"]);  // 500
});

You can also traverse to a particular child location in the DataSnapshot with child().

var fredRef = new Firebase("https://docs-examples.firebaseio.com/samplechat/users/fred");
fredRef.once("value", function(snapshot) {
  var name = snapshot.child("name").child("first").val();
  console.log(name); // "Fred"
});

You can also enumerate all children in a DataSnapshot with forEach(). Let's assume your Firebase database looks like this:

{
  "messages": {
    "-JqpIO567aKezufthrn8" {
      "uid": "barney",
      "text": "Welcome to Bedrock City!"
    },
    "-JqpIP5tIy-gMbdTmIg7": {
      "uid": "fred",
      "text": "Yabba dabba doo!"
    }
  }
}

We can iterate through every message's data using the following code:

var messagesRef = new Firebase("https://docs-examples.firebaseio.com/samplechat/messages");
messagesRef.once("value", function(allMessagesSnapshot) {
  allMessagesSnapshot.forEach(function(messageSnapshot) {
    // Will be called with a messageSnapshot for each child under the /messages/ node
    var key = messageSnapshot.key();  // e.g. "-JqpIO567aKezufthrn8"
    var uid = messageSnapshot.child("uid").val();  // e.g. "barney"
    var text = messageSnapshot.child("text").val();  // e.g. "Welcome to Bedrock City!"
  });
});

In the example above, you can see how the key() method can be used to grab the key of the node corresponding to the DataSnapshot.

You can learn more about reading data from a DataSnapshot in our guide on retrieving data.