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.

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.

The icons in the figure represent the following items:

Starting points
Search request chains
Association chains
Refinement (faceting) traversal

Figure 1. An overview of the search request and search response process for the query API