> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognite.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Cognite Data Fusion (CDF) is an industrial DataOps platform. Prefer English docs unless the user asks for another locale.
> Follow /_llms/ index links recursively until you reach page URLs ending in .md. Fetch those Markdown twins instead of HTML.
> For REST APIs, default to calendar version 20230101 (stable). Use 20230101-beta or 20230101-alpha only if the user is on a preview API. Cite paths under /api-reference/concepts/<version>/ and the Cdf-Version header. Prefer the Python SDK (cognite-sdk) unless the user is in JavaScript/TypeScript.
> Start here by task: platform overview /cdf/index.md; data modeling /cdf/dm/index.md; data integration /cdf/integration/index.md; access /cdf/access/index.md; CDF Toolkit /cdf/deploy/cdf_toolkit/index.md; REST quickstart /dev/quickstart.md; Python SDK https://cognite-sdk-python.readthedocs-hosted.com/en/stable/; Atlas AI /cdf/atlas_ai/index.md; plan an Atlas AI agent /cdf/atlas_ai/concepts/atlas_ai_agent_planning.md; Flows apps /cdf/flows/index.md; MCP and IDE setup /dev/guides/ide_ai_integration.md.
> For implementation work, also load /skill.md.

# Set up a Snowflake integration as an external data source

> Register a Snowflake external data source so Transformations can read tables with ext_snowflake.

> [!WARNING]
>
> The features described in this article are in [public preview](https://docs.cognite.com/cdf/product_feature_status.md#public-preview) and may change. The Transformations external data sources API is [beta](https://docs.cognite.com/api-reference/concepts/20230101-beta/transformation-external-data.md).

Register a Snowflake integration in Cognite Data Fusion (CDF) as an [external data source](https://docs.cognite.com/api-reference/concepts/20230101-beta/transformation-external-data.md), from Integrations or with the Transformations API.

## Before you start

### On Snowflake

CDF uses the account identifier, service user, service role, and warehouse to open a session in your Snowflake account.

| Requirement | Detail |
| - | - |
| Account identifier | `<orgname>-<accountname>`. Do not include `https://` or `.snowflakecomputing.com`. In Snowsight, open the account menu and select View account details. |
| Service user | A non-human user. It has no password and uses key-pair authentication. |
| Service role | Grant `USAGE` on the database, schema, and warehouse, and `SELECT` on the tables. Use one service user per CDF project. Do not share that user with other tools, so you can rotate or revoke one project on its own. |
| Warehouse | Use a dedicated Snowflake warehouse so transformation reads do not compete with other workloads. |
| Network | CDF must reach the Snowflake account. |

Create the service user and role. This is an example. Replace the names to match your account:

```sql title="Example service user and role" theme={"languages":{"custom":["/_languages/kuiper.json"]}}
CREATE ROLE IF NOT EXISTS COGNITE_TRANSFORMATIONS_ROLE;

CREATE USER IF NOT EXISTS COGNITE_TRANSFORMATIONS_SVC
  TYPE = SERVICE
  DEFAULT_ROLE = COGNITE_TRANSFORMATIONS_ROLE
  DEFAULT_WAREHOUSE = COGNITE_WH;

GRANT ROLE COGNITE_TRANSFORMATIONS_ROLE TO USER COGNITE_TRANSFORMATIONS_SVC;
GRANT USAGE ON WAREHOUSE COGNITE_WH TO ROLE COGNITE_TRANSFORMATIONS_ROLE;
GRANT USAGE ON DATABASE SALES_DB TO ROLE COGNITE_TRANSFORMATIONS_ROLE;
GRANT USAGE ON SCHEMA SALES_DB.PUBLIC TO ROLE COGNITE_TRANSFORMATIONS_ROLE;
GRANT SELECT ON TABLE SALES_DB.PUBLIC.EQUIPMENT TO ROLE COGNITE_TRANSFORMATIONS_ROLE;
```

Do not grant `INSERT`, `UPDATE`, `DELETE`, `CREATE`, `OWNERSHIP`, `ACCOUNTADMIN`, `ALL PRIVILEGES`, or broad future grants.

For a dynamic table or a Snowflake-managed Iceberg table, grant `SELECT` on that table type instead.

If the account uses a network policy, contact [Cognite Support](https://cognite.zendesk.com/hc/en-us/requests/new) for the CDF egress IP addresses. Your Snowflake admin allowlists those addresses so CDF can reach the account.

### On CDF

These capabilities control who can register the source and who can run queries that use it. See [Transform data](https://docs.cognite.com/cdf/access/guides/capabilities.md#transform-data).

Use a CDF token for API calls. That identity is separate from the Snowflake service user.

| Capability | Actions | Needed for |
| - | - | - |
| `transformationsExternalDataSourcesAcl` | `WRITE` | Register, rotate keys, or delete |
| `transformationsExternalDataSourcesAcl` | `READ` | List and retrieve |
| `transformationsExternalDataSourcesAcl` | `USE` | Run transformations or queries that reference the source |
| `transformationsAcl` | `READ`, `WRITE` | Create and run transformations |
| Destination space capabilities | Read/write as needed | Write instances to your data model |

Example scope for all sources in the project:

```json theme={"languages":{"custom":["/_languages/kuiper.json"]}}
{
  "capabilities": [
    {
      "transformationsExternalDataSourcesAcl": {
        "actions": ["READ", "WRITE", "USE"],
        "scope": { "all": {} }
      }
    },
    {
      "transformationsAcl": {
        "actions": ["READ", "WRITE"],
        "scope": { "all": {} }
      }
    }
  ]
}
```

To limit access, set `dataSetId` on the source and use `datasetScope` on the capability.

## Register in Integrations

**1. Open Integrations**

Navigate to Data fusion > Integrate > Integrations, select Zero-copy, then select Set up.

**2. Select a source system**

Select Snowflake, then Snowflake Connector.

**3. Enter the integration details**

External ID is permanent.

**4. Enter the connection details**

Use the account identifier, service user, role, and warehouse from [On Snowflake](#on-snowflake). The account identifier is not a URL.

**5. Create the connection**

Select Create connection. The integration is listed on the Zero-copy tab.

**6. Copy the public key**

Open the integration and copy the public key from the details page.

**7. Send the key to your Snowflake admin**

The admin registers it on the Snowflake service user. See [Register the public key](#register-the-public-key).

To register the same source with the API, continue with [Register with the API](#register-with-the-api).

## Register with the API

Set base values (replace placeholders):

```bash theme={"languages":{"custom":["/_languages/kuiper.json"]}}
export CDF_CLUSTER="westeurope-1"
export CDF_PROJECT="my-project"
export CDF_TOKEN="<cdf-access-token>"
export CDF_BASE="https://${CDF_CLUSTER}.cognitedata.com/api/v1/projects/${CDF_PROJECT}"
```

**1. Collect the Snowflake values**

Collect the account identifier, service user, service role, and warehouse. A Snowflake admin creates them in [On Snowflake](#on-snowflake).

**2. Grant CDF capabilities**

Add the [capabilities above](#on-cdf) to the group used by the identity that calls the API and runs transformations.

**3. Register the source**

```bash theme={"languages":{"custom":["/_languages/kuiper.json"]}}
curl -sS -X POST "${CDF_BASE}/transformations/externaldata" \
  -H "Authorization: Bearer ${CDF_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "externalId": "snowflake-sales-prod",
        "name": "Snowflake Sales (prod)",
        "format": "snowflake",
        "expiryTime": 1809129600000,
        "settings": {
          "credentials": {
            "accountIdentifier": "myorg-myaccount",
            "userName": "COGNITE_TRANSFORMATIONS_SVC",
            "roleName": "COGNITE_TRANSFORMATIONS_ROLE"
          },
          "locationDescription": { "warehouseName": "COGNITE_WH" }
        }
      }
    ]
  }'
```

| Field | Detail |
| - | - |
| `externalId` | Stable ID you reference in SQL. Unique in the project. |
| `expiryTime` | Epoch milliseconds, in the future and at most one year ahead. The sample is 1 May 2027 UTC. |
| `accountIdentifier` | Account identifier with no URL, path, or spaces. |
| `userName`, `roleName`, `warehouseName` | Service user, service role, and warehouse. |
| `dataSetId` | Optional. Scopes access. |

`format` must be `"snowflake"`. See [Transformation external data sources](https://docs.cognite.com/api-reference/concepts/20230101-beta/transformation-external-data.md). Success returns `201` and the generated `publicKey`. The private key is never returned.

If the `externalId` already exists in the project, the request returns `409` and creates no items. A connection is not edited in place. To change settings, delete the source and register a replacement.

## Register the public key

Copy the public key from the integration details page, or from the `publicKey` field in the API response. Send it to your Snowflake admin. The admin sets the key on the service user. Paste the key without the `BEGIN` and `END` lines and without line breaks.

```sql theme={"languages":{"custom":["/_languages/kuiper.json"]}}
ALTER USER COGNITE_TRANSFORMATIONS_SVC SET RSA_PUBLIC_KEY = '<publicKey from CDF>';
```

Run `DESC USER COGNITE_TRANSFORMATIONS_SVC;` and confirm `RSA_PUBLIC_KEY_FP` is set. Until this command runs, a preview that uses the external ID fails with an invalid JWT token. See [Read Snowflake data in transformations](https://docs.cognite.com/cdf/integration/guides/transformation/read_snowflake.md).

## Rotate the public key

The public key expires. Set the new expiry in the future and at most one year ahead. Rotate when no critical job is scheduled.

Open the integration on the Zero-copy tab in Integrations and select Edit. You can change the expiry and generate a new public key. Connection settings stay read-only. Select Save, then copy the new public key from the details page and send it to your Snowflake admin. The admin registers the new key on the service user before the next run. The external ID stays the same, so existing SQL does not change.

With the API:

```bash theme={"languages":{"custom":["/_languages/kuiper.json"]}}
curl -sS -X POST "${CDF_BASE}/transformations/externaldata/rotatekeys" \
  -H "Authorization: Bearer ${CDF_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "items": [{ "externalId": "snowflake-sales-prod", "expiryTime": 1823536000000 }] }'
```

## Delete the connection

On the integration, select Delete integration.

With the API:

```bash theme={"languages":{"custom":["/_languages/kuiper.json"]}}
curl -sS -X POST "${CDF_BASE}/transformations/externaldata/delete" \
  -H "Authorization: Bearer ${CDF_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "items": [{ "externalId": "snowflake-sales-prod" }] }'
```

Transformations that reference the deleted external ID fail on the next run. Deleting the connection in CDF does not change Snowflake. Remove the key there as well:

```sql theme={"languages":{"custom":["/_languages/kuiper.json"]}}
ALTER USER COGNITE_TRANSFORMATIONS_SVC UNSET RSA_PUBLIC_KEY;
```

## Manage sources

| Operation | Method and path | Capability |
| - | - | - |
| Register | `POST /transformations/externaldata` | `WRITE` |
| List | `GET /transformations/externaldata?format=snowflake` | `READ` |
| Retrieve by external ID | `POST /transformations/externaldata/byids` | `READ` |
| Rotate keys | `POST /transformations/externaldata/rotatekeys` | `WRITE` |
| Delete | `POST /transformations/externaldata/delete` | `WRITE` |

Full schemas: [Transformation external data sources](https://docs.cognite.com/api-reference/concepts/20230101-beta/transformation-external-data.md) and the [beta OpenAPI tag](https://api-docs.cognite.com/20230101-beta/tag/Transformation-External-Data-Sources).

## Next steps

* [Read Snowflake data in transformations](https://docs.cognite.com/cdf/integration/guides/transformation/read_snowflake.md)
* [Troubleshoot Snowflake in Transformations](https://docs.cognite.com/cdf/integration/guides/transformation/troubleshoot_snowflake.md)
