Common Application Builder Query API Examples

Many options are available when building queries with the Application Builder query API. Some common options are listed in this topic.

The following examples are common queries that you might want to perform. Replace values that are italicized with values from your data.

Find a particular entity type

To find an entity type use the following query:

entity_types('entity_name')

To query multiple entity types:

entity_types(['entity_1', 'entity_2'])

Follow an association

To follow an association, you must start from a particular entity type and follow defined associations and aliases. In the following example, the entity type is user, and only the instance, thomas, is queried. The accounts association is configured on the user entity type as an association to the account entity. The contacts association is an association name on the account entity type, from an account entity to a set of contact entities. Each association name returns a collection of entity instances from which specific elements can be retrieved by using the common Ruby enumerable methods. In the following example, the first method is used to retrieve the first entity from the collection.

entity_types('user').where('thomas').first.accounts.first.contacts

Specify a query string

The following example queries the entity type of user with the contents of the subject.query variable:

entity_types('user').where(subject.query)

Note: The subject.query variable represents a dynamic query and is therefore only useful on the search page. It can be replaced in any of the following examples by something that makes sense in the current context of your application such as subject.association_name or subject['field_name'].first

Search against a field

To find fields that contain the specified subject.query:

entity_types('user').where(field('full_name').contains(subject.query))

To find field contents that are an exact match for the query:

Note: When using the is method, the field full_name must be fast-indexed.

entity_types('user').where(field('full_name').is(subject.query))

To find if the field exists:

entity_types('user').where(field('phone_number')).where(subject.query)

Specify a sort

To specify a field to sort by:

entity_types('user').sorted_by(field('full_name').in_descending_order)

To use an XPath to sort:

Note: XPaths are only valid when querying entities created from collection stores and cluster collection stores.

entity_types('account').sorted_by(xpath('string-length($af.title)').in_ascending_order)

Specify the number of results returned

By default, Application Builder requests 10 results for each query. To specify the number of results requested by the query:

entity_types('user').requesting(20)

Restrict the fields that are returned for each result

By default, Application Builder retrieves all fields for each entity that is returned by a query. Selecting specific fields is useful when an entity has a large number of fields, or very large field contents that are not needed.

To return specific fields for an entity:

entity_types('account').selecting_fields(['title', 'status', 'start_date'])

To return specific fields for associated entities:

subject.association_name.where(field('field_name')).selecting_fields(['name'])

Embolden text with the HTML strong tag

The following code adds the strong tag to the text some_text in returned instances of the entity1 entity type:

entity_type("entity1").where("some_text").bold

Generate snippets with search results

The following code adds a snippet field that contains an excerpt from the text in returned instances of the entity1 entity type. After you generate the snippet field, you can retrieve the snippet text from the entity by using the field name, snippet.

entity_type("entity1").generate_snippets

Remove duplicate results

The following code removes duplicate entity instances that are returned for the entity1 entity type:

entity_type("entity1").filter_duplicates

Require that a span of length words must exist

The following code requires that results have a length of at least five words:

.where(words(5))

The following code requires that results have a field_name field with a length of at least five words:

.where(field("field_name").containing(words(5)))

Require that a regex must match text in the entity

The following code requires that text in the entity matches mat and at least one additional character, such as match, math, or mattias. In regex, the period (.) is a wildcard character, and the plus sign (+) means that at least one additional character is required to match. For this example, mat is not a match.

.where(regex("mat.+"))

Use HTML stored in entity fields

When accessing the field name by using brackets [] (for example, subject["field_name"]), the array of fields that is returned is stripped of all tags and extra white space. This functionality means that if, for example, you have a field that contains HTML and you want to interpret that HTML in the Application Builder display, you cannot access the value of that field by using brackets. Instead, to return the value for the field, use the following syntax: subject.field_value("field_name").text_value

For example, if an entity had HTML content in a field named html_content this HTML content could be rendered in a custom widget by using the following ERB code:

<%= raw subject.field_value("html_content").text_value %>

Note: The raw function is used in the preceding example to return HTML that has not been escaped. Without the raw function, escaped HTML is returned.