# Overview {% hint style="info" %} ChartSQL.js is currently in development. Documentation is for feedback purposes. {% endhint %} ChartSQL.js is an open source library to chart SQL (or any table like data) seamlessly within any web application. We have designed ChartSQL.js to be the easiest to use JavaScript charting library available. #### Key Benefits * Simple .js integration * Supports any SQL table-like or NoSQL source of data * Full rendering control with intuitive 'directives' * What You Query is What You Chart (Whikee-Whic) - Simple and declarative charting. ## Minimal Example The following is all that is required to create a basic column chart {% tabs %} {% tab title="Code" %} ```javascript // Sample data, typically retrieved from an executed SQL query or API call var data = [ {category: 'shoes', total_sales: 5000}, {category: 'pants', total_sales: 10000}, {category: 'shirts', total_sales: 8000}, {category: 'socks', total_sales: 4000} ]; // Render the data into a chart chartsql.createChart({ // Target HTML element id to place the chart, or one // will be created and appended to the body target: 'auto-column', // The data for the chart data: data }); ``` {% endtab %} {% tab title="Chart" %}

An example auto generating column chart

{% endtab %} {% tab title="Codepen" %} {% embed url="" %} {% endtab %} {% endtabs %} ## Quick Start 1. Add `chartsql.js` to Your Project and setup a basic column chart ```html
``` ## createChart({}) `createChart()` allows you to render data into chart visuals at the target HTML element The typical flow is: * Setup ChartSQL * Fetch data * call `createChart()` to render the data into a chart. ### Parameters
ParameterRequired?Description
targetnoThe DOM element ID where the chart will be rendered.
datayesAn object containing the data to be used for rendering the chart. See Working with Data
directivesyesSQL string containing directives, or object of directives.
## Auto Charts ChartSQL.js will try to automatically choose a basic chart type depending on the fields in your data. The auto charts helps you quickly visualize and explore data and then you can [Customize Charts](#customizing-charts) for more control. * [Auto Column](#auto-column-chart) * [Auto Grouped Column](#auto-grouped-column-chart) * [Auto Date Line](#auto-date-line-chart) ### Auto Column Chart When there is one string and one numeric field in the data ```javascript {category: 'shoes', total_sales: 5000} ``` {% tabs %} {% tab title="Chart" %}
{% endtab %} {% tab title="Code" %} ```javascript // Sample data, typically retrieved from an executed SQL query or API call var data = [ {category: 'shoes', total_sales: 5000}, {category: 'pants', total_sales: 10000}, {category: 'shirts', total_sales: 8000}, {category: 'socks', total_sales: 4000} ]; // Render the data into a chart chartsql.createChart({ // Target HTML element id to place the chart, or one // will be created and appended to the body target: 'auto-column', // The data for the chart data: data }); ``` {% endtab %} {% endtabs %} ### Auto Grouped Column Chart When there is one string and 2 or more numeric fields the numeric fields will be grouped ```javascript {category: 'shoes', total_sales: 5000, total_profit: 2000} ``` {% tabs %} {% tab title="Chart" %}
{% endtab %} {% tab title="Code" %} ```javascript var data = { columns: ['category', 'total_sales', 'total_profit'], rows: [ ['shoes', 5000, 2000], ['pants', 10000, 4000], ['shirts', 8000, 3000], ['socks', 4000, 1000] ] } chartsql.createChart({ target: 'auto-grouped-column', data: data, directives: { } }); ``` {% endtab %} {% endtabs %} ### Auto Date Line Chart When there is a date field and a numeric field ```javascript {month: '2022-01-01', total_sales: 5000} ``` {% tabs %} {% tab title="Chart" %}
{% endtab %} {% tab title="Code" %} ```javascript // Sample data, typically retrieved from an executed SQL query var data = [ {month: '2022-01-01', total_sales: 5000}, {month: '2022-02-01', total_sales: 7000}, {month: '2022-03-01', total_sales: 4900}, {month: '2022-04-01', total_sales: 7528}, {month: '2022-05-01', total_sales: 7762}, {month: '2022-06-01', total_sales: 8000}, {month: '2022-07-01', total_sales: 9500}, {month: '2022-08-01', total_sales: 8250}, {month: '2022-09-01', total_sales: 9000}, {month: '2022-10-01', total_sales: 8500}, {month: '2022-11-01', total_sales: 9500}, {month: '2022-12-01', total_sales: 10000} ] // Render a chart at the target element with the data provided chartsql.createChart({ target: 'auto-dateline', data: data }); ``` {% endtab %} {% endtabs %} ## Customizing Charts You can specify exactly how to render the chart with directives (aka @directives). Directives allow you to fully control the type of chart and the selection of the categories, series formats and other ChartSQL.js features. ### Basic Directives Example `createChart()` takes a 'directives' object which contains the directives for controlling rendering of the chart. {% tabs %} {% tab title="Code" %} ```javascript // Sample data, typically retrieved from an executed SQL query var data = [ {category: 'shoes', total_sales: 5000}, {category: 'pants', total_sales: 10000}, {category: 'shirts', total_sales: 8000}, {category: 'socks', total_sales: 4000} ] // Render a chart at the target element with the data provided chartsql.createChart({ target: 'basic-bar', data: data, directives: { chart: 'bar' } }); ``` {% endtab %} {% tab title="Chart" %}
{% endtab %} {% endtabs %} ### Common Directives * chart - The type of chart: bar, column, line etc * category - The column to use for the category (primary axis) of the chart * series - The column/s to use for the data (secondary axis) of the chart * formats - The data formats to render for the series You can [See All Directives](https://docs.chartsql.com/reference/directives) for all the ways in which you can customize your charts. {% hint style="info" %} ChartSQL.js is currently in development and does not support all directives. See the [Supported Directives](#directives) section for current support {% endhint %} ### Directives in SQL ChartSQL's namesake comes from the fact that you can define your chart directives within SQL source code. The same capability is provided to you in ChartSQL.js. If your data is already coming from an executed SQL script, you can also choose to define your directives in your SQL. You pass the full SQL script to createChart directives and it will get parsed {% tabs %} {% tab title="Code" %} ```javascript var sql = ` -- @chart: bar SELECT category, total_sales FROM sales `; // Sample data as if retrieved from an executed SQL query var data = [ {category: 'shoes', total_sales: 5000}, {category: 'pants', total_sales: 10000}, {category: 'shirts', total_sales: 8000}, {category: 'socks', total_sales: 4000} ] // Render a chart at the target element with the data provided chartsql.createChart({ target: 'basic-sql', data: data, directives: sql }); ``` {% endtab %} {% tab title="Chart" %}
{% endtab %} {% endtabs %} ## Working with Data ChartSQL.js is designed to work with table like data of columns and rows. Typically this data will come from executing a SQL query, but data from any source can be charted. The `createChart()` method liberally accepts table data in a few different formats. ### Array of Objects ```javascript var data = [ { category: 'shoes', total_sales: 5000 }, { category: 'pants', total_sales: 10000 }, { category: 'shirts', total_sales: 8000 }, { category: 'socks', total_sales: 4000 } ]; ``` ### Array of Arrays The first row in the array should be the column names ```javascript var data = [ ['category', 'total_sales'], ['shoes', 5000], ['pants', 10000], ['shirts', 8000], ['socks', 4000] ]; ``` ### Table Object ```javascript var data = { columns: ['category', 'total_sales'], rows: [ ['shoes', 5000], ['pants', 10000], ['shirts', 8000], ['socks', 4000] ] }; ``` ### Data Class If desired, you can instantiate your own instance of the Data.js class that ChartSQL creates internally. ```javascript var data = new ChartSQLjs.Data({ columns: ['category', 'total_sales'], rows: [ ['shoes', 5000], ['pants', 10000], ['shirts', 8000], ['socks', 4000] ] }); ``` ## Relationship to ChartSQL Studio, Datasources, Dashboards & Extensions ChartSQL.js is the parsing and rendering layer. It does not handle managing and executing SQL against datasources, creating dashboards, or editing SQL Charts. ## Supported Features ChartSQL.js is a subset of ChartSQL Studio and Dashboard Features. See the tables below of supported features * ✔️ = fully supported * ❌ = no support planned * ☐ = support planned * 〰️ = Partial support ### Auto Charts List of [auto-charts](https://docs.chartsql.com/reference/auto-charts "mention") charts that are currently supported
Auto ChartChartSQL.jsChartSQL Studio
Column✔️✔️
Grouped Column✔️✔️
Date-based Line✔️✔️
Datetime based line✔️✔️
Stacked-Grouped Column☐✔️
Scatter✔️✔️
Bubble (scatter with size)☐✔️
Heatmap☐✔️
### Chart Types List of Chart Types that are currently supported | Type | ChartSQL.js | ChartSQL Studio | | ------- | ----------- | --------------- | | Area | ☐ | ✔️ | | Bar | ☐ | ✔️ | | Bubble | ☐ | ✔️ | | Column | ☐ | ✔️ | | Combo | ☐ | ✔️ | | Gauge | ☐ | ✔️ | | Heatmap | ☐ | ✔️ | | Line | ☐ | ✔️ | | Pie | ☐ | ✔️ | | Radar | ☐ | ✔️ | | Scatter | ☐ | ✔️ | ### Directives
DirectiveChartSQL.jsChartSQL StudioNote
@baselines☐✔️
@baseline-types☐✔️
@chart✔️✔️
@cateogry✔️✔️
@formats☐✔️
@secondary-series☐✔️
@series✔️✔️
@title☐✔️
@subtitle☐✔️
@groups☐✔️
@series-types☐✔️
@series-labels☐✔️
@stacking-mode☐✔️
@dash-id❌✔️Only used for publishing to ChartSQL cloud. No use for ChartSQL.js
@overlay-series☐✔️
@tags❌✔️Used for searching inside ChartSQL Studio and dashboards. Not used by ChartSQL.js
@mongodb-query❌✔️Only used by ChartSQL Studio
### Other Capabilities | Capability | ChartSQL.js | ChartSQL Studio | Note | | --------------- | ----------- | --------------- | ------------------------------------------------------------ | | Series Assist | ✔️ | ✔️ | Assists when selecting series and no @series is defined | | Category Assist | ✔️ | ✔️ | Assists in selecting categories when no @category is defined | | | | | |