I2E Querying: License Consumption

February 23 2015

There’s a variety of ways of running searches using I2E but for most purposes, the modes can be simplified to:

  • Search using the I2E Java Client, and
  • Everything else

This distinction is important for users, administrators and developers because access to querying is licensed in the same way. Today’s post will explain the differences between the two modes as well as how to make sure that you’re using your existing capabilities in the most efficient way, with reference to license pools, capabilities and user groups.
 

Querying using the I2E Java Client

If you’re running a search via the I2E Java client, you will have an interactive license pool that has a “Pro Query” capability (for simplicity, I’m ignoring “Express Query” and “Smart Query” capabilities; the description mostly applies to these as well).

In addition to allowing you to run a search, “Pro Query” capability also provides you with uncontested access to the server (unless you log out or your session times out) and the ability to load, create and save queries.

Tasks available for I2E Java client

If two people want to run the I2E Java client at the same time, they will both need to belong to a license pool with a “Pro Query” capability and the sum of those license pools are at least two (e.g. Two named user license pools or 1 concurrent user license pool with two seats).

If that is the case, then both users will be accessing the interface, communicating with the server and, potentially, submitting queries simultaneously. Importantly, all actions are occurring synchronously: the user submits a query, the query runs on the I2E server, results are generated and the results are returned back to the user in the same session.
 

Querying using the I2E Web Services API

Let’s switch to the other mode: “everything else”, which covers any query submission not done with the I2E Java client. An example of this is the Sample Web GUI – a web page that acts like a I2E Smart Query view but is written in JavaScript, HTML and CSS. As the page loads, a lot of information is retrieved from the server, such as Index Trees and Query Trees (in this regard, it is very similar to the I2E Java client) and a session is started.

This session does not need “Pro Query” capability: it simply needs a license to be available in an interactive pool. But if the session does not have “Pro Query” capability, how can you run a query?

Enter “Batch Query”.

“Batch Query” is a capability associated with non-interactive license pools which permits queries to be submitted outside of the I2E Java client. Such queries could be submitted using the Sample Web GUI, the query_submitter.py sample Python code, the “Query Submitter” Pipeline Pilot component and KNIME nodes and (historically) the “i2e batch” command line program, and would be the way that any external application would run a query.

Having “Batch Query” capability is enormously useful: as well as sparing I2E Java client access for query building and running, 24/7 results generation and integration of I2E with other systems, it provides an ability to control query throughput. It transforms query submission from a contentious process: if you have two licenses, only two people can connect and run queries, into a cooperative process: if you have one license, many people/processes can connect and run queries and the queries will be queued: first-in, first-out.

The use of the “Batch Query” capability is handled by the server: if the account that you are connected with is in a group with the capability, then it will automatically be used. Your initial connection and declaration of a license pool should be to an interactive pool, not the license pool with the “Batch Query” capability.

Tasks available to the I2E Web Services API

Managing License Pools and Users

An I2E license usually contains capabilities grouped by license pool (in addition to host-level capabilities like indexing). These pools permit access by one or more user (1 for a Named User; 1 or more for Concurrent Users).

Consider the example of a license containing four license pools:

  • “querying”: contains “Pro Query” capability
  • “admin”: contains “Administration” capability
  • “batch”: contains “Batch Query” capability
  • “wsclient”: contains any capability to allow the user to connect and authenticate with the server to create a session.

​It is then necessary to set-up accounts as follows:

  • To access the I2E Java client, the user would need to be in a group associated with the “querying” license pool.
  • To run queries using the Web Services API, the user would need to be in two groups: one associated with the “wsclient” license pool, and one associated with the “batch” license pool.
     

Summary

A key difference between running queries via the I2E Java client and the I2E Web Services API is that with the API, connection to the server is separated from query submission. This permits developers to submit tasks to the server at any time with the confidence that the tasks will be queued and run in order.

It is also possible to increase the number of batch query tasks that can be run in parallel by increasing the number of seats in that license pool, e.g. having two batch query licenses will allows the first two queries in the queue to run simultaneously. This may be desirable when using real-time (or near real-time) model or require very high throughput of many queries over many indexes.