Field Filtering

Field filtering provides powerful control over field visibility, allowing you to:

• Hide sensitive fields from specific types
• Create read-only or write-only fields
• Version your API by selectively exposing fields
• Use @gqlIgnoreAll for opt-in field inclusion

Quick Reference

Read-Only Fields (ro)

Fields marked with ro appear only in types, not in inputs:

Generated:

Use case: Timestamps, IDs, computed fields

Write-Only Fields (wo)

Fields marked with wo appear only in inputs, not in types:

Generated:

Use case: Passwords, secrets, confirmation codes

Read-Write Fields (rw)

Fields marked with rw are included everywhere:

All fields appear in both User type and UserInput.

Use case: Explicit inclusion, overriding @gqlIgnoreAll

Field-Specific Filtering with include and omit

Include Field in Specific Types

Use include: to include a field only in specific types:

Generated:

Omit Field from Specific Types

Use omit: or ignore: to exclude a field from specific types:

Generated:

Note: omit and ignore are aliases (identical behavior)

Multiple Type Filtering

Apply filtering rules to multiple types using comma-separated lists:

Syntax rules:

• Multiple types: Use quotes with commas: "Type1,Type2,Type3"
• No spaces: "AdminView,UserView" not "AdminView, UserView"
• Single type: Quotes optional: include:AdminView or include:"AdminView"

Type-Specific Read/Write Rules

Combine ro/wo with type lists for fine-grained control:

Result:

• secret field:
  • ✓ In AdminView type
  • ✗ Not in UserView, AdminInput, UserInput
• balance field:
  • ✓ In AdminView and UserView types
  • ✗ Not in AdminInput or UserInput
• password field:
  • ✓ In AdminInput and UserInput
  • ✗ Not in AdminView or UserView

The @gqlIgnoreAll Directive

Use @gqlIgnoreAll to ignore all fields by default, then selectively include fields:

Generated:

Use case: Security-first approach, expose only explicitly included fields

Wildcard Usage

Use * to apply a rule to all types/inputs:

Equivalents:

• include:* = include = rw:* = rw

API Versioning Example

Create multiple versions of the same type with different field sets:

Generated:

Rules and Precedence

1. @gqlIgnoreAll ignores all fields by default
2. Explicit include, rw overrides @gqlIgnoreAll
3. omit, ignore takes precedence over default inclusion
4. Type-specific rules override global rules (ro, wo, rw)
5. Wildcard * applies to all types/inputs

Best Practices

1. Use ro for timestamps and IDs: Prevents modification in inputs
2. Use wo for passwords: Keeps secrets out of type schemas
3. Use @gqlIgnoreAll for security: Opt-in approach for sensitive data
4. Version with include: Incrementally expose fields across API versions
5. Document filtering logic: Make field visibility rules clear in comments

Once you've configured field filtering, run:

$ gqlschemagen generate

to generate schemas with precise field control.