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

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. The integration requires snowflake-connector-python (≥ 4.6.0) and cryptography (≥ 49.0.0), which handle the connection and PEM deserialization respectively.

pip install semantica[db-snowflake]

The db-snowflake extra is defined in 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, 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 (lines 26‑36).

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.

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.

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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}