Workbook Schema API
The following article covers Sigma’s developer API for workbook schemas. A workbook’s schema defines the structure and high-level content of the workbook.
For Sigma’s baseline workbook API, visit Workbook API.
Summary of Content
Endpoints
The Workbook Schema Object
Attributes
Look up a Workbook’s Schema
Permissions
Parameters
cURL Request
Response
Example
Related Resources
Endpoints
GET /v2/workbooks/{workbookId}/schema
Returns a workbook schema object based on a workbookId. Learn more
Try it in Swagger
The Workbook Schema Object
Attributes
workbookId string
The workbook’s unique identifier.
pages object
An object that maps workbook pageIds to their matching page object.
{ <pageId>: {
"id": string,
"title": string,
"hidden": boolean,
"body": Array<{
"id": string,
"type": string,
"children": Array<Object>
}>,
"sortIndex": number
}
sheets object
An object that maps workbook sheetIds to their matching sheet object.
A sheet refers to a structured table underlying any data element.
{ <sheetId>: {
"id": string,
"columns": { <columnId>: Object },
"base": {
"columns": Array<Object>
},
"type": string,
"levels": Array<Object>
}}
variables object
An object that maps workbook variableIds to their matching variable object.
Variables refer to control elements.
{ <variableId>: {
"id": string,
"defaultValue": {
"type": string,
"value": Object | null
},
}}
elements object
An object that maps workbook elementIds to their matching element object.
Elements refer to all element types.
{ <elementId>: {
"id": string,
"type": string,
"displayName": string | undefined // only included if includeSQL is true in the request
... // additional attributes vary depending on element type
}}
Example
{
"workbookId": "6tWWojYtpnpJqdqkNKAwS5",
"pages": {
"page1": "[Object Page_t]"
},
"sheets": {
"sheet1": "[Object Sheet_t]"
},
"variables": {
"variable1": "[Object Variable_t]"
},
"elements": {
"element1": "[Object Element_t]"
}
}
Look up a Workbook’s Schema
Returns a workbook schema object based on a workbookId.
GET /v2/workbooks/{workbookId}/schema
Permissions
- The user account associated with the API token must have permission to view the workbook.
Note: If you encounter a permission error for the given endpoint, check with your organization Admin to verify your account type and permissions associated with your API token.
Parameters
includeSql boolean [optional]
When true, the returned Workbook Schema Object will include "sqlQueries," a list of key value pairs where the key is the query id and the value is a sql string.
cURL Request
curl --location --request GET 'https://api.sigmacomputing.com/v2/workbooks/{workbookId}/schema?includeSql={boolean} \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \
Response
{
"workbookId": "6tWWojYtpnpJqdqkNKAwS5",
"pages": {
"page1": "[Object Page_t]"
},
"sheets": {
"sheet1": "[Object Sheet_t]"
},
"variables": {
"variable1": "[Object Variable_t]"
},
"elements": {
"element1": "[Object Element_t]"
},
"sqlQueries": {
"query1": "[sql]"
}
Example
Example Request:
curl --location --request GET 'https://api.sigmacomputing.com/v2/workbooks/6tWWojYtpnpJqdqkNKAwS5/schema?includeSql=true' \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \
Example Response:
{
"workbookId": "t75b8368-4988-4253-a6rt-7869dc2fmoat",
"pages": {
"r1ZNi32OnN": {
"id": "r1ZNi32OnN",
"title": "Page 1",
"body": {
"id": "o7JfOaznU2",
"type": "body",
"sections": Array<Object>
},
...
},
"sheets": {
"9YOAVajdAPzyTEa2frCTpt": {
"id": "9YOAVajdAPzyTEa2frCTpt",
"columns": Array<Object>,
"type": "levelTable",
"levels": Array<Object>
},
...
},
"variables": {
"New-Control-1": {
"name": "New-Control-1",
"defaultValue": {
"type": "date",
"value": null
},
...
},
"elements": {
"F8YtuFIyuDQ": {
"id": "F8YtuFIyuDQ",
"type": "viz",
"height": {
"type": "ratio",
"value": "auto"
},
"viz": {
"workbookId": "t75b8368-4988-4253-a6rt-7869dc2fmoat",
"sheetId": "9YOAVajdAPzyTEa2frCTpt"
}
},
...
},
"sqlQueries": {
"34nHIz3pwNK7pwlxAs4sTa": "select ORDER_NUMBER_39 \"Order Number\" ..."
}
}
Related Resources
API Documentation
Get Started with Sigma's API
Create an API Token and Client Id
Identify Unique Ids in Sigma