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 theuser
entity type as an association to the account entity. The contacts association is an association name on the account entity type, from anaccount
entity to a set ofcontact
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, thefirst
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 thesubject.query
variable:entity_types('user').where(subject.query)
Note: Thesubject.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 assubject.association_name
orsubject['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 theis
method, the fieldfull_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 textsome_text
in returned instances of theentity1
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 theentity1
entity type. After you generate thesnippet
field, you can retrieve thesnippet
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 afield_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 asmatch
,math
, ormattias
. 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 namedhtml_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: Theraw
function is used in the preceding example to return HTML that has not been escaped. Without theraw
function, escaped HTML is returned.