Snowflake Semantic View integration APIs

ThoughtSpot provides the Semantic View integrations REST API v2.0 endpoints to create, search, import, and delete semantic integration configurations programmatically.

Overview🔗

Snowflake Semantic Views provide a governed semantic layer for data in Snowflake, including named measures, dimensions, and business-logic formulas. When you create a semantic integration in ThoughtSpot, the platform reads the semantic view definition from Snowflake and generates a corresponding ThoughtSpot data model (Worksheet). The model inherits the column names, descriptions, and formula definitions from the Snowflake Semantic View.

You can use the semantic integration APIs to automate the following tasks:

Create a semantic integration that links a Snowflake Semantic View to a ThoughtSpot data model.
Search and list existing semantic integrations.
Re-import a semantic integration to refresh the ThoughtSpot model after the source Snowflake Semantic View has changed.
Delete a semantic integration and its generated ThoughtSpot model.

Prerequisites🔗

To use these APIs, the authenticated user must have one of the following privileges:

ADMINISTRATION (Can administer ThoughtSpot)
DATAMANAGEMENT (Can manage data)

If Role-Based Access Control (RBAC) is enabled on your instance, the user requires CAN_CREATE_OR_EDIT_CONNECTIONS (Can create/edit Connections) privilege.

API endpoints🔗

Method Endpoint Description

Method	Endpoint	Description
`POST`	`/api/rest/2.0/semantic-integrations/create`	Creates a new semantic integration by reading a Snowflake Semantic View and generating a ThoughtSpot data model.
`POST`	`/api/rest/2.0/semantic-integrations/search`	Returns a list of semantic integrations matching the specified filter criteria.
`POST`	`/api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/import`	Re-imports semantic updates from the CDW source and refreshes the associated ThoughtSpot data model.
`POST`	`/api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/delete`	Deletes a semantic integration and its generated ThoughtSpot data model.

POST

/api/rest/2.0/semantic-integrations/create

Creates a new semantic integration by reading a Snowflake Semantic View and generating a ThoughtSpot data model.

POST

/api/rest/2.0/semantic-integrations/search

Returns a list of semantic integrations matching the specified filter criteria.

POST

/api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/import

Re-imports semantic updates from the CDW source and refreshes the associated ThoughtSpot data model.

POST

/api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/delete

Deletes a semantic integration and its generated ThoughtSpot data model.

Create a semantic integration🔗

To create a new semantic integration by reading the specified Snowflake Semantic View and generating a corresponding ThoughtSpot data model, use the /api/rest/2.0/semantic-integrations/create API endpoint. On success, the response includes the integration GUID, the generated model GUID, and a per-formula import report.

Request parameters🔗

Parameter Description

Parameter	Description
`connection_identifier`	String. GUID or name of the Snowflake connection in ThoughtSpot.
`name`	String. Display name for the semantic integration. Must be unique.
`database_name`	String. Database name in the Snowflake CDW that contains the semantic view.
`schema_name`	String. Schema name in the Snowflake CDW that contains the semantic view.
`semantic_view_name`	String. Name of the Snowflake Semantic View to integrate.
`type`	String. CDW connector type. Valid values: `RDBMS_SNOWFLAKE` `RDBMS_DATABRICKS`
`description`	String. Optional. Description of the semantic integration.
`tags`	Array<String>. Optional. Tag GUIDs or names to associate with the integration.

connection_identifier

String. GUID or name of the Snowflake connection in ThoughtSpot.

name

String. Display name for the semantic integration. Must be unique.

database_name

String. Database name in the Snowflake CDW that contains the semantic view.

schema_name

String. Schema name in the Snowflake CDW that contains the semantic view.

semantic_view_name

String. Name of the Snowflake Semantic View to integrate.

type

String. CDW connector type. Valid values:

RDBMS_SNOWFLAKE
RDBMS_DATABRICKS

description

String. Optional. Description of the semantic integration.

tags

Array<String>. Optional. Tag GUIDs or names to associate with the integration.

Response fields🔗

Field Description

Field	Description
`id`	String. GUID of the newly created semantic integration.
`name`	String. Display name of the semantic integration.
`model_id`	String. GUID of the ThoughtSpot data model generated for this integration.
`model_name`	String. Display name of the generated ThoughtSpot data model.
`semantic_report`	Object. Per-formula import report. See undefined.

id

String. GUID of the newly created semantic integration.

name

String. Display name of the semantic integration.

model_id

String. GUID of the ThoughtSpot data model generated for this integration.

model_name

String. Display name of the generated ThoughtSpot data model.

semantic_report

Object. Per-formula import report. See undefined.

Semantic report fields🔗

The semantic_report object contains a summary and a list of per-formula import results.

summary fields:

Field Description

Field	Description
`total`	Integer. Total number of formulas in the Snowflake Semantic View.
`imported`	Integer. Number of formulas successfully imported.
`failed`	Integer. Number of formulas that failed to import.
`skipped`	Integer. Number of formulas that were skipped.

total

Integer. Total number of formulas in the Snowflake Semantic View.

imported

Integer. Number of formulas successfully imported.

failed

Integer. Number of formulas that failed to import.

skipped

Integer. Number of formulas that were skipped.

formulas array — each entry contains:

Field Description

Field	Description
`id`	String. Formula GUID in the generated ThoughtSpot model.
`name`	String. Formula name.
`description`	String. Formula description.
`source_expression`	String. Original CDW expression.
`translated_formula`	String. Equivalent ThoughtSpot formula expression.
`import_status`	String. One of `IMPORTED`, `FAILED`, or `SKIPPED`.
`change_status`	String. One of `NEW`, `UPDATED`, or `UNCHANGED`. Null on initial create (populated by import).

id

String. Formula GUID in the generated ThoughtSpot model.

name

String. Formula name.

description

String. Formula description.

source_expression

String. Original CDW expression.

translated_formula

String. Equivalent ThoughtSpot formula expression.

import_status

String. One of IMPORTED, FAILED, or SKIPPED.

change_status

String. One of NEW, UPDATED, or UNCHANGED. Null on initial create (populated by import).

Example request🔗

curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/semantic-integrations/create' \
  -H 'Authorization: Bearer {access-token}' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "connection_identifier": "<snowflake-connection-guid-or-name>",
  "name": "Sales Semantic View",
  "database_name": "SALES_DB",
  "schema_name": "PUBLIC",
  "semantic_view_name": "SALES_SEMANTIC_VIEW",
  "type": "RDBMS_SNOWFLAKE",
  "description": "Semantic integration for the Sales Snowflake Semantic View"
}'

Example response🔗

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Sales Semantic View",
  "model_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "model_name": "Sales Semantic View",
  "semantic_report": {
    "summary": {
      "total": 5,
      "imported": 4,
      "failed": 0,
      "skipped": 1
    },
    "formulas": [
      {
        "id": "formula-guid-001",
        "name": "Total Revenue",
        "description": "Sum of all revenue",
        "source_expression": "SUM(revenue)",
        "translated_formula": "sum(revenue)",
        "import_status": "IMPORTED",
        "change_status": null
      }
    ]
  }
}

Search semantic integrations🔗

To fetch a paginated list of semantic integrations matching the specified criteria, use the /api/rest/2.0/semantic-integrations/search API endpoint. Returns all integrations if no filters are specified.

Request parameters🔗

Parameter Description

Parameter	Description
`pattern`	String. Optional. Substring filter to narrow search results by integration name.
`author_identifiers`	Array<String>. Optional. Filter by the GUID or username of the user who created the integration.
`connection_identifiers`	Array<String>. Optional. Filter by the GUID or name of the Snowflake connection associated with the integration.
`sort_options`	Object. Optional. Sort configuration. See undefined.
`record_offset`	Integer. Optional. Number of records to skip for pagination. Minimum: 0. Default: 0.
`record_size`	Integer. Optional. Maximum number of records to return. Use `0` to return all records. Default: 10.

pattern

String. Optional. Substring filter to narrow search results by integration name.

author_identifiers

Array<String>. Optional. Filter by the GUID or username of the user who created the integration.

connection_identifiers

Array<String>. Optional. Filter by the GUID or name of the Snowflake connection associated with the integration.

sort_options

Object. Optional. Sort configuration. See undefined.

record_offset

Integer. Optional. Number of records to skip for pagination. Minimum: 0. Default: 0.

record_size

Integer. Optional. Maximum number of records to return. Use 0 to return all records. Default: 10.

Sort options🔗

Field Description

Field	Description
`field_name`	String. Sort field. One of: `NAME`, `AUTHOR`, `CREATED_TIME`, `MODIFIED_TIME`.
`order`	String. Sort direction. `ASC` for ascending, `DESC` for descending.

field_name

String. Sort field. One of: NAME, AUTHOR, CREATED_TIME, MODIFIED_TIME.

order

String. Sort direction. ASC for ascending, DESC for descending.

Response fields🔗

Returns an array of objects, each with the following fields:

Field Description

Field	Description
`id`	String. GUID of the semantic integration.
`name`	String. Display name of the semantic integration.
`description`	String. Description of the semantic integration. Null if not set.
`model_id`	String. GUID of the associated ThoughtSpot data model.
`model_name`	String. Display name of the associated ThoughtSpot data model.
`import_type`	String. How the semantic definition was sourced. `CDW` for Snowflake Semantic View; `FILE` for file upload.
`type`	String. CDW connector type. Either `RDBMS_SNOWFLAKE` or `RDBMS_DATABRICKS`.
`connection_id`	String. GUID of the Snowflake connection.
`connection_name`	String. Display name of the Snowflake connection.
`author_id`	String. GUID of the user who created the integration.
`author_name`	String. Username of the user who created the integration.
`creation_time_in_millis`	Float. Creation time in Unix epoch milliseconds.
`modification_time_in_millis`	Float. Last modification time in Unix epoch milliseconds.
`tags`	Array. Tags associated with the integration, each with `id` and `name`.

id

String. GUID of the semantic integration.

name

String. Display name of the semantic integration.

description

String. Description of the semantic integration. Null if not set.

model_id

String. GUID of the associated ThoughtSpot data model.

model_name

String. Display name of the associated ThoughtSpot data model.

import_type

String. How the semantic definition was sourced. CDW for Snowflake Semantic View; FILE for file upload.

type

String. CDW connector type. Either RDBMS_SNOWFLAKE or RDBMS_DATABRICKS.

connection_id

String. GUID of the Snowflake connection.

connection_name

String. Display name of the Snowflake connection.

author_id

String. GUID of the user who created the integration.

author_name

String. Username of the user who created the integration.

creation_time_in_millis

Float. Creation time in Unix epoch milliseconds.

modification_time_in_millis

Float. Last modification time in Unix epoch milliseconds.

tags

Array. Tags associated with the integration, each with id and name.

Example request🔗

curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/semantic-integrations/search' \
  -H 'Authorization: Bearer {access-token}' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "connection_identifiers": ["<snowflake-connection-guid-or-name>"],
  "sort_options": {
    "field_name": "MODIFIED_TIME",
    "order": "DESC"
  },
  "record_size": 20,
  "record_offset": 0
}'

Import a semantic integration🔗

To re-import semantic updates from the Snowflake CDW source for an existing integration, and rebuild the corresponding ThoughtSpot data model, send a POST request to the /api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/import API endpoint. Send this API request, after the source Snowflake Semantic View has been updated (formulas added, removed, or modified) to bring the ThoughtSpot model back in line with the CDW definition.

Note	Importing updates is not supported for integrations created using the file upload option in the ThoughtSpot UI. To refresh a file-upload-based integration, use the ThoughtSpot UI.

The import operation:

Preserves the integration GUID, name, and model_id. Only the formula set is refreshed.
Returns the same semantic_report response as create, with an additional change_status per formula indicating whether each formula is NEW, UPDATED, or UNCHANGED since the previous import.

Path parameters🔗

Parameter Description

Parameter	Description
`semantic_integration_identifier`	String. Path parameter. GUID or name of the semantic integration to re-import.

semantic_integration_identifier

String. Path parameter. GUID or name of the semantic integration to re-import.

Response fields🔗

Same as create, with the addition of the change_status field in each formula entry:

change_status value Description

`change_status` value	Description
`NEW`	Formula is new since the previous import.
`UPDATED`	Formula definition changed since the previous import.
`UNCHANGED`	Formula is unchanged since the previous import.

NEW

Formula is new since the previous import.

UPDATED

Formula definition changed since the previous import.

UNCHANGED

Formula is unchanged since the previous import.

Example request🔗

curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/semantic-integrations/Sales%20Semantic%20View/import' \
  -H 'Authorization: Bearer {access-token}' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data-raw '{}'

Example response🔗

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Sales Semantic View",
  "model_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "model_name": "Sales Semantic View",
  "semantic_report": {
    "summary": {
      "total": 6,
      "imported": 5,
      "failed": 0,
      "skipped": 1
    },
    "formulas": [
      {
        "id": "formula-guid-001",
        "name": "Total Revenue",
        "description": "Sum of all revenue",
        "source_expression": "SUM(revenue)",
        "translated_formula": "sum(revenue)",
        "import_status": "IMPORTED",
        "change_status": "UNCHANGED"
      },
      {
        "id": "formula-guid-002",
        "name": "Net Profit",
        "description": "Revenue minus costs",
        "source_expression": "SUM(revenue) - SUM(costs)",
        "translated_formula": "sum(revenue) - sum(costs)",
        "import_status": "IMPORTED",
        "change_status": "NEW"
      }
    ]
  }
}

Delete a semantic integration🔗

To permanently delete the specified semantic integration and its generated ThoughtSpot data model from the system, use the /api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/delete API endpoint.

Warning

Deletion is permanent and cannot be undone. If you need to restore the integration, use the create endpoint to re-import the Snowflake Semantic View.

Path parameters🔗

Parameter Description

Parameter	Description
`semantic_integration_identifier`	String. Path parameter. GUID or name of the semantic integration to delete.

semantic_integration_identifier

String. Path parameter. GUID or name of the semantic integration to delete.

Example request🔗

curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/semantic-integrations/Sales%20Semantic%20View/delete' \
  -H 'Authorization: Bearer {access-token}' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data-raw '{}'

A successful delete returns HTTP 200 with an empty response body.

Error responses🔗

Code	Description
400	Bad Request — required parameter missing or invalid value (for example, unsupported `type`).
401	Unauthorized — authentication token missing, expired, or invalid.
403	Forbidden — the caller lacks the required privilege.
404	Not Found — no semantic integration exists with the given identifier.

Snowflake Semantic View integration APIs

Overview🔗

Prerequisites🔗

API endpoints🔗

Create a semantic integration🔗

Request parameters🔗

Response fields🔗

Semantic report fields🔗

Example request🔗

Example response🔗

Search semantic integrations🔗

Request parameters🔗

Sort options🔗

Response fields🔗

Example request🔗

Import a semantic integration🔗

Path parameters🔗

Response fields🔗

Example request🔗

Example response🔗

Delete a semantic integration🔗

Path parameters🔗

Example request🔗

Error responses🔗

Related resources🔗