# 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" } ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://help.tellius.com/tellius-6.1/api/search-apis.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.