Query Functions

Query functions are predefined functions that are available on all collections in the database (Objects and Arrays). Query functions supply query functionality not supported by querying data using the normal javascript accessors, which can only select individual values from collections by key.

Some query functions are direct, in that they use the keys index of the store, and do not do a table scan.
Other Query Functions may perform a table scan. Query functions can be chained. Chaining query functions will result in both query functions applying. Combining a scanning query function with a direct query function will only scan the result set limited by the direct function.

1.Query Function Reference

Below is a reference of the current query functions. The list is still evolving.

1.1..rge

.rge(key)
Range greater or equal: Limits the collection to values having keys greater than or equal to the parameter. For objects that is key alphanumerically, and for arrays, index numerically. The parameter does not have to be an existing key.

Parameter Description Type
key The key value String or Number

Returns: The source result set limited to only values of the collection with keys greater than or equal to the given parameter.
Performs table scan: No

Example:

1.2..rgt

.rgt(key)
Range greater than: Limits the collection to values having keys greater than to the parameter. For objects that is key alphanumerically, and for arrays, index numerically. The parameter does not have to be an existing key.

Parameter Description Type
key The key value String or Number

Returns: The source result set limited to only values of the collection with keys greater than to the given parameter.
Performs table scan: No

1.3..rle

.rle(key)
Range less than or equal: Limits the collection to values having keys less than or equal to the parameter. For objects that is key alphanumerically, and for arrays, index numerically. The parameter does not have to be an existing key.

Parameter Description Type
key The key value String or Number

Returns: The source result set limited to only values of the collection with keys less than or equal to the given parameter.
Performs table scan: No

1.4..rlt

.rlt(key)
Range less or than: Limits the collection to values having keys less than the parameter. For objects that is key alphanumerically, and for arrays, index numerically. The parameter does not have to be an existing key.

Parameter Description Type
key The key value String or Number

Returns: The source result set limited to only values of the collection with keys less than or the given parameter.
Performs table scan: No

1.5..kge

.kge(key)
Key greater or equal: Returns the first key in the collection greater than or equal to the given key. For objects that is key alphanumerically, and for arrays, index numerically. The parameter does not have to be an existing key.

Parameter Description Type
key The key value String or Number

Returns: The value of the first key in the collection greater than or equal to the given parameter
Performs table scan: No

Example:

1.6..kgt

.kgt(key)
Key greater than: Returns the first key in the collection greater than the given key. For objects that is key alphanumerically, and for arrays, index numerically. The parameter does not have to be an existing key.

Parameter Description Type
key The key value String or Number

Returns: The value of the first key in the collection greater than the given parameter
Performs table scan: No

1.7..select

.select(f)
select
Formats the result in a desired shape, as specified by the return value of the function parameter.
The select function parameter will be passed the object on which it is called. Note that it returns a new unbound object, thus no further query functions can be chained after select.
See examples below.

Parameter Description Type
f Select function. Function

Returns: The return value of the select function.
Performs table scan: No

Example:

1.8..where

.where(f)
Filters the collection based on the filter function provided. The function will iterate over the collection and execute the filter function on each entry. The filter function will be passed two parameters, firstly the key (k), and secondly the collection (o) that where is called on. So the key is available in the function as k, and the value as o[k]. See examples below.

Parameter Description Type
f Filter function. Function

Returns: The collection containing only the values that passes the query function, that is, for which the query function returns true.
Performs table scan: Yes

Example:

1.9..asc

.asc(f)
Sort ascending.
Orders the values in the collection based on the order function provided, or if no parameter is provided, sorts ascending according to key. (Note that by default, collections are already sorted by by key ascending, unless previously reordered.) The function will be used to insert the element in the correct position in the result set. The filter function will be passed three parameters, the first key (k1), the second key, (k2), and lastly the collection (o) that the function is called on is called on. The function returns a positive number if the first is greater then the second, or a negative number if it is less, or zero if equal. See examples below.

Parameter Description Type
f Filter function. Function

Returns: The collection sorted ascending according to the query function.
Performs table scan: Yes

Example:

1.10..desc

.desc(f)
Sort descending.
Orders the values in the collection based on the order function provided, or if no parameter is provided, sorts descending according to key. (Note that by default, collections are sorted by by key ascending.) The function will be used to insert the element in the correct position in the result set. The filter function will be passed three parameters, the first key (k1), the second key, (k2), and lastly the collection (o) that the function is called on is called on. The function returns a positive number if the first is greater then the second, or a negative number if it is less, or zero if equal.

Parameter Description Type
f Filter function. Function

Returns: The collection sorted ascending according to the query function.
Performs table scan: Yes

1.12..limit

.limit(n)
limit the number of entries returned to the first n entries of a result set. Useful for paging functionality.

Parameter Description Type
n Number of results to limit to Number

Returns: The the first n values of the collection.
Performs table scan: Yes (scans n entries only)

Example:

1.13..count

.count()
counts the entries in the result set.

Returns: The number of entries in the reslt set.
Performs table scan: Yes

1.14..dbmap

.dbmap(f)
map
Performs a mapping of each entry in the result set, and returns an array containing the return values of the mapping function for each entry in the result set The mapping function will be passed two parameters, firstly the key (k), and secondly the collection (o) that where is called on. So the key is available in the function as k, and the value as o[k]. See examples below.

Parameter Description Type
f Maping function. Function

Returns: An Array containing the return values of the mapping function for each entry in the result set
Performs table scan: Yes

Example:

1.15..dbreduce

.dbreduce(f)
reduce
Reduces the result set to a single value, by sequentially running the accumulation function on each value.
The accumulation function will be passed three parameters, firstly the key (k), secondly the collection (o) that where is called on, and lastly the current accumulation value (v), that is the value returned by the previous accumulator function call, or undefined for the first element. See examples below.

Parameter Description Type
f Maping function. Function

Returns: The accumulation value reached by runnnig the accumulation function on each value in the result set. Could be of any type (String/Number/Object/Array…), depending on accumulation function.
Performs table scan: Yes

Example:

1.16..kat

.kat(n)
key at
Returns the key at position n in the result set.

Parameter Description Type
n Zero based position of key to return Number

Returns: The value of key at position n in the result set.
Performs table scan: Yes (scans n entries)

Example:

1.17..vat

.vat(n)
value at
Returns the value at position n in the result set.

Parameter Description Type
n Zero based position of value to return Number

Returns: The value at position n in the result set.
Performs table scan: Yes (scans n entries)

Example:

1.18..tobj

.tobj()
to object
Returns an array collection as an object collection. This is useful if the actual key index values are needed. Normally arrays are always returned as non sparse arrays, and so the key indexes are not necessarily preserved in the resultset if the resultset is a sparse Array. Add .tobj anywhere in the query chain will cause the resultset to take object form. See example below

Returns: The result set in object form
Performs table scan: No

Example:

1.19..dbsetter

.dbsetter(f)
Specify setter for a collection.
When a setter function is specified for a collection (object or array), then the function will be called whenever a property is assigned on the object, and the return value will be used as the value to which the property is assigned. The magic property .dbsetter must be assigned a function that takes 3 parameters, firstly the property key (k), secondly the value that is being assigned (v), and lastly the optional collection (o). The .dbsetter magic property will be hidden and will not be enumerated if the collection is iterated or queried, but it’s value can be viewed if referred to directly. A setter is useful to enforce schema or constrain or validate the type of value that may be added to a collection, or to modify the value, or perform any other action, like updating another associated collection (for example reciprocal links in graph db), or to prevent duplicates, etc. If the value is not valid the setter function should throw an exception, which will make the property assignment fail. Be very careful to not assign the same property within the setter, because that will cause the setter to be called from the setter, which will cause a loop. Also be aware that returning nothing from the function will result in undefined being assigned, which will cause the value associated with the key to be deleted!
See examples below.

Parameter Description Type
f Setter function. Function

Performs table scan: No

Example: