Running custom queries

Teneo Query Language (TQL) allows you to write custom queries and retrieve results that can be used to improve your solution. TQL queries run over a session’s transactions events. For example, they could be used to identify all inputs from the end-user that ended up in the safety net or investigate how often people visit a newly created flow that could be important to your business.

Teneo Query Language

TQL queries are written in the Query tab and executed using the 'Run Query' button or the short-cut command Ctrl-c. The main Log Data Source window allows for multiple tabs to be opened but be aware, Studio does not cache these tabs. If you close your main LDS window without saving the queries, they will be lost. Shared queries can be found in the Shared Queries tab and your recent run queries can be found in the tab Recent Queries. Both are located to the left in the main LDS window.

A TQL query consists of a command, one or more selection, and (optionally) a set of constraints and ordering.

• Command dictates how the selection will be displayed.
• Selection is what you want to investigate, such as session IDs, user inputs, or the chat bot’s response. Note that selection can consist of multiple items.
• Constraints are optional and are written with a : after the selection; this is used for making the selection stricter.

In the image below, the command would be d, distribute and the selection would be t.e.userInput and should be read as distribute the transaction events ‘userInput’. This query will return all the user inputs.

Constraints can be added to make the selection more strict. The annotated query below should be read as: Distribute the transaction events 'userInputs' where the transaction event 'userInput' is not empty and order the returned results from most to least.

Note that you can order a command and a selection; the constraint is not required.

In the following example, we will construct a query that will return the number of different coffees that have been purchased, and then order this list to see which coffee has been purchased the most.

Here is the query we will use:

1d t.e.fv:s:orderedCoffeeType : t.e.fv:s:orderedCoffeeType != "" order by count desc
2

With this query, we are looking at how many times the flow variable orderedCoffeeType

has been populated. In the first part of the query - the selection - we are using d

, short for 'distribute', to display a table. t

stands for 'transaction' and contains user input and the bot's response. e

stands for 'event'; events can be found inside transactions. After event, we specify the flow variable named orderedCoffeeType

using fv:s:orderedCoffeeType

. After the colon, we add a constraint to remove cases where the variable is empty. Finally, we order the results by count in descending order.

If we want to use this query again, we can share it so that it's available for our teammates working in the same Studio environment. With the query tab open, we can hit 'Share' in the ribbon bar and give the query a name.

Once we hit 'Save', we can see our shared query in the Shared Queries list.

The TQL cookbook contains pre-built TQL queries with an explanatory text. If you are interested in diving into TQL, take a look at the TQL reference page which goes deeper into all aspects of TQL.

Pre-built queries

Besides the cookbook, here are some pre-defined TQL queries which you can copy and add to your LDS.

List number of sessions by day

1d date: catd(model="date") s.beginTime as date order by date desc
2

Example result

List number of transactions by day

1d date: catd(model="date") t.time as date order by date desc
2

Example result

Flows triggered by day

1d date, t.e.folder as folderPath, t.e.fname as flowName: catd(model="date") t.time as date, t.e.pathType == "flow-trigger" order by date desc
2

Example result

List conversations

1listAll s.id as sessionId, s.beginTime as beginTime, t.e1.userInput as userInput, t.e3.answerText as response, t.e2.fname as flowName, t.e2.folder as folderName, t.index as transactionIndex, t.time as transactionTime : exists t.e1.userInput, t.e1-{type=="response"}>t.e3, t.e2<{pathType == in {"raise-flow", "continue-flow", "resume-flow"}}-t.e3 order by s.beginTime asc, t.time asc
2

Example result
(Some values have been shortened for brevity.)