The Application Builder query API is a Ruby
domain-specific language that you use to search and navigate the Application Builder entity model as you create widgets and endpoints for your
application.
When you create an application using Watson Explorer Application Builder, you
model your data by mapping it to entity types that you can assign properties to, and by
linking related entities with associations. The model that you build is called the
entity model.
The code that you use for the query API comes from the following sources:
- Methods that are built in to Application Builder
- Methods and arguments that take their names from items that you create in your configuration,
such as entity types and associations
- Special objects, such as subject, which represent the topic of the page that
subject is used on. For example:
- On an entity detail page, subject is the entity that the page is about.
- On the search page, subject is the current search object.
The query API is typically used in the following use cases:
- Standard widgets
- For example, you use the query API to select the entities and values that are shown in a table
widget.
- Custom widgets
- For example, you use the query API to build a custom widget that calls a service to analyze and
display data from your entity model.
- Endpoints
- For example, you use the query API to build an endpoint that allows you to access data from your
entity model from outside the Application Builder interface.
In addition to using the query API, when you configure a field that requires custom code, you use
the following languages:
- Ruby and embedded Ruby (ERB) to manipulate and process data that you extract by using the query
API
- Web languages for output, such as HTML, CSS, and JavaScript
For example, you might use the query API to extract a list of entities and Ruby to iterate
through that list of entities, which you show as HTML in a widget.
Example
The following code example uses the query API to create a search request for the top five
instances of the
author entity by word count, and then iterates through each author
and prints an HTML list of their names and word count.
Note: If you have an entity type named
author with a word_count field that is fast-indexed, and a
name field, you can copy and paste this code directly into a custom widget on any
page to see it working and to modify it. Watson Explorer Engine comes
with a search collection called example-appbuilder, which has data in it that you
can use to populate an author entity type.
The code in
bold is part of the query API. The other code is written in Ruby (ERB) and
HTML. Comments are written within HTML comment tags,
<!--
-->.
<!-- build the request: we want 5 authors, sorted by word count -->
<% authors = entity_types("author").sorted_by(field("word_count").
in_descending_order).requesting(5) %>
<ol>
<!-- resolve the request with .each, and make each author from the response available
inside the loop as the variable "author" -->
<% authors.each do |author| %>
<!-- this will happen once for each author -->
<li>
<!-- print the author's "name" and "word_count" fields -->
<!-- I expect each author to have only one name and one word_count value, but field
values always come back as lists, so I grab the first value from the list. If I didn't
use .first, I would see square brackets around the value, which represents an array. -->
<%= author["name"].first %>: <%= author["word_count"].first %>
</li>
<% end %>
</ol>
Diagram
The following figure shows
an overview of the request and response process, which is the main process flow of the query API.
One starting point is to create
a search request that uses the entity_types method. You modify the search request by adding methods
that narrow the scope of entity types that you request. To reach an ending point, you resolve the search request by using methods
that produce a response.
Figure 1. An overview of the search request and search response process for the query API