Sigma Computing Documentation

Different file formats, including CSV, PDF, JSON, and others, are supported for different export choices. See Send or schedule workbook exports for details on supported formats for different types of exports.

Successful requests to the endpoint return a queryId. Use the queryId with the /v2/query/{queryId}/download endpoint to download the requested file when it is ready. See Download an exported file.

Usage notes

Retrieve the workbookId by calling the /v2/workbooks endpoint.
This endpoint is rate limited to 400 requests per minute.
This endpoint exports up to 1 million rows for CSV/XLSX/JSON file formats. You can export more rows if you batch your requests in chunks of up to 1 million rows. Use the rowLimit parameter to specify the size of the chunk and the offset parameter to specify the row to start the next chunk from. For example, if you specify a rowLimit of 2500, to export the next chunk of 2500 rows, specify an offset of 2501. The order of the data matches the order in the data element when the request is made, so there is a possibility of data overlap between requests.
For security and privacy reasons, the queryId used to download the exported data expires 1 hour after your request is received and the file becomes available to download. You can extend this default expiration to 6 hours using the resultsValidityTimeMs request parameter.
When exporting a PNG file, the pixelWidth and pixelHeight parameters are respected on a best effort basis and the output might not match the requested dimensions.

Usage scenarios

Conditional workbook export: Based on an external set of conditions, export a workbook from Sigma.
Data analysis: Export specific sets of data for offline analysis, leveraging tools that might not connect directly to a data warehouse.
Integration: Integrate enriched and analyzed data with other applications, providing the necessary data in a format that these applications can process.

Best practices

Clearly specify parameters to retrieve only the necessary data, optimizing performance and reducing network load.

This endpoint lets you create a file containing data exported from a workbook, allowing you to retrieve large sets of data in a structured format. Export the entire workbook, a single workbook page, or an individual element. You can specify parameters to filter the data and format options for the file. Different file formats, including CSV, PDF, JSON, and others, are supported for different export choices. See [Send or schedule workbook exports](/docs/send-or-schedule-workbook-exports) for details on supported formats for different types of exports. Successful requests to the endpoint return a queryId. Use the **queryId** with the [/v2/query/{queryId}/download](https://help.sigmacomputing.com/reference/download-query) endpoint to download the requested file when it is ready. See [Download an exported file](https://help.sigmacomputing.com/reference/download-query). ## Usage notes - Retrieve the **workbookId** by calling the [/v2/workbooks](https://help.sigmacomputing.com/reference/list-workbooks) endpoint. - This endpoint is rate limited to 400 requests per minute. - This endpoint exports up to 1 million rows for CSV/XLSX/JSON file formats. You can export more rows if you batch your requests in chunks of up to 1 million rows. Use the `rowLimit` parameter to specify the size of the chunk and the `offset` parameter to specify the row to start the next chunk from. For example, if you specify a rowLimit of 2500, to export the next chunk of 2500 rows, specify an offset of 2501. The order of the data matches the order in the data element when the request is made, so there is a possibility of data overlap between requests. - For security and privacy reasons, the `queryId` used to download the exported data expires 1 hour after your request is received and the file becomes available to download. You can extend this default expiration to 6 hours using the `resultsValidityTimeMs` request parameter. - When exporting a PNG file, the `pixelWidth` and `pixelHeight` parameters are respected on a best effort basis and the output might not match the requested dimensions. ## Usage scenarios - Conditional workbook export: Based on an external set of conditions, export a workbook from Sigma. - Data analysis: Export specific sets of data for offline analysis, leveraging tools that might not connect directly to a data warehouse. - Integration: Integrate enriched and analyzed data with other applications, providing the necessary data in a format that these applications can process. ## Best practices - Clearly specify parameters to retrieve only the necessary data, optimizing performance and reducing network load.

Authentication

AuthorizationBearer

OAuth authentication of the form <token>.

Path parameters

workbookIdstringRequired

Request

The request body.

elementIdstringOptional

formatobjectOptional

pageIdstringOptional

Identifier of the workbook page.

parametersmap from strings to stringsOptional

Syntax { control-id: control-value }

The control-id is configured in the Sigma workbook or report. The control-value is the value that is passed to the control.

Values can take multiple forms, depending on the data type of the control:

Boolean

Single value: “true” | “false” | “:null”
List of Boolean: “true,false,:null” (No space after the comma.)

Number

Single value: “10.54”, “:null”
List of values: “10.54,23.45,:null” (No space after the comma.)
Range of numbers: “min:10.54,max:23.45” (No space after the comma or colon.)

Text

Single value: “some-text” | “:null” | “:empty”
List of values: “some-text,more-text,:null,:empty” (No space after the comma.)

Date

All dates use UTC time zones.

Fixed date using ISO-6801 format: “2022-01-01T01:01:59” | “:null”
- Formats supported (where: %Y: year, %m: month, %d: day, %H:hours, %M: minutes, %S: seconds):
  - %Y-%m-%d
  - %Y-%m-%dT%H:%M
  - %Y-%m-%dT%H:%M:%S
List of fixed dates: “2022-01-01T01:01:59,2022-02-02T02:02:59,:null”
Relative date: “prior-day-3” | “next-day-3”
- Format: [prior|next]-[year|quarter|month|week|isoWeek|day|hour|minute]-[number]
Date range: “min:2022-01-01T01:01:59,max:next-day-3” (No spaces after the comma or colon.)
- Leave max blank for “on or after” and min blank for “on or before”, for example:
  - “Date-Range”: “min:2020-04-01,max:”
  - “Date-Range”: “min:,max:next-day-3”

Notes

“:null” is a special value that denotes the null primitive value.
“:empty” is a special value that denotes the empty string "".

Use URL encoding to encode characters in your control values (such as commas) to prevent the system from interpreting them as separators.

For example: “New York, NY,Boston, MA” can be encoded as:

“New%20York%2C%20NY,Boston%2C%20MA”

Specify the control ID and control value of one or more control elements in the workbook or report to filter the returned data. The control must exist in the Sigma workbook or report and target an element before you can export based on the control value. **Syntax** { control-id: control-value } The control-id is configured in the Sigma workbook or report. The control-value is the value that is passed to the control. Values can take multiple forms, depending on the data type of the control: **Boolean** - Single value: "true" | "false" | ":null" - List of Boolean: "true,false,:null" (No space after the comma.) **Number** - Single value: "10.54", ":null" - List of values: "10.54,23.45,:null" (No space after the comma.) - Range of numbers: "min:10.54,max:23.45" (No space after the comma or colon.) **Text** - Single value: "some-text" | ":null" | ":empty" - List of values: "some-text,more-text,:null,:empty" (No space after the comma.) **Date** All dates use UTC time zones. - Fixed date using ISO-6801 format: "2022-01-01T01:01:59" | ":null" - Formats supported (where: %Y: year, %m: month, %d: day, %H:hours, %M: minutes, %S: seconds): - %Y-%m-%d - %Y-%m-%dT%H:%M - %Y-%m-%dT%H:%M:%S - List of fixed dates: "2022-01-01T01:01:59,2022-02-02T02:02:59,:null" - Relative date: "prior-day-3" | "next-day-3" - Format: [prior|next]-[year|quarter|month|week|isoWeek|day|hour|minute]-[number] - Date range: "min:2022-01-01T01:01:59,max:next-day-3" (No spaces after the comma or colon.) - Leave max blank for "on or after" and min blank for "on or before", for example: - "Date-Range": "min:2020-04-01,max:" - "Date-Range": "min:,max:next-day-3" **Notes** - ":null" is a special value that denotes the null primitive value. - ":empty" is a special value that denotes the empty string "". Use [URL encoding](https://help.sigmacomputing.com/docs/special-characters-for-url-parameters) to encode characters in your control values (such as commas) to prevent the system from interpreting them as separators. For example: "New York, NY,Boston, MA" can be encoded as: "New%20York%2C%20NY,Boston%2C%20MA"

timeoutdoubleOptional

tagstringOptional

Specifies the version tag of the workbook to be exported.

exportAsstringOptional

Specifies the user ID of the Sigma user to run the export queries as, such as to enforce row-level security. Not supported for users who access Sigma with OAuth.

rowLimitdoubleOptional

Total number of rows to limit a CSV/XLSX/JSON-formatted export to.

offsetdoubleOptional

The offset number of rows for a CSV/XLSX/JSON-formatted export to start from.

Response

The response body.

jobCompleteboolean

queryIdstring

rowslist of maps from strings to any

messagestring

Usage notes

Retrieve the workbookId by calling the /v2/workbooks endpoint.

This endpoint is rate limited to 400 requests per minute.

This endpoint exports up to 1 million rows for CSV/XLSX/JSON file formats. You can export more rows if you batch your requests in chunks of up to 1 million rows. Use the rowLimit parameter to specify the size of the chunk and the offset parameter to specify the row to start the next chunk from. For example, if you specify a rowLimit of 2500, to export the next chunk of 2500 rows, specify an offset of 2501. The order of the data matches the order in the data element when the request is made, so there is a possibility of data overlap between requests.

For security and privacy reasons, the queryId used to download the exported data expires 1 hour after your request is received and the file becomes available to download. You can extend this default expiration to 6 hours using the resultsValidityTimeMs request parameter.

When exporting a PNG file, the pixelWidth and pixelHeight parameters are respected on a best effort basis and the output might not match the requested dimensions.