Application Builder Query API Overview
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.
- 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 thatsubject
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.
- On an entity detail page,
- 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.
- 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
Example
author
entity by word count, and then iterates through each author
and prints an HTML list of their names and word count.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.<!--
-->
.<!-- 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.
- Starting points
- Search request chains
- Association chains
- Refinement (faceting) traversal