Class: Query

Query

Query sort and filters data at a Webcom location.

Can order and restrict data to a smallest subset.

Queries can be chained easily with filter functions. They return query objects.

Methods

endAt (name)

api/Query.js, line 452

Creates a Query object that returns children beginning at a specific ending point.

Name Type Description
name String optional

The child name to end at

Versions
  • ≥ 2.2

Returns:
Type Description
api.Query
  • Generated query
Example
// Get a reference to friends
var ref = new Webcom("/base/contacts/friends");

// Display friends whoses names (keys) come before john
ref.endAt("john").on("value", function(snapshot){
     console.log(snapshot.val());
});

equalTo (name)

api/Query.js, line 477

Creates a Query object that returns children matching a specific value.

Name Type Description
name String optional

The child name to match for.

Versions
  • ≥ 2.2

Returns:
Type Description
api.Query
  • Generated query
Example
// Get a reference to friends
var ref = new Webcom("/base/contacts/friends");

// Display friends whoses names (keys) is exactly john
ref.equalTo("john").on("value", function(snapshot){
     console.log(snapshot.val());
});

limit (lim)

api/Query.js, line 375

Create Query object to limit number of children

Name Type Description
lim Number

Number of items

Versions
  • ≥ 2.2

Returns:
Type Description
api.Query
  • new limited Query object.
Examples

Last

// Get a reference to friends
var ref = new Webcom("/base/contacts/friends");

var lastfriends = ref.endAt().limit(5);
// Display the 5 last friends
lastfriends.on("value", function(snapshot){
     console.log(snapshot.val());
});

First

// Get a reference to friends
var ref = new Webcom("/base/contacts/friends");

var lastfriends = ref.startAt().limit(5);
// Display the 5 first friends
lastfriends.on("value", function(snapshot){
     console.log(snapshot.val());
});

First starting at some key

// Get a reference to friends
var ref = new Webcom("/base/contacts/friends");

var lastfriends = ref.startAt("john").limit(5);
// Display friends whoses names (keys) come after john display the following 5
lastfriends.on("value", function(snapshot){
     console.log(snapshot.val());
});

off (eventType, callback, context)

api/Query.js, line 243

Unwatches data changes at the data node referred to by this Query instance.

It actually unregisters a callback function (or all ones) previously registered on the data node referred to by this Query instance using the on() method.

Note: unregistering all callback functions attached to a data node doesn't unregister callback functions attached to its child nodes. The off() method must be called on all the data nodes that the on() method has been called on.

Name Type Description
eventType String optional

The type of event to unwatch. It can be either value, child_added, child_changed or child_removed.
If not specified, all callbacks previously registered on the data node are unregistered.

callback api.Query~watchCallback optional

Reference to the callback function to unregister (previously passed to or returned by the on() method).
If not set, all callbacks of type eventType previously registered on the data node are unregistered.

context Object optional

Context object for callback binding, passed to previous call to on().

Examples

Unregister a single callback

// Get a reference to the "friends" node of the "contacts" application
var ref = new Webcom("[[baseUrl]]/base/contacts/friends");

var onChange = ref.on("value", function(snapshot) {
  // your handler
});

// later...
ref.off("value", onChange);

Unregister several callbacks

// Get a reference to the "friends" node of the "contacts" application
var ref = new Webcom("[[baseUrl]]/base/contacts/friends");

var onChanged = function(snapshot) {
  // your first handler
});
var onAdded = function(snapshot) {
  // your second handler
});

ref.on("value", onChanged);
ref.on("child_added", onAdded);

// later...

// Unregister all callback functions from ref...
ref.off();
// ...or all callback function associated to a specific kind of event
ref.off("value"); // onChanged is unregistered while onAdded remains registered

on (eventType, callback, cancelCallback, context)

api/Query.js, line 105

Watches data changes at the data node referred to by this Query instance.

It actually registers a callback function on the data node referred to by this Query instance for a given type of event to watch.

The specified callback will be called initially once (when the on method is called) with the data stored at this node, and then whenever the data change. The notifications can be stopped using the off() method.
Several kinds of callback are available depending on the kind of event to watch:

  • value event

    The callback is called initially once with the current data.
    It is then called again each time the data (stored a this node or any sub-node) change.

    The DataSnapshot passed to the callback refers to the new data stored at the data node referred to by this Query instance.
    The prevChildName argument passed to the callback is not used and remains undefined.

  • child_added event

    The callback is called initially once for each current child node of this node.
    It is then called again each time a new data child is added to this node.

    The DataSnapshot passed to the callback refers to the new data stored at the corresponding child data node.
    The prevChildName argument passed to the callback refers to the name of the sibling child node that precedes the added child node in the data tree structure (following key order), or null if the added child node is the first child of the data node referred to by this Query instance.

  • child_changed event

    The callback is not initially called.
    It is then called each time the value of one of the data children changes (excluding child additions and removals).

    The DataSnapshot passed to the callback refers to the new data stored at the corresponding child data node.
    The prevChildName argument passed to the callback refers to the name of the sibling child node that precedes the changed child node in the data tree structure (following key order), or null if the changed child node is the first child of the data node referred to by this Query instance.

  • child_removed event

    The callback is not initially called.
    It is then called each time one of the data children is removed (or its value becomes null or it loses all of its children).

    The DataSnapshot passed to the callback refers to the old data stored at the corresponding child data node.
    The prevChildName argument passed to the callback is not used and remains undefined.

Note: data is first synchronized locally, so that if you set (using the set() method) some data locally after registering a watch callback, this callback will be called immediately. Later, when the synchronization with the server occurs, the callback will be possibly called again for data update, or even for data deletion if the synchronization fails.

Name Type Description
eventType String

The type of event to watch. It can be either value, child_added, child_changed or child_removed (see above).

callback api.Query~watchCallback

Callback function called when the specified event occurs (see above).

cancelCallback api.Query~cancelCallback optional

Callback function called when the authenticated user loses read permission at the data node referred to by this Query instance. In this case, the watch callback function is automatically unregistered and will no longer be called.

context Object optional

Context object for callback binding

Returns:
Type Description
api.Query~watchCallback A reference to the callback function provided in the callback parameter. It is intended to be passed to the off() method, especially when the callback parameter is given as an inline function.
Examples

Value

// Get a reference to the "friends" node of the "contacts" application
var ref = new Webcom("[[baseUrl]]/base/contacts/friends");

// This callback is called only when some data change under the "friends" node
ref.on("value", function(snapshot) {
  console.log("New friends value is: " + JSON.stringify(snapshot.val()));
});

Child Added

// Get a reference to the "friends" node of the "contacts" application
var ref = new Webcom("[[baseUrl]]/base/contacts/friends");

// This callback is called only when a new child is added to the "friends" node
ref.on("child_added", function(snapshot, prevChildName) {
  console.log("New child for friends: " + snapshot.name() + " -> " + JSON.stringify(snapshot.val()));
  if (prevChildName) {
    console.log("This new child comes after " + prevChildName);
  } else {
    console.log("This new child is the only one");
  }
});

Child Changed

// Get a reference to the "friends" node of the "contacts" application
var ref = new Webcom("[[baseUrl]]/base/contacts/friends");

// This callback is called only when the value of an existing child of the "friends" node changes
ref.on("child_changed", function(snapshot, prevChildName) {
  console.log("The " + snapshot.name() + " child has changed value to: " + JSON.stringify(snapshot.val()));
  if (prevChildName) {
    console.log("This child comes after " + prevChildName);
  } else {
    console.log("This child is the only one");
  }
});

Child Removed

// Get a reference to the "friends" node of the "contacts" application
var ref = new Webcom("[[baseUrl]]/base/contacts/friends");

// This callback is called only when a child of the "friends" node is removed
ref.on("child_removed", function(snapshot) {
  console.log("The " + snapshot.name() + " child has been removed, its value was: " + JSON.stringify(snapshot.val()));
});

once (eventType, callback, cancelCallback, context)

api/Query.js, line 311

Watches the next data change at the data node referred to by this Query instance.

This method is similar to on(), except it automatically unregisters the given callback function from the data node referred to by this Query instance as soon as it is called. In other words, the given callback function will be called no more than once.

With the value event type, this method makes it possible to read (asynchronously) the data stored at a given data node.

Name Type Description
eventType String

The type of event to watch. It can be either value, child_added, child_changed or child_removed (see on()).

callback api.Query~watchCallback

Callback function called when the specified event occurs.

cancelCallback api.Query~cancelCallback optional

Callback function called when the authenticated user loses read permission at the data node referred to by this Query instance. In this case, the watch callback function is automatically unregistered and will no longer be called.

context Object optional

Context object for callback binding

Examples
// Get a reference to the "friends" node of the "contacts" application
var ref = new Webcom("[[baseUrl]]/base/contacts/friends");

// Read the value of the "friends" node
ref.once("value", function(snapshot) {
  console.log("The value of the " + snapshot.name() + " node is: " + JSON.stringify(snapshot.val()));
});
// Get a reference to the "friends" node of the "contacts" application
var ref = new Webcom("[[baseUrl]]/base/contacts/friends");

// Check the read permission on the "friends" node
ref.once("value", function() {}, function(error) {
  console.log("Insufficient read permission");
});

ref (){Webcom}

api/Query.js, line 83

Returns a Webcom reference associated to the data node referred to by this Query instance.

Returns:
Type Description
Webcom A Webcom reference.
Example
// Get a reference to the "friends" data node
var ref = new Webcom("[[baseUrl]]/base/contacts/friends");

var query = ref.limit(2);
var refSameLocation = query.ref(); //ref === refSameLocation

startAt (name)

api/Query.js, line 424

Creates Query object that returns children beginning at a specific starting point.

Name Type Description
name String optional

The child name to start at

Versions
  • ≥ 2.2

Returns:
Type Description
api.Query
  • Generated query
Example
// Get a reference to friends
var ref = new Webcom("/base/contacts/friends");

// Display friends whoses names (keys) come after john
ref.startAt("john").on("value", function(snapshot){
     console.log(snapshot.val());
});

Type Definitions

cancelCallback (error)

api/Query.js, line 585

A callback function to fire when an event subscription must be cancelled because of permission loss.

Name Type Description
error Error

Description of the reason of the event subbscription cancellation.

See:

watchCallback (snapshot, prevChildName)

api/Query.js, line 594

A callback function to fire when a data watching event occurs.

Name Type Description
snapshot api.DataSnapshot

Snapshot data corresponding to the event.

prevChildName String | null optional

Name of the previous sibling child depending on key order, or null for an only child.
This parameter is valued only for the child_added and child_changed events, otherwise it remains undefined.

See: