FraiseQL Terminology Guide¶

Last Updated: 2025-12-30

This guide defines canonical terminology used throughout FraiseQL documentation to ensure consistency and clarity.

Quick Reference¶

Term	Use When	Example	Avoid
PostgreSQL function	Technical docs, API references	`fn_create_user()`	"database function", "DB function"
SQL function	Code comments, casual mentions	`-- SQL function for user creation`	In formal docs
JSONB view	FraiseQL-specific views	`v_user`, `v_post`	Generic "view"
PostgreSQL view	Generic database views	Any `CREATE VIEW`	When discussing JSONB pattern specifically
Projection table	Performance optimization tables	`tv_user_cached`	"table view", "materialized projection"
Rust pipeline	Architecture explanations	PostgreSQL → Rust → HTTP	"Rust extension" (in user docs)
fraiseql_rs	Code/technical references	Import from `fraiseql_rs`	In user-facing docs
Trinity pattern	Architectural pattern	Three-identifier design	"three-tier ID system"
Trinity identifiers	The three ID fields	pk_*, id, identifier	"Trinity IDs"
CQRS	After first definition	Read/write separation	Spell out repeatedly

Database Terminology¶

PostgreSQL Functions¶

Primary term: "PostgreSQL function"

When to use: - Formal documentation - API references - Technical explanations - Mutation descriptions

Acceptable alternatives: - "SQL function" (in code comments, casual use) - "Database function" (only when PostgreSQL is clear from context)

Avoid: - "DB function" (too informal) - "Function" alone (ambiguous - Python vs SQL)

Examples:

✅ CORRECT:

Mutations call PostgreSQL functions for business logic:

CREATE OR REPLACE FUNCTION fn_create_user(...) RETURNS JSONB AS $$

⚠️ ACCEPTABLE (casual context):

# Call SQL function to create user
result = await db.execute_function("fn_create_user", {...})

❌ AVOID:

Create a database function to handle the mutation.

Why: "PostgreSQL function" is precise and differentiates from Python functions, AWS Lambda functions, etc.

Views and Tables¶

JSONB View¶

Primary term: "JSONB view"

When to use: - Describing FraiseQL's view pattern - Views that return JSONB in data column - Most GraphQL type mappings

Pattern:

CREATE VIEW v_user AS
SELECT
    id,
    jsonb_build_object(
        'id', id,
        'name', name
    ) as data
FROM tb_user;

Why JSONB view: - Distinguishes FraiseQL's specific pattern - Differentiates from generic PostgreSQL views - Highlights that JSONB is pre-composed for GraphQL

PostgreSQL View¶

Primary term: "PostgreSQL view"

When to use: - Generic database view discussions - When not using JSONB pattern - Comparing with other databases

Example:

FraiseQL uses PostgreSQL views for read optimization, but specifically
uses the JSONB view pattern for GraphQL types.

Projection Table¶

Primary term: "Projection table" (with tv_* notation)

When to use: - Regular tables storing cached JSONB - Performance optimization discussions - Comparing with views

Avoid: - "Table view" (confusing - is it a table or view?) - "Materialized projection" (too verbose) - "Cached table" (doesn't convey JSONB nature)

Pattern:

CREATE TABLE tv_user (
    id UUID PRIMARY KEY,
    data JSONB NOT NULL,  -- Cached from v_user
    updated_at TIMESTAMPTZ DEFAULT NOW()
);

Key distinction:

Type	What It Is	Storage	Performance
*JSONB view (`v_`)**	Virtual view	None	5-10ms
*Projection table (`tv_`)**	Physical table with cached JSONB	1.5-2x data	0.05-0.5ms
Materialized view	PostgreSQL MATERIALIZED VIEW	1x data	0.1-1ms

Materialized View¶

Primary term: "Materialized view" (PostgreSQL's CREATE MATERIALIZED VIEW)

When to use: - Pre-computed aggregations - PostgreSQL-native materialized views - Rarely used in FraiseQL (projection tables preferred)

Why rare in FraiseQL: - Projection tables (tv_*) offer more control - Explicit sync functions vs REFRESH MATERIALIZED VIEW - Better integration with mutation pipeline

Architecture Terminology¶

Rust Pipeline¶

Primary term: "Rust pipeline"

When to use: - Architecture explanations - User-facing documentation - Performance discussions - "How FraiseQL works" sections

Example:

FraiseQL's Rust pipeline transforms PostgreSQL JSONB to HTTP responses
7-10x faster than Python serialization.

Avoid in user docs: - "Rust extension" (too technical) - "fraiseql_rs module" (implementation detail) - "Rust layer" (vague)

Use in technical docs: - "fraiseql_rs" (when discussing code/implementation)

fraiseql_rs¶

Primary term: "fraiseql_rs"

When to use: - Code examples with imports - Technical/developer documentation - Contributing guides - Source code references

Example:

from fraiseql_rs import transform_jsonb

Avoid in user docs: - Don't expose internal module structure - Use "Rust pipeline" instead

Trinity Pattern and Identifiers¶

Trinity Pattern¶

Primary term: "Trinity pattern"

When to use: - Describing the architectural pattern - High-level explanations - Design discussions

Definition: The architectural pattern of using three identifier types per entity: 1. pk_* (integer primary key - internal) 2. id (UUID - public API) 3. identifier (text slug - human-readable)

Example:

FraiseQL uses the Trinity pattern to optimize both performance
and security.

Trinity Identifiers¶

Primary term: "Trinity identifiers"

When to use: - Referring to the three specific ID fields - SQL schema examples - Field-level discussions

Example:

CREATE TABLE tb_user (
    pk_user INT PRIMARY KEY,      -- Trinity identifiers:
    id UUID UNIQUE NOT NULL,       -- 1. Internal (pk_*)
    identifier TEXT UNIQUE,        -- 2. Public (id)
                                   -- 3. Human-readable (identifier)
    name TEXT
);

Avoid: - "Trinity IDs" (too casual) - "Three-tier ID system" (confusing with application tiers) - "Triple identifier pattern" (not established term)

Summary table:

Identifier	Type	Purpose	Exposed in GraphQL?	Use Case
`pk_*`	Integer	PostgreSQL JOINs	❌ Never	Database performance
`id`	UUID	Public API identifier	✅ Always	GraphQL queries, external APIs
`identifier`	Text	Human-readable slug	✅ Optional	SEO-friendly URLs

CQRS¶

Primary term: "CQRS"

First mention: "CQRS (Command Query Responsibility Segregation)"

Subsequent mentions: "CQRS" (acronym only)

When to use: - Architecture discussions - After defining on first use in document - Well-established pattern (no need to spell out repeatedly)

Example:

✅ CORRECT:

FraiseQL follows CQRS (Command Query Responsibility Segregation)
principles, separating read paths (queries) from write paths (mutations).

The CQRS architecture allows independent optimization of reads and writes.

❌ AVOID (too verbose):

FraiseQL follows Command Query Responsibility Segregation (CQRS).
The Command Query Responsibility Segregation pattern allows...

Always link to definition:

FraiseQL follows [CQRS](../core/concepts-glossary.md#cqrs) principles...

GraphQL Terminology¶

Type¶

Primary term: "GraphQL type"

When to use: - Distinguishing from Python types, database types - GraphQL schema discussions

Avoid: - "Type" alone (ambiguous - Python, SQL, or GraphQL?)

Example:

The @fraiseql.type decorator maps a Python class to a GraphQL type.

Field¶

Primary term: "GraphQL field" (when context needs clarification)

Acceptable: "field" (when GraphQL context is clear)

Avoid confusing with: - "Column" (database term) - "Attribute" (Python term) - "Property" (Python term)

Resolver¶

Primary term: "resolver"

Use when: - Discussing GraphQL field resolution - Query/mutation execution - Custom field logic

Example:

The resolver fetches data from the database and returns it to GraphQL.

Mutation¶

Primary term: "mutation" or "GraphQL mutation"

Use "GraphQL mutation" when: - Distinguishing from database mutations (INSERT/UPDATE/DELETE) - Clarifying context

Example:

GraphQL mutations call PostgreSQL functions for business logic.

The mutation validates input and calls fn_create_user().

Feature-Specific Terminology¶

Auto-Inference¶

Primary term: "auto-inference"

What it means: Automatic detection/generation by FraiseQL: - Field names: created_at → createdAt - View names: User type → v_user view - Success fields: Automatic success, message, data, timestamp

Always link to:

FraiseQL's [auto-inference](../core/auto-inference.md) reduces boilerplate...

Cascade¶

Primary term: "Cascade" or "GraphQL Cascade"

What it means: FraiseQL's automatic cache invalidation based on data relationships.

Avoid: - "CASCADE" (all caps - confuses with SQL CASCADE DELETE) - "Cascade feature" (redundant)

Example:

Enable Cascade for automatic cache invalidation:

mutation {
  createPost(input: {...}) {
    success {
      post { id }
      _cascade { invalidations }  # Cascade metadata
    }
  }
}

Comparison Tables¶

View Types Quick Reference¶

Type	Definition	Performance	Use Case	Storage Overhead
*JSONB view (`v_`)**	`CREATE VIEW` with JSONB	5-10ms	Standard queries	None (virtual)
*Projection table (`tv_`)**	`CREATE TABLE` with cached JSONB	0.05-0.5ms	Ultra-high read:write	1.5-2x
Materialized view	`CREATE MATERIALIZED VIEW`	0.1-1ms	Aggregations	1x
*Standard table (`tb_`)**	`CREATE TABLE` (normalized)	N/A	Write targets	1x

Identifier Types Quick Reference¶

Identifier	PostgreSQL Type	GraphQL Type	Exposed?	Purpose
`pk_*`	`INT`	Not exposed	❌ Never	Database JOINs (fast)
`id`	`UUID`	`UUID!`	✅ Always	Public API (stable)
`identifier`	`TEXT`	`String`	✅ Optional	Human-readable (SEO)

Function Types Quick Reference¶

Term	What It Is	Example
PostgreSQL function	SQL function in database	`fn_create_user()`
Python function	Python function/method	`async def create_user()`
Resolver	GraphQL field resolver	Field execution function
Mutation resolver	GraphQL mutation handler	Mutation execution function

When to Define Terms¶

Always Define on First Use¶

For less common terms: - Projection tables - Trinity pattern - APQ (Automatic Persisted Queries) - Dataloader

Example:

FraiseQL supports projection tables (regular tables storing cached JSONB
for ultra-fast reads) for high-performance use cases.

No Need to Define (Well-Established)¶

For common terms: - CQRS (define once per doc) - GraphQL (assume knowledge) - PostgreSQL (assume knowledge) - UUID (standard term)

Common Mistakes¶

❌ Inconsistent Term Usage¶

WRONG:

Create a database function...
Later: The PostgreSQL function should return JSONB...
Later: The SQL function validates input...

CORRECT:

Create a PostgreSQL function...
The PostgreSQL function should return JSONB...
The function validates input... (or "SQL function" if casual)

❌ Ambiguous "View" Usage¶

WRONG:

Create a view for the User type...
(Is it JSONB view? Materialized view? Regular view?)

CORRECT:

Create a JSONB view for the User type:

CREATE VIEW v_user AS
SELECT id, jsonb_build_object(...) as data FROM tb_user;

❌ Using Technical Terms in User Docs¶

WRONG (in getting-started docs):

The fraiseql_rs module transforms JSONB...

CORRECT:

FraiseQL's Rust pipeline transforms JSONB 7-10x faster than Python...

Style Guidelines¶

Capitalization¶

Term	Capitalization	Example
FraiseQL	Always capital F, QL	FraiseQL is a framework...
PostgreSQL	Always capital P, SQL	PostgreSQL function
GraphQL	Always capital G, QL	GraphQL mutation
CQRS	Always uppercase	CQRS architecture
UUID	Always uppercase	UUID identifier
JSONB	Always uppercase	JSONB view
Rust	Capital R	Rust pipeline
Python	Capital P	Python types

Code Formatting¶

Function names: Use code formatting

Call the `fn_create_user()` function...

View names: Use code formatting

Query the `v_user` view...

Column names: Use code formatting

The `data` column contains JSONB...

Cross-Reference Links¶

When mentioning these concepts, always link to canonical definitions:

Concept	Link To
CQRS	`[CQRS](../core/concepts-glossary.md#cqrs)`
Trinity Pattern	`[Trinity pattern](../core/concepts-glossary.md#trinity-identifiers)`
JSONB View Pattern	`[JSONB view](../core/concepts-glossary.md#jsonb-view-pattern)`
Projection Tables	`[Projection tables](../core/concepts-glossary.md#projection-tables-tv_)`
Auto-Inference	`[Auto-inference](../core/auto-inference.md)`
Rust Pipeline	`[Rust pipeline](../performance/rust-pipeline-optimization.md)`
Cascade	`[Cascade](../features/graphql-cascade.md)`

FraiseQL Terminology Guide¶

Quick Reference¶

Database Terminology¶

PostgreSQL Functions¶

Views and Tables¶

JSONB View¶

PostgreSQL View¶

Projection Table¶

Materialized View¶

Architecture Terminology¶

Rust Pipeline¶

fraiseql_rs¶

Trinity Pattern and Identifiers¶

Trinity Pattern¶

Trinity Identifiers¶

CQRS¶

GraphQL Terminology¶

Type¶

Field¶

Resolver¶

Mutation¶

Feature-Specific Terminology¶

Auto-Inference¶

Cascade¶

Comparison Tables¶

View Types Quick Reference¶

Identifier Types Quick Reference¶

Function Types Quick Reference¶

When to Define Terms¶

Always Define on First Use¶

No Need to Define (Well-Established)¶

Common Mistakes¶

❌ Inconsistent Term Usage¶

❌ Ambiguous "View" Usage¶

❌ Using Technical Terms in User Docs¶

Style Guidelines¶

Capitalization¶

Code Formatting¶

Cross-Reference Links¶

See Also¶