Build from codeManage reports as code (Beta)

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

View as Markdown

This documentation describes one or more public 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.

You can customize the layout of a report in the code representation using the contents.layout and contents.config fields. The layout field is an XML string that controls which page or panel each element belongs to, and the size and position of each element there. The config field controls page-level configurations, including the page size and margins.

To control how elements are arranged on a page when you create or update a report using the API, specify the layout in the representation. When you retrieve the representation of an existing report using the Get a report endpoint with includeContents=true, the layout and config fields populate automatically based on the published version of the report.

The layout field is required. Every element in contents.elements must be placed in the layout, because the layout is what assigns an element to a page or panel. A representation with an element the layout never references is rejected with an error naming that element, such as elements[0]: element 'Vg934XlZ_4' is not placed in layout.

Example representation with layout

The following example shows a YAML representation of a report with a table and a line chart. Both elements span the full width of the page (excluding the margins) and are stacked vertically, with the line chart directly below the table.

reportId: 5353ba23-a5eb-4950-b82a-b04dacc102e1
reportUrlId: 2xeCQoI36qYlYVQC9JaFKV
createdBy: sKsOdrKB6Gwn4YEHnq0D0CO8CPlg4
updatedBy: sKsOdrKB6Gwn4YEHnq0D0CO8CPlg4
createdAt: '2026-07-27T00:28:16.201Z'
updatedAt: '2026-07-31T20:59:35.325Z'
name: Weather Report
url: https://staging.sigmacomputing.io/org-slug/report/Weather-Report-2xeCQoI36qYlYVQC9JaFKV
path: Examples
latestVersion: 6
ownerId: sKsOdrKB6Gwn4YEHnq0D0CO8CPlg4
isArchived: false
documentVersion: 6
contents:
  schemaVersion: 1
  kind: report
  elements:
    - id: fDH5mMDdwi
      kind: table
      source:
        connectionId: 88c88ad1-eee1-4220-bd54-75125ccedc77
        kind: warehouse-table
        path:
          - SAMPLE_CONNECTION_FUN
          - BIKES
          - WEATHER
      columns:
        - id: inode-l8GQlchbkER0Af7BOfjtNa/DATE
          formula: '[WEATHER/Date]'
        - id: inode-l8GQlchbkER0Af7BOfjtNa/MAX_TEMPERATURE_F
          formula: '[WEATHER/Max Temperature F]'
        - id: inode-l8GQlchbkER0Af7BOfjtNa/MEAN_TEMPERATURE_F
          formula: '[WEATHER/Mean Temperature F]'
        - id: inode-l8GQlchbkER0Af7BOfjtNa/MIN_TEMPERATURE_F
          formula: '[WEATHER/Min Temperature F]'
      order:
        - inode-l8GQlchbkER0Af7BOfjtNa/DATE
        - inode-l8GQlchbkER0Af7BOfjtNa/MAX_TEMPERATURE_F
        - inode-l8GQlchbkER0Af7BOfjtNa/MEAN_TEMPERATURE_F
        - inode-l8GQlchbkER0Af7BOfjtNa/MIN_TEMPERATURE_F
      visibleAsSource: false
    - id: n86TkVYCM7
      kind: line-chart
      source:
        connectionId: 88c88ad1-eee1-4220-bd54-75125ccedc77
        kind: warehouse-table
        path:
          - SAMPLE_CONNECTION_FUN
          - BIKES
          - WEATHER
      columns:
        - id: yviHzm5YdO
          formula: DateTrunc("day", [Date])
        - id: nCqIz0Wiw8
          formula: Sum([Max Temperature F])
        - id: inode-l8GQlchbkER0Af7BOfjtNa/DATE
          formula: '[WEATHER/Date]'
        - id: inode-l8GQlchbkER0Af7BOfjtNa/MAX_TEMPERATURE_F
          formula: '[WEATHER/Max Temperature F]'
        - id: inode-l8GQlchbkER0Af7BOfjtNa/MEAN_TEMPERATURE_F
          formula: '[WEATHER/Mean Temperature F]'
        - id: inode-l8GQlchbkER0Af7BOfjtNa/MIN_TEMPERATURE_F
          formula: '[WEATHER/Min Temperature F]'
      yAxis:
        columnIds:
          - nCqIz0Wiw8
      xAxis:
        columnId: yviHzm5YdO
  pages:
    - id: SE7diV3TMX
      name: Page 1
  config:
    margin: 50
    pageHeight: 1123
    pageWidth: 794
  layout: |
    <?xml version="1.0" encoding="utf-8"?>
    <Page id="SE7diV3TMX">
      <Element elementId="fDH5mMDdwi" x="0" y="0" width="694" height="286.78242677824267"/>
      <Element elementId="n86TkVYCM7" x="0" y="312" width="694" height="290"/>
    </Page>

Report layouts use a pixel system, instead of a grid system like workbooks. Instead of using gridColumn and gridRow attributes to position elements, report layouts use x and y coordinates. For more information on workbook layout, see Customize the layout of a workbook in code representation.

Representing page layout

In this example representation, the element layout is defined in the layout field, and margin and page size are defined in the config field.

config:
  margin: 50
  pageHeight: 1123
  pageWidth: 794
layout: |
  <?xml version="1.0" encoding="utf-8"?>
  <Page id="SE7diV3TMX">
    <Element elementId="fDH5mMDdwi" x="0" y="0" width="694" height="286.78242677824267"/>
    <Element elementId="n86TkVYCM7" x="0" y="312" width="694" height="290"/>
  </Page>

The layout field contains one <Page> element per report page. The id attribute of <Page> must match the id of the corresponding page in the contents.pages array. Inside <Page>, each <Element> entry places one element on that page — the elementId attribute must match the id of the corresponding element in the contents.elements array.

Each <Element> entry contains information about the element’s position and size on the page:

  • Position: x and y pixel values set the position of the element’s top-left corner. The x and y positions are relative to the top-left corner of the page (0,0), excluding the margins.

  • Size: width and height attributes set the element’s size.

Representing page size and margins

The config field defines report-level page setup. It contains the following values, all measured in pixels:

FieldDescription
marginThe page margin, which insets the content area from the edges of the page.
pageHeightThe height of the report page.
pageWidthThe width of the report page.