Skip to content
Marmot Development Kit

Async Queries

Handle long-running queries with execute_query_async, which submits a query, polls until Snowflake finishes, and returns the same cursor with results ready to fetch.

When to use async

Section titled “When to use async”

Use execute_query_async when:

  • Queries take seconds or minutes.
  • You want an async/await flow (for example alongside other asyncio code).

For fast queries, ordinary synchronous cursor.execute() is simpler.

Basic example

Section titled “Basic example”

execute_query_async returns the cursor after the query completes (it does not return a query-id string). Call fetchall(), fetch_pandas_all(), etc. on that cursor.

import asyncio
from komodo import get_snowflake_connection, execute_query_async




async def run_async_query():
    conn = get_snowflake_connection()
    cursor = conn.cursor()
    cursor.execute("USE DATABASE DATA")


    query = "SELECT column_name, table_name FROM INFORMATION_SCHEMA.COLUMNS LIMIT 20"
    cursor = await execute_query_async(cursor=cursor, query=query)


    rows = cursor.fetchall()
    print(f"Query returned {len(rows)} rows")


    cursor.close()
    conn.close()




asyncio.run(run_async_query())

Blocking I/O

Section titled “Blocking I/O”

The underlying connector still performs blocking I/O while polling query status. The library docstring notes that in FastAPI, similar work is often run in a thread pool. In a plain asyncio app, using await execute_query_async(...) is still appropriate; if you mix in synchronous cursor.execute calls inside async handlers, consider asyncio.to_thread for those sync calls so the event loop stays responsive.

Concurrent queries

Section titled “Concurrent queries”

You can run multiple async query helpers concurrently — each needs its own connection and cursor (do not share a single cursor across concurrent tasks).

import asyncio
from komodo import get_snowflake_connection, execute_query_async




async def one_query(sql: str):
    conn = get_snowflake_connection()
    try:
        cur = conn.cursor()
        try:
            cur.execute("USE DATABASE DATA")
            cur = await execute_query_async(cursor=cur, query=sql)
            return cur.fetchall()
        finally:
            cur.close()
    finally:
        conn.close()




async def main():
    results = await asyncio.gather(
        one_query("SELECT CURRENT_TIMESTAMP()"),
        one_query("SELECT CURRENT_USER()"),
    )
    print(results)




asyncio.run(main())

Inspecting failures

Section titled “Inspecting failures”

If an async query fails, the raised error includes the full Snowflake detail (message, error code, SQL state, and query ID). You can also pass the query ID to get_query_diagnostics(conn, query_id) to retrieve the recorded error code/message, execution status, warehouse, and timing. See Inspecting failures in the Executing Queries guide.

Section titled “Related”