> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://help.sigmacomputing.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://help.sigmacomputing.com/_mcp/server.

# Update a data model from a code representation

PUT https://api.sigmacomputing.com/v2/dataModels/{dataModelId}/spec
Content-Type: application/json

This endpoint replaces a data model with the contents defined in a code representation. You can programmatically update the data model's structure, metadata, and contents. This creates a new version of the data model, which is accessible from the Sigma UI.

For more information on managing data models via the Sigma API, see [Manage data models as code](https://help.sigmacomputing.com/docs/manage-data-models-as-code). For more information on using this endpoint, including an end-to-end example, see [Update a data model from a code representation](https://help.sigmacomputing.com/docs/update-a-data-model-from-a-code-representation).

### Usage notes

* To perform this operation, you must use API credentials owned by a user assigned an account type with **Create, edit, and publish data models** permission.
* To perform this operation, you must use API credentials owned by a user with **Can edit** access to the data model.
* Retrieve a representation of an existing data model by calling the [/v2/dataModels/\{dataModelId}/spec](https://help.sigmacomputing.com/reference/get-data-model-spec) endpoint.
* To create a new data model from code, use the [/v2/dataModels/spec](https://help.sigmacomputing.com/reference/create-data-model-spec) endpoint.
* The endpoint only supports updates to the `pages` array and its contents. Additional fields are not required and are ignored in the request body.
* Partial updates are not supported. You must provide the entire representation of the data model in the request body.
* The default format of the representation is JSON. To use YAML, add the header `Content-Type: application/yaml`.

### Usage scenarios

* **Automation**: If you want to update several data models across one or more organizations, or in response to external events, you can use this endpoint to programmatically update the data models.
* **Integration**: Using this endpoint, you can update data models based on external data sources or integrate Sigma with other tools and platforms.
* **Version control**: Developers can use this endpoint to programmatically manage, update, and version control data models between several organizations or tenants.
* **Agentic workflows**: Agents can use these endpoints to directly manage data model contents in code.

Reference: https://help.sigmacomputing.com/reference/update-data-model-spec

## Authentication

- `Authorization` header (bearer token, required)

## Servers

- `https://api.sigmacomputing.com` (Server for GCP (US) hosted organizations, default)
- `https://api.sa.gcp.sigmacomputing.com` (Server for GCP (KSA) hosted organizations)
- `https://aws-api.sigmacomputing.com` (Server for AWS US (West) hosted organizations)
- `https://api.us-a.aws.sigmacomputing.com` (Server for AWS US (East) hosted organizations)
- `https://api.ca.aws.sigmacomputing.com` (Server for AWS Canada hosted organizations)
- `https://api.eu.aws.sigmacomputing.com` (Server for AWS Europe hosted organizations)
- `https://api.au.aws.sigmacomputing.com` (Server for AWS Australia and APAC hosted organizations)
- `https://api.uk.aws.sigmacomputing.com` (Server for AWS UK hosted organizations)
- `https://api.us.azure.sigmacomputing.com` (Server for Azure US hosted organizations)
- `https://api.eu.azure.sigmacomputing.com` (Server for Azure Europe hosted organizations)
- `https://api.ca.azure.sigmacomputing.com` (Server for Azure Canada hosted organizations)
- `https://api.uk.azure.sigmacomputing.com` (Server for Azure United Kingdom hosted organizations)
- `https://api.au.azure.sigmacomputing.com` (Server for Azure Australia hosted organizations)

## Request

### Path parameters

- `dataModelId` (string, required)

### Body (application/json)

- `schemaVersion` (enum, required) — The schema version used by this representation of the data model.
  - Allowed values: `1`
- `pages` (list of object, required) — The pages of the data model and their contents.
  - `id` (string, required) — The identifier of the page in the data model.
  - `name` (string, required) — The name of the page.
  - `elements` (list of object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object, required) — The elements on the page.
    - Table
      - `id` (string, required) — The identifier of the table.
      - `kind` (enum, required)
        - Allowed values: `table`
      - `columns` (list of object, required) — The columns of the table and their formulas.
        - `id` (string, required) — The identifier of the column.
        - `formula` (string, required) — The reference or calculation for the column.
        - `name` (string, optional) — The display name of the column.
        - `description` (string, optional) — The description of the column.
        - `hidden` (boolean, optional) — Indicates whether or not the column is hidden from view.
        - `format` (object or object, optional) — The display format of the column.
          - object
            - `kind` (enum, required)
            - `formatString` (string, optional) — The format of the number specified in d3 format.
            - `prefix` (string, optional) — The prefix to apply to the number.
            - `suffix` (string, optional) — The suffix to apply to the number.
            - `displayNullAs` (string, optional) — The display value to show for null values.
            - `decimalSymbol` (string, optional) — The character used for decimal notation.
            - `digitGroupingSymbol` (string, optional) — The character used to separate digits in large numbers.
            - `digitGroupingSize` (list of double, optional) — The interval at which to use the digit grouping symbol.
            - `currencySymbol` (string, optional) — The characters used for currency.
          - object
            - `kind` (enum, required)
            - `formatString` (string, optional) — The format of the date specified in d3 time format.
      - `source` (object or object or object or object or object or object or object or object, required) — The source of the table.
        - Warehouse Table
          - `connectionId` (string, required) — The identifier of the connection to the data platform.
          - `kind` (enum, required)
            - Allowed values: `warehouse-table`
          - `path` (list of string, required) — The path of the table in the data platform.
        - Custom SQL
          - `connectionId` (string, required) — The identifier of the connection to the data platform.
          - `kind` (enum, required)
            - Allowed values: `sql`
          - `statement` (string, required) — The custom SQL statement used in the element.
        - Table
          - `kind` (enum, required)
            - Allowed values: `table`
          - `elementId` (string, required) — The identifier of the table in this data model.
          - `groupingId` (string, optional) — The identifier of the grouping to apply to the table.
        - Data Model
          - `dataModelId` (string, required) — The identifier of the data model source.
          - `elementId` (string, required) — The identifier of the table in the referenced data model.
          - `kind` (enum, required)
            - Allowed values: `data-model`
          - `groupingId` (string, optional) — The identifier of the grouping to apply to the table.
        - Join
          - `kind` (enum, required)
            - Allowed values: `join`
          - `joins` (list of object, required) — A list of the joins and their definitions. The left of each join must be either the primary source or the right of some other join.
            - `left` (object or object or object, required) — The name of the left table in the join.
            - `right` (object or object or object, required) — The name of the right table in the join.
            - `columns` (list of object, required) — A list of the column pairs and operators that define this join.
            - `name` (string, optional) — The name of the join. Defaults to the name of the right.
            - `joinType` (enum or enum or enum or enum or enum, optional) — The logical join type.
          - `name` (string, optional) — The name of the join. Defaults to the name of the primary source.
          - `primarySource` (object or object or object, optional) — The primary/head source of the join. If not specified, it is inferred as the unique source that appears on the left of some join but never on the right.
            - Warehouse Table
            - Table
            - Data Model
        - Union
          - `kind` (enum, required)
            - Allowed values: `union`
          - `sources` (list of object or object or object, required) — The identifiers of the sources in the union.
            - Warehouse Table
            - Table
            - Data Model
          - `matches` (list of object, required) — The union output columns and the matched source columns that comprise them.
            - `outputColumnName` (string, required) — The name of the union output column.
            - `sourceColumns` (list of string, required) — The matching set of source columns that correspond to the union output column.
      - `name` (string, optional) — The name of the table.
      - `description` (string, optional) — The description of the table.
      - `metrics` (list of object, optional) — The metrics associated with this table and their configurations.
        - `id` (string, required) — The identifier of the metric.
        - `formula` (string, required) — The formula defining the metric.
        - `name` (string, optional) — The name of the metric.
        - `description` (string, optional) — The description of the metric.
        - `isHighlighted` (boolean, optional) — Indicates whether or not the metric is highlighted.
        - `format` (object or object, optional) — The display format of the column.
          - object
            - `kind` (enum, required)
            - `formatString` (string, optional) — The format of the number specified in d3 format.
            - `prefix` (string, optional) — The prefix to apply to the number.
            - `suffix` (string, optional) — The suffix to apply to the number.
            - `displayNullAs` (string, optional) — The display value to show for null values.
            - `decimalSymbol` (string, optional) — The character used for decimal notation.
            - `digitGroupingSymbol` (string, optional) — The character used to separate digits in large numbers.
            - `digitGroupingSize` (list of double, optional) — The interval at which to use the digit grouping symbol.
            - `currencySymbol` (string, optional) — The characters used for currency.
          - object
            - `kind` (enum, required)
            - `formatString` (string, optional) — The format of the date specified in d3 time format.
        - `timeline` (object, optional) — The timeline configuration for the metric.
          - `dateColumnId` (string, required) — The column of date data used to create the metric timeline.
          - `truncation` (enum or enum or enum or enum or enum or enum or enum or enum, optional) — The precision to truncate the date to.
          - `comparison` (object, optional) — The time period to compare the current metric value against.
            - `comparisonPeriod` (enum or enum or enum or enum or enum or enum or enum or enum, required) — The time period to compare the current metric value against.
            - `direction` (enum or enum, optional) — Indicates whether higher or lower comparison values are better for that metric.
      - `relationships` (list of object, optional) — The relationships sourced from this table and their targets.
        - `id` (string, required) — The identifier of the relationship.
        - `targetElementId` (string, required) — The identifier of the table joined to the parent table in the relationship.
        - `keys` (list of object, required) — The pairs of source and target column IDs joined in this relationship.
          - `sourceColumnId` (string, required) — The column from the parent table joined in this relationship.
          - `targetColumnId` (string, required) — The column from the target table joined in this relationship.
        - `name` (string, optional) — The name of the relationship.
        - `description` (string, optional) — The description of the relationship.
        - `relationshipType` (enum or enum or enum, optional) — [Private beta] The cardinality of the relationship.
      - `filters` (list of object or object or object or object or object or object, optional) — The filters applied to this table and their configurations.
        - Number Range
          - `kind` (enum, required)
            - Allowed values: `number-range`
          - `id` (string, required) — The identifier of the filter.
          - `columnId` (string, required) — The identifier of the column this filter targets.
          - `includeNulls` (enum or enum or enum, optional) — Indicates when to include null values.
          - `min` (double, optional) — The lower bound of the selected number range.
          - `max` (double, optional) — The upper bound of the selected number range.
          - `state` (enum or enum, optional) — Indicates whether or not the filter is enabled.
        - Date Range
          - `kind` (enum, required)
            - Allowed values: `date-range`
          - `id` (string, required) — The identifier of the filter.
          - `columnId` (string, required) — The identifier of the column this filter targets.
          - `includeNulls` (enum or enum or enum, optional) — Indicates when to include null values.
          - `state` (enum or enum, optional) — Indicates whether or not the filter is enabled.
        - Top N
          - `kind` (enum, required)
            - Allowed values: `top-n`
          - `id` (string, required) — The identifier of the filter.
          - `columnId` (string, required) — The identifier of the column this filter targets.
          - `state` (enum or enum, optional) — Indicates whether or not the filter is enabled.
        - List
          - `kind` (enum, required)
            - Allowed values: `list`
          - `id` (string, required) — The identifier of the filter.
          - `columnId` (string, required) — The identifier of the column this filter targets.
          - `mode` (enum or enum, optional) — Indicates whether to 'include' or 'exclude' the list of values.
          - `values` (list of boolean or list of double or list of string or list of string, optional) — The list of selected values in the filter.
          - `state` (enum or enum, optional) — Indicates whether or not the filter is enabled.
        - Text Match
          - `kind` (enum, required)
            - Allowed values: `text-match`
          - `mode` (enum or enum or enum or enum or enum or enum or enum or enum or enum or enum or enum or enum, required) — Indicates the type of text comparison to make.
          - `id` (string, required) — The identifier of the filter.
          - `columnId` (string, required) — The identifier of the column this filter targets.
          - `value` (string, optional) — The string to compare against.
          - `case` (enum or enum, optional) — Indicates whether the text comparison is case 'sensitive' or 'insensitive'.
          - `includeNulls` (enum or enum or enum, optional) — Indicates when to include null values.
          - `state` (enum or enum, optional) — Indicates whether or not the filter is enabled.
        - Hierarchy
          - `kind` (enum, required)
            - Allowed values: `hierarchy`
          - `id` (string, required) — The identifier of the filter.
          - `columnId` (string, required) — The identifier of the column this filter targets.
          - `mode` (enum or enum, optional) — Indicates whether to 'include' or 'exclude' the list of values.
          - `values` (list of list of string, optional) — The hierarchy paths selected by the filter.
          - `state` (enum or enum, optional) — Indicates whether or not the filter is enabled.
      - `folders` (list of object, optional) — The folders in the table and their contents.
        - `id` (string, required) — The identifier of the folder.
        - `name` (string, required) — The name of the folder.
        - `items` (list of string, optional) — The column and folder IDs contained within the folder.
      - `groupings` (list of object, optional) — The groupings in the table and their contents.
        - `id` (string, required) — The identifier of the grouping.
        - `groupBy` (list of string, optional) — The columns or folders that define the grouping.
        - `calculations` (list of string, optional) — The calculations applied to the grouping.
      - `summary` (list of string, optional) — The identifiers of all columns in the table that are summaries.
      - `order` (list of string, optional) — A list of identifiers that determines the order in which columns and folders are displayed in the UI. Does not include summary columns.
      - `visibleAsSource` (boolean, optional) — Indicates whether or not the table can be used as a source in other documents.
      - `sort` (list of object, optional) — The column, direction, and null behavior used to sort the rows of this table.
        - `columnId` (string, required) — The identifier of the column by which to sort.
        - `direction` (enum or enum, required) — The direction in which to sort.
        - `nulls` (enum or enum or enum, optional) — Indicates how the sort order treats null values.
      - `columnSecurities` (list of object, optional) — A list of the column security rules applied to columns in this table.
        - `id` (string, required) — The identifier of the column security rule.
        - `restrictedColumns` (list of string, required) — The list of columns restricted by the column security rule.
        - `criteria` (object or object or object, required)
          - No One Can View
            - `kind` (enum, required)
          - Specific Users and Teams
            - `kind` (enum, required)
            - `assignments` (list of object or object, required) — The identifiers of the users and teams that can access the columns restricted by the column security rule.
          - User Attribute
            - `kind` (enum, required)
            - `assignments` (list of object, required) — The identifier of a user attribute and the value users must be assigned to view the columns restricted by the column security rule.
      - `uniqueKeys` (list of string, optional) — [Private beta] The identifiers of the columns that uniquely identify records in the table.
- `kind` (enum, optional) — Document kind. Informational field, ignored when creating or updating a document.
  - Allowed values: `data-model`

## Response

### 200

The response body.

- `success` (boolean, required)
- `dataModelId` (string, required)

## Examples

**Request**

```json
{
  "schemaVersion": 1,
  "pages": [
    {
      "id": "string",
      "name": "string",
      "elements": [
        {
          "columns": [
            {
              "formula": "string",
              "id": "string"
            }
          ],
          "id": "string",
          "kind": "table",
          "source": {
            "connectionId": "string",
            "kind": "warehouse-table",
            "path": [
              "string"
            ]
          }
        }
      ]
    }
  ]
}
```

**Response**

```json
{
  "success": true,
  "dataModelId": "string"
}
```

**SDK Code**

```python
import requests

url = "https://api.sigmacomputing.com/v2/dataModels/dataModelId/spec"

payload = {
    "schemaVersion": 1,
    "pages": [
        {
            "id": "string",
            "name": "string",
            "elements": [
                {
                    "columns": [
                        {
                            "formula": "string",
                            "id": "string"
                        }
                    ],
                    "id": "string",
                    "kind": "table",
                    "source": {
                        "connectionId": "string",
                        "kind": "warehouse-table",
                        "path": ["string"]
                    }
                }
            ]
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.sigmacomputing.com/v2/dataModels/dataModelId/spec';
const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"schemaVersion":1,"pages":[{"id":"string","name":"string","elements":[{"columns":[{"formula":"string","id":"string"}],"id":"string","kind":"table","source":{"connectionId":"string","kind":"warehouse-table","path":["string"]}}]}]}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sigmacomputing.com/v2/dataModels/dataModelId/spec"

	payload := strings.NewReader("{\n  \"schemaVersion\": 1,\n  \"pages\": [\n    {\n      \"id\": \"string\",\n      \"name\": \"string\",\n      \"elements\": [\n        {\n          \"columns\": [\n            {\n              \"formula\": \"string\",\n              \"id\": \"string\"\n            }\n          ],\n          \"id\": \"string\",\n          \"kind\": \"table\",\n          \"source\": {\n            \"connectionId\": \"string\",\n            \"kind\": \"warehouse-table\",\n            \"path\": [\n              \"string\"\n            ]\n          }\n        }\n      ]\n    }\n  ]\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.sigmacomputing.com/v2/dataModels/dataModelId/spec")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"schemaVersion\": 1,\n  \"pages\": [\n    {\n      \"id\": \"string\",\n      \"name\": \"string\",\n      \"elements\": [\n        {\n          \"columns\": [\n            {\n              \"formula\": \"string\",\n              \"id\": \"string\"\n            }\n          ],\n          \"id\": \"string\",\n          \"kind\": \"table\",\n          \"source\": {\n            \"connectionId\": \"string\",\n            \"kind\": \"warehouse-table\",\n            \"path\": [\n              \"string\"\n            ]\n          }\n        }\n      ]\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.put("https://api.sigmacomputing.com/v2/dataModels/dataModelId/spec")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"schemaVersion\": 1,\n  \"pages\": [\n    {\n      \"id\": \"string\",\n      \"name\": \"string\",\n      \"elements\": [\n        {\n          \"columns\": [\n            {\n              \"formula\": \"string\",\n              \"id\": \"string\"\n            }\n          ],\n          \"id\": \"string\",\n          \"kind\": \"table\",\n          \"source\": {\n            \"connectionId\": \"string\",\n            \"kind\": \"warehouse-table\",\n            \"path\": [\n              \"string\"\n            ]\n          }\n        }\n      ]\n    }\n  ]\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('PUT', 'https://api.sigmacomputing.com/v2/dataModels/dataModelId/spec', [
  'body' => '{
  "schemaVersion": 1,
  "pages": [
    {
      "id": "string",
      "name": "string",
      "elements": [
        {
          "columns": [
            {
              "formula": "string",
              "id": "string"
            }
          ],
          "id": "string",
          "kind": "table",
          "source": {
            "connectionId": "string",
            "kind": "warehouse-table",
            "path": [
              "string"
            ]
          }
        }
      ]
    }
  ]
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.sigmacomputing.com/v2/dataModels/dataModelId/spec");
var request = new RestRequest(Method.PUT);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"schemaVersion\": 1,\n  \"pages\": [\n    {\n      \"id\": \"string\",\n      \"name\": \"string\",\n      \"elements\": [\n        {\n          \"columns\": [\n            {\n              \"formula\": \"string\",\n              \"id\": \"string\"\n            }\n          ],\n          \"id\": \"string\",\n          \"kind\": \"table\",\n          \"source\": {\n            \"connectionId\": \"string\",\n            \"kind\": \"warehouse-table\",\n            \"path\": [\n              \"string\"\n            ]\n          }\n        }\n      ]\n    }\n  ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "schemaVersion": 1,
  "pages": [
    [
      "id": "string",
      "name": "string",
      "elements": [
        [
          "columns": [
            [
              "formula": "string",
              "id": "string"
            ]
          ],
          "id": "string",
          "kind": "table",
          "source": [
            "connectionId": "string",
            "kind": "warehouse-table",
            "path": ["string"]
          ]
        ]
      ]
    ]
  ]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.sigmacomputing.com/v2/dataModels/dataModelId/spec")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PUT"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```