Last updated 23 February 2015
Dataclips allow the results of SQL queries on a Heroku Postgres database to be easily shared. Simply create a query on dataclips.heroku.com, 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.
From within the Dataclips dashboard, when logged in, click on Create Clip.
Enter your query into the area, choose a database and name your clip:
Click create Dataclip
Dataclips can be accessed in several forms:
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 - https://dataclips.heroku.com/vgyygvzqtezwpmwpcmmjlluamjlk 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
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.