# How to Configure Snowflake Ingestion with Key-Pair Authentication in Semantica

> Learn how to configure Snowflake ingestion with key-pair authentication using Semantica's SnowflakeIngestor. Securely ingest data without passwords. Read our guide now.

- Repository: [Semantica /semantica](https://github.com/semantica-agi/semantica)
- Tags: how-to-guide
- Published: 2026-08-20

---

**Semantica's `SnowflakeIngestor` supports passwordless Snowflake ingestion with key-pair authentication by accepting a PEM-encoded private key file or raw key bytes, which the internal `SnowflakeConnector` loads and passes directly to the Snowflake Python connector.**

Semantica, an open-source data ingestion framework maintained in the `semantica-agi/semantica` repository, simplifies Snowflake connectivity through its `SnowflakeIngestor` class. When you configure Snowflake ingestion with key-pair authentication, you eliminate password dependencies by supplying an RSA or ECC private key that the library validates and forwards to Snowflake's connector. This guide walks through the dependency requirements, connection parameters, and exact code paths that enable secure, passwordless ingestion.

## Install the Snowflake Extra Dependencies

Before configuring key-pair authentication, install the Snowflake-specific extras declared in the project's [`pyproject.toml`](https://github.com/semantica-agi/semantica/blob/main/pyproject.toml). The integration requires **snowflake-connector-python** (≥ 4.6.0) and **cryptography** (≥ 49.0.0), which handle the connection and PEM deserialization respectively.

```bash
pip install semantica[db-snowflake]

```

The `db-snowflake` extra is defined in [`pyproject.toml`](https://github.com/semantica-agi/semantica/blob/main/pyproject.toml) under the optional dependency block.

## How Key-Pair Authentication Works

The authentication flow follows three clear steps inside the Semantica source code:

1. **`SnowflakeIngestor` initialization** — you pass the Snowflake account identifier, username, and private key material via the constructor.
2. **`SnowflakeConnector._load_private_key`** — if you provide `private_key_path`, this private method reads the PEM file and uses the `cryptography` library to return DER-encoded key bytes. Encrypted keys are decrypted automatically when `private_key_passphrase` is supplied.
3. **`SnowflakeConnector.connect`** — the connector assembles the argument dictionary for `snowflake.connector.connect`. When a private key is present, it injects the `private_key` parameter and intentionally omits `password`, forcing Snowflake to authenticate via key-pair.

This flow is implemented in [`semantica/ingest/snowflake_ingestor.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/ingest/snowflake_ingestor.py), specifically in the private-key loader at lines 184‑202 and the connection builder at lines 66‑71.

## Required and Optional Parameters

Configure your ingestor by providing at minimum an `account` and `user` value, plus one form of private key material. The following parameters control key-pair authentication:

- **`account`** — your Snowflake account identifier (for example, `myorg-account`).
- **`user`** — the Snowflake username for the session.
- **`private_key_path`** — filesystem path to a PEM-encoded private key file. The connector reads this file in `_load_private_key` and converts it to DER-encoded bytes.
- **`private_key`** — raw byte string of an already-loaded private key. Use this instead of `private_key_path` when you prefer to load the PEM file yourself.
- **`private_key_passphrase`** *(optional)* — passphrase for decrypting an encrypted PEM file.
- **`warehouse`**, **`database`**, **`schema`**, **`role`** *(optional)* — session defaults forwarded to the Snowflake connection.
- **`authenticator`** — not required for key-pair flows; leave this unset.

## Ingest Data Using a Private Key File

The most common pattern loads the key from a PEM file. The snippet below matches the official cookbook example in [`cookbook/advanced/snowflake_ingestion_examples.py`](https://github.com/semantica-agi/semantica/blob/main/cookbook/advanced/snowflake_ingestion_examples.py) (lines 26‑36).

```python
import os
from semantica.ingest import SnowflakeIngestor

ingestor = SnowflakeIngestor(
    account=os.getenv("SNOWFLAKE_ACCOUNT"),
    user=os.getenv("SNOWFLAKE_USER"),
    private_key_path=os.getenv("SNOWFLAKE_PRIVATE_KEY_PATH"),
    warehouse="COMPUTE_WH",
)

data = ingestor.ingest_table("CUSTOMERS", limit=5)
print(f"Retrieved {data.row_count} rows via key-pair authentication")
ingestor.close()

```

When `private_key_path` is supplied, `SnowflakeConnector` automatically invokes its internal loader, decrypts the file if necessary, and passes the DER bytes to the underlying Snowflake connector.

## Ingest Data Using Raw Private Key Bytes

If you already hold the private key in memory, bypass the file loader by passing `private_key` directly. This is useful when keys are fetched from a secrets manager rather than the local filesystem.

```python
from semantica.ingest import SnowflakeIngestor

# Load your PEM bytes from a secrets manager or environment variable

pem_bytes = b"-----BEGIN PRIVATE KEY-----\n..."

ingestor = SnowflakeIngestor(
    account="myorg-account",
    user="ingest_user",
    private_key=pem_bytes,
    warehouse="COMPUTE_WH",
)

data = ingestor.ingest_table("ORDERS", limit=10)
ingestor.close()

```

Because `private_key` is already in bytes form, the connector skips the `_load_private_key` file-reading step and sends the value straight to `snowflake.connector.connect`.

## Use SnowflakeConnector Directly (Advanced)

For scenarios that require manual connection handling, instantiate `SnowflakeConnector` directly from `semantica.ingest.snowflake_ingestor`. This exposes the same key-pair logic while giving you raw access to the Snowflake session.

```python
from semantica.ingest.snowflake_ingestor import SnowflakeConnector

connector = SnowflakeConnector(
    account="myaccount",
    user="myuser",
    private_key_path="/path/to/rsa_key.pem",
    private_key_passphrase="myPassphrase",  # omit if the key is unencrypted

    warehouse="COMPUTE_WH",
)

conn = connector.connect()

# Execute custom queries via conn.cursor() ...

connector.disconnect()

```

The `connect` method validates the key format and opens the session, while `disconnect` terminates it cleanly.

## Summary

- **Semantica's `SnowflakeIngestor`** delegates connection logic to **`SnowflakeConnector`**, which natively supports Snowflake key-pair authentication.
- Install the **`db-snowflake`** extra to pull in `snowflake-connector-python` and `cryptography`.
- Supply either **`private_key_path`** for automatic PEM loading or **`private_key`** when you manage the bytes yourself.
- The connector's **`_load_private_key`** method (lines 184‑202) decrypts and deserializes PEM files, while **`connect`** (lines 66‑71) forwards the DER bytes to Snowflake and omits the password field.
- After connection, use **`ingest_table`**, **`ingest_query`**, or direct cursor access exactly as you would with password authentication.

## Frequently Asked Questions

### What dependencies are required for Snowflake key-pair authentication in Semantica?

You must install the `db-snowflake` extra, which resolves `snowflake-connector-python` (≥ 4.6.0) and `cryptography` (≥ 49.0.0). The `cryptography` library is essential because `SnowflakeConnector._load_private_key` uses it to parse and convert PEM files into DER-encoded bytes.

### Can I use an encrypted private key with SnowflakeIngestor?

Yes. Provide the `private_key_passphrase` argument alongside `private_key_path`. The internal `_load_private_key` method detects the passphrase and decrypts the PEM file before returning the DER-encoded key material to the Snowflake connector.

### What happens if I provide both a password and a private key?

According to the source code in [`semantica/ingest/snowflake_ingestor.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/ingest/snowflake_ingestor.py), the `connect` method prioritizes key-pair authentication. When a private key is present, the connector adds the `private_key` entry to the connection dictionary and omits `password`, so Snowflake authenticates with the key regardless of any password value.

### Does key-pair authentication work with all Semantica Snowflake ingestion methods?

Yes. Once the connector establishes the session via `connect`, all ingestion operations—including `ingest_table`, `ingest_query`, and direct cursor usage—behave identically to password-based sessions. The authentication mechanism only affects connection creation, not the subsequent query interface.