Teneo Developers

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.

Query Results

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.

Basic Query Annotated

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.

Basic Query with constraint

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

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.

tql example most ordered coffees

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.

shared queries

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

saved shared queries

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

Example result


List number of transactions by day


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

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

Example result

"2019-12-16""/Greeting Message""Greeting message""65"
"2019-12-16""/Dialogue/Connecting Phrases/Acknowledgement""The user expresses agreement""2"
"2019-12-16""/Dialogue/Connecting Phrases/Acknowledgement""The user shows encouragement to the conversation""2"
"2019-12-16""/Dialogue/Connecting Phrases/Acknowledgement""The user says Yes""12"
"2019-12-16""/Dialogue/Conversational/Conversation""The user comments on the weather""2"
"2019-12-16""/Dialogue/Conversational/Conversation""The user wants to know the time""12"
"2019-12-16""/Dialogue/Connecting Phrases/Social""The user is telling his name""38"

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

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

"117...E80""12/16/2019 9:44:33 PM""""Hello! My name is Sara.""Greeting message""/Greeting Message""0""12/16/2019 9:44:33 PM"
"117...E80""12/16/2019 9:44:33 PM""How are you doing?""Thanks for asking. I'm having a great time.""The user asks, How are you? How was your day""/Dialogue/Connecting Phrases/Greetings""1""12/16/2019 9:44:46 PM"
"117...E80""12/16/2019 9:44:33 PM""Okay. Bye bye.""Goodbye! See you again soon, I hope.""The user says Goodbye""/Goodbye Message""2""12/16/2019 9:44:53 PM"
"420...94B""12/16/2019 9:44:57 PM""""Hi! My name is Sara.""Greeting message""/Greeting Message""0""12/16/2019 9:44:57 PM"
"420...94B""12/16/2019 9:44:57 PM""What time is it?""My watch says it's 10:45 PM.""The user wants to know the time""/Dialogue/Conversational/ Conversation""1""12/16/2019 9:45:09 PM"
"420...94B""12/16/2019 9:44:57 PM""fantastic""Glad to hear that!""The user says Good, Great, or Excellent""/Dialogue/Connecting Phrases/ Acknowledgement""2""12/16/2019 9:45:17 PM"
"420...94B""12/16/2019 9:44:57 PM""Goodbye.""Goodbye! See you again soon, I hope.""The user says Goodbye""/Goodbye Message""3""12/16/2019 9:45:23 PM"