Metadata-Version: 2.5
Name: snowflake-spark-connect
Version: 0.1.0
Summary: Python client for Snowflake Runtime for Apache Spark
Project-URL: Homepage, https://github.com/snowflake-eng/sras-client
Project-URL: Repository, https://github.com/snowflake-eng/sras-client
Project-URL: Issues, https://github.com/snowflake-eng/sras-client/issues
Author-email: "Snowflake, Inc" <snowflake-python-libraries-dl@snowflake.com>
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Database
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: googleapis-common-protos>=1.56.4
Requires-Dist: grpcio-status>=1.56.0
Requires-Dist: grpcio>=1.56.0
Requires-Dist: numpy<2,>=1.15
Requires-Dist: pandas>=1.0.5
Requires-Dist: py4j==0.10.9.7
Requires-Dist: pyarrow>=4.0.0
Requires-Dist: pyjwt>=2.15.0
Requires-Dist: setuptools>=68; python_version >= '3.12'
Requires-Dist: snowflake-connector-python>=4.7.3
Requires-Dist: snowflake-snowpark-python
Requires-Dist: urllib3>=2.8.0
Description-Content-Type: text/markdown

# sras-client

> [!IMPORTANT]
> This client is in Private Preview. It is not yet in production and is available only to selected accounts.

Python client for Snowflake Runtime for Apache Spark.

```bash
pip install snowflake-spark-connect
```

## Usage

```python
from datetime import timedelta

from snowflake.sparkconnect import SparkSession

spark = (
    SparkSession.builder.idlettl(timedelta(minutes=30))
    .sessionttl(timedelta(hours=4))
    .getOrCreate()
)

spark.sql("SELECT 1").show()
spark.stop()
```

`getOrCreate()` reuses the process session when the builder has no credentials. A later call with **different** credentials, TTLs, or database/schema settings raises instead of sharing another identity, including TTL-only builders such as `.idlettl(...)`. `create()` starts a new Spark Connect server with a new session in the current process.

In a Snowflake Notebook, `get_active_session()` binds to the active Snowpark session. Pass optional named `database` and `schema` arguments to set that context before the Spark Connect server starts.

## Authentication options

Use one of the following authentication options when creating a session.
Pick **one**. `.connection("prod")` uses that toml profile as-is (not mixed with `SNOWFLAKE_*`).

| Method | What it does |
| --- | --- |
| *(nothing)* | `getOrCreate()` — env, default `connections.toml`, or the Notebook session |
| `.snowpark_session(session)` | Existing Snowpark session (Snowflake Notebook) |
| `.connection("prod")` | Named profile from `~/.snowflake/connections.toml` |
| `.remote(account=..., ...)` | Snowflake connection parameters (see below) |

Do not mix `.connection("prod")`, `.remote(...)`, and `.snowpark_session(...)`.

### Session lifetime

| Option | Meaning |
| --- | --- |
| `.idlettl(timedelta(...))` | Stop the Spark server after this much idle time |
| `.sessionttl(timedelta(...))` | Hard cap on total session lifetime |
| `.tokenttl(timedelta(...))` | Lifetime of each Spark Connect JWT |
| `spark_idlettl` / `spark_sessionttl` / `spark_tokenttl` inside `.remote(...)` | Same TTLs, passed as Snowflake kwargs |

These apply only when the builder STARTs a server. They cannot be combined with a `sc://` URL.

### Database and schema

| Option | Meaning |
| --- | --- |
| `.database(name)` | Use this Snowflake database on the control session before START |
| `.schema(name)` | Use this Snowflake schema on the control session before START |

Explicit `.database(...)` / `.schema(...)` values always override database/schema from a connection, configuration, or supplied/active Snowpark session. They apply only when the builder STARTs a server and cannot be combined with a `sc://` URL.

The `snowflake.sparkconnect.SparkSession` refreshes its token in the background to automatically stay authenticated.

### `.remote(**kwargs)` Snowflake parameters

These are the same parameters as [`snowpark-python`](https://github.com/snowflakedb/snowpark-python).

Spark-specific kwargs:

| Parameter | Notes |
| --- | --- |
| `spark_idlettl` / `spark_sessionttl` / `spark_tokenttl` | Same as `.idlettl()` / `.sessionttl()` / `.tokenttl()` |

### Environment variables

When the builder has no `.connection()` / `.remote()`, Snowflake `SNOWFLAKE_*` login vars are used (including `SNOWFLAKE_HOST`), then `SNOWFLAKE_CONNECTION_NAME`, then the default toml profile, then an active Notebook session. Blank env values are ignored.
