Python ↔ Rust Integration¶
This guide explains how FraiseQL's Python code integrates with the Rust pipeline.
Overview¶
FraiseQL's architecture separates responsibilities: Python handles GraphQL schema, resolvers, and PostgreSQL queries, while an exclusive Rust pipeline handles all JSON transformation, field projection, and HTTP response generation. Every query flows through the Rust pipeline—there is no fallback or mode detection.
Competitive Advantage: Exclusive Architecture¶
Other frameworks can't do this—they're locked into ORM serialization. Traditional GraphQL frameworks serialize ORM objects to JSON in Python, creating unavoidable performance bottlenecks. FraiseQL's exclusive Rust pipeline bypasses Python entirely for JSON processing, delivering 7-10x faster response times.
This architecture is unique to FraiseQL. No other GraphQL framework combines:
- PostgreSQL-native JSONB views
- Zero Python serialization overhead
- Rust-powered JSON transformation
- Direct UTF-8 byte output to HTTP
graph TB
Client[GraphQL Client]
Python[Python Layer<br/>GraphQL Schema, Resolvers, Business Logic]
Postgres[(PostgreSQL<br/>JSONB Views)]
Rust[Rust Pipeline fraiseql-rs<br/>JSON Transform, camelCase, __typename]
HTTP[FastAPI HTTP Response]
Client -->|GraphQL Query| Python
Python -->|SQL Query| Postgres
Postgres -->|JSONB Strings| Python
Python -->|Vec<String>| Rust
Rust -->|UTF-8 Bytes| HTTP
HTTP -->|JSON Response| Client
style Rust fill:#f96,stroke:#333,stroke-width:4px
style Python fill:#69f,stroke:#333,stroke-width:2px
style Postgres fill:#336791,stroke:#333,stroke-width:2px,color:#fff
Request Flow Diagram¶
sequenceDiagram
participant Client
participant FastAPI
participant Python as Python Resolver
participant PostgreSQL
participant Rust as fraiseql_rs
Client->>FastAPI: POST /graphql<br/>{query: "{ users { id firstName } }"}
FastAPI->>Python: Execute GraphQL query
Python->>PostgreSQL: SELECT data FROM v_user
PostgreSQL->>Python: [<br/> '{"id": "...", "first_name": "Alice"}',<br/> '{"id": "...", "first_name": "Bob"}'<br/>]
Python->>Rust: build_graphql_response(<br/> json_strings=Vec<String>,<br/> field_name="users",<br/> type_name="User"<br/>)
Rust->>Rust: Concatenate JSON array
Rust->>Rust: Transform snake_case → camelCase
Rust->>Rust: Inject __typename="User"
Rust->>Python: Vec<u8> (UTF-8 bytes)
Python->>FastAPI: RustResponseBytes
FastAPI->>Client: HTTP 200 OK<br/>{"data": {"users": [...]}}
The Boundary¶
What Python Does¶
- Define GraphQL types and queries
- Execute PostgreSQL queries
- Collect JSONB strings from database
- Call Rust pipeline with JSON strings
What Rust Does¶
- Concatenate JSON array
- Transform JSONB to GraphQL JSON
- Keep the selected fields only, each under its response key (alias)
- Write
__typenamewhere the query selects it - Return UTF-8 bytes directly for HTTP
__typename is included where the query selects it¶
A response built by the Rust pipeline holds exactly the selected fields, as the
GraphQL spec requires: __typename too is written only where the query selects
it, under its alias if it has one. A mutation selecting post { id title }
returns {"id": ..., "title": ...}; post { __typename id } returns
{"__typename": "Post", "id": ...}. This applies to query results (db.find,
db.find_one, several root fields) and to mutation results, including nested
entities. Clients that normalize by type (Apollo Client, urql's Graphcache,
Relay) add __typename to the queries they send, so they get it.
Where graphql-core completes the result instead (a find below the root, or a
mutation outside HTTP mode), the data Rust hands it keeps __typename on every
object of a known type: graphql-core reads it to resolve unions and interfaces,
and leaves it out of the response where it isn't selected. Cascade entities
(cascade.updated, cascade.deleted) keep the __typename their data has, the
entity's type, as the GraphQL Cascade format defines it.
A mutation entity's __typename comes from the SQL function's entity_type, a
__typename key in the entity's data, or the schema type of the success type's
entity field when that type is concrete (location: Location). When none of these
applies, __typename is left out, and a warning names the SQL function once.
For a field whose type is an interface or a union, the object behind it can be
one of several types. FraiseQL never guesses the type from the schema there:
__typename is included only when the data provides it (a __typename key in
the JSONB).
In a mutation entity, fragments under an interface or union field
(owner { ... on Person { name } ... on Org { title } }) select the union of
their fields for every object: a Person owner keeps title too if its data has
one. Per-type filtering, which would keep only name for a Person, isn't done
yet.
Code Example¶
Python Side¶
import fraiseql
from fraiseql.types import ID
# 1. Define GraphQL type
@fraiseql.type(sql_source="v_user")
class User:
id: ID
first_name: str # Python uses snake_case
created_at: datetime
# 2. Define query resolver
@fraiseql.query
async def users(info) -> list[User]:
db = info.context["db"]
# 3. Execute PostgreSQL query (returns JSONB)
# Rust pipeline handles transformation automatically
return await repo.find("v_user")
Under the Hood¶
FraiseQLRepository.find() reads the view's data column as JSON text, one string per
row, and hands the strings to the Rust extension (shipped inside the fraiseql package)
with the selection of the query; it returns the bytes as a RustResponseBytes, which
the /graphql route sends as the HTTP response. The call, on its own (applications
don't make it; find does):
from fraiseql import fraiseql_rs
# What the view's data column holds, one JSON string per row
json_strings = ['{"id": 1, "first_name": "Ada"}']
response_bytes = fraiseql_rs.build_graphql_response(
json_strings=json_strings,
field_name="users",
type_name="User",
field_paths=None,
)
print(response_bytes)
# b'{"data":{"users":[{"__typename":"User","id":1,"firstName":"Ada"}]}}'
Without a selection, as here, every key is kept and the row gets its __typename.
find passes the query's field_selections, and inject_typename=False when the
response goes to the client as is (HTTP mode), so it holds exactly the selected fields,
__typename included only where selected.
Rust Side (fraiseql_rs crate)¶
#[pyfunction]
pub fn build_graphql_response(
json_strings: Vec<String>,
field_name: String,
type_name: Option<String>,
field_paths: Option<Vec<Vec<String>>>,
) -> PyResult<Vec<u8>> {
// 1. Concatenate JSON strings
let array = format!("[{}]", json_strings.join(","));
// 2. Wrap in GraphQL response
let response = format!(
r#"{{"data":{{"{}":{}}}}}"#,
field_name, array
);
// 3. Transform to camelCase + inject __typename
let transformed = transform_json(&response, type_name);
// 4. Return UTF-8 bytes
Ok(transformed.into_bytes())
}
Performance Benefits¶
By delegating to Rust:
- 7-10x faster JSON transformation
- Zero Python overhead for string operations
- Direct UTF-8 bytes to HTTP (no Python serialization)
Type Safety¶
The Python/Rust boundary is type-safe via PyO3:
- Python
list[str]→ RustVec<String> - Python
str | None→ RustOption<String> - Rust
Vec<u8>→ Pythonbytes
Debugging¶
Enable Rust Logs¶
RUST_LOG=fraiseql_rs=debug python app.py
Inspect Rust Output¶
from fraiseql.core.rust_pipeline import RustResponseBytes
import json
result = await repo.find("v_user")
if isinstance(result, RustResponseBytes):
# Convert bytes to string for inspection
json_str = result.bytes.decode('utf-8')
print(json_str) # See what Rust produced
# Parse to verify structure
data = json.loads(json_str)
print(json.dumps(data, indent=2))
Contributing to Rust Code¶
The Rust code lives in fraiseql_rs/ directory:
fraiseql_rs/
├── Cargo.toml # Rust dependencies
├── src/
│ ├── lib.rs # Main entry point
│ ├── transform.rs # CamelCase transformation
│ ├── typename.rs # __typename injection
│ └── response.rs # GraphQL response building
└── tests/ # Rust tests
See Contributing Guide for Rust development setup.