Last Updated: 23 February 2015

Table of Contents

Dataclips allow the results of SQL queries on a Heroku Postgres database to be easily shared. Simply create a query on, and then share the resulting URL with co-workers, colleagues, or the world. The recipients of a Dataclip are able to view the data in their browser or download it in JSON, CSV, XML, or Microsoft Excel formats.

Creating Dataclips

  1. From within the Dataclips dashboard, when logged in, click on Create Clip.

  2. Enter your query into the area, choose a database and name your clip:

  3. Click create Dataclip


Dataclips can be accessed in several forms:

  • JSON
  • CSV
  • XLS

You may access each format by selecting the format from the Dataclips menu, or by appending the file format to the URL of the Dataclip.

The JSON endpoint is handy for prototyping APIs but should not be used as a replacement for a production API. The JSON endpoint also supports Cross-Origin Resource Sharing (CORS) on GET requests to a clip’s JSON URL.

Interacting with Dataclips

Dataclips provides the ability to access all previous versions of your query and previous result sets as well. You can access previous versions and results from within the menu on a specific Dataclip. You may also access previous versions and results if you have a direct URL to a Dataclip as well, including with specific file formats.

Given an example Dataclip - you could access it in several forms when getting the csv format:

  • The latest results in csv by adding .csv to the url
  • The first version of the Dataclip created by adding .csv and ?version=1
  • The first version of the Dataclip and its first result set by adding the above and result=1

Data refresh

When accessing a Dataclip through any means (html/csv/json/xls), it will immediately show the last available results.

The query will also be run again if the last results are older than 1 minute.

If viewing on the web, it will alert you if there is a new result set available.

Queries that take longer than 10 minutes to run are automatically cancelled.

When connecting your Dataclips to Google Docs, Google caches the clip on an hourly basis.


All Dataclips are secured through unique un-guessable URLs. Standard, Premium and Enterprise tier databases also have the ability to secure Dataclips to a heroku user account.


  • Dataclips may return up to 100,000 rows
  • Dataclips can only be secured via authentication on Standard, Premium and Enterprise tier databases
  • Dataclips will cancel queries after 10 minutes.