Draw charts from Azure Data Explorer queries
Перейти к файлу
Violet Voronetzky b4fd213d49 Added additional options to chart options: disable legend, yMinValue, yMaxValue, yAxisTitleFormatter to set custom y-axis title 2020-03-16 10:51:49 +02:00
.vscode Initial release 2019-11-10 18:08:31 +02:00
src Fixed bug when yMin / yMax are 0 2020-03-16 10:18:01 +02:00
test PR modifications 2020-02-04 11:04:34 +02:00
.gitignore Initial release 2019-11-10 18:08:31 +02:00
.travis.yml Add Travis + badge 2019-11-11 09:06:59 +02:00
CODE_OF_CONDUCT.md Update to MS Code Of Conduct + MIT lisence 2019-11-11 14:45:49 +02:00
LICENSE Updating LICENSE to template content 2019-11-10 07:38:22 -08:00
README.md PR modifications 2020-03-15 20:49:47 +02:00
SECURITY.md Initial SECURITY.md commit 2019-11-10 07:38:25 -08:00
index.ts Added bar chart option 2020-03-11 17:48:18 +02:00
launch.json Initial release 2019-11-10 18:08:31 +02:00
package-lock.json Added additional options to chart options: disable legend, yMinValue, yMaxValue, yAxisTitleFormatter to set custom y-axis title 2020-03-16 10:51:49 +02:00
package.json Added additional options to chart options: disable legend, yMinValue, yMaxValue, yAxisTitleFormatter to set custom y-axis title 2020-03-16 10:51:49 +02:00
tasks.json Initial release 2019-11-10 18:08:31 +02:00
tsconfig.json Initial release 2019-11-10 18:08:31 +02:00

README.md

adx-query-charts

Build Status    npm version

Draw charts from Azure Data Explorer queries

Installation

npm install adx-query-charts

Dependencies

  1. lodash: npm i lodash
  2. css-element-queries: npm i css-element-queries
  3. highcharts: npm i highcharts Please note: Highcharts/Highstock libraries are free to use with Log Analytics/adx-query-charts.
    If you plan to use Highcharts separately, in your own project, you must obtain a license:
    follow the link License and Pricing.

Usage

import * as Charts from 'adx-query-charts';

const highchartsVisualizer = new Charts.HighchartsVisualizer();
const chartHelper = chartHelper = new Charts.KustoChartHelper('chart-elem-id', highchartsVisualizer);
const chartOptions: Charts.IChartOptions = {
    chartType: Charts.ChartType.UnstackedColumn,
    columnsSelection: {
        xAxis: { name: 'timestamp', type: Charts.DraftColumnType.DateTime },
        yAxes: [{ name: 'requestCount', type: Charts.DraftColumnType.Int }]
    }
};

// Draw the chart - the chart will be drawn inside an element with 'chart-elem-id' id
chartHelper.draw(queryResultData, chartOptions);

API

KustoChartHelper

Method: Description: Input: Return value:
draw Draw the chart IQueryResultData - The original query result data
IChartOptions - The information required to draw the chart
Promise<IChartInfo>
changeTheme Change the theme of an existing chart ChartTheme - The theme to apply Promise<void>
getSupportedColumnTypes Get the supported column types for the axes and the split-by
for a specific chart type
ChartType - The type of the chart ISupportedColumnTypes
getSupportedColumnsInResult Get the supported columns from the query result data for the axes and the split-by for a specific chart type IQueryResultData - The original query result data
ChartType - The type of the chart
ISupportedColumns
getDefaultSelection Get the default columns selection from the query result data.
Select the default columns for the axes and the split-by for drawing a default chart of a specific chart type.
IQueryResultData - The original query result data
ChartType - The type of the chart
ISupportedColumns - (Optional) The list of the supported column types for the axes and the split-by
ColumnsSelection
downloadChartJPGImage Download the chart as JPG image (error: Error) => void - [Optional] A callback that will be called if the module failed to export the chart image void

IChartOptions

Option name: Type: Details: Default value:
chartType ChartType Mandatory.
The type of the chart to draw
columnsSelection ColumnsSelection The columns selection for the Axes and the split-by of the chart If not provided, default columns will be selected.
See: getDefaultSelection method
maxUniqueXValues number The maximum number of the unique X-axis values.
The chart will show the biggest values, and the rest will be aggregated to a separate data point.
100
exceedMaxDataPointLabel string The label of the data point that contains the aggregated value of all the X-axis values that exceed the 'maxUniqueXValues' 'OTHER'
aggregationType AggregationType Multiple rows with the same values for the X-axis and the split-by will be aggregated using a function of this type.
For example, assume we get the following query result data:
['2016-08-02T10:00:00Z', 'Chrome 51.0', 15],
['2016-08-02T10:00:00Z', 'Internet Explorer 9.0', 4]
When drawing a chart with columnsSelection = { xAxis: timestamp, yAxes: count_ }, and aggregationType = AggregationType.Sum we need to aggregate the values of the same timestamp value and return one row with ["2016-08-02T10:00:00Z", 19]
AggregationType.Sum
title string The title of the chart
utcOffset number The desired offset from UTC in hours for date values. Used to handle timezone.
The offset will be added to the original date from the query results data.
For example:
For 'Africa/Harare' timezone provide utcOffset = 2 and the displayed date will be be:
'11/25/2019, 2:00 AM' instead of '11/25/2019, 12:00 AM'
See time zone [info](https://msdn.microsoft.com/en-us/library/ms912391(v=winembedded.11)
0
legendOptions ILegendOptions The legend configuration options
yMinimumValue number The minimum value to be displayed on the y-axis
If not provided, the minimum value is automatically calculated
yMaximumValue number The maximum value to be displayed on the y-axis
If not provided, the maximum value is automatically calculated
chartTheme ChartTheme The theme of the chart ChartTheme.Light
dateFormatter Function
(dateValue: Date, defaultFormat: DateFormat): string
Callback that is used to format the date values both in the axis and the tooltip
Callback inputs:
    dateValue - The original date value. If utcOffset was provided, this value will include the utcOffset
    DateFormat - The default format of the label
Callback return value:
    The string represents the display value of the dateValue
If not provided - the default formatting will apply
numberFormatter Function
(numberValue: number): string
Callback that is used to format number values both in the axis and the tooltip
Callback inputs:
    numberValue - The original number
Callback return value:
    The string represents the display value of the numberValue
If not provided - the default formatting will apply
xAxisTitleFormatter Function
(xAxisColumn: IColumn): string
Callback that is used to get the xAxis title
Callback inputs:
    IColumn - The x-axis column
Callback return value:
    The desired x-axis title
If not provided - the xAxis title will be the xAxis column name
yAxisTitleFormatter Function
(yAxisColumns: IColumn[]): string
Callback that is used to get the yAxis title
Callback inputs:
    IColumn[] - The y-axis columns
Callback return value:
    The desired y-axis title
If not provided - the yAxis title will be the first yAxis column name
onFinishDataTransformation Function(dataTransformationInfo: IDataTransformationInfo) : Promise<boolean> Callback that is called when all the data transformations required to draw the chart are finished
Callback inputs:
    IDataTransformationInfo - The information regarding the applied transformations on the original query results
Callback return value:
    The promise that is used to continue/stop drawing the chart
    When provided, the drawing of the chart will be suspended until this promise will be resolved
    When resolved with true - the chart will continue the drawing
    When resolved with false - the chart drawing will be canceled
onFinishDrawing Function(chartInfo: IChartInfo) : void Callback that is called when the chart drawing is finished
Callback inputs:
    IChartInfo - The information regarding the chart
onFinishChartAnimation Function(chartInfo: IChartInfo) : void Callback that is called when the chart animation is finished
Callback inputs:
    IChartInfo - The information regarding the chart

IDataTransformationInfo

Option name: Type: Details:
numberOfDataPoints number The amount of the data points that will be drawn for the chart
isPartialData boolean True if the chart presents partial data from the original query results
The chart data will be partial when the maximum number of the unique X-axis values exceed the
'maxUniqueXValues' in IChartOptions
isAggregationApplied boolean True if aggregation was applied on the original query results in order to draw the chart
See 'aggregationType' in IChartOptions for more details

IChartInfo

Option name: Type: Details:
dataTransformationInfo IDataTransformationInfo The information regarding the applied transformations on the original query results
status DrawChartStatus The status of the draw action
error [ChartError] (#ChartError) [Optional] The error information in case that the draw action failed

ILegendOptions

Option name: Type: Details:
isEnabled boolean Set to false if you want to hide the legend.
[Default value: true (show legend)]

ChartType

enum ChartType {
    Line,
    Scatter,
    UnstackedArea,
    StackedArea,
    PercentageArea,
    UnstackedColumn,
    StackedColumn,
    PercentageColumn,
    UnstackedBar,
    StackedBar,
    PercentageBar,
    Pie,
    Donut,
}

Columns selection per chart type

Chart type: X-axis: Y-axis: Split-by:
Line / Scatter
UnstackedArea / StackedArea / PercentageArea
UnstackedColumn / StackedColumn / PercentageColumn
UnstackedBar / StackedBar / PercentageBar
[Single selection]
DateTime / Int / Long
Decimal / Real / String
[If split-by column is selected: y-axis restricted to single selection]
[If split-by column is not selected: y-axis can be single/multi selection]
Int / Long / Decimal / Real
[Single selection]
String
Pie / Donut [Single selection]
String
[Single selection]
Int / Long / Decimal / Real
[Single / Multi selection]
String / DateTime / Bool

ColumnsSelection

interface IColumn {
    name: string;
    type: DraftColumnType;
}

class ColumnsSelection {
    xAxis: IColumn;
    yAxes: IColumn[];
    splitBy?: IColumn[];
}

See [Columns selection per chart type](#Columns selection per chart type)

AggregationType

enum AggregationType {
    Sum,
    Average,
    Min,
    Max
}

ChartTheme

enum ChartTheme {
    Dark,
    Light
}

ErrorCode

enum ErrorCode {
    InvalidQueryResultData,
    InvalidColumnsSelection,
    UnsupportedTypeInColumnsSelection,
    InvalidChartContainerElementId,
    InvalidDate,
    FailedToCreateVisualization,
    EmptyPie
}

CustomError

class ChartError extends Error {
    errorCode: ErrorCode;
}

See ErrorCode

DateFormat


export enum DateFormat {
    FullDate       // The full date and time. For example: 12/7/2019, 2:30:00.600
    Time           // The full time, without the milliseconds. For example: 2:30:00
    FullTime       // The full time, including the milliseconds. For example: 2:30:00.600
    HourAndMinute  // The hours and minutes. For example: 2:30
    MonthAndDay    // The month and day. For example: July 12th
    MonthAndYear   // The month and day. For example: July 2019
    Year           // The year. For example: 2019
}

DrawChartStatus


export enum DrawChartStatus {
    Success = 'Success',   // Successfully drawn the chart
    Failed = 'Failed',     // There was an error while trying to draw the chart
    Canceled = 'Canceled'  // The chart drawing was canceled
}

See 'onFinishDataTransformation' return value in IChartOptions for more information regarding drawing cancellation

IColumn

type IRowValue = string | number;
type ISeriesRowValue = IRowValue | string[] | number[];
type IRow = IRowValue[];
type ISeriesRow = ISeriesRowValue[];

interface IColumn {
    name: string;
    type: DraftColumnType;
}

IQueryResultData

interface IQueryResultData {
    rows: IRow[] | ISeriesRow[];
    columns: IColumn[];
}

See IColumn

ISupportedColumns

interface ISupportedColumns {
    xAxis: IColumn[];
    yAxis: IColumn[];
    splitBy: IColumn[];
}

See IColumn

DraftColumnType

See: https://kusto.azurewebsites.net/docs/query/scalar-data-types/index.html

enum DraftColumnType {
    Bool,
    DateTime,
    Decimal,
    Dynamic,
    Guid,
    Int,
    Long,
    Real,
    String,
    TimeSpan
}

ISupportedColumnTypes

interface ISupportedColumnTypes {
    xAxis: DraftColumnType[];
    yAxis: DraftColumnType[];
    splitBy: DraftColumnType[];
}

See DraftColumnType

Test

Unit tests are written using Jest.

Run tests: npm run test

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.