Skip to main content

FraiseQL v2 - Python Schema Authoring

Python decorators for authoring FraiseQL schemas

This package provides Python decorators to define GraphQL schemas that are compiled by the FraiseQL Rust engine.

Architecture

Python Decorators → schema.json → fraiseql-cli compile → schema.compiled.json → Rust Runtime

Important: This package is for schema authoring only. It does NOT provide runtime execution. The compiled schema is executed by the standalone Rust server.

Installation

pip install fraiseql

Quick Start

import fraiseql

# Define a GraphQL type
@fraiseql.type
class User:
    id: int
    name: str
    email: str
    created_at: str

# Define a query
@fraiseql.query(sql_source="v_user")
def users(limit: int = 10) -> list[User]:
    """Get all users with pagination."""
    pass

# Define a mutation
@fraiseql.mutation(sql_source="fn_create_user", operation="CREATE")
def create_user(name: str, email: str) -> User:
    """Create a new user."""
    pass

# Export schema to JSON
if __name__ == "__main__":
    fraiseql.export_schema("schema.json")

Compile Schema

# Compile schema.json to optimized schema.compiled.json
fraiseql-cli compile schema.json -o schema.compiled.json

# Start server with compiled schema
fraiseql-server --schema schema.compiled.json

Features

  • Type-safe: Python type hints map to GraphQL types
  • Database-backed: Queries map to SQL views, mutations to functions
  • Compile-time: All validation happens at compile time, zero runtime overhead
  • No FFI: Pure JSON output, no Python-Rust bindings needed
  • Analytics: Fact tables and aggregate queries for OLAP workloads

Analytics / Fact Tables

FraiseQL supports high-performance analytics via fact tables:

import fraiseql

# Declare a fact table: a plain function call, not a decorator
fraiseql.fact_table(
    "tf_sales",
    measures=[
        {"name": "revenue", "sql_type": "numeric", "nullable": False},
        {"name": "quantity", "sql_type": "int", "nullable": False},
        {"name": "cost", "sql_type": "numeric", "nullable": False},
    ],
    dimensions={
        "name": "data",
        "paths": [
            {"name": "category", "json_path": "data->>'category'", "data_type": "text"},
            {"name": "region", "json_path": "data->>'region'", "data_type": "text"},
        ],
    },
    denormalized_filters=[
        {"name": "customer_id", "sql_type": "uuid", "indexed": True},
        {"name": "occurred_at", "sql_type": "timestamptz", "indexed": True},
    ],
)

There is no aggregate query to declare: tf_sales gets the GraphQL roots sales_aggregate and sales_window when the schema compiles.

{
  sales_aggregate(
    groupBy: { category: true, occurred_at_month: true }
    aggregates: [{ revenue_sum: true }, { count: true }]
  ) { category occurred_at_month revenue_sum count }
}

The sales_aggregate root supports:

  • GROUP BY: Dimensions (category, region) and temporal buckets (occurred_at_day, occurred_at_month)
  • Aggregates: count, revenue_sum, revenue_avg, quantity_sum, etc.
  • WHERE: Pre-aggregation filters (customer_id, occurred_at range)
  • HAVING: Post-aggregation filters (revenue_sum_gt: 1000)
  • ORDER BY: Any aggregate or dimension
  • LIMIT/OFFSET: Pagination

Fact Table Pattern

-- Table name starts with tf_ (table fact)
CREATE TABLE tf_sales (
    id BIGSERIAL PRIMARY KEY,
    -- Measures: Numeric columns for fast aggregation
    revenue DECIMAL(10,2) NOT NULL,
    quantity INT NOT NULL,
    cost DECIMAL(10,2) NOT NULL,
    -- Dimensions: JSONB column for flexible GROUP BY
    data JSONB NOT NULL,
    -- Denormalized filters: Indexed columns for fast WHERE
    customer_id UUID NOT NULL,
    occurred_at TIMESTAMPTZ NOT NULL
);
CREATE INDEX ON tf_sales(customer_id);
CREATE INDEX ON tf_sales(occurred_at);

Key Principles:

  • Measures: SQL columns (numeric types) for fast aggregation
  • Dimensions: JSONB data column for flexible grouping
  • Denormalized Filters: Indexed SQL columns for fast WHERE clauses
  • No Joins: All dimensional data denormalized at ETL time

Localized Fields

A field whose label exists in several languages is stored as a map of locale to label and returned to each client as the label of its request locale:

@fraiseql.type(sql_source="tv_product")
class Product:
    id: ID
    name: fraiseql.Localized[str]                # data->'name' = {"fr-FR": "Pomme", "en-US": "Apple"}
    description: fraiseql.Localized[str] | None

@fraiseql.mutation(sql_source="fn_rename_product", operation="update")
def rename_product(id: ID, name: fraiseql.Localized[str]) -> Product: ...

The project's fraiseql.toml declares the locales ([locale] with default and allowed). A mutation argument or input field marked Localized accepts a label for the request locale, {translations: [...]}, or the map, and the SQL function receives the map. Only str can be localized; Localized[int] raises when the class is decorated.

Type Mapping

Python Type GraphQL Type
int Int
float Float
str String
bool Boolean
list[T] [T]
T | None T (nullable)
Custom class Object type

Documentation

Full documentation: https://fraiseql.readthedocs.io

License

MIT

Metadata

Release files for fraiseql 2.19.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for fraiseql 2.19.1
File Size Uploaded Provenance Actions
fraiseql-2.19.1.tar.gz 385.3 kB Without provenance Details for fraiseql-2.19.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for fraiseql 2.19.1
File Interpreter ABI Platform Actions
fraiseql-2.19.1-py3-none-any.whl Python 3 none any Details for fraiseql-2.19.1-py3-none-any.whl

Total release size: 475.7 kB

Release files / fraiseql-2.19.1.tar.gz

Download URL fraiseql-2.19.1.tar.gz
Size 385.3 kB
Tags Source
SHA-256 checksum
How to use checksums
4766e0ffd226e52e71461b92cb6a2c99ee63cb32418e915d18a0a050c07098a0
BLAKE2b-256 checksum
How to use checksums
8c6469b70fbbb5a4ed07f7e8eedd462c50bcf606af458e97dfded9e2eeb3c630
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.16

Release files / fraiseql-2.19.1-py3-none-any.whl

Download URL fraiseql-2.19.1-py3-none-any.whl
Size 90.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ac8422451454e0d25a5707e1d0caed8eb01f89190ed814aa8cafa480f819478d
BLAKE2b-256 checksum
How to use checksums
e229e748597b47bb39dff67fa0702dfdea2c606bb5e204dfab1cd60a6102ea3a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.16

Security for fraiseql 2.19.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

2.19.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page