Variables and Variable Providers

Using Variables and Variable Providers for dynamic field selection in Viaduct.

Purpose: Enable dynamic field selection and conditional GraphQL queries through runtime variable computation.

Usage: Variables can be bound to resolver arguments or computed dynamically using VariableProvider classes to control which fields are selected at the GraphQL execution level.

Viaduct supports three approaches for dynamic field resolution:

1. Variables with @Variable and fromArgument

Variables can be bound directly to resolver arguments to control GraphQL directive evaluation:

@Resolver(
   """
   fragment _ on Character {
       name
       birthYear @include(if: ${'$'}includeDetails)
       height @include(if: ${'$'}includeDetails)
       mass @include(if: ${'$'}includeDetails)
   }
   """,
   variables = [Variable("includeDetails", fromArgument = "includeDetails")]
)
class ProfileFieldResolver : CharacterResolvers.CharacterProfile() {
   override suspend fun resolve(ctx: Context): String? {
       val character = ctx.objectValue
       val name = character.getName() ?: "Unknown"

       return try {
           // If includeDetails is true, these fields will be available

Benefits: GraphQL-level optimization, declarative field selection, efficient data fetching.

2. Argument-Based Statistics Logic

For practical demo purposes, the character stats use argument-based conditional logic:

@Resolver(
   """
   fragment _ on Character {
       name
       birthYear
       height
       species {
           name
       }
   }
   """
)
class CharacterStatsResolver : CharacterResolvers.CharacterStats() {
   override suspend fun resolve(ctx: Context): String? {
       val character = ctx.objectValue
       val name = character.getName() ?: "Unknown"
       val args = ctx.arguments

       return try {
           buildString {
               append("Stats for $name")
               append(" (Age range: ${args.minAge}-${args.maxAge})")

Benefits: Simple implementation, full access to all fields, easy to debug and maintain.

Note: The full VariableProvider API with dynamic computation is available in the complete Viaduct runtime but simplified here for demo clarity.

3. Argument-Based Conditional Logic

For simpler cases, traditional argument processing within resolvers:

@Resolver(
   """
   fragment _ on Character {
       name
       birthYear
       eyeColor
       hairColor
   }
   """
)
class CharacterFormattedDescriptionResolver : CharacterResolvers.FormattedDescription() {
   override suspend fun resolve(ctx: Context): String? {
       val character = ctx.objectValue
       val name = character.getName() ?: "Unknown"
       val format = ctx.arguments.format

       return when (format) {
           "detailed" -> {
               val birthYear = character.getBirthYear()

Benefits: Simplicity, full Kotlin language features, easy debugging.

Example Schema:

type Character {
  # Variables with fromArgument - demonstrates GraphQL-level field selection
  characterProfile(includeDetails: Boolean = false): String @resolver

  # Argument-based statistics - practical implementation for demos
  characterStats(minAge: Int, maxAge: Int): String @resolver

  # Argument-based conditional logic - flexible formatting
  formattedDescription(format: String = "default"): String @resolver
}

Query Examples

@Variable fromArgument

query BasicProfile {
  node(id: "Q2hhcmFjdGVyOjE=") {  # Luke Skywalker
    ... on Character {
      name
      characterProfile(includeDetails: false)
      # Result: "Character Profile: Luke Skywalker (basic info only)"
    }
  }
}

Include details example

query DetailedProfile {
  node(id: "Q2hhcmFjdGVyOjE=") {
    ... on Character {
      name
      characterProfile(includeDetails: true)
      # Result: "Character Profile: Luke Skywalker, Born: 19BBY, Height: 172cm, Mass: 77.0kg"
    }
  }
}

VariableProvider with dynamic computation

query CharacterStats {
  node(id: "Q2hhcmFjdGVyOjU=") {  # Obi-Wan Kenobi
    ... on Character {
      name
      characterStats(minAge: 25, maxAge: 100)
      # Result: "Stats for Obi-Wan Kenobi (Age range: 25-100), Born: 57BBY, Height: 182cm, Species: Human"
    }
  }
}

Argument-based conditional logic

query FormattedDescriptions {
  node(id: "Q2hhcmFjdGVyOjI=") {  # Princess Leia
    ... on Character {
      name
      detailed: formattedDescription(format: "detailed")
      # Result: "Princess Leia (born 19BBY) - brown eyes, brown hair"

      yearOnly: formattedDescription(format: "year-only")
      # Result: "Princess Leia (born 19BBY)"

      default: formattedDescription(format: "default")
      # Result: "Princess Leia"
    }
  }
}

Combined usage of all three approaches

query CombinedVariablesDemo {
  node(id: "Q2hhcmFjdGVyOjE=") {  # Luke Skywalker
    ... on Character {
      name

      # @Variable with fromArgument examples
      basicProfile: characterProfile(includeDetails: false)
      detailedProfile: characterProfile(includeDetails: true)

      # VariableProvider with dynamic computation
      youngStats: characterStats(minAge: 0, maxAge: 30)
      oldStats: characterStats(minAge: 30, maxAge: 100)

      # Argument-based conditional logic
      nameOnly: formattedDescription(format: "default")
      yearOnly: formattedDescription(format: "year-only")
      detailed: formattedDescription(format: "detailed")
    }
  }
}

Film Fragment Examples

query {
  allFilms(limit: 2) {
    # Standard fields
    title
    director

    # Shorthand fragment - delegates to title
    displayTitle

    # Full fragment - combines episode, title, director
    summary

    # Full fragment - production details
    productionDetails

    # Full fragment with character data
    characterCountSummary
  }
}