Connection API

The Connection API endpoints allow you to create, update, list, delete and test a data warehouse connection. 
 

Summary of Content

Endpoints
The Connection Object
      Attributes
Create a Connection
List Connections
Look Up a Connection
Update a Connection
Test a Connection
Delete a Connection
Related Resources

Endpoints

Try these endpoints in Swagger

POST /v2/connections

      Use this endpoint to create a data warehouse connection object.

GET /v2/connections?limit=<number>&page=<page-string>

      Returns a list of the active data warehouse connection objects. 

GET /v2/connections/{connectionId}

      Returns a connection object based on the input connectionId. 

PUT /v2/connections/:id

      This endpoint allows you to update or restore a connection object to a data warehouse.

GET /v2/connections/:connectionId/test

      Use this endpoint to validate a data warehouse connection object.

DELETE /v2/connections/:connectionId

      Use this endpoint to delete a data warehouse connection object.

 

The Connection Object

Attributes

organizationId string

The unique identifier associated with the connections' organization.

connectionId string

The unique identifier associated with the individual connection.

isSample boolean

True if the connection contains Sigma sample data.

lastActiveAt string

The timestamp at which a query was last run against the connection.

name string

The connection's name, as is listed in Sigma.

type string

The connection's Cloud Data Warehouse (CDW) provider.

useOauth boolean | undefined

True if access to the connection is authenticated with OAuth through your Identity Provider (IdP).
Note: Only applicable to Snowflake connections.

createdBy string

The unique identifier, memberId, of the organization member who created the connection.

updatedBy string

The unique identifier, memberId, of the organization member who last updated the connection.

createdAt string

The timestamp at which the connection was created.

updatedAt string

The timestamp at which the connection was last updated.

isArchived boolean | undefined

True if the connection is archived.

 

{
    "organizationId": "cf2de26e-9a2c-4c58-ba1c-91a0955df7ez",
    "connectionId": "48726c98-8495-4488-bb6e-108a115b732df",
    "isSample": false,
    "lastActiveAt": "2022-02-28T21:26:52.033Z",
    "name": "My First Connection",
    "type": "snowflake",
    "useOauth": false,
    "createdBy": "6VZszXPJqLXpIezceRadESnwfPPUg",
    "updatedBy": "6VZszXPJqLXpIezceRadESnwfPPUg",
    "createdAt": "2021-10-04T20:36:41.044Z",
    "updatedAt": "2021-10-08T21:38:25.044Z"
    isArchived: false
}

Create a Connection

Use this endpoint to create a data warehouse connection.

POST /v2/connections

Try it in Swagger

Permissions

  • You must be an admin to use this endpoint. 

Parameters

Note: The parameters below map to the fields in the data warehouse connection section in the administration portal. Each data warehouse uses a different schema, see swagger examples for more information. 

details | { <db details object> } | [required]

The key/value pairs for this parameter are determined by the specific data warehouse connection. The example below reflects a Snowflake connection. 

{  
   "details": { 
 "type": "snowflake", 
 "account": "tester", 
 "host": "testing.snowtest.com", 
 "password": "<password>", 
 "role": "A_ROLE", 
 "user": "THE_DEV", 
 "warehouse": "TEST_WAREHOUSE", 
 "writeAccess": { 
        "writeDatabase": "PUBLIC_API", 
        "writeSchema": "PUBLIC", 
        "materializationWarehouse": "" 
        } 
 }

name | string | [required]

The name of the connection. 

description | { <description object> } | [optional]

Any key/value pair. 

timeoutSecs | number | [optional]

Number of seconds Sigma waits for a query to return results before it times out.

useFriendlyNames | boolean | [true or false]

If set to "true", Sigma will make the column names more readable. A column with a name like "SALES_JSON" would become "Sales Json". If set to "false," then the warehouse column names are used, unaltered.

cURL Request

The example below is based on a Snowflake connection.

curl -X 'POST' \ 
  'https://api.sigmacomputing.com/v2/connections/' \ 
  --header 'accept: application/json' \ 
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {access_token}' \
  --data-raw '{  
  "details": {  
    "account": "snowflake",  
    "user": "string",
    "host": "string",  
    "password": "string",
    "role": "string",
         "user": "string", 
         "warehouse": "string", 
    "writeAccess": {
             "writeDatabase": "string",  
      "writeSchema": "string",
      "materializationWarehouse": "string"
      } 
   },  
   "name": "string",  
   "timeoutSecs": "integer",  
   "useFriendlyNames": boolean
}

 

Response

{ 
"organizationId": "string", 
"connectionId": "string", 
"isSample": boolean, 
"lastActiveAt": "2022-07-21T23:05:00.453Z", 
"name": "string", 
"type": "string", 
"useOauth": boolean, 
"createdBy": "string", 
"updatedBy": "string", 
"createdAt": "string", 
"updatedAt": "string", 
"isArchived": boolean
}

Example

Example Request:

curl -X 'POST' \ 
     'https://api.sigmacomputing.com/v2/connections/' \ 
      --header 'accept: application/json' \ 
      --header 'Content-Type: application/json' \
      --header 'Authorization: Bearer {access_token}' \
      --data-raw '{ 
      "details": { 
          "type": "snowflake", 
          "account": "tester", 
          "host": "testing.snowtest.com", 
          "password": "<password>", 
          "role": "A_ROLE", 
          "user": "THE_DEV", 
          "warehouse": "TEST_WAREHOUSE", 
          "writeAccess": { 
              "writeDatabase": "PUBLIC_API", 
              "writeSchema": "PUBLIC", 
              "materializationWarehouse": "" 
          } 
       }
       "name": "string",
      "timeoutSecs": "integer",
      "useFriendlyNames": boolean,
}

Example Response:

{ 
 "organizationId": "98da0f2b-8482-4f37-833a-0b042443f1c9",
 "connectionId": "c96b6e71-a40f-47a3-a84d-33a742eead7f", 
 "isSample": false, 
 "lastActiveAt": "2022-06-22T20:47:07.000Z", 
 "name": "test_write_7_ctas", 
 "type": "snowflake", 
 "useOauth": false, 
 "createdBy": "f0hGBLjzzmMNW3fWKiCUUDKYDlKNz", 
 "updatedBy": "f0hGBLjzzmMNW3fWKiCUUDKYDlKNz", 
 "createdAt": "2022-06-22T20:47:07.899Z", 
 "updatedAt": "2022-06-22T20:47:07.899Z", 
 "isArchived": false 
}

 

List Connections

Use this endpoint to list the active data warehouse connections. 

GET /v2/connections?limit=<number>&page=<page-string>

Try it in Swagger

Permissions

  • The user account associated with the API access token must have permission to access the requested connection.
    Note: If you encounter a permission error for the given endpoint, check with your organization Admin to verify your account type and permissions associated with your API token.

Query Parameters

page | string [optional]

An identifier used for pagination.

limit | number [optional]

The number of connections to return.

cURL Request

curl --location --request GET 'https://api.sigmacomputing.com/v2/connections?limit=<number>&page=<page-string> \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \

Response

{ 
    "entries": [ 
        { 
               "organizationId": 'string',  
               "connectionId": 'string',  
               "isSample": boolean,  
               "lastActiveAt": '2022-06-17T10:03:25.000Z',  
               "name": 'string',
               "type": 'string', 
               "useOauth": boolean, 
               "createdBy": 'string', 
               "updatedBy": 'string', 
               "createdAt": '2022-06-17T10:03:25.311Z', 
               "updatedAt": '2022-06-17T10:03:25.311Z', 
               "isArchived": boolean 
              }, 
              {  
               "organizationId: 'string', 
               "connectionId: 'string', 
               "isSample: boolean, 
               "lastActiveAt: '2022-06-17T10:03:25.000Z',  
               "name: 'string',  
               "type: 'string', 
               "useOauth: boolean, 
               "createdBy: 'string', 
               "updatedBy: 'string', 
               "createdAt: '2022-06-17T10:03:25.306Z',  
               "updatedAt: '2022-06-17T10:03:25.306Z', 
               "isArchived: boolean 
              }, 
  ], 
  "hasMore": boolean, 
  "nextPage": 'string'
  "total": 2

Example

Example Request:

curl --location --request GET 'https://api.sigmacomputing.com/v2/connections?limit=<number>&page=<page-string> \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \

Example Response:

{ 
    entries: [ 
        { 
               "organizationId": 'a7f0d337-99d4-4c26-be65-1d657343c45e',  
               "connectionId": 'd378f08a-4fe9-456e-bca6-43ec6b540f55',  
               "isSample": false,  
               "lastActiveAt": '2022-06-17T10:03:25.000Z',  
               "name": 'a_conn0002',
               "type": 'snowflake', 
               "useOauth": false, 
               "createdBy"": '01faRqtvlAsPshvyd2D7qlcgcZJJv', 
               "updatedBy": '01faRqtvlAsPshvyd2D7qlcgcZJJv', 
               "createdAt": '2022-06-17T10:03:25.311Z', 
               "updatedAt": '2022-06-17T10:03:25.311Z', 
               "isArchived": false 
              }, 
              {  
               "organizationId": 'a7f0d337-99d4-4c26-be65-1d657343c45e', 
               "connectionId": 'f046df8b-a528-42a3-a1d7-c11f4740e067', 
               "isSample": false, 
               "lastActiveAt": '2022-06-17T10:03:25.000Z',  
               "name": 'b_conn0001',  
               "type": 'snowflake', 
               "useOauth": false, 
               "createdBy": '01faRqtvlAsPshvyd2D7qlcgcZJJv', 
               "updatedBy": '01faRqtvlAsPshvyd2D7qlcgcZJJv', 
               "createdAt": '2022-06-17T10:03:25.306Z',  
               "updatedAt": '2022-06-17T10:03:25.306Z', 
               "isArchived": false 
             }, 
  ], 
  "hasMore": true, 
  "nextPage": '{"name":"c_conn0005","lastCreatedAt":1655460205324}'

Look Up a Connection

Returns a connection object based on the input connectionId.

GET /v2/connections/{connectionId}

Try it in Swagger

Permissions

  • The user account associated with the API access token must have permission to access the requested connection.
    Note: If you encounter a permission error for the given endpoint, check with your organization Admin to verify your account type and permissions associated with your API token.

Parameters

None

cURL Request

curl --location --request GET 'https://api.sigmacomputing.com/v2/connections/{connectionId}' \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \

 

Response

{
   "organizationId": string,
   "connectionId": string,
   "isSample": boolean,
   "lastActiveAt": string,
   "name": string,
   "type": string,
   "useOauth": boolean,
   "createdBy": string,
   "updatedBy": string,
   "createdAt": string,
   "updatedAt": string,
   "isArchived": boolean
}

 

Example

Example Request:

curl --location --request GET 'https://api.sigmacomputing.com/v2/connections/48726c98-8495-4488-bb6e-108a115b732df' \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \

 

Example Response:

 {
   "organizationId": "cf2de26e-9a2c-4c58-ba1c-91a0955df7ez",
   "connectionId": "65726g36-8495-4588-er6e-194a115b734kf",
   "isSample": false,
   "lastActiveAt": "2022-01-08T21:16:42.053Z",
   "name": "My First Connection",
   "type": "snowflake",
   "useOauth": false,
   "createdBy": "6VZszXPJqLXpIezceRadESnwfPPUg",
   "updatedBy": "6VZszXPJqLXpIezceRadESnwfPPUg",
   "createdAt": "2021-08-09T20:33:41.044Z",
   "updatedAt": "2021-10-08T21:28:25.044Z",
   "isArchived": false
}

 

Update a Connection

Use this endpoint to update or restore a connection to a data warehouse. 

PUT /v2/connections/:id

Note: We have deprecated the PATCH endpoint below. Use PUT instead. 

PATCH /v2/connections/{connectionId}

Try it in Swagger


Permissions

  • You must be an admin to use this endpoint. 

Parameters

Note: The parameters below map to the fields in the data warehouse connection section in the administration portal. Each data warehouse uses a different schema, see swagger examples for more information. 

connectionId | string [required]

The ID of the connection to update or restore.

details | { <db details object> } | [required]

The key/value pairs for this parameter are determined by the specific data warehouse connection. The example below reflects a Snowflake connection. 

{  
    "details": { 
    "type": "snowflake", 
    "account": "tester", 
    "host": "testing.snowtest.com", 
    "password": "<password>", 
    "role": "A_ROLE", 
    "user": "THE_DEV", 
    "warehouse": "TEST_WAREHOUSE", 
    "writeAccess": { 
           "writeDatabase": "PUBLIC_API", 
           "writeSchema": "PUBLIC", 
           "materializationWarehouse": "" 
           } 
}

name | string | [required]

The name of the connection. 

description | { <description object> } | [optional]

Any key/value pair. 

timeoutSecs | number | [optional]

Number of seconds Sigma waits for a query to return results before timing out.

useFriendlyNames | boolean | [true or false]

If set to "true", Sigma will make the column names more readable. A column with a name like "SALES_JSON" would become "Sales Json". If set to "false," then the warehouse column names are used, unaltered.

restore | boolean [optional]  

Set to true if the updated connection is archived and needs to be restored.

 

cURL Request

The example below is based on a Snowflake connection. 

curl -X 'PUT' \
  'https://api.sigmacomputing.com/v2/connections/:id' \
   --header 'accept: application/json' \
   --header 'Content-Type: application/json' \
   --header 'Authorization: Bearer {access_token}' \
   --data-raw '{
   "details": {
     "account": "snowflake",
     "user": "string",
     "host": "string",
     "password": "string",
     "role": "string",
      "user": "string", 
           "warehouse": "string",
     "database": "string",
     "writeAccess": {
       "writeDatabase": "string", 
      "writeSchema": "string",
      "materializationWarehouse": "string"
      }
   },
   "name": "string",
   "timeoutSecs": "integer", 
   "useFriendlyNames": "boolean"
}'

Response

{
  "organizationId": "string",
  "connectionId": "string",
  "isSample": boolean,
  "lastActiveAt": "2022-07-21T23:05:00.453Z",
  "name": "string",
  "type": "string",
  "useOauth": boolean,
  "createdBy": "string",
  "updatedBy": "string",
  "createdAt": "string",
  "updatedAt": "string",
  "isArchived": boolean
}

Example

Example Request:

curl -X 'PUT' \ 
  'https://api.sigmacomputing.com/v2/connections/:id' \ 
   --header 'accept: application/json' \ 
   --header 'Content-Type: application/json' \
   --header 'Authorization: Bearer {access_token}' \ 
   --data-raw '{ 
    "details": {
       "type": "snowflake", 
       "account": "tester", 
       "host": "testing.snowtest.com",
       "password": "<password>", 
       "role": "A_ROLE", 
       "user": "THE_DEV", 
       "warehouse": "TEST_WAREHOUSE", 
       "writeAccess": { 
          "writeDatabase": "PUBLIC_API", 
          "writeSchema": "PUBLIC", 
          "materializationWarehouse": "" 
          } 
    },
    "name": "string",
    "timeoutSecs": "integer",
    "useFriendlyNames": boolean,
    "restore": true// Set to true if the updated connection is archived and needs to be restored
}

Example Response:

{ 
    "organizationId": "98da0f2b-8482-4f37-833a-0b042443f1c9",
    "connectionId": "c96b6e71-a40f-47a3-a84d-33a742eead7f", 
    "isSample": false, 
    "lastActiveAt": "2022-06-22T20:47:07.000Z", 
    "name": "test_write_7_ctas", 
    "type": "snowflake", 
    "useOauth": false, 
    "createdBy": "f0hGBLjzzmMNW3fWKiCUUDKYDlKNz", 
    "updatedBy": "f0hGBLjzzmMNW3fWKiCUUDKYDlKNz", 
    "createdAt": "2022-06-22T20:47:07.899Z", 
    "updatedAt": "2022-06-22T20:47:07.899Z", 
    "isArchived": false 
}

 

Test a Connection

Use this endpoint to validate a data warehouse connection.

GET /v2/connections/:connectionId/test

Try it in Swagger

Permissions

  • The user account associated with the API access token must have permission to updated the requested connection.
    Note: If you encounter a permission error for the given endpoint, check with your organization Admin to verify your account type and permissions associated with your API token.

Path Parameters

connectionId | string [required]

The ID of the connection to delete.

cURL Request

curl --location --request GET 'https://api.sigmacomputing.com/v2/connections/:connectionId/test' \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \

Response

{
  "read": "SUCCESS",
  "write": "SUCCESS"
}

Example

Example Request:

curl --location --request GET 'https://api.sigmacomputing.com/v2/connections/c96c6e71-a43f-47a3-a84d-33a742eead7f/test' \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \

Example Response:

200 OK

{
  "read": "SUCCESS",
  "write": "SUCCESS"
}

 

Delete a Connection

Use this endpoint to delete a data warehouse connection.

DELETE /v2/connections/:connectionId

Try it in Swagger

Permissions

You must be an admin to use this endpoint. 

Path Parameters

connectionId | string [required]

The ID of the connection to delete.

cURL Request

curl --location --request DELETE 'https://api.sigmacomputing.com/v2/connections/:connectionId' \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \

Response

{}

Example

Example Request:

curl --location --request DELETE 'https://api.sigmacomputing.com/v2/connections/:1234' \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \

Example Response:

{}

 

Related Resources

API Documentation

Get an API Token and Client ID
Identify Unique IDs in Sigma

Product Documentation

Create a Connection

Was this page helpful?
Yes No