Last updated 29 September 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 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 Create Dataclip.
Name your Dataclip, choose a database, and type your query into the area:
Click Create Dataclip.
Dataclips can be accessed in several formats:
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 provide 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 URLs that are unique and difficult to guess. Standard, Premium and Enterprise tier databases also have the ability to secure Dataclips to a Heroku user account.
To configure security permissions for a Dataclip, from the Dataclip’s page click Settings, modify the security permissions and then click Save Permissions.
When a database is upgraded or migrated to a different database, for example as a result of upgrading, the Dataclips associated with the old database become orphaned and require recovery.
To recover these dataclips, go to the Dataclips listing and click Recover Dataclips to navigate to your recoverable Dataclips. A list of orphaned Dataclips is shown, which can be assigned to the appropriate database.
- 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.