Type-Aware Filter Generation

What is Type-Aware Filter Generation?

FraiseQL automatically generates GraphQL filter operators based on your field types. String fields get text operators, numbers get comparison operators, network types get subnet operators, and hierarchical types get ancestor/descendant queries—all without writing a single line of filter definition code.

Field Type	Auto-Generated Operators	Example Use Case
String	eq, ne, in, contains, startsWith, endsWith, regex	Text search, pattern matching
Int, Float	eq, ne, lt, lte, gt, gte, in, between	Range queries, comparisons
Boolean	eq, ne, isTrue, isFalse, isNull	Flag filtering
Date/DateTime	eq, ne, before, after, between, overlaps	Time-based queries
IPv4/IPv6	inSubnet, isPrivate, isLoopback, eq, ne	Network management
LTree	ancestor_of, descendant_of, matches, eq	Hierarchical data
DateRange	overlaps, contains, adjacent, eq	Scheduling, availability
JSONB	contains, has_key, path_exists, eq	Flexible schema queries

How It Works

1. Define Your Types (Python)

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

@fraiseql.type
class Server:
    id: int
    hostname: str
    ip_address: IPv4Address
    location_path: LTree
    created_at: datetime
    is_active: bool
    metadata: dict  # JSONB

# That's it! No filter definitions needed.

2. Filters Auto-Generated (GraphQL)

# FraiseQL automatically generates:

input ServerWhereInput {
  # String operators
  hostname: StringFilter

  # IPv4 operators
  ip_address: IPv4Filter

  # LTree operators
  location_path: LTreeFilter

  # DateTime operators
  created_at: DateTimeFilter

  # Boolean operators
  is_active: BooleanFilter

  # JSONB operators
  metadata: JSONBFilter

  # Logical operators
  AND: [ServerWhereInput!]
  OR: [ServerWhereInput!]
  NOT: ServerWhereInput
}

# 35+ total operators across all types!

3. Use Intelligent Filters

# String operators
{
  servers(where: {
    hostname: { contains: "prod" }
  }) { ... }
}

# Network operators (type-aware!)
{
  servers(where: {
    ip_address: { inSubnet: "10.0.0.0/8" }
  }) { ... }
}

# Hierarchical operators
{
  servers(where: {
    location_path: { ancestor_of: "usa.california" }
  }) { ... }
}

# Date range queries
{
  servers(where: {
    created_at: { after: "2024-01-01" }
  }) { ... }
}

# Complex logical queries
{
  servers(where: {
    AND: [
      { hostname: { startsWith: "web" } }
      { is_active: { isTrue: true } }
      { ip_address: { isPrivate: true } }
    ]
  }) { ... }
}

Key Benefits

⚡

Zero Boilerplate

No manual filter input type definitions. Define field type once, get all relevant operators automatically.

🎯

Type-Safe

Operators match field types. Can't use `inSubnet` on strings or `contains` on numbers. Type system enforces correctness.

🧠

Intelligent Operators

Network types get subnet operations. Hierarchical types get ancestor/descendant queries. Date types get before/after.

🔧

PostgreSQL-Aware

Generates SQL that leverages PostgreSQL-specific features: JSONB operators, ltree queries, inet functions.

📚

Auto-Documented

All 35+ operators documented in GraphQL schema. Developers see available filters in Apollo Studio.

🔄

Always Consistent

Change field type, operators update automatically. No manual filter maintenance needed.

Complete Operator Reference

String Operators

hostname: {
  eq: "web-01"              # Exact match
  ne: "web-02"              # Not equal
  in: ["web-01", "web-02"]  # In list
  contains: "prod"          # Contains substring
  startsWith: "web"         # Starts with prefix
  endsWith: "01"            # Ends with suffix
  regex: "^web-[0-9]+$"     # Regex pattern match
  isNull: false             # Null check
}

Numeric Operators (Int, Float, Decimal)

port: {
  eq: 8080                  # Exact match
  ne: 80                    # Not equal
  lt: 9000                  # Less than
  lte: 8080                 # Less than or equal
  gt: 1024                  # Greater than
  gte: 1024                 # Greater than or equal
  in: [80, 443, 8080]       # In list
  between: [1024, 65535]    # Range (inclusive)
  isNull: false             # Null check
}

Boolean Operators

is_active: {
  eq: true                  # Exact match
  ne: false                 # Not equal
  isTrue: true              # Explicitly true
  isFalse: true             # Explicitly false
  isNull: false             # Null check
}

Date/DateTime Operators

created_at: {
  eq: "2024-01-01"          # Exact match
  ne: "2023-12-31"          # Not equal
  before: "2024-01-01"      # Before date
  after: "2023-12-31"       # After date
  between: ["2023-01-01", "2023-12-31"]  # Date range
  isNull: false             # Null check
}

Network Operators (IPv4/IPv6)

ip_address: {
  eq: "192.168.1.1"         # Exact match
  inSubnet: "10.0.0.0/8"    # IP in subnet
  isPrivate: true           # RFC 1918 private
  isLoopback: true          # 127.0.0.1
  isNull: false             # Null check
}

Hierarchical Operators (LTree)

location_path: {
  eq: "usa.california.sf"              # Exact match
  ancestor_of: "usa.california"        # Parent of
  descendant_of: "usa"                 # Child of
  matches: "usa.*.san_*"               # Pattern match
  isNull: false                        # Null check
}

Logical Operators (All Types)

{
  AND: [
    { hostname: { startsWith: "web" } }
    { is_active: { isTrue: true } }
  ]
  OR: [
    { port: { eq: 80 } }
    { port: { eq: 443 } }
  ]
  NOT: {
    ip_address: { isPrivate: true }
  }
}

Framework	Filter Generation	Type-Aware	PostgreSQL Operators
Hasura	✅ Automatic	⚠️ Basic types only	❌ Limited
PostGraphile	✅ Automatic	⚠️ Some types	⚠️ Plugin required
Strawberry/Graphene	❌ Manual definitions	❌ Manual per type	❌ Custom resolvers
FraiseQL	✅ Automatic	✅ All types + PostgreSQL	✅ Native support

🎨 Type-Aware Filter Generation