Inquire client

Introduction

Teneo Inquire exposes a public Rest API that can be used to perform queries and manage log data. To this extent, a Groovy client is distributed to facilitate the integration of other components. This client makes use of the Inquire Client Java API, whose JavaDocs are also distributed with the package.

This section is aimed at developers who want to connect their services with the Inquire API. It describes the basic use of the Groovy Client and provides code examples of all its features.

Java documentation is directly provided through the JavaDoc or access the Inquire REST API for details on the endpoints which can be called in order to interact with Teneo Inquire for querying session logs and other functions..

swagger/teneo-inquire/client/index.html provides the jar files and dependency list for the Inquire client.

Groovy Client

Requirements

Teneo Inquire includes Java and Groovy clients that allow interacting with the Teneo Inquire server. Both clients include methods for querying the "query" server using TQL as well as executing other querying related operations such as the creation of Augmenters or saving partial results. The Java client includes methods for interacting with the "importer" server as well, i.e., managing LDS and keyspace data.

The requirements for running the Teneo Inquire API Clients are:

A Teneo Inquire environment that can be reached from the local computer.

The Java client includes methods for interacting with the "importer" server as well, i.e. managing Log Data Sources and keyspace data.

The requirements for running the Teneo Inquire API Clients are:

A Teneo Inquire environment that can be reached from the local computer
Groovy and/or Java installed locally
A Teneo Inquire Client API library compatible with the Teneo Inquire environment version.

The Teneo Inquire Client API is shipped along with the distribution package.

Groovy Client Methods and Usage

Once the Client API jar file has been obtained, the file must be added to the classpath of the Groovy script. This can be achieved in to different ways, either

via the Groovy console user interface, or
by adding a -cp parameter when running the script from the command line.

Import

The Client API is imported into a Groovy script as follows:

groovy

1import com.artisol.teneo.inquire.client.Client
2

Initialization

The Client.Init method is used to initialize the client. The method takes three arguments:

context: the calling object, typically this
backendUrl: a string specifying the URL where the Inquire server API is running.
tqlOptions (optional) a map supplying optional arguments.

The tqlOptions map provides a way to override certain default properties for queries. The following properties are currently supported.

timeout time in seconds that will cause a query timeout; it is a non-negative integer with a default value of 1200
esPageSize the maximum size of a partial results page; it is a non-negative integer with a default value of 1500

The example below sets the client up with a timeout of 1000 seconds and a page size of 500. These parameters will be used in all query requests:

groovy

1Client.init(this, 'http://example.com:8087/teneo-inquire/rest', ['timeout':1000, 'esPageSize':500])
2

Default PageSize and Timeout configuration

The default Page Size is configurable in the Inquire properties file and affects any query sent via Studio or via the Inquire API when a Page Size is not specified in the request.

Timeout can be configured in the Studio properties and affects any query sent via Studio.

ElasticSearch Page Size can be edited in Teneo Inquire backend's configuration file, using the 'defaultPageSize' attribute. The preconfigured value is 1500. It can be configured within the 'Elasticsearch' block:

/etc/teneo/inquire-query/query-backend.yml

properties

1[...]
2elasticsearch:
3	defaultPageSize: 1500
4	servers: ["elasticsearch-host:9300"]
5[...]
6

TQL Query Timeout for Studio frontend queries can be configured in the 'teneo-studio.properties' file, by editing the 'inquire.defaultTimeout' property:

/etc/teneo/studio/teneo-studio.properties

properties

1[...]
2## Inquire query timeout in seconds
3inquire.defaultTimeout=1200
4[...]
5

Login and Logout

The login method authenticates the client with the Teneo Inquire server and receives a token back, which is added to subsequent calls.

The method takes two parameters, username and password, as strings:

groovy

1login('$user.name', '$password123')
2

The beginning of a script using the login authentication method can look like this:

groovy

1import com.artisol.teneo.inquire.client.Client
2
3Client.init(this, 'http://example.com:8087/teneo-inquire/rest', ['timeout':10000, 'esPageSize':50])
4
5login('$user.name', '$password123')
6
7// Main body of script follows here
8

The logout method revokes the user's authentication and deletes the stored authentication token. It does not need any parameter.

groovy

1logout()
2

Get the Teneo Manager user access token

The user's access token can be obtained from the token method. This method takes no arguments. Notice that the user must be logged in, otherwise this method will return nothing.

Example of usage:

groovy

1import com.artisol.teneo.inquire.client.Client
2
3Client.init(this,'http://example.com:8087/teneo-inquire/rest', ['timeout':100, 'esPageSize':50])
4
5login('$user.name', '$password123')
6
7def token = token()
8// Will return a long string with the teneo-manager
9// access token for the logged user
10
11println token
12//>> this-is-the-string-with-the-access-token-of-the-user
13
14logout()
15

Get the list of available Log Data Sources

To get a list of the allowed Log Data sources (LDSs), the Client API provides the listLds method. This method has no parameters.

Example of usage:

groovy

1import com.artisol.teneo.inquire.client.Client
2
3Client.init(this,'http://example.com:8087/teneo-inquire/rest', ['timeout':100, 'esPageSize':50])
4
5login('$user.name', '$password123')
6
7def allLds = listLds()
8// Will return a list of strings with all allowed
9// LDSs for the authenticated user
10
11println allLds
12//>> [my_lds_1, my_lds_2]
13
14logout()
15

Note: parameters named lds in the API and the Client refer to a named Log Data Source.

Querying the Data layer (Elasticsearch)

The Groovy client provides the tql method for querying Log Data Sources stored in Elasticsearch. It needs two parameters:

LDS the data source to be used
TQL query a string holding a well-formed TQL query.

It returns an iterative collection that can be assigned to a variable in Groovy.

Example of usage:

groovy

1import com.artisol.teneo.inquire.client.Client
2
3Client.init(this,'http://example.com:8087/teneo-inquire/rest', ['timeout':100, 'esPageSize':50])
4
5login('$user.name', '$password123')
6
7def result = tql('my_lds_1','sample 3 la s.id : s.transactionCount > 3')
8
9// Submits the TQL query that returns maximum 3 session
10// identifiers from all sessions having more than 3 transactions
11
12println result
13//>>[479116121a, ffafb0012a, 591a4aee52]
14
15logout()
16

Store data in the Data layer

The example below illustrates how to save partial results as data in the Data layer using the TQL operation save, and then use the saved data in the subsequent queries:

groovy

1import com.artisol.teneo.inquire.client.Client
2
3Client.init(this, 'http://example.com:8087/teneo-inquire/rest', ['timeout':100, 'esPageSize':50])
4
5login('$user.name', '$password123')
6
7tql('my_lds_1','save(name="my-saved-data") sample 3 lu s.id : s.transactionCount > 3')
8
9// Submits the same TQL query as above,
10// and stores the results with the given name 'my-saved-data'.
11
12def loadSaved = tql('my_lds_1','lu (source='my-saved-data') s.id')
13// This TQL query lists all session IDs
14// from the data stored as 'my-saved-data'.
15
16println loadSaved
17//>>[479116121a, ffafb0012a, 591a4aee52]
18
19logout()
20

The Client API provides an explicit saveResults method as well. It can be used in replacement of the TQL one shown above. This method takes three arguments:

LDS the data source to be used
data name a name to identify the saved data
data the data to be saved.

This method is more convenient if the user needs to manipulate the results (transform or add data) before saving.

In the example below, the rows in the results are extended with a length column before they are saved in the Data layer. Then, these data can be queried using TQL:

groovy

1import com.artisol.teneo.inquire.client.Client
2
3Client.init(this,'http://example.com:8087/teneo-inquire/rest', ['timeout':100, 'esPageSize':50])
4
5login('$user.name', '$password123')
6
7// Retrieve all inputs containing the word please
8def result = tql('my_lds_1','la t.e1.userInput as input : t.e1.userInputWords ~~ "please"')
9
10// Augment the result rows with a length column,
11// holding the length of the input
12
13result.each{ row -> row['length'] = row['input'].length()}
14
15//store the results on the Teneo Inquire server
16saveResults('my_lds_1', 'length_of_inputs_containing_please', result)
17
18logout()
19

groovy

1import com.artisol.teneo.inquire.client.Client
2
3Client.init(this, 'http://example.com:8087/teneo-inquire/rest', ['timeout':100, 'esPageSize':50])
4
5login('$user.name', '$password123')
6
7// list all inputs from the 'length_of_inputs_containing_please'
8// saved dataset which are longer than 20 characters,
9// sorted by length
10
11tql('my_lds_1', 'la(s="length_of_inputs_containing_please") input, length order by length desc')
12
13logout()
14

Check for saved data

In order to check if there is any saved data with a given name, the Client API provides the containsSavedResults method. This method takes two arguments:

LDS the data source to be used
data name the name to identify the saved data.

Example of usage:

groovy

1import com.artisol.teneo.inquire.client.Client
2
3Client.init(this, 'http://example.com:8087/teneo-inquire/rest', ['timeout':100, 'esPageSize':50])
4
5login('$user.name', '$password123')
6
7def itis = containsSavedResults('my_lds_1','my-saved-data')
8// Will return a boolean
9
10println itis
11//>> true
12
13logout()
14

Get sessions overview

To get the sessions information that is stored the Client API provides the indexOverview method. This method takes one argument:

LDS the data source to be used.

Example of usage:

groovy

1import com.artisol.teneo.inquire.client.Client
2
3Client.init(this, 'http://example.com:8087/teneo-inquire/rest', ['timeout':100, 'esPageSize':50])
4
5login('$user.name', '$password123')
6
7def io\_ES = indexOverview('my_lds_1')
8// Will return an `indexOverview` object holding information
9// about the sessions stored in the Data layer.
10
11println io_ES.size()
12println io_ES.keySet()
13println io_ES
14
15logout()
16

Usage example

The following Groovy script illustrates how to use the Groovy Client API:

Groovy

1import com.artisol.teneo.inquire.client.Client
2import java.text.SimpleDateFormat
3
4def username = 'user.name'
5def password = '$password123'
6
7Client.init(this,'http://example.com:8087/teneo-inquire/rest', ['timeout':100, 'esPageSize':50])
8
9login(username, password)
10
11def allLds = listLds()
12def results = [ : ]
13
14allLds.each { lds ->
15	// Retrieve the DataOverview for the lds def
16	overview = indexOverview(lds)
17
18SimpleDateFormat formatter = new SimpleDateFormat("ww-yyyy")
19SimpleDateFormat outFormatter = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ssZ")
20
21if ( overview != null && overview.size() != 0 ) {
22	// Retrieve the last week with more than 0 sessions stored,
23	// which will be a string with the week and the year
24	String lwString = overview.entrySet().find{ weekCount -> weekCount.value > 0 }.key
25	Calendar lw = new Calendar.Builder().setInstant(formatter.parse(lwString)).build()
26	Calendar ed = lw.clone()
27
28	lw.add(Calendar.MONTH, -1)
29
30	ed.add(Calendar.WEEK_OF_YEAR, 1)
31	ed.add(Calendar.DAY_OF_MONTH, 1)
32
33	// Find the distribution of the top 10 words for the
34	// last month in the LDS
35		def query = "d e.userInputWords : e.type == 'request', e.userInput != '', " +
36			"s.beginTime == in {'${outFormatter.format(lw.getTime())}'..'${outFormatter.format(ed.getTime())}'} " +
37			"order by count desc limit 10"
38
39	def ldsResults = tqlSync(lds, query)
40	// Will return an array of maps having in the key the user
41	// input word, and the value the count, e.g.:
42	//>> [[e.userInputWords:you, count:19],
43	//>> [e.userInputWords:to, count:16],
44	//>> [e.userInputWords:text, count:12]...]
45	
46	// Iterate over the found rows and add them to the results map 
47	ldsResults.each { row ->
48		def word = row["e.userInputWords"]
49		def count = row["count"]
50		results[word] = results[word] ?	
51						results[word] + count : count
52		}
53	}
54}
55
56// Logout from the backend
57logout()
58
59// Print all the results by value descending
60// (using the groovy spaceship operator)
61results .sort { a, b -> b.value <=> a.value } .each
62	{ word, count -> println "${word}\t${count}" }
63
64println results
65// Will print the total count of top 10 words for all LDS, e.g.:
66//>>[you:39, to:32, text:24, i:21, brooklyn:17, send:17, a:15...]
67