JSDoc: Class: Query

Constructor

new Query(repo, path, limitopt, startNameopt, endNameopt)

Query constructor

Parameters:

Name	Type	Attributes	Description
`repo`	core.Repo		Repository used to make query
`path`	core.util.Path		Path used to make query
`limit`	Number	<optional>	The number of items to include in this query.
`startName`	String	<optional>
`endName`	String	<optional>

Methods

endAt(nameopt) → {api.Query}

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

Parameters:

Name	Type	Attributes	Description
`name`	String	<optional>	The child name to end at

Version:

2.2+

Returns:

Generated query

Type: api.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(nameopt) → {api.Query}

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

Parameters:

Name	Type	Attributes	Description
`name`	String	<optional>	The child name to match for.

Version:

2.2+

Returns:

Generated query

Type: api.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}

Create Query object to limit number of children

Parameters:

Name	Type	Description
`lim`	Number	Number of items

Version:

2.2+

Returns:

new limited Query object.

Type: api.Query

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(eventTypeopt, callbackopt, contextopt)

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.

Parameters:

Name	Type	Attributes	Description
`eventType`	string \| Array.<string>	<optional>	The type of event to unwatch. It can be either a single value among `value`, `child_added`, `child_changed` or `child_removed`, or a list of values among the same constants. 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("contacts").child("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("contacts").child("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, cancelCallbackopt, contextopt) → {api.Query~watchCallback}

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 or a given set of types of events to watch.

The specified callback may be called initially (when the on method is called) with respect to the data currently stored at this node (depending on the requested event type). And then, it will be called 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.

Parameters:

Name	Type	Attributes	Description
`eventType`	string \| Array.<string>		The type of event to watch. It can be either a single value among `value`, `child_added`, `child_changed` or `child_removed` (see above), or a list of values among the same constants. [comment]: # (or `child_moved`)
`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:

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.

Type: api.Query~watchCallback

Examples

Value

// Get a reference to the "friends" node of the "contacts" application
var ref = new Webcom("contacts").child("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("contacts").child("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("contacts").child("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("contacts").child("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, cancelCallbackopt, contextopt)

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.

Parameters:

Name	Type	Attributes	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("contacts").child("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("contacts").child("friends");

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

pathString() → {String}

Returns the path of the data node represented by this instance of Query.

Version:

2.6.2+

Returns:

The path of this data node, with path levels separated by "/" (slashes)

Type: String

ref() → {Webcom}

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

Returns:

A Webcom reference.

Type: Webcom

Example

// Get a reference to the "friends" data node
var ref = new Webcom("contacts").child("friends");

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

startAt(nameopt) → {api.Query}

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

Parameters:

Name	Type	Attributes	Description
`name`	String	<optional>	The child name to start at

Version:

2.2+

Returns:

Generated query

Type: api.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)

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

Parameters:

Name	Type	Description
`error`	Error	Description of the reason of the event subbscription cancellation.

See:

on(), once() and off()

watchCallback(snapshot, prevChildNameopt)

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

Parameters:

Name	Type	Attributes	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:

on(), once() and off()