Skip to main content

Data visualization with Chart Builder

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.