Query Output
On this page:
About Query Output
Query Output is a data visualization widget that accepts the response from the query endpoint.
Currently there are 10 options available for displaying the response data.
For more information on each display type and how to get the supported display types for each response, visit the "Display Types" section in this doc.
Setting Up Query Output
The following sections in this document contain detailed information about how to customize the properties of this widget.
import { QueryOutput } from 'autoql'
var queryOutput = new QueryOutput('#query-output', {
displayType: 'line',
})
Options
| Option Name | Data Type | Default Value |
|---|---|---|
| queryResponse (Required) | Object | - |
| queryInputRef | Instance of <QueryInput/> | undefined |
| displayType | String | undefined |
| height | Number | undefined |
| width | Number | undefined |
| onDataClick | Function | (groupByObject, queryID, activeKey) => {} |
| activeChartElementKey | String | undefined |
| renderTooltips | Boolean | true |
| onQueryValidationSelectOption | Function | () => {} |
| autoSelectQueryValidationSuggestion | Boolean | true |
| queryValidationSelections | Array of Suggestion Objects | undefined |
| renderSuggestionsAsDropdown | Boolean | false |
| suggestionSelection | String | undefined |
| dataFormatting | Object | {} |
| themeConfig | Object | {} |
queryResponse (Required): This is the whole response object supplied from the query endpoint (or validate endpoint, if enabled). You must pass in this whole object to the QueryOutput component.
For more information on the structure of a query response, please visit API Reference
QueryInputRef: The ref of the QueryInput component. This is used when the response returns a list of suggestions or when the response is returned from the validate endpoint. If the user clicks on a suggestion to run a new query, the QueryInput component will animate and submit the suggested query automatically.
displayType: This is where you can pass in the type of visualization you wish to use for the data. You must pass in a supported display type to the QueryOutput (see the Display Types section below for more details). If an invalid display type or non-supported display type is passed in, the returned display will default to a table.
height: Specify a height (in px) for the response container. This is especially important to set when you want to display a large amount of information in a table. If this height option or the height of your container is not set explicitly, the component will try to render the whole table without progressive rendering. This can significantly impact the performance of your application. You can also set the max-height css property on your container instead of setting a constant height.
Set the height to allow progressive rendering in tables
If the height option or the height of your container is not set explicitly, the component will try to render the whole table without progressive rendering. This can significantly impact the performance of your application.
width: Specify a width (in px) for the response container.
onDataClick: (groupByObject, queryID, activeKey): Function to be called when a table or chart element is clicked. The Data Messenger widget uses the drilldown endpoint.
groupByObject: An object containing the detailed information of the data that was clicked. This is required by the drilldown endpoint.
queryID: A unique ID for the exact query request that the data was returned from.
activeKey: For chart clicks only: a unique ID for the specific element of the chart that was clicked. This ID can be passed into the QueryOutput as an option (see activeChartElementKey below) to highlight the clicked element.
activeChartElementKey: The ID of one of the chart elements such as a bar or column. The active chart element will be highlighted in the secondary chart color to indicate that it is active.
renderTooltips: Determines whether or not to render tooltips when hovering over a chart element. When this value is true, each chart element will have a tooltip showing the ordinal title/value and numerical title/value.
onQueryValidationSelectOption: (queryText, newSelectedSuggestions): A function that is called when a user changes the word in any of the suggested replacement dropdowns.
queryText: The new query string
newSelectedSuggestions: An array populated with each selected suggestion corresponding to each dropdown.
autoSelectQueryValidationSuggestion: If set to true, each dropdown with a detected unknown word will automatically be populated with the first replacement suggestion for that word. If set to false, each dropdown will be populated with the original word from the user's query.
queryValidationSelections: If you already know the replacement suggestions and want to specify the initial array of selected words, you can use this option. This will override the autoSelectQueryValidationSuggestion option.
renderSuggestionsAsDropdown: In the case where a query could not be interpreted with high confidence, a list of query suggestions that the user can click on will be returned. If this option is set to true, the suggestions will be rendered as a dropdown instead of a list.
suggestionSelection: If renderSuggestionsAsDropdown is set to true, you can specify the initial selection with this option if it is known.
dataFormatting Option
| Key | Value Type | Description |
|---|---|---|
| currencyCode | String | 'USD' |
| languageCode | String | 'en-US' |
| currencyDecimals | Number | 2 |
| quantityDecimals | Number | 1 |
| comparisonDisplay | String: 'PERCENT' || 'RATIO' | 'PERCENT' |
| monthYearFormat | String | 'MMM YYYY' |
| dayMonthYearFormat | String | 'll' |
currencyCode: If your data is not in USD, you can specify a different currency code here. All visualizations (tables and charts) will show the default currency formatting for the specified code.
Currency
Setting a currency code does not perform a currency conversion. It only displays the number in the desired format.
languageCode: If the currency code from your country requires letters not contained in the English alphabet in order to show symbols correctly, you can pass in a locale here. For more details on how to do this, visit: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/NumberFormat
currencyDecimals: Number of digits to display after a decimal point for currencies.
quantityDecimals: Number of digits to display after a decimal point for quantity values.
comparisonDisplay: Format for displaying comparison types (ex. changes in data). "Percent" will multiply the number by 100 and display a "%" symbol. "Ratio" will display the original number as-is.
monthYearFormat: The format to display the representation of a whole month. (ex. March 2020). Chata.ai defaults to dayjs for date formatting, however most Moment.js formatting will work here as well. Please see the dayjs docs for formatting options.
dayMonthYearFormat: The format to display the representation of a single day (e.g. March 18, 2020). Chata.ai defaults to dayjs for date formatting, however most Moment.js formatting will work here as well. Please see the dayjs docs for formatting options.
themeConfig Option
| Key | Value Type | Description |
|---|---|---|
| theme | String: 'light' || 'dark' | 'light' |
| accentColor | String | light theme: '#28a8e0', dark theme: '#525252' |
| fontFamily | String | 'sans-serif' |
| chartColors | Array | ['#26A7E9', '#A5CD39', '#DD6A6A', '#FFA700', '#00C1B2'] |
theme: Color theme for Query Output. Currently there are two options: light theme and dark theme. In addition to changing the overall theme, you can also change the accent color using the accentColor option.
accentColor: Primary accent color used in Query Output. This is the color of the header and all the messages displayed in the interface (both natural language query inputs from users and the associated responses that are generated and returned to the user). The visualization (table and chart) colors will not be affected here.
fontFamily: Customize the font family to the provided font wherever possible. Accepts any CSS font family that is available, and if none is provided, will default to Sans-Serif.
chartColors: Array of color options for the visualization themes, starting with the most primary. You can pass any valid CSS color format in here, however it is recommended that the color is opaque (ex. "#26A7E9", "rgb(111, 227, 142)", or "red"). Charts will always apply the colors in order from first to last. If the visualization requires more colors than provided, all colors will be used and then repeated in order.
Display Types
There are 9 display types available for data visualization. Below are the names and descriptions for each display type:
| Display Type | Option Value | Description |
|---|---|---|
| Table | table | Displays array data in a regular table. (We use the Tabulator library) |
| Pivot Table | pivot_table | Displays a multi-dimensional table, with the first column frozen. |
| Bar Chart | bar | Ordinal data is on the y-axis, numerical data is on the x-axis, bars are horizontal. Will show a series for each column of data where applicable. |
| Column Chart | column | Ordinal data is on the x-axis, numerical data is on the y-axis, bars are vertical. Will show a series for each column of data where applicable. |
| Line Chart | line | Ordinal data is on the x-axis, numerical data is on the y-axis. Will show a line series for each column of data where applicable. |
| Heat Map | heatmap | The position of the squares are based on the categories, and the opacity of the squares are based on the values. |
| Bubble Chart | bubble | The position of the bubbles are based on the categories, and the radius of the bubbles are based on the values. |
| Stacked Column Chart | stacked_column | Ordinal data is on the x-axis, numerical data is on the y-axis, bars are vertical. Columns are split into categories using the third dimension. Will show a legend for the categories on the right hand side. |
| Stacked Bar Chart | stacked_bar | Ordinal data is on the y-axis, numerical data is on the x-axis, bars are horizontal. Bars are split into categories using the third dimension. Will show a legend for the categories on the right hand side. |
| Stacked Area Chart | stacked_area | Ordinal data is on the x-axis, numerical data is on the y-axis. Each area is stacked on top of the previous area. Will show a legend for the categories on the right hand side. |
Supported Display Types
Depending on the data structure of the query response, only certain display types may be supported. To learn about which display types are supported for your query response, see the "Supported Display Types" section below.
Supported Display Types
To get a list of display types supported by the response data, you can access the following function from the library:
getSupportedDisplayTypes(queryResponse): returns an array of supported display types.
Simply pass in the query response as a function parameter:
<script>
...
var supportedDisplayTypes = getSupportedDisplayTypes(queryResponse)
</script>
If you wish to see if a particular display type is valid, you can use the isDisplayTypeValid function:
isDisplayTypeValid(queryResponse, displayType): checks if the provided display type is included in the supported display types array. Returns either true or false.
<script>
...
if (isDisplayTypeValid('bar')) {
queryOutput.setOption('displayType', 'bar')
}
</script>
Default Display Types
Depending on the data structure, the default display type may change. If we are able to return a pivot table out of the data, this will be the default response, otherwise a regular table will be returned as the default.
You can also call the getDefaultDisplayType function to get this value:
getDefaultDisplayType(queryResponse): returns either 'table' or 'pivot_table' depending on the data structure.
Examples
<body>
<div id="query-output"></div>
<div id="query-input"></div>
<script>
var queryOutput = new QueryOutput('#query-output', {
displayType: 'table',
})
var queryInput = new QueryInput('#query-input', {
authentication: {
token: token,
apiKey: apiKey,
domain: domain,
},
autoCompletePlacement: 'bottom',
});
queryInput.bind(queryOutput)
</script>
</body>
Updated about 1 year ago