Skip to main content

​
Overview

A Session is the entry point for all Fenic operations. Similar to PySpark’s SparkSession, it manages configuration, execution context, and resource lifecycle. All DataFrame operations flow through a session.

​
Creating a Session

Use Session.get_or_create() to initialize a session with your configuration: 
from fenic.api import Session, SessionConfig

session = Session.get_or_create(
    SessionConfig(app_name="my_app")
)
Sessions cannot be created directly using Session(). Always use Session.get_or_create().

​
Session Configuration

The SessionConfig class controls all session behavior, from execution backend to LLM providers.

​
Basic Configuration

from fenic.api import SessionConfig

config = SessionConfig(
    app_name="data_pipeline",
    cloud=False  # Use local execution (default)
)

​
Semantic Configuration

Configure language and embedding models for semantic operations: 
from fenic.api import (
    SessionConfig,
    SemanticConfig,
    OpenAILanguageModel
)

config = SessionConfig(
    app_name="my_app",
    semantic=SemanticConfig(
        language_models={
            "gpt4": OpenAILanguageModel(
                model_name="gpt-4.1-nano",
                rpm=100,
                tpm=100_000
            )
        }
    )
)

​
Supported Model Providers

Fenic supports multiple LLM providers:

OpenAI

OpenAILanguageModel and OpenAIEmbeddingModelSupports GPT-4, GPT-4o, o-series reasoning models

Anthropic

AnthropicLanguageModelSupports Claude 3.5 and Claude Opus 4 models with extended thinking

Google

GoogleDeveloperLanguageModel, GoogleVertexLanguageModelSupports Gemini 2.0, 2.5, and 3.0 models with thinking budgets

OpenRouter

OpenRouterLanguageModelAccess 100+ models with provider routing and fallbacks

​
Session Lifecycle

​
Reading Data

Use the session.read interface to load data: 
# Read CSV
df = session.read.csv("data.csv")

# Read Parquet
df = session.read.parquet("data.parquet")

# Read JSON
df = session.read.json("data.json")

# Create from in-memory data
df = session.create_dataframe({
    "id": [1, 2, 3],
    "name": ["Alice", "Bob", "Charlie"]
})

​
Accessing Tables and Views

# Load a registered table
df = session.table("my_table")

# Load a view
df = session.view("my_view")

​
Running SQL Queries

df1 = session.create_dataframe({"id": [1, 2]})
df2 = session.create_dataframe({"id": [2, 3]})

result = session.sql(
    "SELECT * FROM {df1} JOIN {df2} USING (id)",
    df1=df1,
    df2=df2
)

​
Catalog Operations

Access the session catalog to manage tables and views: 
# List all tables
session.catalog.list_tables()

# Check if table exists
if session.catalog.table_exists("my_table"):
    df = session.table("my_table")

# Drop a table
session.catalog.drop_table("my_table")

​
Stopping the Session

Always stop your session when done to release resources: 
# Stop and show usage summary
session.stop()

# Stop without showing summary
session.stop(skip_usage_summary=True)

​
Execution Backends

Fenic supports two execution backends:

​
Local Backend (Default)

Uses Polars for in-process execution. Ideal for development and datasets that fit in memory. 
config = SessionConfig(app_name="my_app", cloud=False)
session = Session.get_or_create(config)

​
Cloud Backend

Executes on Fenic’s managed infrastructure. Ideal for production workloads and large-scale data processing. 
config = SessionConfig(
    app_name="my_app",
    cloud=True,
    api_key="your_api_key"
)
session = Session.get_or_create(config)

​
Best Practices

Consider wrapping session lifecycle in a context manager pattern:
session = Session.get_or_create(config)
try:
    # Do work
    df = session.read.csv("data.csv")
    result = df.select("column").collect()
finally:
    session.stop()
Configure rpm (requests per minute) and tpm (tokens per minute) based on your provider’s actual limits to avoid throttling:
OpenAILanguageModel(
    model_name="gpt-4.1-nano",
    rpm=500,  # Match your tier
    tpm=200_000  # Match your tier
)
Create one session per application and reuse it across operations rather than creating multiple sessions.
When using reasoning models (o-series, Claude Opus 4, Gemini 2.5+), configure profiles with different reasoning efforts:
profiles={
    "fast": Profile(reasoning_effort="low"),
    "thorough": Profile(reasoning_effort="high")
}

​
Common Patterns

​
Multi-Provider Configuration

from fenic.api import *

config = SessionConfig(
    app_name="production_pipeline",
    semantic=SemanticConfig(
        language_models={
            "fast": OpenAILanguageModel(
                model_name="gpt-4.1-nano",
                rpm=500,
                tpm=200_000
            ),
            "powerful": AnthropicLanguageModel(
                model_name="claude-opus-4-0",
                rpm=100,
                input_tpm=100_000,
                output_tpm=100_000
            ),
            "reasoning": GoogleDeveloperLanguageModel(
                model_name="gemini-2.5-flash",
                rpm=100,
                tpm=100_000,
                profiles={
                    "fast": GoogleDeveloperLanguageModel.Profile(
                        thinking_token_budget=1024
                    ),
                    "thorough": GoogleDeveloperLanguageModel.Profile(
                        thinking_token_budget=8192
                    )
                },
                default_profile="fast"
            )
        },
        default_language_model="fast"
    )
)

session = Session.get_or_create(config)

​
Cost-Optimized Configuration

config = SessionConfig(
    app_name="cost_optimized",
    semantic=SemanticConfig(
        language_models={
            "budget": OpenRouterLanguageModel(
                model_name="openai/gpt-oss-20b",
                profiles={
                    "default": OpenRouterLanguageModel.Profile(
                        provider=OpenRouterLanguageModel.Provider(
                            sort="price"  # Route to cheapest provider
                        )
                    )
                }
            )
        }
    )
)

​
Next Steps

DataFrames

Learn about DataFrame operations and transformations

Semantic Operators

Explore LLM-powered data transformations

Build docs developers (and LLMs) love

Get started for freeTalk to us