Community docs

Chart Builder

One of the most powerful ways to share results of your data analysis is through visualizations. On you have access to integrations for many third-party tools and also to Chart Builder, a visual editor for Vega-Lite built specifically for It is the perfect tool for those looking to create a simple visualization that is lightweight and easy to embed.

Visualizations in Chart Builder can be made from either a file or a query. They can be saved in various formats, shared, or embedded in the various Simple Editor windows.

Using Chart Builder with files

You can create visualizations of tabular data files in either projects or datasets without ever writing a query. To follow along with this example, open the dataset Shark attack data updated daily. To create a visualization of all the data in the file, select the View icon to the right of the file name on the overview page:


You'll be taken to the data workspace and a view of all the data in the file. Next, click the dropdown arrow next to Open in app and choose Open with Chart Builder:


If you're using Chart Builder for the first time, you'll be directed to a page requesting authorization. After authorizing, you'll be redirected to the Chart Builder workspace.

Chart Builder comes with two options for creating and modifying charts: a Visual Builder and a Vega-Lite Editor. The easiest way to use it is to create your initial chart on the Visual Builder tab and then switch over to the Vega-Lite Editor to make any changes outside the scope of the Visual Builder. See our article on using Vega-Lite or the Vega-Lite website for more information.

To create a quick bar chart of the number of people in the dataset who have been fatally attacked by sharks, select the field fatal_y_n from the dropdown list for the X axis, and COUNT(*) from the bottom of the list on the Y axis. Like magic, our chart appears on the right side of the screen:


Using Chart Builder with queries

Chart Builder can also be used on queries. Using a query as the basis for your chart enables you to:

  • Clean up data (e.g., remove NULL values)

  • Filter out data (e.g., specify a time period, a specific value, an aggregation, etc.)

  • Change your data structure so that it can be charted

In the shark attack dataset referenced above there is a saved query called Query for analysis by year or country This query has been written to exclude NULL values and remove non-binary entries on specific fields. It can be used to create a number of different charts. Click the dropdown arrow next to Open in app and choose Open with Chart Builder:


Formatting options for visualizations

Continuing with the example above, to make a chart with circles for marks that compares the number of attacks on men vs on women across the years select Circle from the Marks dropdown, and year from the X axis dropdown:


If the axis doesn't display the way you want it to, you can override the default format for the Type under the Options dropdown. In this case the year was read as a number because of the underlying data type and the type was set to Quantitative when Ordinal was the right choice:


Set the Y axis to COUNT(*) and Color to sex:


If your chart is not appropriately sized for viewing you can manually set the chart size. A size that shows the data of this chart to best effect is a width of 950 and a height of 730:


Another handy thing you can do in the options section is order the results in your graph. You may have ordered them already in your query results, but that order does not carry over to the graph. For this example we'll use the saved query Countries with >10 unprovoked attacks since 1960 with mortality data. After running the query, click Chart, set the X axis to country and the Y axis to # attacks:


To sort by the country with he most attacks select Options on the X axis, choose Descending for the sort and y - # attacks on the field:


To add information on if the attacks were fatal or not, select fatal_y_n next to color.


If your results do not seem to display as they should, check to make sure the field you are sorting on is not being improperly aggregated. Being able to switch over to the Vega-Lite Editor is very handy for identifying this kind of configuration issues. Looking in the Vega-Lite Editor in the area dealing with "sort" the operation is set to "average":


In this case "sum" is the correct option, and upon replacing "average" with "sum" the visualization displays properly:


NOTE: Once you have made edits in the Vega-Lite Editor you can no longer make any changes in the Visual Builder so save your Vega-Lite Editor changes for when you are finished building the chart with the Visual Builder.

Saving and sharing visualizations

Chart-builder visualizations on can be saved in a number of json, image, and html formats shown under the Download button:


There are also a variety of options for sharing your visualization on


Selecting Share > Insight lets you add your visualization to any project on for which you have permission. To share the insight you are prompted to chose a project where you will share it, to give it a title, and optionally to add comments. The final option (selected by default) is to save the visualization as a Vega-Lite source file on the project.

Share > File lets you add the visualization to any dataset or project for which you have permission. Share > Markdown Embed (Comment) you can embed your chart in any place which uses Markdown (e.g., insights, comments, summaries). By default the embedded chart will be a static rendering of the data from when the visualization was created. However using the Vega-Lite Editor you can create a 'live' chart that updates as the data on which it's based updates. The shark attack dataset is an example of continually-updating data.

To make a chart 'live', go to the Vega-Lite Editor and scroll down to the section referencing the "data" parameters:


Under the "data" element replace "source" with "url" and add a hardcoded url for the query that drives the visualization (you get this in the workspace while viewing the query), and add a "format" element with the type "csv":


Then when you select Share > Markdown Embed (Comment), you'll get Markdown text for a live version of the visualization that you can copy and paste into Insights, Comments, and Summaries on


Here is an example of the live visualization above used as an insight on a project that uses the dataset:


Finally, if you want to share a link to the Chart Builder screen for the visualization so someone else can edit and run it, you can do so with the Share > URL option:



Error loading data

An expired token can cause one to receive a "Error loading data." message when opening Chart Builder. To remedy this:

  • Click on your account avatar on the top right corner of and go to 'Your integrations'

  • Select the Chart Builder tile

  • On the Chart Builder page, select the Manage tab

  • Click the Revoke button and disconnect the Chart Builder integration

  • Click the Enable integration button and authorize access

Re-launching Chart Builder will now allow it to fetch the data successfully

Blank chart

When using the Vega-Lite editor to modify the Chart Builder output, many errors cause a blank chart to display. Troubleshooting must be manually carried out in this case - the Vega-Lite editor does not include any error identification functionality.

Using multiple columns of data in Chart Builder visualizations

Chart Builder is a quick and easy tool for creating visualizations of data on the fly, but there is one thing that isn't easy to do with it: include data from more than one column in your graph. This limitation can be a real problem if, say, you want to look at both the high and low temperatures on the days when Bigfoot was sighted. Or if you want to have a graph with gender, attack type, and fatality in shark attacks so you can see if there is any correlation between them. Though you can easily run the queries to display the data, you can't obviously render it all at the same time in Chart Builder. However, though it is a bit tricky and requires the use of UNPIVOT, you can build visualizations in Chart Builder that include data from more than one column in a query.

In this article we'll use the Project Monsters Among Us to show how to include two related fields in a visualization, and Analysis of shark attacks by region and species to do a little fancier combination of multiple columns of unrelated data into one visualization.

How to show data from two related fields in a Chart Builder visualization

There is a query called High and low temperatures on the dates of Bigfoot sightings in the Monsters project that returns a simple table with three columns:


Click on the Chart icon above the results to build a quick visualization from the query results. Set the X axis to date, the Y axis to temperature_low, and you have a visualization, but where do you put temperature_high?:


Looking at the data, the solution is to put both the high temp and the low temp values in the same column and call it temperature, and to have another column called temp_value that would indicate whether the temp shown is a high temp or a low temp for the day. Fortunately, this kind of data reorganization where columns get collapsed into rows is what the SQL UNPIVOT command does. Here is the original query rewritten to use UNPIVOT to collapse the high and low temp columns into one column, and the resulting table:


Select Chart to use Chart Builder on the results of the query, set the marks to Circle, the X axis to date, the Y axis to temperature, the color to temp_type, resize the chart toto 640 X 700, and you'll have this visualization:

Combining multiple columns of unrelated data into one visualization

In this example we have a query in the project Analysis of shark attacks by region and species that returns dates, type of attack, gender of the victim, and whether the attack was fatal or not:


To get a quick visualization of it select Chart, setCircle for marks,year for the X axis (you might have to open the options and set the type to Ordinal), COUNT (*) for the Y axis, and Gender for the color. Once it's been resized you get this chart:


As in the last example, there's no way to include attack-type or fatality data. However, a redo of the original query with UNPIVOT combines all the data into one column ready for Chart Builder:


Note: Even though there is a warning that only the first 10,000 rows of the results are displayed, when we chart the query with chart Builder, all the data is used in the visualization.

The chart from the query is built the same as before. SetCircle for marks,year for the X axis (you might have to open the options and set the type to Ordinal), COUNT (*) for the Y axis. Set Type for the color. Once it's been resized you get this chart::


If you want to try unpivoting some queries on your own and charting them, there are a couple more--Provocation and gender in shark attacks, and Provocation and fatality in shark attacks--saved on the project that you can use.

Additional information about UNPIVOT can be found in our SQL documentation.

Using the Vega Lite editor in Chart Builder

Chart Builder uses Vega-Lite, which provides a JSON syntax for creating and styling visualizations. While the Visual Builder interface within Chart Builder on allows one to quickly generate a simple chart, using the Vega Lite editor allows extensive customization of the appearance of the chart.

One important note - once you modify a chart using the Vega Lite editor, the Visual Builder will no longer be accessible. Customize the chart as much as possible in the Visual Builder first before switching to the Vega Lite editor for fine-tuning to keep yourself from needing to do extra work.

This article assumes that you have already enabled the Chart Builder integration on your account. If you have not already, you can enable it from the integrations page while logged into your account.

For a primer on using Chart Builder, please see the Data visualization with Chart Builder.

Getting started

As an example, I've created a project based on a dataset from the US Department of Energy regarding types of energy production throughout the US.

  1. Open up the following query saved to that project: Top 10 states by residential solar energy production

  2. You can then open these query results in Chart Builder using the dropdown menu above the results pane:

  3. Title the chart "Rooftop photovoltaic energy production by US state (top 10)" by clicking on the text that says Untitled chart above.

  4. To the left of the chart, configure the the X axis to use the state field and the Y axis to use the gwh field.

  5. Click on the Options dropdown for the X axis, and under the Sort section, choose Descending by y - gwh.


You will then see the same chart as below:


That's a good start, but it's a bit bland and would be difficult to read if projected onto a screen across a conference room. Let's get to work!

Styling the chart title

By default, a Chart Builder adds the title automatically, but does not provide any graphical way to style it. Click on the Vega Lite editor on the top left and you'll see the following entry near the top:

"title": "Rooftop photovoltaic energy production by US state (top 10)"

To transform the title into a field that we can customize, make it into a JSON object by adding curly braces and adding the text property:

"title": {"text": "Rooftop photovoltaic energy production by US state (top 10)" }

The title will look the same as before, but we've laid the foundation for further styling by turning it into a JSON object.


The anchor attribute determines the horizontal alignment of the title. Options include:

  • start

  • middle

  • end

In our example, let's align the title on the left side of the chart:

"title": {
   "text": "Rooftop photovoltaic energy production by US state (top 10)",
   "anchor": "start"

We'll use the following attributes to style the font used for the title:

  • font - the name of the font

  • fontSize - the size of the font in pixels

  • color - color of the font, given in a CSS-compatible hex code or color name

This attributes are great for matching the chart to an organization's own branding guidelines. Make the following update to give the title that authentic feel:

"title": {
   "text": "Rooftop photovoltaic energy production by US state (top 10)",
   "anchor": "start",
   "font": "Lato",   "fontSize": 24,   "color": "#355D8A"

Our title is looking much better now, but there isn't much space between it and the chart beneath it. Give it some breathing room by adding the offsetattribute. The offset value is the number of pixels between the title and the edge of the chart.

"title": {
   "text": "Rooftop photovoltaic energy production by US state (top 10)",
   "anchor": "start",
   "font": "Lato",
   "fontSize": 24,
   "color": "#355D8A",
   "offset": 40

And here's the result so far:

Styling the axis labels

To modify the axis labels (in this case, the names on the x-axis andnumbers on on the y-axis), we'll add some additional attributes within the configobject already present in our Vega Lite editor. By default, the config object will look like:

"config": {
   "background": "#ffffff",
   "padding": 20,

Within that configobject, add a new object called axis to modify the labels on both the X and Y axes at the same time. That object will accept a number of attributes; we'll use the following:

  • labelFontSize - label font size in pixels

  • labelFont - label font name

  • labelColor - color of the label font, given in a CSS-compatible hex code or color name

Our config object now looks like this:

"config": {
   "background": "#ffffff",
   "padding": 20,
   "axis": {     "labelFontSize": 20,     "labelFont": "Lato",     "labelColor": "#6290C3"   }

We modified labels for both axes above, but we can also style axes singly as well. The state names under the X axis are difficult to read with their current orientation, so change that by adding an axisX object within the config object.

Use the labelAngle attribute to control the angle of those labels, providing the number of degrees to rotate them.

"config": {
   "background": "#ffffff",
   "padding": 20,
   "axis": {
     "labelFontSize": 20,
     "labelFont": "Lato",
     "labelColor": "#6290C3",
     "titleFontSize": 24,
     "titleColor": "#333D49",
     "titleFont": "Lato"
   "axisX": {     "labelAngle": 40   }
Styling the axis titles

Our labels are much more readable now, but we need to update those state and gwh axis titles as well. For those, specify the following attributes within the config>axis object:

  • titleFont - axis title font name

  • titleFontSize - axis title font size in pixels

  • titleFontColor - color of the axis title font, given in a CSS-compatible hex code or color name

"config": {
 "background": "#ffffff",
 "padding": 20,
 "axis": {
   "labelFontSize": 20,
   "labelFont": "Lato",
   "labelColor": "#6290C3",
   "titleFontSize": 24,   "titleColor": "#333D49",   "titleFont": "Lato"

Finally, let's edit the title text for each axis (e.g. state and gwh). This will use the column name from our query results by default. In our case, those titles aren't so bad, but in many cases they'll be difficult to read and full of underscores and abbreviations.

Navigate to the encoding object within the Vega Lite editor. It will have a number of nested objects below it already. Find the nested object encoding>x. Add and attribute called title and provide the desired name to that attribute - in this case, give it the value "State Name".

Also add a title attribute under encoding>y and provide the value "Gigawatt hours (GWh)".

Here's our new encoding object:

"encoding": {
 "x": {
   "field": "state",
   "title": "State Name",
   "type": "nominal",
   "sort": {
     "field": "gwh",
     "op": "sum",
     "order": "descending"
   "scale": {
   "type": "linear",
   "zero": true
 "y": {
   "field": "gwh",
   "title": "Gigawatt hours (GWh)",
   "type": "quantitative",
   "scale": {
     "type": "linear",
     "zero": true

And our final chart:


This tutorial provided some basic styling functionality by accessing the Vega Lite editor in Chart Builder directly, but it can do so much more. Check out the official Vega Lite examples, tutorials, and full documentation for an in depth look.