# 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. ```json { "token": "" } ``` ### **Response** ```json { "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** ```json { "partialQuery": "profi", "maximumAllowedRows": 10, "limit": 10, "isSearchQL": false, "corrId": "Ma6jN", "requestType": "history" } ``` #### **Response** ```json { "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** ```json { "businessViewId": "bv_c97bee81-4743-47a2-95e8-837946757617", "corrId": "auW6F", "performQuery": false, "getNlpSuggestionsFor": "profit", "timezone": "GMT+0530" } ``` #### **Response** ```json { "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**. ```json { "businessViewId": "ID_of_Business_View", "corrId": "f7jfx", "enterKeyPress": false, "nlpQuery": "profit", "timezone": "GMT+0530" } ``` #### **Response** * The `aggregatedField` in 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 the `aggregatedField` array. * 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 `original`attribute. Tellius corrects any typos and errors (if present) in the query, and the rectified query will be displayed as a value for `fixedQuery` attribute. ```json { "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: ```json { "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** ```json { "businessViewId": "bv_9802", "corrId": "Eymyb", "performQuery": true, "enterKeyPress": true, "nlpQuery": "profit", "createViz": true, "timezone": "GMT+0530" } ``` #### **Response** ```json { "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" } ```