This endpoint lets you export data from a workbook, facilitating the retrieval of large datasets in a structured format. You can specify filters, format options, and the scope of data to be exported, such as specific tables or columns. The export operation supports various file formats including CSV, PDF, JSON and others, accommodating diverse integration needs and downstream processing requirements.
The endpoint also offers parameters for asynchronous processing, allowing users to initiate an export job and retrieve the data after it is ready, which is essential for handling large data volumes efficiently. This makes it suitable for applications that require regular data dumps or ad-hoc data extraction for analysis and reporting purposes.
Usage Notes
At this time, the workbook export endpoint can be used to export the entire workbook, a single workbook page, or an individual element. Different formats are supported for different export choices. See Send or schedule workbook exports for details on supported formats for different types of exports.
There is a 1 million row export limit for CSV/XLSX/JSON types. To export more rows, you can batch your requests in up to 1 million row chunks using the "rowLimit" and "offset" parameters, or you can use another export method such as exporting to Cloud Storage, which has a 5GB size limit per export.
If your request is successful, the API returns a queryId to associate with your workbook export request. You can then use this queryId to download the file using the /v2/query/{queryId}/download endpoint. See Download an exported file.
For security and privacy reasons, the queryId expires 1 hour after your export request has been received and the file becomes available for download. This default expiration time can be extended to up to 6 hours using the "resultsValidityTimeMs" request parameter.
Usage Scenarios
- Data Backup: Users can schedule regular exports to back up critical data from their warehouse.
- Data Analysis: Analysts can export specific datasets for offline analysis, leveraging tools that may not directly connect to the warehouse.
- Integration: Enables the integration of warehouse data with other applications, providing the necessary data in a format that these applications can process.
Best Practices
- Use the asynchronous export option for large datasets to avoid timeouts and ensure system stability.
- Clearly specify the scope and filters to retrieve only the necessary data, optimizing performance and reducing network load.
- Check the status of asynchronous exports regularly and implement error handling to manage incomplete or failed exports gracefully.