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.11..skip
.skip(n)
Skip the first number of entries of a result set. Useful for paging functionality.
Parameter | Description | Type |
---|---|---|
n | Number of results to skip | Number |
Returns: The collection, excluding the fist n values
Performs table scan: Yes (scans n entries only)
Example:
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:
1.20..dbeq
.dbeq(o)
db object/array reference equality
Tests whether this object/array is the exact same object/array as the parameter, by checking for reference equality in the database. See examples below.
Parameter | Description | Type |
---|---|---|
o | Another object or array | Object/Array |
Returns: true if the same object else false.
Performs table scan: No
Example:
1.21..dbcomp
.dbcomp(o)
db object/array reference comparison
Useful for sorting elements by internal db id/reference.
See examples below.
Parameter | Description | Type |
---|---|---|
o | Another object or array | Object/Array |
Returns: 1 if this id greater than parameter’s id, 0 if equeal, and -1 if less than. Returns -2 if parameter is not db object.
Performs table scan: No
Example:
1.22..dbeach
.dbeach(f,p)
each
Perform the passed function for each element in the collection.
Parameter | Description | Type |
---|---|---|
f | Function to execute on each element. | Function |
p | User passed value. Optional value passed by user to use in the function. | Anytype |
Returns: The original collection.
Performs table scan: Yes