Update a data model from a code representation

You can update an existing data model from a code representation by calling the Update a data model from a representation endpoint with the code representation in the request body.

This document provides step-by-step instructions for using this endpoint to update a data model from a code representation. For more information on working with data models programmatically, see Manage data models as code.

System and user requirements

The ability to update a data model from a code representation requires the following:

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

Generate API client credentials and an API access token

To start, you must generate credentials for the Sigma API. These credentials are used to retrieve an access token, which is required to make requests to the API.

For step-by-step instructions on generating developer credentials in Sigma and using them to authenticate to the Sigma API, see the instructions in Generate client credentials.

Identify the data model and retrieve the data model ID

To update an existing data model from a code representation, you must know the unique dataModelId for that data model. When you have identified the data model you want to update the representation for, you can call the List data models endpoint to retrieve the dataModelId:

Go to your Home page.
In the navigation menu, select My documents.
Click the Document type filter and select Data models.

The list of your data models appears.
Identify the data model you want to update the representation for, by name, owner, or other details.

Make a GET request to the List data models endpoint like the following:

List data models request format

curl --request GET \
     --url <base_url>/v2/dataModels \
     --header 'Authorization: Bearer <access_token>' \
     --header 'accept:application/json' \
     --header 'content-type: application/x-www-form-urlencoded'

The response includes a list of data models in your organization, in the following format:

List data models response format

{
  "entries":
    [
      {
        "dataModelId": "<dataModelId>",
        "dataModelUrlId": "<dataModelUrlId>",
        "createdBy": "<userId>",
        "updatedBy": "<userId>",
        "createdAt": "<timestamp>",
        "updatedAt": "<timestamp>",
        "name": "<dataModelName>",
        "url": "<dataModelUrl>",
        "path": "<folderPath>",
        "latestVersion": "<versionNumber>",
        "ownerId": "<userId>"
      },
      {
        "dataModelId": "<dataModelId>",
        "dataModelUrlId": "<dataModelUrlId>",
        "createdBy": "<userId>",
        "updatedBy": "<userId>",
        "createdAt": "<timestamp>",
        "updatedAt": "<timestamp>",
        "name": "<dataModelName>",
        "url": "<dataModelUrl>",
        "path": "<folderPath>",
        "latestVersion": "<versionNumber>",
        "ownerId": "<userId>"
      }
    ],
  "hasMore": <boolean>,
  "total": <number>,
  "nextPage": null
}

Identify the data model you want to update the representation for, and copy the dataModelId to pass to the Update a data model from a representation endpoint.

Prepare the representation

To update an existing data model from a code representation, you must prepare a valid code representation of the data model with the updates you want to apply. You can base this on the representation of the existing data model, or update the data model using an entirely new representation.

💡
The Update a data model from a representation endpoint supports PUT requests, and does not support partial updates. To update a data model, you must pass in a complete representation of the data model, even if you are only making minor changes. Sigma recommends retrieving the existing representation and basing your changes on that.

The code representation you prepare can be passed into the request body of the Update a data model from a representation endpoint to update the data model.

Using the dataModelId you identified in the previous section, follow the instructions in Retrieve the code representation to get the current representation.

For example, you might retrieve the representation for a data model with a single table, like the following:

JSON representation example

{
    "dataModelId": "467bc369-5db7-4963-8172-b24a49dbc75b",
    "name": "Plugs Orders",
    "url": "https://aws-api.sigmacomputing.com/org-name/data-model/Plugs-Orders-ZwGvRngQvdGnD3FLar3PMD",
    "documentVersion": 2,
    "latestDocumentVersion": 2,
    "schemaVersion": 1,
    "ownerId": "Gm0tRQp8R91nfN7nhZ1RnXyhAFbGm",
    "folderId": "21c662bd-d01e-4b2a-b6c9-559670a79a1d",
    "createdBy": "Gm0tRQp8R91nfN7nhZ1RnXyhAFbGm",
    "updatedBy": "Gm0tRQp8R91nfN7nhZ1RnXyhAFbGm",
    "createdAt": "2025-11-17T20:30:10.664Z",
    "updatedAt": "2025-11-17T20:31:30.158Z",
    "pages": [
        {
            "id": "baXffaLXOI",
            "name": "Page 1",
            "elements": [
                {
                    "id": "4djgrzPSow",
                    "name": "PLUGS_ELECTRONICS_HANDS_ON_LAB_DATA",
                    "kind": "table",
                    "source": {
                        "connectionId": "d61d33dd-3f3b-4cf6-bb08-d7e5bf0136ac",
                        "kind": "warehouse-table",
                        "path": [
                            "EXAMPLES",
                            "PLUGS_ELECTRONICS",
                            "PLUGS_ELECTRONICS_HANDS_ON_LAB_DATA"
                        ]
                    },
                    "columns": [
                        {
                            "id": "inode-LJa8JXHzrn17EZwat5E2Nl/ORDER_NUMBER",
                            "name": "Order Number",
                            "formula": "[PLUGS_ELECTRONICS_HANDS_ON_LAB_DATA/Order Number]"
                        },
                        {
                            "id": "inode-yvWqP8VnON8oUDb8lmJ8B2/DATE",
                            "name": "Date",
                            "formula": "[PLUGS_ELECTRONICS_HANDS_ON_LAB_DATA/Date]"
                        },
                        {
                            "id": "inode-WbKTcIN42uMYNlYhbpzogv/SKU_NUMBER",
                            "name": "Sku Number",
                            "formula": "[PLUGS_ELECTRONICS_HANDS_ON_LAB_DATA/Sku Number]"
                        },
                        {
                            "id": "inode-NY4wMCOm7QujeIHq0d5anY/QUANTITY",
                            "name": "Quantity",
                            "formula": "[PLUGS_ELECTRONICS_HANDS_ON_LAB_DATA/Quantity]"
                        },
                        {
                            "id": "inode-CTxW1UliF9QWazEl5T92uT/COST",
                            "name": "Cost",
                            "formula": "[PLUGS_ELECTRONICS_HANDS_ON_LAB_DATA/Cost]"
                        },
                        {
                            "id": "inode-Fy2o6baZbqWOfjip58IrCE/PRICE",
                            "name": "Price",
                            "formula": "[PLUGS_ELECTRONICS_HANDS_ON_LAB_DATA/Price]"
                        },
                        {
                            "id": "inode-WMjybeW9fa9zk2u5K13Pqx/PRODUCT_TYPE",
                            "name": "Product Type",
                            "formula": "[PLUGS_ELECTRONICS_HANDS_ON_LAB_DATA/Product Type]"
                        },
                        {
                            "id": "inode-WLqLQd9ENQCRxV4LrUJ7qf/PRODUCT_FAMILY",
                            "name": "Product Family",
                            "formula": "[PLUGS_ELECTRONICS_HANDS_ON_LAB_DATA/Product Family]"
                        },
                        {
                            "id": "inode-giyZw4qmHaW2qDDZBii5mb/PRODUCT_LINE",
                            "name": "Product Line",
                            "formula": "[PLUGS_ELECTRONICS_HANDS_ON_LAB_DATA/Product Line]"
                        },
                        {
                            "id": "inode-gTKFYv8ZS2nIv6usesHjlf/BRAND",
                            "name": "Brand",
                            "formula": "[PLUGS_ELECTRONICS_HANDS_ON_LAB_DATA/Brand]"
                        },
                        {
                            "id": "inode-9kt9D0p9LJq61ACBsSw1OW/PRODUCT_NAME",
                            "name": "Product Name",
                            "formula": "[PLUGS_ELECTRONICS_HANDS_ON_LAB_DATA/Product Name]"
                        },
                        {
                            "id": "inode-4XtEgutaHeutNJgCi2PlgF/STORE_NAME",
                            "name": "Store Name",
                            "formula": "[PLUGS_ELECTRONICS_HANDS_ON_LAB_DATA/Store Name]"
                        },
                        {
                            "id": "inode-xShEp3luq2RCArDMR0GKRh/STORE_KEY",
                            "name": "Store Key",
                            "formula": "[PLUGS_ELECTRONICS_HANDS_ON_LAB_DATA/Store Key]"
                        },
                        {
                            "id": "inode-Oq3r91PU5rsPuOItrWluYz/STORE_REGION",
                            "name": "Store Region",
                            "formula": "[PLUGS_ELECTRONICS_HANDS_ON_LAB_DATA/Store Region]"
                        },
                        {
                            "id": "inode-iyLC777OS3Ooz2Wszj9tIt/STORE_STATE",
                            "name": "Store State",
                            "formula": "[PLUGS_ELECTRONICS_HANDS_ON_LAB_DATA/Store State]"
                        },
                        {
                            "id": "inode-Ws2A04tFoAcfMwRhgGNmeF/STORE_CITY",
                            "name": "Store City",
                            "formula": "[PLUGS_ELECTRONICS_HANDS_ON_LAB_DATA/Store City]"
                        },
                        {
                            "id": "inode-GaC4Q5vA4S5tss9IW9lX7p/STORE_ZIP_CODE",
                            "name": "Store Zip Code",
                            "formula": "[PLUGS_ELECTRONICS_HANDS_ON_LAB_DATA/Store Zip Code]"
                        },
                        {
                            "id": "inode-4368IkHBFTUzyp0GZkohAr/STORE_LATITUDE",
                            "name": "Store Latitude",
                            "formula": "[PLUGS_ELECTRONICS_HANDS_ON_LAB_DATA/Store Latitude]"
                        },
                        {
                            "id": "inode-qEsGa6zBmEaaWUQYZ80STX/STORE_LONGITUDE",
                            "name": "Store Longitude",
                            "formula": "[PLUGS_ELECTRONICS_HANDS_ON_LAB_DATA/Store Longitude]"
                        },
                        {
                            "id": "inode-JlzDPzOrU5BfBDKFT0H6FN/CUST_KEY",
                            "name": "Cust Key",
                            "formula": "[PLUGS_ELECTRONICS_HANDS_ON_LAB_DATA/Cust Key]"
                        },
                        {
                            "id": "inode-OwDwDT19u01VhSFVCwTaNQ/CUSTOMER_NAME",
                            "name": "Customer Name",
                            "formula": "[PLUGS_ELECTRONICS_HANDS_ON_LAB_DATA/Customer Name]"
                        },
                        {
                            "id": "inode-nhIjdidh5elnMfWyazbBFI/CUST_JSON",
                            "name": "Cust Json",
                            "formula": "[PLUGS_ELECTRONICS_HANDS_ON_LAB_DATA/Cust Json]"
                        }
                    ]
                }
            ]
        }
    ]
}

Make any desired changes to the representation. For example, you might want to rename the data model, rename a table, or add a new column.

In this example, most columns are removed from the representation, leaving only the Order Number and Date:

Updated JSON representation

{
    "dataModelId": "467bc369-5db7-4963-8172-b24a49dbc75b",
    "name": "Plugs Orders",
    "url": "https://aws-api.sigmacomputing.com/org-name/data-model/Plugs-Orders-ZwGvRngQvdGnD3FLar3PMD",
    "documentVersion": 2,
    "latestDocumentVersion": 2,
    "schemaVersion": 1,
    "ownerId": "Gm0tRQp8R91nfN7nhZ1RnXyhAFbGm",
    "folderId": "21c662bd-d01e-4b2a-b6c9-559670a79a1d",
    "createdBy": "Gm0tRQp8R91nfN7nhZ1RnXyhAFbGm",
    "updatedBy": "Gm0tRQp8R91nfN7nhZ1RnXyhAFbGm",
    "createdAt": "2025-11-17T20:30:10.664Z",
    "updatedAt": "2025-11-17T20:31:30.158Z",
    "pages": [
        {
            "id": "baXffaLXOI",
            "name": "Page 1",
            "elements": [
                {
                    "id": "4djgrzPSow",
                    "name": "PLUGS_ELECTRONICS_HANDS_ON_LAB_DATA",
                    "kind": "table",
                    "source": {
                        "connectionId": "d61d33dd-3f3b-4cf6-bb08-d7e5bf0136ac",
                        "kind": "warehouse-table",
                        "path": [
                            "EXAMPLES",
                            "PLUGS_ELECTRONICS",
                            "PLUGS_ELECTRONICS_HANDS_ON_LAB_DATA"
                        ]
                    },
                    "columns": [
                        {
                            "id": "inode-5FCsrDpnzcdw5YYJRBbY6l/ORDER_NUMBER",
                            "name": "Order Number",
                            "formula": "[PLUGS_ELECTRONICS_HANDS_ON_LAB_DATA/Order Number]"
                        },
                        {
                            "id": "inode-5FCsrDpnzcdw5YYJRBbY6l/DATE",
                            "name": "Date",
                            "formula": "[PLUGS_ELECTRONICS_HANDS_ON_LAB_DATA/Date]"
                        }
                    ]
                }
            ]
        }
    ]
}

Call the Update a data model from a code representation endpoint

Finally, call the Update a data model from a code representation endpoint, passing the dataModelId as a path parameter and the updated code representation in the request body. The request format is as follows:

Update a data model from a representation request format

curl --request PUT \
    --url <base_url>/v2/dataModels/<dataModelId>/spec \
    --header 'Authorization: Bearer <access_token>' \
    --header 'content-type:application/json' \
    --data '<json_representation>'

This example request replaces the example representation shown after step one of the previous section with the truncated representation from step two:

Update a data model from a representation request example

curl --request PUT \                               
    --url https://aws-api.sigmacomputing.com/v2/dataModels/575ba1f9-7c5d-4cf0-83df-9a0bea884b8d/spec \
    --header 'Authorization: Bearer <access_token>' \
    --header 'content-type:application/json' \
    --data '{"dataModelId":"467bc369-5db7-4963-8172-b24a49dbc75b","name":"Plugs Orders","url":"https://aws-api.sigmacomputing.com/org-name/data-model/Plugs-Orders-ZwGvRngQvdGnD3FLar3PMD","documentVersion":2,"latestDocumentVersion":2,"schemaVersion":1,"ownerId":"Gm0tRQp8R91nfN7nhZ1RnXyhAFbGm","folderId":"21c662bd-d01e-4b2a-b6c9-559670a79a1d","createdBy":"Gm0tRQp8R91nfN7nhZ1RnXyhAFbGm","updatedBy":"Gm0tRQp8R91nfN7nhZ1RnXyhAFbGm","createdAt":"2025-11-17T20:30:10.664Z","updatedAt":"2025-11-17T20:31:30.158Z","pages":[{"id":"baXffaLXOI","name":"Page 1","elements":[{"id":"4djgrzPSow","name":"PLUGS_ELECTRONICS_HANDS_ON_LAB_DATA","kind":"table","source":{"connectionId":"d61d33dd-3f3b-4cf6-bb08-d7e5bf0136ac","kind":"warehouse-table","path":["EXAMPLES","PLUGS_ELECTRONICS","PLUGS_ELECTRONICS_HANDS_ON_LAB_DATA"]},"columns":[{"id":"inode-5FCsrDpnzcdw5YYJRBbY6l/ORDER_NUMBER","name":"Order Number","formula":"[PLUGS_ELECTRONICS_HANDS_ON_LAB_DATA/Order Number]"},{"id":"inode-5FCsrDpnzcdw5YYJRBbY6l/DATE","name":"Date","formula":"[PLUGS_ELECTRONICS_HANDS_ON_LAB_DATA/Date]"}]}]}]}'

The data model is updated with the new representation.

Updated about 6 hours ago