Manage data models as code

You can use the Sigma API to retrieve, update, and create data models based on a JSON or YAML representation. These endpoints enable a programmatic workflow, allowing you to manage and review data models without using the Sigma UI.

Data models generated from the API are also accessible in the UI. You can view, edit, and manage a data model that was created programmatically in the same way as any other data model created in Sigma.

Use these endpoints when you want to:

• Automate the creation and management of data models at scale
• Develop data models using AI assistants
• Manage data models as part of your CI/CD pipeline
• Integrate data model development with external tools

About representing data models as code

Sigma offers programmatic data model API endpoints, which use a JSON or YAML representation of a data model as the input and output. The representation, sometimes referred to as a schema or specification, defines the structure of the data model, including its data sources, pages, elements, and their configurations.

Using these endpoints, you can programmatically scale your data governance and semantic modeling in Sigma. You can use tables to model fact and dimension data, metrics to standardize calculations, and relationships to pre-define common joins. To see a list of elements that are not supported in the representation, see Limitations.

The representation does not include data from your data sources. It lists IDs, which reference the data sources, and then describes how to arrange the contents of the data sources in the data model. For example, instead of listing individual records like a CSV file, the representation lists the columns of a table, and the connection those columns are sourced from.

A valid representation is formatted like the following:

{
  "dataModelId": "<data-model-uuid>",
  "name": "<data-model-name>",
  "url": "<data-model-url>",
  "documentVersion": <document-version>,
  "latestDocumentVersion": <latest-document-version>,
  "ownerId": "<user-uuid>",
  "folderId": "<folder-uuid>",
  "createdBy": "<user-uuid>",
  "updatedBy": "<user-uuid>",
  "createdAt": "<created-at-timestamp>",
  "updatedAt": "<updated-at-timestamp>",
  "schemaVersion": <schema-version>,
  "pages": [
    {
      "id": "<page-uuid>",
      "name": "<page-name>",
      "elements": [
        {
          "id": "<element-uuid>",
          "kind": "table",
          "source": {
            "connectionId": "<connection-uuid>",
            "kind": "warehouse-table",
            "path": [
              "<database>",
              "<schema>",
              "<table-name>"
            ]
          },
          "columns": [
            {
              "id": "<column-uuid>",
              "formula": "[<table-name>/<column-name>]",
              "name": "<column-name>"
            },
            {
              "id": "<column-uuid>",
              "formula": "[<table-name>/<column-name>]",
              "name": "<column-name>"
            },
            {
              "id": "<column-uuid>",
              "formula": "[<table-name>/<column-name>]",
              "name": "<column-name>"
            },
            {
              "id": "<column-uuid>",
              "formula": "[<table-name>/<column-name>]",
              "name": "<column-name>"
            },
            {
              "id": "<column-uuid>",
              "formula": "[<table-name>/<column-name>]",
              "name": "<column-name>"
            }
          ],
          "order": [
            "<column-uuid>",
            "<column-uuid>",
            "<column-uuid>",
            "<column-uuid>",
            "<column-uuid>"
          ],
          "name": "<element-name>"
        }
      ]
    }
  ]
}

Over time, Sigma will release new versions of this specification to add fields, change data types, and more. When this happens, the schemaVersion field in the representation is incremented for new representations. The schemaVersion field in the representation indicates the version of the current representation, and is required when creating or updating a data model to ensure backwards compatibility. The example above uses schema version 1.

System and user requirements

The ability to create and manage data models from code requires the following:

• You must be the document owner or be granted Can edit access to the data model.
• You must have developer credentials for the Sigma API. For more information, see Get started with the Sigma REST API.
• The user associated with your API credentials must be assigned the Admin account type.

Limitations

• Workbooks do not have a representation like data models. If you need to manage a workbook element programmatically, consider creating a data model, using it as the data source for a workbook, and managing that data model programmatically.
• Programmatically managing multiple tables with the same name in the same data model is not supported.
• The following features are not supported when managing data models programmatically:
  • Input tables
  • Python element
  • UI elements
  • Referencing Sigma elements in custom SQL

Notes

• Existing data model endpoints, like List data models, can be used to retrieve details on data models in your organization, but cannot be used to create or update a data model from a code representation the way the /spec endpoints can.
• The default format for the representation is JSON. To receive YAML, you can add the query parameter ?format=yaml or the headers Accept: application/yaml and Content-Type: application/yaml.

Get the code representation of an existing data model

To retrieve the code representation of an existing data model, call the Get the code representation of a data model endpoint with the dataModelId for the data model:

1. Identify the existing data model you want the representation for by name, owner, or other details.
2. Call the List data models endpoint to retrieve the dataModelId for the data model.
3. Call the Get the code representation of a data model endpoint, passing the dataModelId as a path parameter.

The endpoint returns the code representation of the data model.

For step-by-step instructions, see Get the code representation of a data model.

Create a data model from a code representation

To create a data model from a code representation, call the Create a data model from a code representation endpoint with the code representation in the request body.

1. Prepare a code representation of the data model you want to create. This might be based on a representation retrieved from an existing data model, or it might be a new representation. For example representations, see the Example library.
2. Call the Create a data model from a code representation endpoint, passing the code representation in the request body.

The data model is created and the response body contains the dataModelId for the new data model.

For step-by-step instructions, see Create a data model from a code representation.

Update an existing data model from a code representation

To update an existing data model from a code representation, call the Update a data model from a representation endpoint with the code representation in the request body.

1. Identify the existing data model you want to update, by name, owner, or other details.
2. Call the List data models endpoint to retrieve the dataModelId for the data model.
3. Prepare a code representation of the data model with the updates you want to apply. For an example, see the Example library.
4. Call the Update a data model from a representation endpoint, passing the dataModelId as a path parameter and the code representation in the request body.

The data model is updated.

For step-by-step instructions, see Update a data model from a code representation.