Built-in Functions

The following global functions and namespaces are directly injected into the Python script scope — no import is required.

query

query(sql: str, *args) -> DataFrame

Executes a SQL query against bound/mounted data sources and returns the result rows as a DataFrame. Uses the same query engine pathway as regular SQL queries, supporting multiple data sources and cross-source queries.

def main():
    df = query("SELECT id, name, amount FROM orders WHERE amount > ?", 100)
    return df

• Positional *args replace ? placeholders in the SQL, enabling parameterized queries.

• Timestamp / date columns: SQL returns timestamp/date columns as strings. Convert them with .str.to_datetime() or .str.to_date() before performing date operations:

  df = df.with_columns(pl.col("created_at").str.to_datetime())

fetch

fetch(url: str, method="GET", body=None, headers=None, timeout=30) -> Response

Performs an HTTP request, returning a Response object. JS fetch-style wrapper.

def main():
    res = fetch(
        "https://api.example.com/items",
        method="POST",
        body={"page": 1},
        headers={"Authorization": "Bearer ..."},
    )
    if not res.ok:
        return [{"error": res.status}]
    return res.json()

Parameters

Parameter	Description
url	Request URL
method	HTTP method, default "GET"
body	Request body; dict / list are auto-serialized to JSON with default content-type: application/json
headers	Request headers dict
timeout	Timeout in seconds, default 30

Error Handling

• Transport-level errors (DNS / connection failures, etc.) raise catchable exceptions.
• HTTP 4xx / 5xx status codes do NOT raise exceptions — check res.ok / res.status instead.

Response Object

Member	Description
res.ok	Boolean, whether status code is 2xx
res.status	HTTP status code (int)
res.status_text	Status description text
res.headers.get(name, default=None)	Read a response header by name (case-insensitive)
res.text()	Raw response body as string
res.json()	Parse response body as JSON

note

fetch() is only for accessing external HTTP services.

args

args: dict

Script parameters passed in by the caller — always a dict.

def main():
    threshold = args["threshold"]
    return query("SELECT * FROM sales").filter(pl.col("revenue") > threshold)

print

print(*values)

The built-in print() is redirected to the script log — its output does not enter the result set, making it useful for debugging.

def main():
    df = query("SELECT * FROM orders")
    print("Row count:", df.height)
    return df

pl Namespace

pl provides expression constructors, dtype constants, and the DataFrame / Series types.

Member	Description
pl.col(name)	Reference a column by name, returns Expr
pl.lit(value)	Build a literal expression from a scalar, returns Expr
pl.when(*predicates)	Start a conditional expression, chain .then().when().otherwise()
pl.cov(a, b, ddof=1)	Sample covariance between two Series (eager)
pl.corr(a, b, method="pearson", ...)	Correlation coefficient between two Series; method supports "pearson" / "spearman"
pl.DataFrame	DataFrame type
pl.Series	Series type
pl.Int / pl.Float / pl.Boolean / pl.String / pl.Datetime / pl.Date …	Data type constants (see Overview)

def main():
    df = query("SELECT category, amount FROM sales")
    return df.with_columns((pl.col("amount") * pl.lit(1.1)).alias("amount_with_tax"))

Conditional Expressions

pl.when() supports chained conditional branches, similar to SQL's CASE WHEN:

df.with_columns(
    pl.when(pl.col("amount") > 100)
      .then(pl.lit("high"))
      .when(pl.col("amount") > 50)
      .then(pl.lit("mid"))
      .otherwise(pl.lit("low"))
      .alias("level")
)

If .otherwise() is omitted, unmatched rows become null.

Covariance and Correlation

s1 = df.get_column("a")
s2 = df.get_column("b")
cov_ab = pl.cov(s1, s2)          # sample covariance
r = pl.corr(s1, s2)              # Pearson correlation (default)
r_spearman = pl.corr(s1, s2, method="spearman")

note

DataFrame and Series can be used directly as global names or accessed via pl.DataFrame / pl.Series — both are equivalent.