Submitting an I2E Query via API

July 30 2013

Your most common usage of the I2E Web Services API is likely to be to automate query execution to generate results.

Queries themselves are always constructed and refined in the I2E client interface; from there they can be saved onto the I2E server ready for batch processing. When running a query automatically you need to provide, as a minimum, two pieces of information: the location of the index and the location of the query.

In this post we won’t worry too much about the index — we’ll assume that the index that the user originally used to create their query is still available — and focus on the query.

As saved by the user, the query contains sufficient information to specify the search itself (keywords, classes, phrases, etc.) as well as controlling the output settings, which will include (among other things) the format of the results (HTML, TSV, XML, etc) along with the ordering of results and selection of columns and highlighting.

When thinking about automating query submission, there are four use cases to consider: submit the query with no modifications; submit the query with modifications to the output settings; submit the query with modifications to the search terms in the query; and submit the query with modifications to both the output settings and the query search terms.

In each case, the query is run automatically by POSTing information (as a query template) about the query (in JSON format)  to the I2E server: the query template also contains information about the index to be searched.

The I2E server will then return some information about the query task including the status of the search and the location of the results.
 

Submit the query with no modifications

It is possible to generate results by simply specifying the original query with no changes and you will therefore be regenerating the results seen by the original user. This is a rare use case but may be useful if a large query is generating many results and will tie up a users license (batch querying uses a separately-licensed capability) for the duration of the search.

In this case, no changes need to be made to the information about the query before it is added to a query template that is POSTed to the I2E server.
 

Submit the query with modifications to the output settings

Another use case is where the output settings themselves are modified as part of the automatic query – so the user may run a quick, limited, search over a few thousand documents and generate results in HTML, but then wish to perform the full search over millions of documents and generate results in TSV for post processing.

In this case, the output settings need to be edited (in JSON) before it is added to a query template that is POSTed to the I2E server. These edits are usually straightforward and are usually either changing one number for another, e.g. changing number of documents to search, or from one string to another, e.g. changing from “html” output to “tsv” output.
 

Submit the query with modifications to the query search terms

For the third use case, the query when run automatically uses different search terms and so will generate different results. The choice of which query items can be changed is under the control of the designer of the original query: this choice is exposed in the smart query interface.

In this case, the smart query settings need to be edited (in JSON) before it is added to a query template that is POSTed to the I2E server. These edits require the most understanding of I2E (and its query notation) and the intent of the query being submitted. However, to start with you can use words or phrases (or lists of both) in your settings: to populate your smart query with a search for a number of pets, you could use [ cat dog "guinea pig" ].

The I2E Query Notation will be covered in more detail in the next blog post.
 

Submit the query with modifications to the output settings and the query search terms

This is probably the most common of the four use cases: a query designer has built a query and that is then “automated” to some way to leverage its power. For example, a query identifies drug side-effects: it could be run in an alerting system where another user specifies particular drugs that they wish to monitor. the choice of drugs is a change to the query search terms and output settings will probably be adjusted to ensure that all results are results and they’re in the correct format, for example.

Because the output settings and the query search terms are independent (they’re in different parts of the JSON), modifications can be independent, too. So in this case, the smart query settings and the output settings need to be edited (in JSON) before it is added to a query template that is POSTed to the I2E server.