Search APIs

Integrate Search APIs to execute natural language queries, retrieve insights, and embed search functionality into your applications seamlessly.

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 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 originalattribute. Tellius corrects any typos and errors (if present) in the query, and the rectified query will be displayed as a value for fixedQuery attribute.

{
    "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"
}