Deep-dive on the Next Gen Platform. Join the Webinar!

Skip Navigation
Show nav
Dev Center
  • Get Started
  • Documentation
  • Changelog
  • Search
  • Get Started
    • Node.js
    • Ruby on Rails
    • Ruby
    • Python
    • Java
    • PHP
    • Go
    • Scala
    • Clojure
    • .NET
  • Documentation
  • Changelog
  • More
    Additional Resources
    • Home
    • Elements
    • Products
    • Pricing
    • Careers
    • Help
    • Status
    • Events
    • Podcasts
    • Compliance Center
    Heroku Blog

    Heroku Blog

    Find out what's new with Heroku on our blog.

    Visit Blog
  • Log inorSign up
Hide categories

Categories

  • Heroku Architecture
    • Compute (Dynos)
      • Dyno Management
      • Dyno Concepts
      • Dyno Behavior
      • Dyno Reference
      • Dyno Troubleshooting
    • Stacks (operating system images)
    • Networking & DNS
    • Platform Policies
    • Platform Principles
  • Developer Tools
    • Command Line
    • Heroku VS Code Extension
  • Deployment
    • Deploying with Git
    • Deploying with Docker
    • Deployment Integrations
  • Continuous Delivery & Integration (Heroku Flow)
    • Continuous Integration
  • Language Support
    • Node.js
      • Node.js Behavior in Heroku
      • Working with Node.js
      • Troubleshooting Node.js Apps
    • Ruby
      • Rails Support
      • Working with Bundler
      • Working with Ruby
      • Ruby Behavior in Heroku
      • Troubleshooting Ruby Apps
    • Python
      • Working with Python
      • Background Jobs in Python
      • Python Behavior in Heroku
      • Working with Django
    • Java
      • Java Behavior in Heroku
      • Working with Java
      • Working with Maven
      • Working with Spring Boot
      • Troubleshooting Java Apps
    • PHP
      • Working with PHP
      • PHP Behavior in Heroku
    • Go
      • Go Dependency Management
    • Scala
    • Clojure
    • .NET
      • Working with .NET
  • Databases & Data Management
    • Heroku Postgres
      • Postgres Basics
      • Postgres Getting Started
      • Postgres Performance
      • Postgres Data Transfer & Preservation
      • Postgres Availability
      • Postgres Special Topics
      • Migrating to Heroku Postgres
    • Heroku Key-Value Store
    • Apache Kafka on Heroku
    • Other Data Stores
  • AI
    • Working with AI
    • Heroku Inference
      • AI Models
      • Inference Essentials
      • Inference API
      • Quick Start Guides
  • Monitoring & Metrics
    • Logging
  • App Performance
  • Add-ons
    • All Add-ons
  • Collaboration
  • Security
    • App Security
    • Identities & Authentication
      • Single Sign-on (SSO)
    • Private Spaces
      • Infrastructure Networking
    • Compliance
  • Heroku Enterprise
    • Enterprise Accounts
    • Enterprise Teams
    • Heroku Connect (Salesforce sync)
      • Heroku Connect Administration
      • Heroku Connect Reference
      • Heroku Connect Troubleshooting
  • Patterns & Best Practices
  • Extending Heroku
    • Platform API
    • App Webhooks
    • Heroku Labs
    • Building Add-ons
      • Add-on Development Tasks
      • Add-on APIs
      • Add-on Guidelines & Requirements
    • Building CLI Plugins
    • Developing Buildpacks
    • Dev Center
  • Accounts & Billing
  • Troubleshooting & Support
  • Integrating with Salesforce
  • Databases & Data Management
  • Heroku Postgres
  • Postgres Basics
  • Sharing Query Results with Dataclips

Sharing Query Results with Dataclips

English — 日本語に切り替える

Last updated May 02, 2024

Table of Contents

  • Quickstart
  • Creating Dataclips
  • Viewing Results
  • Dataclip Access and Visibility
  • Sharing Dataclip Results
  • Downloading Results
  • Dataclip Execution and Data Freshness
  • Dataclip Recovery
  • Limits and Restrictions

Heroku Dataclips enable you to create SQL queries for your Heroku Postgres databases and share the results with colleagues, third-party tools, and the public. Recipients of a dataclip can view the data in their browser and also download it in JSON and CSV formats.

Dataclips can’t connect to Shield databases.

Quickstart

  1. Visit data.heroku.com/dataclips and click New Dataclip: Image showing the "New Dataclip" button

  2. Specify a title for your dataclip and a Heroku Postgres database to run it against. Type your SQL query into the main text area like so: Screenshot of the clip creation screen

  3. Click Save & Run. The query’s results appear in a table below the query.

Creating Dataclips

The Schema Explorer

The Schema Explorer displays table and column information for your dataclip’s associated database, including the data type for each column:

Screenshot of a populated schema exporer

For larger schemas, you can filter the information displayed by typing in the text box at the top of the Schema Explorer.

The Schema Explorer automatically updates to reflect the schema of whichever database is selected for the dataclip.

Editor Autocomplete

The query editor offers autocompletion suggestions as you type. These suggestions are based on the schema of the selected database, as well as the syntax and functions of the Postgres SQL dialect:

Screenshot of autocomplete offering options inside the query editor

Viewing Results

Whenever you save a dataclip with a valid query, the query is executed and its results are displayed in a table below the query:

A Dataclip displaying a table of results

Chart Display

If your dataclip’s results include both a column of date or timestamp data and a column of numeric data, you can display the results as a chart. The toggle above the results table activates when displaying a chart is possible:

Animated recording of toggling between chart and tabular results

Chart display is possible when all of the following are true about the dataclip’s results:

  • There are two or more columns.
  • For timeseries data: One of the columns is a date or timestamp and another is numeric.
  • For categorical data: One of the columns is a category (string) and the other is numeric.
  • There are between 10 and 1,000 rows.

Dataclip Access and Visibility

All Heroku users who are collaborators on an app can access and edit dataclips that are created on the app’s associated database. You can view an app’s collaborators via either the Heroku CLI or the Heroku Dashboard.

If an Enterprise Team owns the app, a team member must also have the deploy or operate permissions for the app to receive access to dataclips.

In all cases, users must have access to the default credential for the database.

A Heroku Postgres database can be attached to a Heroku app that doesn’t own it. To view dataclips for a particular database, a Heroku user must have the necessary permissions for the app that owns the database. It’s insufficient to have permissions for an app that the database is only attached to.

Sharing Dataclip Results

You can share a dataclip’s results with specific people, teams, or the general public. Sharing results this way doesn’t expose the dataclip’s query, or any other information about the underlying application (such as the app name, database details, or the dataclip creator’s email address).

After you create a dataclip you want to share, click the Share button:

Screenshot of header with share button

The sharing flyout appears:

Screenshot of data.heroku.com with the Dataclip sharing flyout visible

Sharing with the Public

To share a dataclip with the public, click Enable next to Shareable Links to generate a unique URL:

Screenshot of data.heroku.com with a shareable Dataclip link

An authenticated Heroku user session isn’t required to access this URL.

The shareable link URL differs from the URL you use to access the dataclip as a collaborator. Make sure to copy the URL from the text box in the sharing flyout, not from your browser’s address bar.

To revoke existing shareable links, click Disable. This revokes access for all visitors, including anyone who’s visited the URL in the past and exported URLs.

To replace existing Shareable Links, simply disable and re-enable it from the sharing flyout. A new URL is generated each time.

Exporting Dataclip Results

To enable a third-party application to consume the results, click Enable next to Shareable Links and copy either the CSV or JSON URL (whichever format the third-party application expects).

Screenshot of data.heroku.com with a exportable Dataclip link

Keep these URLs secret. Anyone with the shareable URL can view your dataclip’s results without authenticating.

If you think that your dataclip’s shareable URL has been compromised. Disabling the URL invalidates the existing shareable links and you can generate new ones. All URLs with the old shareable links immediately stop working.

Google Sheets Integration

Importing the results of a Dataclip into a Google Sheets spreadsheet is an excellent approach to further refinement of data for presentation, or to synthesize the output of multiple Dataclips into dashboards and other artifacts.

To embed a dataclip’s results into a Google Sheets spreadsheet, paste the =IMPORTDATA(...) text from the Shareable Links dialog into cell A1 of the spreadsheet. The =IMPORTDATA(...) string contains the same public URL as the dataclip’s CSV and JSON URLs.

Google Sheets doesn’t hide the contents of the =IMPORTDATA(...) function from viewers. Anyone who can see the spreadsheet is able to copy and paste the CSV URL from the =IMPORTDATA(...) string. You must restrict access to the Google Sheet to ensure that only trusted parties can open it.

Sharing with Individuals and Teams

You can share dataclip results with individual Heroku users, along with Heroku Teams that you belong to. Click the Add button in the sharing flyout to display the following form:

Screenshot of the People and Teams sharing form

To share with an individual, specify their email address and click Add.

You can share dataclip results with any email address. However, that email address must be associated with a Heroku account for the recipient to be able to access the dataclip’s results.

To share with a Heroku Team that you belong to, begin typing the team’s name and select it from the dropdown options that appear:

Animation showing sharing with a team

All members of the selected team can view the dataclip’s results.

To revoke sharing access, click the Delete button next to whichever individual or team you want to revoke access for:

Screenshot of sharing with the delete button under the mouse cursor

Downloading Results

Dataclip results can be downloaded in CSV and JSON formats. To download the results to your local machine as a CSV or JSON file, click the corresponding button in the results section.

Screenshot of download dataclip results buttons

Dataclip Execution and Data Freshness

There’s an important distinction between dataclip execution — the moment when a query is run against your database — and viewing results.

Whenever a dataclip is viewed or downloaded, Heroku executes its query if it hasn’t done so in the last sixty seconds. However, the dataclip doesn’t wait for the new query execution to complete. Instead, it immediately returns the results of its most recently completed execution.

If a dataclip is viewed or downloaded at least one time in the past seven days, Heroku automatically executes its query and updates its results. Heroku does this action about one time per hour whether the results are viewed or downloaded. After seven days of inactivity, Heroku doesn’t execute the query at all until the dataclip is accessed again.

If you keep a dataclip open in your browser, its query is executed every one to two minutes. When a new execution completes, a banner appears on the page to indicate that updated results are available.

Dataclip Recovery

When a database is migrated to a different instance of Heroku Postgres (for example, as a result of upgrading), the dataclips associated with the old database become orphaned and require recovery. These dataclips are shown with the following notice in red in your dataclip list view:

Detached Dataclip

To attach an orphaned dataclip to a new database, visit the dataclip’s detail page:

Re-targeting a Detached Dataclip

Select a new database from the dropdown menu that says Select a datastore, then click Save & Run. The dataclip attaches to the specified database and executes your query.

If you must recover a large number of dataclips, open a support ticket.

Limits and Restrictions

  • Dataclips can be created for any Heroku Postgres databases except Shield Tier plans.
  • A dataclip can return up to 100,000 rows.
  • A dataclip’s results can be at most 104,857,600 bytes in size.
  • Dataclip results that are larger than 26,214,400 bytes in size are downloadable, but you can’t explore the results in your browser.
  • Dataclip queries time out after ten minutes.
  • You can’t share dataclip results with Heroku Teams that you don’t belong to.
  • Unauthenticated users retrieving results from the .csv or .json endpoints are limited to 30 requests per minute per IP.

Keep reading

  • Postgres Basics

Feedback

Log in to submit feedback.

Upgrading the Version of a Heroku Postgres Database Testing PostgreSQL Major Version Upgrades

Information & Support

  • Getting Started
  • Documentation
  • Changelog
  • Compliance Center
  • Training & Education
  • Blog
  • Support Channels
  • Status

Language Reference

  • Node.js
  • Ruby
  • Java
  • PHP
  • Python
  • Go
  • Scala
  • Clojure
  • .NET

Other Resources

  • Careers
  • Elements
  • Products
  • Pricing
  • RSS
    • Dev Center Articles
    • Dev Center Changelog
    • Heroku Blog
    • Heroku News Blog
    • Heroku Engineering Blog
  • Twitter
    • Dev Center Articles
    • Dev Center Changelog
    • Heroku
    • Heroku Status
  • Github
  • LinkedIn
  • © 2025 Salesforce, Inc. All rights reserved. Various trademarks held by their respective owners. Salesforce Tower, 415 Mission Street, 3rd Floor, San Francisco, CA 94105, United States
  • heroku.com
  • Legal
  • Terms of Service
  • Privacy Information
  • Responsible Disclosure
  • Trust
  • Contact
  • Cookie Preferences
  • Your Privacy Choices