You have been redirected from an outdated version of the article. Below is the content available on this topic. To view the old article click here.

find()

Usage

find(type, key, value, key, value, ...)
find(type, key, value)
find(type, map)
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 to retrieve from the database. The second parameter can either be a UUID (string), a map (e.g. a result from nested function calls) or a list of (key, value) pairs. 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).

Note
The find() method will always use exact search, if you are interested in inexact / case-insensitive search, use search().

Examples

${find('User')}
${find('User', 'name', 'admin')}
${find('User', '7379af469cd645aebe1a3f8d52b105bd')}

results in

[7379af469cd645aebe1a3f8d52b105bd, a05c044697d648aefe3ae4589af305bd, 505d0d469cd645aebe1a3f8d52b105bd]
[7379af469cd645aebe1a3f8d52b105bd]

// This is a special case - a UUID was supplied, therefore only a single object is returned instead of a collection
7379af469cd645aebe1a3f8d52b105bd

Search results for "find()"

Advanced find()

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 predicates (key, value pairs) and other query options like sort order or pagination controls. See the examples below for an overview of the possible parameter combinations for an advanced find() query. The simpler usage of the find() function is documented below in the article for find()

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 [, withStart = true [, withEnd = true ]] ) Returns only those nodes where the given propertyKey is in the range between start and end
range(null, end) Unbounded range() to emulate “less than”
range(start, null) Unbounded range() to emulate “greater than”
starts_with(key, prefix) Returns only those nodes whose value for the given key starts with the given prefix
ends_with(key, suffix) Returns only those nodes whose value for the given key ends with the given suffix
within_distance(latitude, longitude, distance) Returns only those nodes that are within distance meters around the given coordinates. The type that is being searched for needs to extend the built-in type Location

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)Limits the result size to pageSize, returning the given page
 
find(type, predicates..., options...)

find()

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 to retrieve from the database. The second parameter can either be a UUID (string), a map (e.g. a result from nested function calls) or a list of (key, value) pairs.

The given query parameters are combined with an AND predicate. For node attributes an exact match is searched for the given value. For remote attribute collections the given search values are combined with an OR predicate (see examples).

find(type [, key1, value1 [, ... ]] )
find(type [, map ])
find(type [, uuid ])

Dynamic Content / Repeater

The find() function is another Structr built-in function, just like capitalize() we used in the page’s title and heading above. The find() function takes as argument the name of a type and returns a collection of all instances of this type.

The result returned by the find() function is not sorted, so in order to get a sorted project list, we need to add the system function sort() which requires two parameters: A a collection and the name of a property to sort by. Modify the function query of the repeater element as follows:

StructrScript

The above example shows the use of three different built-in functions. The find() function executes a database query and returns the result collection. extract() converts the collection of database objects into a collection of strings and join() concatenates the collection of strings into a single string, using the given separator between the elements.

Scripting Migration

Here the $.sort() function is used to sort the nodes fetched via regular find and is not used within the find() function itself. Nothing has to be changed here!