snowflake.snowpark.Session.sql¶

Session.sql(query: str, params: Optional[Sequence[Any]] = None) → DataFrame[source]¶

Returns a new DataFrame representing the results of a SQL query.

Note

You can use this method to execute a SQL query lazily, which means the SQL is not executed until methods like DataFrame.collect() or DataFrame.to_pandas() evaluate the DataFrame. For immediate execution, chain the call with the collect method: session.sql(query).collect().

SQL compilation and execution errors usually surface when an action executes the query, not when this method creates the DataFrame. Operations that request schema metadata can also contact Snowflake before collection. Catch SnowparkSQLException around the operation that triggers evaluation; inspect its message and query ID to diagnose the server error. This is not an exhaustive list of possible client, connection, or argument errors.

Raises:

NotImplementedError – SQL execution is not supported in local testing mode. See mocking SQL operations.

Parameters:

query – The SQL statement to execute.
params – binding parameters. We only support qmark bind variables. For more information, check https://docs.snowflake.com/en/developer-guide/python-connector/python-connector-example#qmark-or-numeric-binding
_ast_stmt – when invoked internally, supplies the AST to use for the resulting dataframe.

Example:

>>> # create a dataframe from a SQL query
>>> df = session.sql("select 1/2")
>>> # execute the query
>>> df.collect()
[Row(1/2=Decimal('0.500000'))]

>>> # Use params to bind variables
>>> session.sql("select * from values (?, ?), (?, ?)", params=[1, "a", 2, "b"]).sort("column1").collect()
[Row(COLUMN1=1, COLUMN2='a'), Row(COLUMN1=2, COLUMN2='b')]