Caliban Documentation

Once code is generated, every GraphQL type has a corresponding Scala object, and every field has a corresponding function returning a SelectionBuilder[Parent, ResultType].

Combining Fields

Use the ~ operator to combine multiple selections. This results in a tuple of the combined types.

// Returns SelectionBuilder[Character, (String, List[String])]
val selection = Character.name ~ Character.nicknames

Mapping to Case Classes

To avoid working with nested tuples, use .mapN to map selections directly into a case class:

case class CharacterView(name: String, nickname: List[String], origin: Origin)

val character: SelectionBuilder[Character, CharacterView] =
  (Character.name ~ Character.nicknames ~ Character.origin).mapN(CharacterView)

Nested Selections

For fields that return object types, pass a SelectionBuilder as a block to specify which sub-fields to retrieve:

// Querying a list of characters from the RootQuery
val query: SelectionBuilder[RootQuery, List[CharacterView]] =
  Query.characters { 
    character 
  }

Arguments

If a GraphQL field requires arguments, the generated Scala function will require them as well:

// Querying characters with a specific origin argument
val query = Query.characters(Origin.MARS) { character }

Federation allows your graph to become part of a larger graph without brittle schema stitching. You can enable basic federation by wrapping your existing schema with the federated annotation from caliban.federation.v1.

To support entity resolution, you must:

1. Annotate types with @GQLKey to define resolvable keys.
2. Use @GQLExtend and @GQLExternal when extending types defined in other services.
3. Define an EntityResolver for each type you wish to support.
4. Pass the resolver(s) to the federated function when wrapping the schema.

import caliban.federation.v1._

// 1. Basic federation
val federatedSchema: GraphQL[R] = schema @@ federated

// 2. Entity resolution with keys and resolvers
@GQLKey("name")
case class Character(name: String)

val resolver = EntityResolver[CharacterService, CharacterArgs, Character](args => 
  ZQuery.fromZIO(characters.getCharacter(args.name))
)

// 3. Apply resolvers to the schema
val federatedSchema = schema @@ federated(resolver)

You can share a context between Cats Effect and ZIO using CatsInterop. This is useful when working with contextual effects like Kleisli.

Use CatsInterop.contextual(dispatcher) to create a CatsInterop.Contextual[Effect, Context] instance. This allows you to convert between RIO[Context, A] and Kleisli[IO, Context, A] using .toEffect and .fromEffect respectively.

import cats.data.Kleisli
import cats.effect.IO
import cats.effect.std.Dispatcher
import caliban.interop.cats.CatsInterop
import zio.RIO

trait Context
type Effect[A] = Kleisli[IO, Context, A]

implicit val dispatcher: Dispatcher[Effect] = ???
implicit val runtime: Runtime[Context] = ???

val interop: CatsInterop.Contextual[Effect, Context] = CatsInterop.contextual(dispatcher)

val rio: RIO[Context, Int] = ???
val ce: Kleisli[IO, Context, Int] = ???

val fromRIO: Kleisli[IO, Context, Int] = interop.toEffect(rio)
val fromCE: RIO[Context, Int] = interop.fromEffect(ce)

The @newtype directive allows you to wrap GraphQL fields (like ID) into statically typed Scala value classes (e.g., FooId) for better backend type safety, without breaking client-side compatibility.

Usage

Apply the directive to FIELD_DEFINITION, ARGUMENT_DEFINITION, or INPUT_FIELD_DEFINITION:

directive @newtype(name : String) on FIELD_DEFINITION | ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION

type Query {
  getFoo(id: ID! @newtype(name: "FooId")): Foo
}

type Foo {
  id: ID! @newtype(name: "FooId")
}

Implementation Details

• Type Erasure: The generated Scala code uses extends AnyVal. This ensures that at runtime, the types are erased to their underlying primitives, meaning GraphQL queries remain unchanged and performant.
• Schema Mapping: To make this work, you must provide implicit Schema and ArgBuilder instances in the companion object of your newtype to handle the conversion between the underlying type (e.g., Int or String) and the newtype.
• Metadata: Caliban uses the @GQLDirective annotation in the generated code to preserve the link between the Scala type and the GraphQL directive.

// Example of generated newtype with required implicits
case class FooId(value: Int) extends AnyVal
object FooId {
  implicit val schema: Schema[Any, FooId] = implicitly[Schema[Any, Int]].contramap(_.value)
  implicit val argBuilder: ArgBuilder[FooId] = implicitly[ArgBuilder[Int]].map(FooId(_))
}

// Usage in a generated class
final case class Foo(
  @GQLDirective(Directive("newtype", Map("name" -> StringValue("FooId"))))
  id: FooId
)

Caliban uses the Schema typeclass to transform Scala types into GraphQL types. You can generate Schema instances for your custom types (case classes and sealed traits) using two methods:

Auto derivation

Easiest for getting started. Import caliban.schema.Schema.auto._ to automatically generate Schema instances for all case classes and sealed traits found inside your resolver.

Limitations:

• Can lead to longer compilation times and high amounts of generated code if types are referenced in multiple places.
• Error messages for missing nested types may point to the root type instead of the specific missing type.
• May struggle with highly nested or recursive types.

Semi-auto derivation

Recommended for non-trivial schemas to improve compilation and error clarity.

Scala 2: Use Schema.gen to create an implicit Schema instance.

Scala 3: Use the derives Schema.SemiAuto syntax on the class, or define a given Schema[Any, MyClass] = Schema.gen.

// Scala 2
import caliban.schema.Schema
case class MyClass(field: String)
implicit val schemaForMyClass: Schema[Any, MyClass] = Schema.gen

// Scala 3
import caliban.schema.Schema
case class MyClass(field: String) derives Schema.SemiAuto
// OR
given Schema[Any, MyClass] = Schema.gen