Sangria GraphQL Library for Scala

To add Sangria to your Scala project using SBT, add the following dependency to your libraryDependencies. Replace <latest version> with the current version of Sangria.

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

Sangria uses an automated release process triggered by Git tags. To initiate a release, create a new annotated Git tag where the version string must start with a v. Once the tag is pushed to the origin, the CI pipeline will handle the release automatically. Note that publishing artifacts to Maven Central may take some time after the pipeline starts.

git tag -a v0.1.0 -m "v0.1.0"
git push origin v0.1.0

Sangria benchmarks are executed using OpenJDK JMH and integrated into the build system via sbt-jmh.

To run a full, standard benchmark suite, use:

jmh:run

When developing or debugging a new benchmark, you can use specific flags to reduce execution time by limiting iterations, warmups, forks, and threads.

To use Sangria with the Circe JSON library for marshalling, include the sangria-circe dependency in your SBT configuration.

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

The Sangria AST is built on a hierarchy of traits. All nodes implement AstNode, which provides a location (the lexical position in the source code).

Core abstractions:

• Definition: The building blocks of a Document. Includes OperationDefinition (executable operations like queries/mutations) and FragmentDefinition (reusable selection sets).
• Selection: Components of a query. A SelectionContainer (like a Field or InlineFragment) contains a selections: Vector[Selection].
• Type: Represents GraphQL types. Type can be a NamedType, NonNullType, or ListType. You can use .namedType on any Type to recursively find the underlying NamedType (stripping away list and non-null wrappers).
• Value: Represents input values (scalars like IntValue, StringValue, BooleanValue, or complex types like ListValue and ObjectValue).

Sangria distinguishes between OutputType (used for data returned by the server) and InputType (used for data provided by the client, like arguments or input objects).

• LeafType: The most basic types, such as ScalarType or EnumType.
• CompositeType: Types that contain other fields, such as ObjectType, InterfaceType, or UnionType.
• InputType: A hierarchy for client-side data, including ScalarType, EnumType, InputObjectType, and wrappers like ListInputType or OptionInputType.

A Schema is the top-level container for a GraphQL service. It defines the entry points for execution: query, mutation, and subscription (all of which are ObjectTypes).

• ObjectType: Represents the data structures returned by the server. They contain fields that resolve to other types.
• InputObjectType: Represents the data structures sent by the client as arguments to fields or mutations.
• Schema: Composes these types and includes global configuration like directives, validationRules, and additionalTypes (used to ensure all types in the graph are known).

The AST includes types for representing a GraphQL schema (the type system). These are categorized as:

• TypeSystemDefinition: Definitions of types (e.g., ScalarTypeDefinition, ObjectTypeDefinition, InterfaceTypeDefinition, UnionTypeDefinition, EnumTypeDefinition, InputObjectTypeDefinition).
• TypeSystemExtensionDefinition: Extensions to existing types (e.g., ObjectTypeExtensionDefinition, InterfaceTypeExtensionDefinition, etc.).
• SchemaDefinition: The root definition of a schema, specifying operationTypes (Query, Mutation, Subscription).

This example demonstrates how to define a simple GraphQL schema using Sangria, a Query type with a single hello field, and execute a query using the Executor. This example uses sangria-circe for JSON marshalling.

import sangria.schema._
import sangria.execution._
import sangria.macros._
import sangria.marshalling.circe._
import scala.concurrent.ExecutionContext.Implicits.global

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)

result.foreach(res => println(res.spaces2))