Sangria GraphQL for Scala: Schema and Execution

Sangria's place in a Scala GraphQL service

Sangria solves the schema and execution part of building a GraphQL service in Scala. It is aimed at developers who want to define GraphQL types in Scala code, execute GraphQL documents against those types, and return results through a Scala data structure. The README calls it a Scala GraphQL library and states that it is spec compliant, which makes it relevant to servers consumed by Apollo, Relay, GraphiQL, and other GraphQL tools.

The important boundary is that Sangria is not presented as a complete server application. The README points to `sangria-akka-http-example` for an application using `akka-http`, and to `sangria-playground` for an interactive GraphQL server built with Play framework. That distinction affects adoption. Sangria can provide the GraphQL core, while transport, routing, authentication, deployment, and production operations remain separate application concerns.

It is best suited to Scala teams that prefer a typed library integrated into an existing service. A team that needs a ready-made endpoint, administrative interface, or hosted development environment will need more than the dependency declaration shown in the README.

Schema definitions and execution flow in the Hello World example

The README's example makes the basic flow explicit. First, the code imports `sangria.schema._`, `sangria.execution._`, `sangria.macros._`, and `sangria.marshalling.circe._`. It defines a `QueryType` with `ObjectType` and a `Field` named `hello`. The field uses `StringType`, and its resolver returns the literal string `Hello world!`.

The schema is then assembled with `Schema(QueryType)`. The query is written with the `graphql` macro as `graphql"{ hello }"`. After that, `Executor.execute(schema, query)` runs the query against the schema. The result is asynchronous from the caller's perspective, as the example uses `result.foreach` and prints `res.spaces2` inside the callback. The README shows that this produces JSON containing a `data` object and the resolved `hello` value.

This example demonstrates a resolver returning a plain Scala value rather than a database result or remote service call. More complex applications can resolve fields from their own services, but the README does not specify a data-loading, batching, subscription, or persistence mechanism. The architecture visible here is therefore a direct schema and execution library, with application code responsible for supplying field behavior and the surrounding service integration.

SBT installation and the first query

The README documents the core dependency through SBT. It uses a placeholder for the version, so the value must be selected by the project rather than copied literally. The JSON integration shown by the example is `sangria-circe`, and the README specifies version `1.3.2` for that example.

Add the core library to the SBT build:

libraryDependencies += "org.sangria-graphql" %% "sangria" % "<latest version>"

For the Circe marshalling used in the Hello World example, add the companion module:

libraryDependencies += "org.sangria-graphql" %% "sangria-circe" % "1.3.2"

The first executable step can remain close to the README example. The schema defines one query field, the GraphQL document asks for `hello`, and `Executor.execute` returns the encoded result:

val QueryType = ObjectType("Query", fields[Unit, Unit](
  Field("hello", StringType, resolve = _ => "Hello world!")
))

val schema = Schema(QueryType)
val query = graphql"{ hello }"
val result = Executor.execute(schema, query)

The README uses `scala.concurrent.ExecutionContext.Implicits.global` in the complete example and prints the result with `println(res.spaces2)`. It does not document an HTTP route, listening port, deployment command, or standalone startup command. A new user therefore needs to place this logic inside the Scala application or use one of the linked example applications.

Circe marshalling and client compatibility

The example selects `sangria-circe` because Sangria separates execution from the marshalling integration used to represent results. In the shown code, `res.spaces2` produces the JSON text printed to standard output. The documented output is:

{
  "data" : {
    "hello" : "Hello world!"
  }
}

That output is a useful check for the first use. If the schema field resolves and the result is marshalled as documented, the response contains the GraphQL `data` member and the `hello` field. The README does not document error formatting, partial data behavior, request parsing, or HTTP content negotiation, so those parts should not be inferred from this minimal example.

Sangria's stated compatibility with Apollo, Relay, GraphiQL, and other GraphQL tools concerns GraphQL interoperability. It does not mean that the library supplies their clients, browsers, or server integrations. Those remain separate dependencies and application decisions. The linked `sangria-relay` project is mentioned specifically for use with React Relay, which indicates that protocol compatibility does not eliminate the need for framework-specific integrations.

Transport choices and the boundary of the core library

The repository gives two concrete directions for running Sangria. The `sangria-akka-http-example` is an example application using `akka-http`. That path is relevant when the service already uses Akka HTTP and the team wants to connect schema execution to an HTTP endpoint. The README does not provide that example's route code or server configuration, so the exact request handling cannot be reproduced from the Sangria README alone.

The other documented route is `sangria-playground`, an example GraphQL server written with Play framework and Sangria. It also provides a playground for interactively executing GraphQL queries and examples. Compared with embedding Sangria in an existing service, the Playground is positioned as a ready-made example and interactive environment. It is a different operating mode, not simply another function inside the core library.

This creates a real choice for evaluation. Use the linked Akka HTTP example when transport integration is the main uncertainty. Use the Playground when the immediate need is an interactive server and example queries. Neither example turns the core dependency into a documented production deployment procedure.

Operational constraints, licensing, and maintenance

The repository is not archived, and its last push was on 2026-10-14. The release list includes `v4.2.19` dated 2026-07-07, followed by `v4.2.18` and `v4.2.17`. Those facts indicate recent release and repository activity, but the README does not describe compatibility guarantees, upgrade procedures, or migration support for particular versions.

The upgrade cost depends on the surrounding Scala project. Sangria uses SBT coordinates with the `%%` cross-version notation, so the Scala binary version selected by the build can affect which dependency artifact is resolved. The README does not list supported Scala versions, migration notes, or a compatibility matrix. A team upgrading Sangria should check the repository's `CHANGELOG.md`, `build.sbt`, and release history rather than assuming that the latest listed version can be substituted without review.

Sangria is licensed under Apache License, Version 2.0. The repository includes `LICENSE`, and the README links to the Apache license text. That license information identifies the project's stated licensing terms. It does not replace legal review for distribution, notices, or compatibility obligations in a particular product.

Editorial conclusion

Adopt Sangria when the application is written in Scala and the GraphQL schema, execution, and marshalling layer should be controlled directly in application code. Do not choose it as a standalone server without confirming transport and deployment requirements. Verify first which Scala version and Sangria release your build uses, then confirm that your HTTP framework can expose `Executor.execute` through the API shape you need.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. sangria-graphql/sangria on GitHub