Search APIs
WebSockets
In WebSockets, a connection is established with the SQE service using an auth token. Each communication message is associated with a corrId (correlation ID) to map a response with its corresponding request.
Initialization
Endpoint: ws://qa.minion.tellius.com:31144/sqeWebSocket
As per the following snippet, the connection needs to be validated with an initial request consisting of a user token.
{
"token": "<your_authorization_token_here>"
}Response
{
"userId": "abcde34",
"status": "initialized",
"rId": "5da08f43-0ad5-4a13-932e-7e7f8f64d390"
}Heartbeat
The WebSocket can always be tested for the established connection using a heartbeat call, which also ensures that the socket connection is not timeout under idle.
To test a connection
Request - {"requestType": "ping"}
Response - {"status":"CONNECTED","responseType":"pong"}
Search queries APIs
The entire Search function works on WebSocket communication. For each query function, users need to generate corrId. Every Response will be matched with its corresponding Request using corrId. The search box will be available in the UI, and the user can hit the following APIs to view history and suggestions, validate, and execute queries.
View history
To view the history of previously typed queries, use the following request:
Request
{
"partialQuery": "profi",
"maximumAllowedRows": 10,
"limit": 10,
"isSearchQL": false,
"corrId": "Ma6jN",
"requestType": "history"
}Response
{
"totalCount": 154,
"responseType": "history",
"query": "profit",
"history": [
{
"timeDescription": "This month - Jan 2023",
"time": "2023-01-13 08:08:47.078",
"query": "profit ",
"historyId": "hist_41",
"businessViewName": "bv_Name",
"businessViewId": "bv_Id",
"bookmarked": false
},
{
"timeDescription": "This month - Jan 2023",
"time": "2023-01-13 09:46:54.586",
"query": "profit",
"historyId": "hist_06",
"businessViewName": "bv_Name",
"businessViewId": "bv_Id",
"bookmarked": false
},
{
"timeDescription": "Last month - Dec 2022",
"time": "2022-12-12 03:22:28.477",
"query": "profit",
"historyId": "hist_98",
"businessViewName": "bv_Name",
"businessViewId": "bv_Id",
"bookmarked": false
},
{
"timeDescription": "This month - Jan 2023",
"time": "2023-01-13 04:59:05.743",
"query": "profit",
"historyId": "hist_92",
"businessViewName": "bv_Name",
"businessViewId": "bv_Id",
"bookmarked": false
},
{
"timeDescription": "This month - Jan 2023",
"time": "2023-01-13 05:16:27.337",
"query": "profit",
"historyId": "hist_45",
"businessViewName": "bv_Name",
"businessViewId": "bv_Id",
"bookmarked": false
},
{
"timeDescription": "This month - Jan 2023",
"time": "2023-01-13 04:49:00.634",
"query": "profit",
"historyId": "hist_42",
"businessViewName": "bv_Name",
"businessViewId": "bv_Id",
"bookmarked": false
},
{
"timeDescription": "Last month - Dec 2022",
"time": "2022-12-09 05:47:50.269",
"query": "profit",
"historyId": "hist_14",
"businessViewName": "bv_Name",
"businessViewId": "bv_Id",
"bookmarked": false
},
{
"timeDescription": "Last month - Dec 2022",
"time": "2022-12-09 08:05:52.727",
"query": "profit",
"historyId": "hist_77",
"businessViewName": "bv_Name",
"businessViewId": "bv_Id",
"bookmarked": false
},
{
"timeDescription": "Last week",
"time": "2023-01-19 06:11:17.625",
"query": "profit ",
"historyId": "hist_84",
"businessViewName": "bv_Name",
"businessViewId": "bv_Id",
"bookmarked": false
},
{
"timeDescription": "This month - Jan 2023",
"time": "2023-01-13 10:06:56.161",
"query": "profit",
"historyId": "hist_06",
"businessViewName": "bv_Name",
"businessViewId": "bv_Id",
"bookmarked": false
}
],
"corrId": "QqJJR"
}If there is no history to be displayed, then an empty history object will be returned.
View suggestions
To display the list of suggestions
Request
{
"businessViewId": "bv_c97bee81-4743-47a2-95e8-837946757617",
"corrId": "auW6F",
"performQuery": false,
"getNlpSuggestionsFor": "profit",
"timezone": "GMT+0530"
}Response
{
"suggestions": [
"Profit"
],
"original": "profit",
"nextWordStartInd": 0,
"corrId": "auW6F"
}Validate a query
Request
A query will be validated if the attribute enterKeyPress is set to false.
{
"businessViewId": "ID_of_Business_View",
"corrId": "f7jfx",
"enterKeyPress": false,
"nlpQuery": "profit",
"timezone": "GMT+0530"
}Response
The
aggregatedFieldin the response refers to a measure used in the query. For example, if you use two measures "Profit" and "Sales", then there will be two components in theaggregatedFieldarray.When you click on any token that is used in the query, a list of suggestions will be displayed. For example, for the
tokenString(token) Profit, avg Profit, sum Profit, min Proft, max Profit, total Profit, and maxshare Profit are displayed as suggestions.Towards the end, the original query typed by the user will be displayed under
originalattribute. Tellius corrects any typos and errors (if present) in the query, and the rectified query will be displayed as a value forfixedQueryattribute.
{
"witResponse": {
"query": "profit",
"intent": "followup",
"entities": {
"businessViewId": [
{
"value": {
"value": "bv_bee",
"type": "string"
},
"start": 0,
"end": 0,
"confidence": 1
}
],
"aggregatedField": [
{
"value": {
"type": "aggregation",
"aggregationField": {
"name": "Profit",
"isExpression": false,
"datasetName": "Retail_01",
"datasetId": "bv_bee",
"databaseTable": "save_9"
}
},
"start": 0,
"end": 6,
"confidence": 1
}
]
},
"confidence": 0.653732419013977
},
"tokens": [
{
"type": "measure",
"tokenString": "profit",
"suggestions": [
{
"type": "measure",
"tokenString": "avg Profit",
"suggestions": [],
"column": {
"name": "Profit"
},
"aggregation": "avg"
},
{
"type": "measure",
"tokenString": "sum Profit",
"suggestions": [],
"column": {
"name": "Profit"
},
"aggregation": "sum"
},
{
"type": "measure",
"tokenString": "min Profit",
"suggestions": [],
"column": {
"name": "Profit"
},
"aggregation": "min"
},
{
"type": "measure",
"tokenString": "max Profit",
"suggestions": [],
"column": {
"name": "Profit"
},
"aggregation": "max"
},
{
"type": "measure",
"tokenString": "total Profit",
"suggestions": [],
"column": {
"name": "Profit"
},
"aggregation": "total"
},
{
"type": "measure",
"tokenString": "marketShare Profit",
"suggestions": [],
"column": {
"name": "Profit"
},
"aggregation": "marketShare"
},
{
"type": "measure",
"tokenString": "sum Sales",
"suggestions": [],
"column": {
"name": "Sales"
},
"aggregation": "sum"
},
{
"type": "measure",
"tokenString": "sum Quantity",
"suggestions": [],
"column": {
"name": "Quantity"
},
"aggregation": "sum"
},
{
"type": "measure",
"tokenString": "sum Discount",
"suggestions": [],
"column": {
"name": "Discount"
},
"aggregation": "sum"
},
{
"type": "measure",
"tokenString": "sum Shipping_Cost",
"suggestions": [],
"column": {
"name": "Shipping_Cost"
},
"aggregation": "sum"
},
{
"type": "measure",
"tokenString": "sum Order_Priority",
"suggestions": [],
"column": {
"name": "Order_Priority"
},
"aggregation": "sum"
},
{
"type": "measure",
"tokenString": "sum Test",
"suggestions": [],
"column": {
"name": "Test"
},
"aggregation": "sum"
}
],
"start": 0,
"end": 6,
"column": {
"name": "Profit"
},
"changeTo": "Profit",
"aggregation": "avg"
}
],
"suggestions": [],
"responseType": "validQuery",
"original": "profit",
"fixedQuery": "Profit",
"corrId": "f7jfx"
}Failure
If a query cannot be validated, then the following response will be sent:
{
"responseType": "error",
"msg": "Not Enough Details in the Query",
"errorType": "info",
"corrId": "OJKrr"
}Execute a query
A query will be executed only if performQuery, enterKeyPress, and createViz is set to true.
Request
{
"businessViewId": "bv_9802",
"corrId": "Eymyb",
"performQuery": true,
"enterKeyPress": true,
"nlpQuery": "profit",
"createViz": true,
"timezone": "GMT+0530"
}Response
{
"vizResponse": {
"vizResponseType": "kpi",
"viz": {
"vizpad": {
"displayNameForColumns": {
"Test": "Test",
"State": "display_state",
"Segment": "display_segment",
"City": "display_city",
"Category": "display_category"
}
},
"vizType": "kpi",
"title": "Average Profit",
"theme": {
"vizBackground": {
"transparency": "0.9",
"image": "img/test",
"color": "white"
},
"name": "dark",
"color": "black"
},
"size": {
"width": 200,
"height": 100
},
"placement": {
"yDistance": 20,
"xDistance": 10
},
"metadata": {
"timezone": "GMT+0530",
"language": "english",
"format": {
"title": {
"font": {
"weight": "normal",
"size": "16",
"color": "#000000"
},
"enabled": true
},
"numberFormats": {
"numberFormats": {
"Profit": {
"type": "number",
"suffix": "",
"prefix": "",
"isCommaSeparated": true,
"displayUnit": "default",
"decimals": 2
}
},
"lastColumn": "",
"enabled": false
},
"legend": {
"font": {
"weight": "normal",
"size": "14",
"color": "#78909c"
},
"enabled": true
},
"includeGeneratedSQL": true,
"dataLabel": {
"enabled": true,
"detailedFormat": false
},
"colorPaletteInfo": {
"colors": [
"#1565C0",
"#F57F17",
"#558B2F",
"#BF360C",
"#5E35B1",
"#00838F",
"#C62828",
"#827717",
"#E65100",
"#5D4037",
"#AD1457",
"#6A1B9A",
"#1976D2",
"#F9A825",
"#689F38",
"#D84315",
"#673AB7",
"#0097A7",
"#D32F2F",
"#9E9D24",
"#EF6C00",
"#6D4C41",
"#C2185B",
"#7B1FA2",
"#42A5F5",
"#FFEB3B",
"#9CCC65",
"#FF8A65",
"#9575CD",
"#4DD0E1",
"#EF5350",
"#C0CA33",
"#FF9800",
"#8D6E63",
"#EC407A",
"#AB47BC",
"#64B5F6",
"#FFF176",
"#AED581",
"#FFAB91",
"#B39DDB",
"#80DEEA",
"#E57373",
"#D4E157",
"#FFB74D",
"#A1887F",
"#F06292",
"#BA68C8",
"#90CAF9",
"#FFF59D",
"#C5E1A5",
"#FFCCBC",
"#D1C4E9",
"#B2EBF2",
"#EF9A9A",
"#DCE775",
"#FFCC80",
"#BCAAA4",
"#F48FB1",
"#CE93D8"
]
},
"background": {
"enableGrid": false,
"color": "#FFFFFF"
},
"axes": {
"yAxis": {
"enabled": true
},
"xAxis": {
"enabled": true
},
"font": {
"weight": "normal",
"size": "14",
"color": "#78909c"
}
}
},
"dualAxis": true,
"colorPalette": "colorPalette_ID"
},
"id": "123456",
"chartType": "simpleCount",
"businessViewId": "bv_Id",
"axes": {
"yAxis": [
{
"columnName": "Profit",
"aggregation": "avg"
}
],
"isMultipleAxes": false
}
},
"tooltip": [
{
"translatedAggregation": "avg",
"originalValue": 9.516207509663207,
"isYAxis": true,
"isXAxis": false,
"isGroupBy": false,
"formattedValue": "9.52",
"columnName": "Profit",
"alias": "Profit",
"aggregation": "avg"
}
],
"textColor": "#333333",
"responseText": "**Average Profit** is **9.52**",
"possibleTransitions": [
"funnel",
"detailTable",
"simpleCount",
"radialProgress",
"viewData",
"interactiveTable",
"histogram",
"bar",
"column",
"barConversion",
"table"
],
"possibleBucketInfo": {
"possibleBuckets": {
"measureType": {
"values": {
"tooltips": 5,
"measures": 0
}
}
}
},
"metadata": {
"tqlResponseRowCount": 1,
"totalRowCount": 1811,
"timeTakenInMilliSeconds": 126,
"responseDataCount": 1,
"generatedSql": "select * from (select Profit_avg_9765131377838500110 FROM (select avg(Profit) as \"Profit_avg_9765131377838500110\" FROM save_92741413666804 ) from_alias where ((isNotNull(Profit_avg_9765131377838500110) and NOT isInfinite(Profit_avg_9765131377838500110)))) outer_alias LIMIT 10001 OFFSET 0"
},
"count": "9.52",
"columns": [
{
"name": "Profit",
"format": {
"type": "number",
"isCommaSeparated": true,
"displayUnit": "default",
"decimals": 2
},
"datasetName": "Retail_01",
"datasetId": "bv_Id",
"aggregation": "avg"
}
],
"columnDetails": {
"measureType": [
{
"indexInBucket": 0,
"column": {
"name": "Profit",
"isWeekEndDate": false,
"aggregation": "avg"
},
"bucket": "measures"
}
],
"dimensionType": [],
"dateType": []
}
},
"responseType": "vizResponse",
"metadata": {
"witResponse": {
"query": "profit",
"intent": "followup",
"entities": {
"businessViewId": [
{
"value": {
"value": "bv_10",
"type": "string"
},
"start": 0,
"end": 0,
"confidence": 1
}
],
"aggregatedField": [
{
"value": {
"type": "aggregation",
"aggregationField": {
"name": "Profit",
"isExpression": false,
"datasetName": "Retail_01",
"datasetId": "bv_Id",
"databaseTable": "save_1"
}
},
"start": 0,
"end": 6,
"confidence": 1
}
]
},
"confidence": 0.653732419013977
},
"tokens": [
{
"type": "measure",
"tokenString": "profit",
"suggestions": [
{
"type": "measure",
"tokenString": "avg Profit",
"suggestions": [],
"column": {
"name": "Profit"
},
"aggregation": "avg"
},
{
"type": "measure",
"tokenString": "sum Profit",
"suggestions": [],
"column": {
"name": "Profit"
},
"aggregation": "sum"
},
{
"type": "measure",
"tokenString": "min Profit",
"suggestions": [],
"column": {
"name": "Profit"
},
"aggregation": "min"
},
{
"type": "measure",
"tokenString": "max Profit",
"suggestions": [],
"column": {
"name": "Profit"
},
"aggregation": "max"
},
{
"type": "measure",
"tokenString": "total Profit",
"suggestions": [],
"column": {
"name": "Profit"
},
"aggregation": "total"
},
{
"type": "measure",
"tokenString": "marketShare Profit",
"suggestions": [],
"column": {
"name": "Profit"
},
"aggregation": "marketShare"
},
{
"type": "measure",
"tokenString": "sum Sales",
"suggestions": [],
"column": {
"name": "Sales"
},
"aggregation": "sum"
},
{
"type": "measure",
"tokenString": "sum Quantity",
"suggestions": [],
"column": {
"name": "Quantity"
},
"aggregation": "sum"
},
{
"type": "measure",
"tokenString": "sum Discount",
"suggestions": [],
"column": {
"name": "Discount"
},
"aggregation": "sum"
},
{
"type": "measure",
"tokenString": "sum Shipping_Cost",
"suggestions": [],
"column": {
"name": "Shipping_Cost"
},
"aggregation": "sum"
},
{
"type": "measure",
"tokenString": "sum Order_Priority",
"suggestions": [],
"column": {
"name": "Order_Priority"
},
"aggregation": "sum"
},
{
"type": "measure",
"tokenString": "sum Test",
"suggestions": [],
"column": {
"name": "Test"
},
"aggregation": "sum"
}
],
"start": 0,
"end": 6,
"column": {
"name": "Profit"
},
"changeTo": "Profit",
"aggregation": "avg"
}
],
"suggestions": [],
"rowsCount": 1,
"responseType": "viz",
"original": "profit",
"fixedQuery": "Profit",
"filterDescriptions": [],
"chartType": "simpleCount",
"chartTitle": "Average Profit",
"BVId": "bv_ID"
},
"corrId": "85rGn"
}Last updated
Was this helpful?