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.
      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

Try it in Swagger

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

Product Documentation

Workbooks overview