SDK Reference

get_snowflake_connection

Creates and returns a Snowflake database connection using Komodo authentication.

Import

from komodo import get_snowflake_connection

Function Signature

def get_snowflake_connection(
    account_id: str | None = None,
    jwt: str | None = None,
    client_id: str | None = None,
    client_secret: str | None = None,
    service_principal_id: str | None = None,
    profile: str | None = None
) -> Connection

Parameters

Name	Type	Description
account_id	str | None	The Komodo account ID to use for the connection. If not provided, the SDK will attempt to read it from the client session or credentials file. Cannot be used with profile.
jwt	str | None	The JSON Web Token (JWT) for authentication. If not provided, the SDK will use the default authentication session.
client_id	str | None	The client ID for machine-to-machine (M2M) authentication. Used in conjunction with client_secret and service_principal_id.
client_secret	str | None	The client secret for machine-to-machine (M2M) authentication. Used in conjunction with client_id and service_principal_id.
service_principal_id	str | None	The service principal ID for machine-to-machine (M2M) authentication. Used in conjunction with client_id and client_secret.
profile	str | None	The name of a profile from ~/.komodo/credentials to use for authentication. Profiles contain M2M credentials (client_id, client_secret, account_id). Cannot be combined with other authentication parameters.

Returns

Type	Description
KomodoSnowflakeCursor	A Snowflake database connection object that can be used to execute queries and interact with the Komodo data warehouse. A DB-API 2.0 compliant connection object.

Raises

Exception	Description
UnsetAccountError	Raised when an account_id is not provided and cannot be read from the SDK client session.

Example

from komodo.extensions import get_snowflake_connection

# Create a connection using default credentials
connection = get_snowflake_connection()

# Create a connection with a specific account ID
connection = get_snowflake_connection(account_id="your-account-id")

# Create a connection with a specific account ID and JWT
connection = get_snowflake_connection(
    account_id="your-account-id",
    jwt="your-jwt-token"
)

# Create a connection using a named profile
connection = get_snowflake_connection(profile="production")

# Use the connection to execute queries
cursor = connection.cursor()
cursor.execute("SELECT * FROM your_table LIMIT 10")
results = cursor.fetchall()
cursor.close()

Notes

• Default authentication: If no parameters are provided, the function uses the default Client() configuration with credentials from the session or credentials file.
• JWT authentication: If only jwt is provided, it creates a client with that JWT but uses the default account.
• M2M authentication: For machine-to-machine authentication, provide all three parameters: client_id, client_secret, and service_principal_id. These must be used together.
• Profile authentication: Use profile to reference named profiles from ~/.komodo/credentials. Profiles contain M2M credentials and cannot be combined with other authentication parameters.
• Authentication rules: You can only use one authentication method at a time. Profiles cannot be combined with account_id as the profile contains the account ID.
• The function automatically sets up query tagging for tracking purposes.
• The connection uses the Komodo connector which provides enhanced Snowflake functionality.
• Returns a DB-API 2.0 compliant connection object compatible with standard Python database libraries.

---

execute_query_async

Executes a Snowflake query asynchronously and returns the query ID for later retrieval of results.

Import

from komodo import execute_query_async

Function Signature

async def execute_query_async(
    cursor: KomodoSnowflakeCursor,
    query: str,
    query_params: list[str] | dict[str, str] | None = None,
) -> str

Parameters

Name	Type	Description
cursor	KomodoSnowflakeCursor	A Snowflake cursor object from a Komodo connection.
query	str	The SQL query to execute. Supports parameterized queries using ? for list params or :name for dict params.
query_params	list[str] | dict[str, str] | None	Optional parameters to bind to the query. Can be a list for positional parameters or a dict for named parameters.

Returns

Type	Description
str	The query ID that can be used to retrieve results later.

Example

import asyncio
from komodo import get_snowflake_connection
from komodo import execute_query_async

async def run_async_query():
    # Create connection and cursor
    conn = get_snowflake_connection()
    cursor = conn.cursor()

    # Execute query asynchronously
    query_id = await execute_query_async(
        cursor,
        "SELECT * FROM large_table WHERE region = ?",
        ["US"]
    )

    print(f"Query submitted with ID: {query_id}")

    cursor.close()
    conn.close()

    return query_id

# Run the async function
query_id = asyncio.run(run_async_query())

Notes

• This function submits a query for asynchronous execution and immediately returns a query ID.
• The query runs in the background on Snowflake’s servers.
• Ideal for long-running queries that don’t need immediate results.
• The cursor must be from a connection created with get_snowflake_connection().