Realtime Cloud Storage

TableRef

class TableRef

Class with the definition of a table reference.

Methods

TableRef asc()

Defines if the items will be retrieved in ascending order.

Sample

// Create a storage reference
var storageRef = Realtime.Storage.create({
	applicationKey: "myApplicationKey",
	authenticationToken: "myAuthenticationToken"
});

// Create a table reference
var tableRef = storageRef.table("myTable");

tableRef.asc().getItems(
	function success(itemSnapshot) {
		console.log(itemSnapshot.val());
	}
);

TableRef beginsWith(Object filter, [function(String message) error])

Applies a filter to the table. When fetched, it will return the items that begins with the filter property value.

Parameters

Object filter

The structure with the filter arguments.

Properties

String item

The name of the property to filter.

String value

The value of the property to filter.

function(String message) error optional

Response if client side validation failed or if an error was returned from the server.

Arguments

String message

The message detailing the error.

Sample

// Create a storage reference
var storageRef = Realtime.Storage.create({
	applicationKey: "myApplicationKey",
	authenticationToken: "myAuthenticationToken"
});

// Create a table reference
var tableRef = storageRef.table("myTable");

// Retrieve all items with property 'itemProperty' value starting with 'xpto'
tableRef.beginsWith({ item: "itemProperty", value: "xpto" } ).getItems(
	function success(itemSnapshot) {
		console.log(itemSnapshot.val());
	}
);

TableRef between(Object filter, [function(String message) error])

Applies a filter to the table. When fetched, it will return the items in range of the filter property value.

Parameters

Object filter

The structure with the filter arguments.

Properties

String item

The name of the property to filter.

Array value

The definition of the interval. Array of numbers (ex: [1, 5]).

function(String message) error optional

Response if client side validation failed or if an error was returned from the server.

Arguments

String message

The message detailing the error.

Sample

// Create a storage reference
var storageRef = Realtime.Storage.create({
	applicationKey: "myApplicationKey",
	authenticationToken: "myAuthenticationToken"
});

// Create a table reference
var tableRef = storageRef.table("myTable");

// Retrieve all items where property 'itemProperty' has a value between 1 and 10
tableRef.between({item: "itemProperty", value: [1, 10] }).getItems(
	function success(itemSnapshot) {
		console.log(itemSnapshot.val());
	}
);

TableRef contains(Object filter, [function(String message) error])

Applies a filter to the table. When fetched, it will return the items that contains the filter property value.

Parameters

Object filter

The structure with the filter arguments.

Properties

String item

The name of the property to filter.

String value

The value of the property to filter.

function(String message) error optional

Response if client side validation failed or if an error was returned from the server.

Arguments

String message

The message detailing the error.

Sample

// Create a storage reference
var storageRef = Realtime.Storage.create({
	applicationKey: "myApplicationKey",
	authenticationToken: "myAuthenticationToken"
});

// Create a table reference
var tableRef = storageRef.table("myTable");

// Retrieve all items where property 'itemProperty' contains the value 'xpto'
tableRef.contains({ item: "itemProperty", value: "xpto" }).getItems(
	function(itemSnapshot) {
		console.log(itemSnapshot.val());
	}
);

TableRef create(Object args, function(Metadata metadata) success, [function(String message) error])

Creates a new table.

Parameters

Object args

Structure with the table properties.

Properties

Number provisionType

The provision type id. Use the ProvisionType object.

Number provisionLoad

The provision load id. Use the ProvisionLoad object. Not mandatory when it is a table with custom provision type.

Key key

The definition of the key for this table. Must contain a primary property. The primary property is also an object that must contain a name and datatype. The table can have a secondary key ( { primary: { name: "id", dataType: "string" }, secondary: { name: "timestamp", dataType: "number" } }).

Throughput throughput optional

The custom provision to apply (ex: throughput: { read: 1, write: 1 }). Required when the provision type is Custom.

function(Metadata metadata) success

Response from the server when the request was completed successfully.

Arguments

Metadata metadata

Information regarding the table structure.

function(String message) error optional

Response if client side validation failed or if an error was returned from the server.

Arguments

String message

The message detailing the error.

Sample

// Create a storage reference
var storageRef = Realtime.Storage.create({
	applicationKey: "myApplicationKey",
	authenticationToken: "myAuthenticationToken"
});

// Create a table reference
var tableRef = storageRef.table("myTable");

// Create table 'myTable' with the following schema
tableRef.create({
	key: {
		primary: { 
			name: "id", 
			dataType: "string"
		}, 
		secondary: { 
			name: "timestamp",
			dataType: "number" 
		}
	},
	provisionLoad: Realtime.Storage.ProvisionLoad.Balanced,
	provisionType: Realtime.Storage.ProvisionType.Light
});

// Create table 'myTable' with the following schema (with custom provisioning)
tableRef.create({
	key: {
		primary: { 
			name: "id", 
			dataType: "string"
		}, 
		secondary: { 
			name: "timestamp",
			dataType: "number" 
		}
	},
	provisionType: Realtime.Storage.ProvisionType.Custom,
	throughput: {
		read: 1,
		write: 1
	}
});

TableRef del(function(Boolean data) success, [function(String message) error])

Delete this table.

Parameters

function(Boolean data) success

Response from the server when the request was completed successfully.

Arguments

Boolean data

Indicates if the table was deleted. If false, no table was found to be deleted.

function(String message) error optional

Response if client side validation failed or if an error was returned from the server.

Arguments

String message

The message detailing the error.

Sample

// Create a storage reference
var storageRef = Realtime.Storage.create({
	applicationKey: "myApplicationKey",
	authenticationToken: "myAuthenticationToken"
});	

// Create a table reference
var tableRef = storageRef.table("myTable");

// Delete table 'myTable'
tableRef.del();

TableRef desc()

Defines if the items will be retrieved in descending order.

Sample

// Create a storage reference
var storageRef = Realtime.Storage.create({
	applicationKey: "myApplicationKey",
	authenticationToken: "myAuthenticationToken"
});

// Create a table reference
var tableRef = storageRef.table("myTable");

tableRef.desc().getItems(
	function success(itemSnapshot) {
		console.log(itemSnapshot.val());
	}
);

TableRef equals(Object filter, [function(String message) error])

Applies a filter to the table. When fetched, it will return the items that match the filter property value.

Parameters

Object filter

The structure with the filter arguments.

Properties

String item

The name of the property to filter.

Object value

The value of the property to filter.

function(String message) error optional

Response if client side validation failed or if an error was returned from the server.

Arguments

String message

The message detailing the error.

Sample

// Create a storage reference
var storageRef = Realtime.Storage.create({
	applicationKey: "myApplicationKey",
	authenticationToken: "myAuthenticationToken"
});

// Create a table reference
var tableRef = storageRef.table("myTable");

// Retrieve all items that have their 'itemProperty' value equal to 'theValue'
tableRef.equals({ item: "itemProperty", value: "theValue" }).getItems(
	function success(itemSnapshot) {
		console.log(itemSnapshot.val());
	}
);

Object[] filters()

Returns a copy of the filters of the referred table.

Sample

// Create a storage reference
var storageRef = Realtime.Storage.create({
	applicationKey: "myApplicationKey",
	authenticationToken: "myAuthenticationToken"
});	

// Create a table reference
var tableRef = storageRef.table("myTable");

// Display all the filters applied to the table
console.log(tableRef.filters());

TableRef getItems(function(ItemSnapshot itemSnapshot) success, [function(String message) error])

Get the items of this tableRef.

Parameters

function(ItemSnapshot itemSnapshot) success

Response from the server when the request was completed successfully. This function will be called for each item retrieved and once more with 'null' value when all items have been processed.

Arguments

ItemSnapshot itemSnapshot

An immutable copy of the retrieved item.

function(String message) error optional

Response if client side validation failed or if an error was returned from the server.

Arguments

String message

The message detailing the error.

Sample

// Create a storage reference
var storageRef = Realtime.Storage.create({
	applicationKey: "myApplicationKey",
	authenticationToken: "myAuthenticationToken"
});

// Create a table reference
var tableRef = storageRef.table("myTable");

// Get all of the table's items
tableRef.getItems(function success(itemSnapshot) {
	console.log(itemSnapshot.val());
});

TableRef greaterEqual(Object filter, [function(String message) error])

Applies a filter to the table. When fetched, it will return the items greater or equal to filter property value.

Parameters

Object filter

The structure with the filter arguments.

Properties

String item

The name of the property to filter.

Object value

The value of the property to filter.

function(String message) error optional

Response if client side validation failed or if an error was returned from the server.

Arguments

String message

The message detailing the error.

Sample

// Create a storage reference
var storageRef = Realtime.Storage.create({
	applicationKey: "myApplicationKey",
	authenticationToken: "myAuthenticationToken"
});

// Create a table reference
var tableRef = storageRef.table("myTable");

// Retrieve all items that have their 'itemProperty' value greater or equal to 10
tableRef.greaterEqual({item: "itemProperty", value: 10 }).getItems(
	function success(itemSnapshot) {
		console.log(itemSnapshot.val());
	}
);

TableRef greaterThan(Object filter, [function(String message) error])

Applies a filter to the table. When fetched, it will return the items greater than the filter property value.

Parameters

Object filter

The structure with the filter arguments.

Properties

String item

The name of the property to filter.

Object value

The value of the property to filter.

function(String message) error optional

Response if client side validation failed or if an error was returned from the server.

Arguments

String message

The message detailing the error.

Sample

// Create a storage reference
var storageRef = Realtime.Storage.create({
	applicationKey: "myApplicationKey",
	authenticationToken: "myAuthenticationToken"
});

//Create a table reference
var tableRef = storageRef.table("myTable");

// Retrieve all items that have their 'itemProperty' greater than 10
tableRef.greaterThan({item: "itemProperty", value: 10 }).getItems(
	function success(itemSnapshot) {
		console.log(itemSnapshot.val());
	}
);

TableRef isNull(Object filter, [function(String message) error])

Applies a filter that, upon retrieval, will have the items that have the selected property with a null value.

Parameters

Object filter

The structure with the filter arguments.

Properties

String item

The name of the item's property.

function(String message) error optional

Response if client side validation failed or if an error was returned from the server.

Arguments

String message

The message detailing the error.

Sample

// Create a storage reference
var storageRef = Realtime.Storage.create({
	applicationKey: "myApplicationKey",
	authenticationToken: "myAuthenticationToken"
});	

// Create a table reference
var tableRef = storageRef.table("myTable");

// Retrieve all items where their 'itemProperty' value is null
tableRef.isNull({item: "itemProperty", value: "theValue" }).getItems(
	function(itemSnapshot) {
		console.log(itemSnapshot.val());
	}
);

ItemRef item(Object key, [function(String message) error])

Creates a new item reference.

Parameters

Object key

Structure with the key properties.

Properties

Object primary

The primary key. Must match the table schema.

Object secondary

The secondary key. Must match the table schema.

function(String message) error optional

Response if client side validation failed or if an error was returned from the server.

Arguments

String message

The message detailing the error.

Sample

// Create a storage reference
var storageRef = Realtime.Storage.create({
	applicationKey: "myApplicationKey",
	authenticationToken: "myAuthenticationToken"
});

// Create a table reference
var tableRef = storageRef.table("myTable");

// Creates an item reference
var itemRef = tableRef.item({ primary: "myId", secondary: 111222333444 });

TableRef lesserEqual(Object filter, [function(String message) error])

Applies a filter to the table. When fetched, it will return the items lesser or equals to the filter property value.

Parameters

Object filter

The structure with the filter arguments.

Properties

String item

The name of the property to filter.

Object value

The value of the property to filter.

function(String message) error optional

Response if client side validation failed or if an error was returned from the server.

Arguments

String message

The message detailing the error.

Sample

// Create a storage reference
var storageRef = Realtime.Storage.create({
	applicationKey: "myApplicationKey",
	authenticationToken: "myAuthenticationToken"
});

//Create a table reference
var tableRef = storageRef.table("myTable");

// Retrieve all items that have their 'itemProperty' value lesser or equal to 10
tableRef.lesserEqual({item: "itemProperty", value: 10 }).getItems(
	function success(itemSnapshot) {
		console.log(itemSnapshot.val());
	}
);

TableRef lesserThan(Object filter, [function(String message) error])

Applies a filter to the table. When fetched, it will return the items lesser than the filter property value.

Parameters

Object filter

The structure with the filter arguments.

Properties

String item

The name of the property to filter.

Object value

The value of the property to filter.

function(String message) error optional

Response if client side validation failed or if an error was returned from the server.

Arguments

String message

The message detailing the error.

Sample

// Create a storage reference
var storageRef = Realtime.Storage.create({
	applicationKey: "myApplicationKey",
	authenticationToken: "myAuthenticationToken"
});

//Create a table reference
var tableRef = storageRef.table("myTable");

// Retrieve all items that have their 'itemProperty' value lesser than 10
tableRef.lesserEqual({item: "itemProperty", value: 10 }).getItems(
	function success(itemSnapshot) {
		console.log(itemSnapshot.val());
	}
);

TableRef limit(Number value, [function(String message) error])

Applies a limit over the number of items a search will return.

Parameters

Number value

The limit to apply.

function(String message) error optional

Response if client side validation failed or if an error was returned from the server.

Arguments

String message

The message detailing the error.

Sample

// Create a storage reference
var storageRef = Realtime.Storage.create({
	applicationKey: "myApplicationKey",
	authenticationToken: "myAuthenticationToken"
});

// Create a table reference
var tableRef = storageRef.table("myTable");

// Retrieves, up to 10, items from table 'myTable'
tableRef.limit(10).getItems(
	function success(itemSnapshot) {
		console.log(itemSnapshot.val());
	}
);

TableRef meta(function(Metadata metadata) success, [function(String message) error])

Contains information about the table, including the current status of the table, the primary key schema and when the table was created.

Parameters

function(Metadata metadata) success

Response from the server when the request was completed successfully.

Arguments

Metadata metadata

Information regarding the table structure.

function(String message) error optional

Response if client side validation failed or if an error was returned from the server.

Arguments

String message

The message detailing the error.

Sample

// Create a storage reference
var storageRef = Realtime.Storage.create({
	applicationKey: "myApplicationKey",
	authenticationToken: "myAuthenticationToken"
});	

// Create a table reference
var tableRef = storageRef.table("myTable");

// Get table metadata
tableRef.meta(function success(metadata) {
	console.log(metadata);
});

String name()

Returns the name of the table.

Sample

// Create a storage reference
var storageRef = Realtime.Storage.create({
	applicationKey: "myApplicationKey",
	authenticationToken: "myAuthenticationToken"
});	

// Create a table reference
var tableRef = storageRef.table("myTable");

// Display the table's name
console.log(tableRef.name());

TableRef notContains(Object filter, [function(String message) error])

Applies a filter to the table. When fetched, it will return the items that does not contains the filter property value.

Parameters

Object filter

The structure with the filter arguments.

Properties

String item

The name of the property to filter.

String value

The value of the property to filter.

function(String message) error optional

Response if client side validation failed or if an error was returned from the server.

Arguments

String message

The message detailing the error.

Sample

// Create a storage reference
var storageRef = Realtime.Storage.create({
	applicationKey: "myApplicationKey",
	authenticationToken: "myAuthenticationToken"
});	

// Create a table reference
var tableRef = storageRef.table("myTable");

// Retrieve all items that don't have in their 'itemProperty' value the word 'theValue'
tableRef.notContains({item: "itemProperty", value: "theValue" }).getItems(
	function success(itemSnapshot) {
		console.log(itemSnapshot.val());
	}
);

TableRef notEquals(Object filter, [function(String message) error])

Applies a filter to the table. When fetched, it will return the items that does not match the filter property value.

Parameters

Object filter

The structure with the filter arguments.

Properties

String item

The name of the property to filter.

Object value

The value of the property to filter.

function(String message) error optional

Response if client side validation failed or if an error was returned from the server.

Arguments

String message

The message detailing the error.

Sample

// Create a storage reference
var storageRef = Realtime.Storage.create({
	applicationKey: "myApplicationKey",
	authenticationToken: "myAuthenticationToken"
});	

// Create a table reference
var tableRef = storageRef.table("myTable");

// Retrieve all items where their 'itemProperty' value is different from 'theValue'
tableRef.notEquals({item: "itemProperty", value: "theValue" }).getItems(
	function(itemSnapshot) {
		console.log(itemSnapshot.val());
	}
);

TableRef notNull(Object filter, [function(String message) error])

Applies a filter that, upon retrieval, will have the items that have the selected property with a value other than null.

Parameters

Object filter

The structure with the filter arguments.

Properties

String item

The name of the item's property.

function(String message) error optional

Response if client side validation failed or if an error was returned from the server.

Arguments

String message

The message detailing the error.

Sample

// Create a storage reference
var storageRef = Realtime.Storage.create({
	applicationKey: "myApplicationKey",
	authenticationToken: "myAuthenticationToken"
});	

// Create a table reference
var tableRef = storageRef.table("myTable");

// Retrieve all items where their 'itemProperty' value is different from null
tableRef.notNull({item: "itemProperty", value: "theValue" }).getItems(
	function(itemSnapshot) {
		console.log(itemSnapshot.val());
	}
);

TableRef off([String eventType], [String primaryKey], [function(ItemSnapshot itemSnapshot) handler], [function(String message) error])

Remove an event handler.

Parameters

String eventType optional

The type of the event to remove. Possible values: put, update, delete. If not specified, it will remove all listeners of this reference.

String primaryKey optional

The primary key of the items to stop listen.

function(ItemSnapshot itemSnapshot) handler optional

A previously attached listener. If not specified, it will remove all listeners of the specified type or all listeners of this reference.

Arguments

ItemSnapshot itemSnapshot

An immutable copy of the modified item.

function(String message) error optional

Response if client side validation failed or if an error was returned from the server.

Arguments

String message

The message detailing the error.

Sample

// Create a storage reference
var storageRef = Realtime.Storage.create({
	applicationKey: "myApplicationKey",
	authenticationToken: "myAuthenticationToken"
});

// Create a table reference
var tableRef = storageRef.table("myTable");

// Define the handler function
var handler = function(itemSnapshot) {
	console.log(itemSnapshot.val());
};

// Add an update listener
tableRef.on("update", handler);

// Stop listening after 5 seconds
setTimeout(function() {
	// Remove the listener
	tableRef.off("update", handler);
}, 5000);

TableRef on(String eventType, [String primaryKey], function(ItemSnapshot itemSnapshot) handler, [function(String message) error])

Attach a listener to run every time the eventType occurs.

Parameters

String eventType

The type of the event to listen. Possible values: put, update, delete.

String primaryKey optional

The primary key of the item(s). Everytime a change occurs to the item(s), the handler is called.

function(ItemSnapshot itemSnapshot) handler

The function to run whenever the notification is received. If the event type is "put", it will immediately trigger a "getItems" to get the initial data and run the callback with each item snapshot as argument.

Arguments

ItemSnapshot itemSnapshot

An immutable copy of the modified item.

function(String message) error optional

Response if client side validation failed or if an error was returned from the server.

Arguments

String message

The message detailing the error.

Sample

// Create a storage reference
var storageRef = Realtime.Storage.create({
	applicationKey: "myApplicationKey",
	authenticationToken: "myAuthenticationToken"
});

// Create a table reference
var tableRef = storageRef.table("myTable");

// Add an update listener
tableRef.on("update", function handler(itemSnapshot) {
	console.log(itemSnapshot.val());
});

TableRef once(String eventType, [String primaryKey], function(ItemSnapshot itemSnapshot) handler, [function(String message) error])

Attach a listener to run only once when event type occurs.

Parameters

String eventType

The type of the event to listen. Possible values: put, update, delete.

String primaryKey optional

The primary key of the item(s). When a change occurs to the item(s), the handler is called once.

function(ItemSnapshot itemSnapshot) handler

The function invoked, only once, when the notification is received. If the event type is "put", it will immediately trigger a "getItems" to get the initial data and run the callback with each item snapshot as argument.

Arguments

ItemSnapshot itemSnapshot

An immutable copy of the modified item.

function(String message) error optional

Response if client side validation failed or if an error was returned from the server.

Arguments

String message

The message detailing the error.

Sample

// Create a storage reference
var storageRef = Realtime.Storage.create({
	applicationKey: "myApplicationKey",
	authenticationToken: "myAuthenticationToken"
});

// Create a table reference
var tableRef = storageRef.table("myTable");

// Add an update listener. Only one notification is received once the item is updated after the listener is set.
tableRef.once("update", function handler(itemSnapshot) {
	console.log(itemSnapshot.val());
});

TableRef push(Object item, function(ItemSnapshot item success, ItemSnapshot item, [function(String message) error])

Adds a new item to the table.

Parameters

Object item

The item to add.

function(ItemSnapshot item success

Response from the server when the request was completed successfully.

ItemSnapshot item

An immutable copy of the inserted item.

function(String message) error optional

Response if client side validation failed or if an error was returned from the server.

Arguments

String message

The message detailing the error.

Sample

// Create a storage reference
var storageRef = Realtime.Storage.create({
	applicationKey: "myApplicationKey",
	authenticationToken: "myAuthenticationToken"
});

// Create a table reference
var tableRef = storageRef.table("myTable");

// Insert the item into table 'myTable'. The item must contain the primary key and secondary key (if part of schema).
tableRef.push({
	id: "myID",
	timestamp: 123456789,
	itemProperty: "myValue"
});

TableRef update(Object args, function(Metadata metadata) success, [function(String message) error])

Updates the provision type of the referenced table.

Parameters

Object args

Structure with the table properties.

Properties

Number provisionType

The new provision type id. Use the ProvisionType object.

Number provisionLoad

The new provision load id. Use the ProvisionLoad object.

Throughput throughput optional

The custom provision to apply (ex: throughput: { read: 1, write: 1 }). Required when the provision type is Custom.

function(Metadata metadata) success

Response from the server when the request was completed successfully.

Arguments

Metadata metadata

Information regarding the table structure.

function(String message) error optional

Response if client side validation failed or if an error was returned from the server.

Arguments

String message

The message detailing the error.

Sample

// Create a storage reference
var storageRef = Realtime.Storage.create({
	applicationKey: "myApplicationKey",
	authenticationToken: "myAuthenticationToken"
});

// Create a table reference
var tableRef = storageRef.table("myTable");

// Update the table's provision type using a defined value
tableRef.update({
	provisionType: Realtime.Storage.ProvisionType.Medium
});

// Update the table's provision load using a defined value
tableRef.update({
	provisionLoad: Realtime.Storage.ProvisionLoad.Write
});

// Update the table's provision type using a custom value
tableRef.update({
	provisionType: Realtime.Storage.provisionType.Custom,
	throughput: {
		read: 1,
		write: 1
	}
});

Objects

Key

Specification of the key structure for table maintenance operations.

Properties

String dataType

Type of the key. The allowed types are String and Number.

String name

The name of the key.

Metadata

Specification of the metadata structure regarding the table schema.

Properties

String applicationKey

Public key of the application's license.

Number creationDate

The date the table was created.

Boolean isActive

Control flag.

Number itemCount

The number of items in the specified table. Recent changes might not be reflected in this value.

Key key

The key schema. Can be a single (primary) or composite (primary and secondary) key.

String name

The name of the table.

ProvisionLoad provisionLoad

The provision load set for the table.

ProvisionType provisionType

The provision type set for the table.

Number size

The total size of the specified table, in bytes. Recent changes might not be reflected in this value.

String status

The current status of the table. Possible values include: "Creating", "Updating", "Deleting", "Active".

Throughput throughput

The read and write capacity units set for the table.

Number updateDate

The date of the last change made to the table schema.

Throughput

Specification of a table read and write operation capacity.

Properties

Number read

Read operations per second of a table.

Number write

Write operations per second of a table.