Customize the layout of a workbook in code representation (Beta)

🚩
This documentation describes one or more private beta features that are in development. Beta features are subject to quick, iterative changes; therefore the current user experience in the Sigma service can differ from the information provided in this page.
This page should not be considered official published documentation until Sigma removes this notice and the beta flag on the corresponding feature(s) in the Sigma service. For the full beta feature disclaimer, see Beta features.
If you are interested in joining a limited test group and enabling this feature in your Sigma organization, contact Support or reach out to your Account Executive.

You can customize the layout of a workbook page in the code representation using the layout field. The layout field is an XML string that controls the size and position of each element on a page using a 24-column grid system. To control how elements are arranged on a page when you create or update a workbook using the API, specify the layout in the representation.

When you retrieve the representation of an existing workbook using the Get the code representation of a workbook endpoint, the layout field populates automatically based on the arrangement of elements on each page in the published version.

Example representation with layout

The following example shows a YAML representation of a workbook with a table and a bar chart. Both elements span the full width of the page and are stacked vertically, one above the other.

YAML representation with layout

workbookId: bc9e239e-6e00-4f0f-a5b1-2e16df3245a2
name: bar-chart
url: https://aws-api.sigmacomputing.com/org-name/workbook/bar-chart-K6nD3mi0cQAx9f8rriM64z
documentVersion: 2
latestDocumentVersion: 2
ownerId: TnQGIaVmMru7kyHwWPCQfUWjypPtZ
folderId: b6c4f574-9ab6-4525-b25a-b45ed39b5e05
createdBy: TnQGIaVmMru7kyHwWPCQfUWjypPtZ
updatedBy: TnQGIaVmMru7kyHwWPCQfUWjypPtZ
createdAt: '2026-04-20T20:09:52.987Z'
updatedAt: '2026-04-21T14:22:44.075Z'
schemaVersion: 1
pages:
  - id: QKIgFmOpQt
    name: Page 1
    elements:
      - id: ammWveJOET
        kind: table
        source:
          connectionId: 6944db1a-f9f0-496f-91ba-4781e7f0490d
          kind: warehouse-table
          path:
            - FUN
            - BIKES
            - TRIP
        columns:
          - id: VGGdL5h1XL
            formula: '[TRIP/Id]'
          - id: XfekGVjpYe
            formula: '[TRIP/Duration]'
          - id: vSNXcQlbgo
            formula: '[TRIP/Start Date]'
          - id: n0viQISda6
            formula: '[TRIP/Start Station Name]'
          - id: otGGHmPqJZ
            formula: '[TRIP/Start Station Id]'
          - id: jrQpKNxZxF
            formula: '[TRIP/End Date]'
          - id: xT5p03z0yD
            formula: '[TRIP/End Station Name]'
          - id: kctIxpAAqM
            formula: '[TRIP/End Station Id]'
          - id: VwSnzv10lZ
            formula: '[TRIP/Bike Id]'
          - id: pxvj425aDk
            formula: '[TRIP/Subscription Type]'
          - id: HZOjVcwDG1
            formula: '[TRIP/Zip Code]'
        order:
          - VGGdL5h1XL
          - XfekGVjpYe
          - vSNXcQlbgo
          - n0viQISda6
          - otGGHmPqJZ
          - jrQpKNxZxF
          - xT5p03z0yD
          - kctIxpAAqM
          - VwSnzv10lZ
          - pxvj425aDk
          - HZOjVcwDG1
      - id: LBMxXnUDCS
        kind: bar-chart
        source:
          elementId: ammWveJOET
          kind: table
        columns:
          - id: xwi1BMJ3PL
            formula: '[TRIP/Start Station Name]'
          - id: vKP79P5tMl
            formula: Count([Id])
          - id: HlVOO3VkmU
            formula: '[TRIP/Subscription Type]'
          - id: 7vIMaF82Ea
            formula: '[TRIP/Id]'
          - id: OaVsOl70Mu
            formula: '[TRIP/Duration]'
          - id: 2EupEbY2C1
            formula: '[TRIP/Start Date]'
          - id: cOt55IxOwt
            formula: '[TRIP/Start Station Id]'
          - id: pOeY8EgDKh
            formula: '[TRIP/End Date]'
          - id: YvYBibU28Y
            formula: '[TRIP/End Station Name]'
          - id: W8iYZkmMus
            formula: '[TRIP/End Station Id]'
          - id: 9xgXlflRhB
            formula: '[TRIP/Bike Id]'
          - id: eBbsizX2wU
            formula: '[TRIP/Zip Code]'
        yAxis:
          - id: vKP79P5tMl
        xAxis:
          id: xwi1BMJ3PL
          sort:
            by: vKP79P5tMl
            direction: descending
layout: |
  <?xml version="1.0" encoding="utf-8"?>
  <Page type="grid" gridTemplateColumns="repeat(24, 1fr)" gridTemplateRows="auto" id="QKIgFmOpQt">
    <LayoutElement elementId="ammWveJOET" gridColumn="1 / 25" gridRow="1 / 21"/>
    <LayoutElement elementId="LBMxXnUDCS" gridColumn="1 / 25" gridRow="21 / 41"/>
  </Page>

Representing layout

In this example representation, the layout for Page 1 is defined in the layout field.

Layout representation

layout: |
  <?xml version="1.0" encoding="utf-8"?>
  <Page type="grid" gridTemplateColumns="repeat(24, 1fr)" gridTemplateRows="auto" id="QKIgFmOpQt">
    <LayoutElement elementId="ammWveJOET" gridColumn="1 / 25" gridRow="1 / 21"/>
    <LayoutElement elementId="LBMxXnUDCS" gridColumn="1 / 25" gridRow="21 / 41"/>
  </Page>

The layout field contains one <Page> element per workbook page. The id attribute of <Page> must match the id of the corresponding page in the pages array. Inside <Page>, each <LayoutElement> entry corresponds to one element on the page — the elementId attribute must match the id of the corresponding element in the elements array.

The gridColumn attribute controls the horizontal position and width of an element. The grid is 1-indexed across 24 columns, where 1 is the left edge and 25 is the right edge. For example, "1 / 25" spans the full width, "1 / 13" spans the left half, and "13 / 25" spans the right half.

The gridRow attribute controls the vertical position and height of an element. In this example, "1 / 21" places the table at the top of the page and "21 / 41" places the bar chart directly below it.