Tutorial: Browse data

Before doing any operation on a [[service]] database, you need a Webcom reference, which provides a pointer to a location or a data node inside your database tree. When creating a new Webcom reference, it points to the root node of the specified [[service]] application:

var sampleChatRef = new Webcom('samplechat');

Webcom sampleChatRef = new Webcom(new WebcomApp("samplechat"));

var sampleChatRef: WCWebcom = WCWebcom(url: "[[baseUrl]]/base/samplechat")!

Creating a Webcom reference is an extremely light-weight operation, so you can create as many as you like without worrying about wasting bandwidth or memory.

Webcom references then come with a couple of methods to easily navigate through the tree-like structure of the data.

child() method

First, each reference provides a function that takes the relative path to a child and returns a reference pointing to this child node

var childRef = sampleChatRef.child('users');

Webcom childRef = sampleChatRef.child("users");

var childRef : WCWebcom =  sampleChatRef.child("users")!
// This is equivalent to:
var childRef: WCWebcom = WCWebcom(url: "[[baseUrl]]/base/samplechat/users")!

The child() method accept several path segments separated by slashes (/), as well as usual "." and ".." segments to browse relatively within the data tree hierarchy:

var otherRef = sampleChatRef.child('users/mary/../john');

Webcom otherRef = sampleChatRef.child("users/mary/../john");

var otherRef : WCWebcom =  sampleChatRef.child("users/mary/../john")!

Management of large child counts

In order to work around width limitations, which limit the number of children of data nodes, the child() method also support special hashed path segments. A hashed segment starts with the hash (or sharp) character (#) and is substituted with a uniformly distributed set of 4 path segments. These sub segments are automatically built from the 6 first digits of the base64 representation of the SHA-1 of the path segment to hash, followed by the path segment to hash itself:

var hashedRef = sampleChatRef.child('users/#mary');
// is the same as
var hashedRef = sampleChatRef.child('users/Vm/Uz/G5/mary');

Webcom hashedRef = sampleChatRef.child("users/#mary");
// is the same as
Webcom hashedRef = sampleChatRef.child("users/Vm/Uz/G5/mary");

var hashedRef : WCWebcom =  sampleChatRef.child("users/#mary")!
// is the same as
var hashedRef : WCWebcom =  sampleChatRef.child("users/Vm/Uz/G5/mary")!

In this way, a hashed path segment makes it possible to manage up to 68,719,476,736 virtual children (actually 4096 children, which have each 4096 children, which have each 4096 children) for a given data node.
Caution! the overall data attached to such a node with a large number of virtual children is nonetheless submitted to the weigth limitations and can generally not be read in one bulk. Instead each (virtual) child node will have to be read separately.

parent() method

Second, each reference provides a function that returns a reference to its parent node, or null if the reference already points to the data root node.

var parentRef = childRef.parent();
// parentRef and sampleChatRef now point to the same node.

Webcom parentRef = childRef.parent();
// parentRef and sampleChatRef now point to the same node.

var parentRef: WCWebcom = childRef.parent!
// parentRef and sampleChatRef now point to the same node.

Examples

Here are several ways of creating a reference that points to the same [[service]] data node.

var usersRef = sampleChatRef.child('users');
var fredRef = usersRef.child('fred');
// is equivalent to:
var fredRef = sampleChatRef.child('users/fred');

var messageListRef = fredRef.parent().parent().child('message_list');
// is equivalent to:
var messageListRef = new Webcom('samplechat').child('message_list');
var messageListRef = fredRef.child('../../message_list');

Webcom usersRef = sampleChatRef.child("users");
Webcom fredRef = usersRef.child("fred");
// is equivalent to:
Webcom fredRef = sampleChatRef.child("users/fred");

Webcom messageListRef = fredRef.parent().parent().child("message_list");
// is equivalent to:
Webcom messageListRef = new Webcom(new WebcomApp("samplechat")).child("message_list");
Webcom messageListRef = fredRef.child("../../message_list");

var usersRef : WCWebcom =  sampleChatRef.child("users")!
var fredRef : WCWebcom =  usersRef.child("fred")!
// is equivalent to:
var fredRef: WCWebcom = sampleChatRef.child("users/fred")!

var messageListRef : WCWebcom = fredRef.parent.parent.child("message_List")!
// is equivalent to:
var messageListRef : WCWebcom = WCWebcom(url:"[[baseUrl]]/base/samplechat/message_list")!
var messageListRef : WCWebcom = fredRef.child("../../message_List")!

Note that the behaviors of the child and parent methods differ when applied on the reference pointing to the data root node:

sampleChatRef.child('..');
// => returns sampleChatRef
sampleChatRef.parent();
// => returns null

sampleChatRef.child("..");
// => returns sampleChatRef
sampleChatRef.parent();
// => returns null

sampleChatRef.child("..")!
// => returns sampleChatRet
sampleChatRef.parent
// => returns nil

Once you have a Webcom reference, you can use it to write, read and query the corresponding data node within your data tree using the other Webcom API functions.