🎯 51+ Specialized Types

Financial, logistics, AI vectors, network, geographic—validated at the GraphQL layer.

IBAN • VIN • Vector • ISIN • Coordinate • LTree • UUID • PhoneNumber • and 43 more...

50+ Specialized Types

FraiseQL includes 51 built-in scalar types with validation, PostgreSQL integration, and GraphQL operators. From network addresses to financial identifiers to AI embeddings—all validated at the GraphQL layer before hitting your database.

🌐 Network & Infrastructure

  • IpAddress - IPv4/IPv6 with subnet operators
  • CIDR - Network ranges (10.0.0.0/8)
  • MacAddress - Hardware addresses
  • Port - Network ports (1-65535)
  • Hostname - RFC 1123 compliant
  • DomainName - DNS domain names
  • URL - Valid URLs with protocol

💰 Financial & Banking

  • Money - NUMERIC(19,4) precision
  • CurrencyCode - ISO 4217 (USD, EUR)
  • ExchangeRate - High-precision rates
  • IBAN - Bank accounts (mod-97 validated)
  • ISIN - Securities identification
  • CUSIP - US/Canada securities
  • SEDOL - UK securities
  • LEI - Legal Entity Identifiers
  • StockSymbol - Ticker symbols
  • MIC - Market Identifier Codes
  • ExchangeCode - Stock exchanges
  • Percentage - 0.00-100.00 values

🗺️ Geographic & Location

  • Coordinate - Lat/lng with distance queries
  • Latitude - -90 to +90 degrees
  • Longitude - -180 to +180 degrees
  • LTree - Hierarchical paths (usa.ca.sf)
  • AirportCode - IATA codes (LAX, JFK)
  • PortCode - Seaport codes (UN/LOCODE)
  • PostalCode - Postal/ZIP codes
  • Timezone - IANA timezone IDs

📅 Date & Time

  • Date - ISO 8601 calendar date
  • DateTime - Timezone-aware timestamps
  • Time - Time of day
  • DateRange - Date ranges with overlap
  • Duration - Time intervals
  • Timezone - IANA timezone database

🚚 Logistics & Transportation

  • VIN - Vehicle ID (ISO 3779 check digit)
  • LicensePlate - Vehicle plates
  • TrackingNumber - Shipping tracking
  • ContainerNumber - ISO 6346 containers
  • FlightNumber - Airline flights
  • AirportCode - IATA airport codes
  • PortCode - UN/LOCODE seaports

🤖 AI & Vector Search

  • Vector - pgvector embeddings
  • HalfVector - 16-bit vectors (50% memory)
  • SparseVector - High-dimensional sparse
  • JSON - Arbitrary JSON data
  • HashSHA256 - Content hashes

🔐 Identity & Security

  • UUID - RFC 4122 identifiers
  • ApiKey - API key format validation
  • HashSHA256 - 64-char hex hashes
  • Slug - URL-safe identifiers
  • EmailAddress - RFC 5322 emails
  • PhoneNumber - E.164 format

📝 Content & Media

  • Markdown - Markdown text
  • HTML - HTML content
  • URL - Valid URLs
  • MimeType - MIME types (image/png)
  • Image - Image file references
  • File - File references
  • Color - Hex color codes

🌍 Localization

  • LanguageCode - ISO 639-1 (en, fr, de)
  • LocaleCode - BCP 47 (en-US, fr-FR)
  • CurrencyCode - ISO 4217 currencies
  • Timezone - IANA timezones
  • PostalCode - Country-aware postal
  • SemanticVersion - SemVer (1.2.3)

Every type includes: GraphQL validation • PostgreSQL type mapping • Filtering operators • Error messages

Network Types

1. Define Network Schema

from fraiseql import fraiseql
from fraiseql.types.scalars import IPv4Address, IPv6Address

@fraiseql.type
class Server:
    id: int
    hostname: str
    ipv4: IPv4Address
    ipv6: IPv6Address
    location: str

2. Query with Network Operators

# Find all servers in a subnet
{
  servers(where: {
    ipv4: { inSubnet: "10.0.0.0/8" }
  }) {
    hostname
    ipv4
    location
  }
}

# Find private IP addresses
{
  servers(where: {
    ipv4: { isPrivate: true }
  }) {
    hostname
    ipv4
  }
}

# Find loopback addresses
{
  servers(where: {
    ipv4: { isLoopback: true }
  }) {
    hostname
    ipv4
  }
}

3. Generated SQL

-- FraiseQL generates type-aware PostgreSQL
SELECT * FROM tb_server
WHERE ipv4::inet << '10.0.0.0/8'::inet;

SELECT * FROM tb_server
WHERE inet_is_private(ipv4::inet);

SELECT * FROM tb_server
WHERE host(ipv4::inet) = '127.0.0.1';

-- Native PostgreSQL type casting and functions ✅

Hierarchical Data (LTree)

1. Define Hierarchical Schema

from fraiseql import fraiseql
from fraiseql.types.scalars import LTree

@fraiseql.type
class Location:
    id: int
    name: str
    path: LTree  # e.g., "usa.california.san_francisco"

@fraiseql.type
class Machine:
    id: str
    name: str
    location: Location

2. Query with Hierarchical Operators

# Find all machines in California (any city)
{
  machines(where: {
    location: {
      path: { ancestor_of: "usa.california.*" }
    }
  }) {
    name
    location { name path }
  }
}

# Find all US locations
{
  locations(where: {
    path: { descendant_of: "usa" }
  }) {
    name
    path
  }
}

# Pattern matching
{
  locations(where: {
    path: { matches: "usa.*.san_*" }
  }) {
    name
    path
  }
}

3. Generated SQL

-- FraiseQL generates ltree-aware queries
SELECT m.* FROM tb_machine m
JOIN tb_location l ON m.fk_location = l.pk_location
WHERE l.path::ltree @> 'usa.california'::ltree;

SELECT * FROM tb_location
WHERE path::ltree <@ 'usa'::ltree;

SELECT * FROM tb_location
WHERE path::ltree ~ 'usa.*.san_*'::lquery;

-- Hierarchical queries with ltree operators ✅

Financial Types

1. Banking & Payments

from fraiseql import fraiseql
from fraiseql.types.scalars import (
    Money, CurrencyCode, IBAN, Percentage
)

@fraiseql.type
class BankAccount:
    id: UUID
    iban: IBAN           # Mod-97 validated
    balance: Money       # NUMERIC(19,4)
    currency: CurrencyCode  # ISO 4217
    interest_rate: Percentage

2. Securities Trading

from fraiseql.types.scalars import (
    ISIN, CUSIP, StockSymbol, MIC, LEI
)

@fraiseql.type
class Security:
    id: UUID
    isin: ISIN           # International ID
    cusip: CUSIP         # US/Canada ID
    symbol: StockSymbol  # Ticker (AAPL)
    exchange: MIC        # Market ID (XNAS)
    issuer_lei: LEI      # Legal Entity ID

3. Query with Validation

# Invalid IBAN rejected at GraphQL layer
mutation {
  createAccount(input: {
    iban: "GB82WEST12345698765432"
    balance: "10000.00"
    currency: "USD"
    interestRate: "2.5"
  }) {
    id
    iban
  }
}

# Check digit validation prevents typos
# "GB99INVALID" → Error before DB hit

AI & Vector Search (pgvector)

1. Define Embeddings

from fraiseql import fraiseql
from fraiseql.types.scalars import Vector, HalfVector

@fraiseql.type
class Document:
    id: UUID
    title: str
    content: str
    # 1536-dim OpenAI embeddings
    embedding: Vector
    # 50% memory with HalfVector
    embedding_lite: HalfVector

2. Semantic Search Queries

# Find similar documents
{
  documents(
    orderBy: {
      embedding: {
        cosine_distance: $queryVector
      }
    }
    limit: 10
  ) {
    id
    title
    _distance  # Similarity score
  }
}

3. Generated SQL

-- pgvector cosine distance
SELECT id, title,
  embedding <=> $1 AS _distance
FROM tb_document
ORDER BY embedding <=> $1
LIMIT 10;

-- Uses HNSW or IVFFlat indexes
-- Sub-10ms even with millions of vectors

Vector types: Vector (float32) • HalfVector (float16, 50% memory) • SparseVector (high-dimensional)

Key Benefits

✅

Input Validation

IBAN mod-97, VIN check digits, UUID format. Invalid data rejected before hitting PostgreSQL.

💰

Financial Compliance

ISO 4217 currencies, ISIN/CUSIP/SEDOL securities, LEI entity identifiers. Built for fintech.

🤖

AI-Ready

Native pgvector support. Vector, HalfVector, SparseVector for RAG and semantic search.

🚚

Logistics Support

VIN, container numbers, tracking IDs, airport/port codes. Supply chain ready.

⚡

Native Performance

PostgreSQL GiST, GIN, HNSW indexes. Type-aware query optimization.

🎯

Clear Error Messages

"Invalid IBAN: check digit mismatch" not "constraint violation". Debugging made simple.

Type-Specific Operators

Network Types (IPv4/IPv6)

# Network operators
ipv4: {
  inSubnet: "10.0.0.0/8"      # IP in subnet
  isPrivate: true             # RFC 1918 private
  isLoopback: true            # 127.0.0.1
  eq: "192.168.1.1"           # Exact match
}

LTree (Hierarchical)

# Hierarchical operators
path: {
  ancestor_of: "usa.california"
  descendant_of: "usa"
  matches: "usa.*.san_*"
  eq: "usa.california.sf"
}

Date Ranges

# Range operators
availability: {
  overlaps: ["2024-01-01", "2024-12-31"]
  contains: "2024-06-15"
  adjacent: ["2024-12-31", "2025-01-01"]
}

Geographic (Coordinates)

# Spatial operators
coordinates: {
  eq: "37.7749,-122.4194"
  distance_within: {
    center: [37.7749, -122.4194]
    radius: 5000  # meters
  }
}

Vector (AI Embeddings)

# Vector distance operators
embedding: {
  cosine_distance: $queryVector
  l2_distance: $queryVector
  inner_product: $queryVector
}

Standard Operators (All Types)

# Common to all scalar types
field: {
  eq: "value"      # Exact match
  ne: "value"      # Not equal
  in: ["a", "b"]   # In list
  notin: ["c"]     # Not in list
}

Industry Applications

💰 Financial Services

  • ✅ Banking: IBAN validation, Money precision
  • ✅ Trading: ISIN, CUSIP, SEDOL securities
  • ✅ Compliance: LEI, MIC identifiers
  • ✅ FX: CurrencyCode, ExchangeRate

🚚 Logistics & Supply Chain

  • ✅ Fleet: VIN tracking, LicensePlate
  • ✅ Shipping: ContainerNumber, TrackingNumber
  • ✅ Aviation: FlightNumber, AirportCode
  • ✅ Maritime: PortCode (UN/LOCODE)

🤖 AI & Machine Learning

  • ✅ RAG: Vector embeddings, semantic search
  • ✅ Memory: HalfVector (50% savings)
  • ✅ Scale: SparseVector for high dimensions
  • ✅ Similarity: Cosine, L2, inner product

🏢 Enterprise

  • ✅ Org structure: LTree hierarchies
  • ✅ Multi-tenant: Geographic isolation
  • ✅ Scheduling: DateRange overlap detection
  • ✅ Localization: LanguageCode, LocaleCode

🌐 DevOps & Infrastructure

  • ✅ Networking: IPv4/IPv6, CIDR, subnet queries
  • ✅ Inventory: MacAddress, Hostname
  • ✅ Monitoring: Port, DomainName
  • ✅ IoT: Device hierarchies with LTree

📍 Location-Based Services

  • ✅ Proximity: Coordinate distance queries
  • ✅ Delivery: PostalCode, PhoneNumber
  • ✅ Internationalization: Timezone, LocaleCode
  • ✅ Travel: AirportCode, PortCode

Type Coverage Comparison

Category Hasura PostGraphile Strawberry FraiseQL
Network (IP/CIDR) ❌ Strings ⚠️ Limited ❌ Manual ✅ 7 types + operators
Financial (IBAN/ISIN) ❌ None ❌ None ❌ None ✅ 12 types validated
Vector (pgvector) ❌ None ⚠️ Plugin ❌ Manual ✅ 4 types + distance ops
Hierarchical (ltree) ❌ JSON ⚠️ Plugin ❌ Manual ✅ Native + 4 operators
Logistics (VIN/Container) ❌ None ❌ None ❌ None ✅ 7 types check-digit
Geographic (Coords) ⚠️ PostGIS ⚠️ PostGIS ❌ Manual ✅ 8 types + distance
Total Built-in Types ~10 ~15 ~5 51+ types

FraiseQL ships with 51+ validated scalar types. No plugins, no custom code, no manual validation. Domain types like IBAN, VIN, and ISIN include check-digit validation at the GraphQL layer.

Ready for PostgreSQL's Full Power?

Specialized types are a core feature of FraiseQL+

Read the Docs See Examples