Advanced find()#

The find() function can be used to execute database queries in StructrScript and server-side JavaScript environments such as Repeaters.

Usage

find(type, predicates..., options...)
find(type, uuid)
find(type)

Description
This method is one of the most important and frequently used built-in functions. It returns a collection of entities, which can be empty if none of the existing nodes or relationships matches the given search parameters.

find() accepts several different parameter combinations, whereas the first parameter is always the name of the type (a string) to retrieve from the database. The second parameter can either be a UUID (string), a map (e.g. a result from nested function calls), a list of predicates and/or (key, value) pairs or other query options like sort order or pagination controls. See the examples below for an overview of all the possible parameter combinations.

Note
Calling find() with only a single parameter will return all the nodes of the given type (which might be dangerous if there are many of them in the database).

Predicates
The following predicates can be specified. Predicates can be combined and mixed to build complex queries. Some predicates and property keys need to be combined in a different way than others, please refer to the examples below for an overview.

Predicate	Description
and(...)	Logical AND
or(...)	Logical OR
not(...)	Logical NOT
equals(key, value)	Returns only those nodes that match the given (key, value) pair
contains(key, text)	Returns only those nodes whose value contains the given text
empty('key')	Returns only those nodes that don’t have a value set for the given key
range(start, end)	Returns only those nodes that match the given (key, value) pair
range(start, end, withStart, withEnd)	Like range(start, end) above but with flags for the endpoints
range(null, end)	Unbounded range() to emulate “less than”
range(start, null)	Unbounded range() to emulate “greater than”

Options
The following options can be specified:

Option	Description
sort(key)	Sorts the result according to the given property key (ascending)
sort(key, true)	Sorts the result according to the given property key (descending)
page(page, pageSize)	Limnits the result size to pageSize, returning the given page

StructrScript Examples

${find('User')}
=> returns all User entities in the database

${find('User', sort('name'))}
=> returns all User entities in the database, sorted by name

${find('User', sort('name'), page(1, 10)}
=> returns the first 10 User entities in the database, sorted by name

${find('User', 'name', 'admin')}
=> returns all User entities with the name "admin"

${find('User', '7379af469cd645aebe1a3f8d52b105bd')}
=> returns the user entity with the given UUID

${find('User', '7379af469cd645aebe1a3f8d52b105bd')}
=> returns the user entity with the given UUID

${find('User', 'name', contains('e'))}
=> returns all user entities whose name property contains the letter 'e'

${find('User', contains('name', 'e'))}
=> returns all user entities whose name property contains the letter 'e' (same as above)

${find('User', 'age', range(0, 18))}
=> returns all user entities whose age property is between 0 and 18 (inclusive)

${find('User', 'age', range(0, 18, false, false))}
=> returns all user entities whose age property is between 0 and 18 (exclusive)

${find('User', and(equals('name', 'Tester), equals('age', range(0, 18))))}
=> returns all user entities whose name is 'Tester' and whose age is between 0 and 18 (inclusive)

JavaScript Example

${{
    let users = $.find('Project',
        {
            $and: {
                'name1': 'structr',
                'age': $.range(30, 50)
            }
        },
        $.sort('name', true),
        $.page(1, 10)
    );

    return users;
}}