Performing a Class Match using the API

June 25 2014

Part of the I2E Enterprise installation is the Sample Web GUI — a Smart Query interface written as a web application that allows users to run smart queries using only their browser.

The Smart Query interface

A neat trick that it performs is on-the-fly class matching: start typing in a word and the server starts to suggest terms in your dictionary that would match. So a search for “psor” will suggest Psoriasis, Psoriatic Arthritis, etc.

Accepting the suggestion will then populate the search with that class rather than the word. The autosuggestion, dropdowns and tooltips are very nice from the user experience perspective, but today’s post will concentrate on the class match itself – how can a search for “psoriasis” retrieve a class match?

There is a two-part answer to that question – the first part is quite easy to answer and the second part is (only slightly) more complicated. So, let’s start with the first part.

Using the query parameters “search”, “pt” or “synonym”

Class matching is a synchronous operation in I2E that uses a query parameter to specify the input and returns the matches as a list/array of classes. Because of this, it’s something that you can try very simply with your web browser. The general form of the URL is (omitting the protocol, servername and port information for brevity):

/api;type=class/pathto/myindex/?search=psoriasis

The query parameter “search” will search in both Preferred Terms and Synonyms: to restrict to one or other, replace “search” with “pt” or “synonym” respectively:

/api;type=class/pathto/myindex/?pt=psoriasis
/api;type=class/pathto/myindex/?synonym=psoriasis

There are lots of other query parameters that can be used with class matching. Together, these allow you to make requests that reproduce what can be searched for in the Class Chooser (including Substructure and Similarity searches with SMARTS). For more details, consult the I2E Manual or contact us.

OK, so the class matching is pretty straightforward: specify a resource with a query parameter and wait for the response. We’ve covered the query parameter in this first part; the appropriate resource is the second part.
 

Selecting the Appropriate Resource

One thing that may strike you as odd in the example shown above is the resource type is “class” but the path is for an index: why is that? Well, consider a class match in the I2E client interface: you cannot open the Class Chooser until you’ve got an index open. In a sense, classes only exists within indexes: they form an integral part of each index.

(As an aside, once you have understood that, it actually makes the distinction between type=ontology and type=class clearer: an Ontology is the resource that is input to indexing; a Class is the same information when part of that index.)

Then what is the resource needed for the class search? Working forwards from opening a published index, the two steps are as follows:

  1. GET the handle of type=published_index to find type=index. Note that this is similar to how to get the Saved Query type from Published Query type outlined in a previous post.
  2. Replace “type=index” with “type=class” to switch resource type.