<p align="center"><img src="graphql_query.png" alt="GraphQL Query" width="350"></p>

GraphQL Query provides a library for validating, parsing, and formatting GraphQL queries and schemas

⚠️ Disclaimer: This library is still in early development. APIs may change as it evolves.

Table of Contents

• Why This Library?
• Features
• Quick Start
  • Installation
  • Examples
• Usage
  • ~GQL Sigil
  • gql_from_file Macro
  • gql Macro
  • document_with_options Macro
• Use the documents in HTTP Requests
• Fragment support
  • Define fragments
  • Use fragments
• Schema Support
  • Parsing and Validating Schemas
  • Schema Modules
  • Document Validation Against Schema
• Formatter Integration
• Manual API
• Roadmap
• License
• Links

Why This Library?

• Developer tool: Focused on validation, formatting, compile-time and runtime safety.
• External APIs integration: Build and validate queries against external GraphQL APIs. Never miss a deprecated field, a type error in the arguments or a typo in the fields you are fetching.
• Best match for your tests: Use in your tests to build and validate queries against any GraphQL schema (external APIs, you own Absinthe schema, ...), catch issues early on development.
• Not a GraphQL server: Absinthe is for building GraphQL servers. GraphqlQuery is for validating and formatting queries against schemas (including external APIs). They complement each other.

Features

• ✅ GraphQL queries and mutations validation (syntax, unused vars, fragments, spec compliance)
• ✅ Schema parsing and validation (from strings or files)
• ✅ Fragment support with composition, reusability, and validation
• ✅ Schema-aware query, mutation and fragments validation (detect invalid fields/types)
• ✅ Compile-time macros:
  • ~GQL sigil for static queries
  • gql_from_file for file-based queries
  • gql macro for dynamic queries
  • document_with_options for applying options to multiple macros
• ✅ Query formatting with consistent indentation
• ✅ Mix format integration for ~GQL sigil, .graphql and .gql files
• ✅ Schema modules with automatic recompilation on schema changes
• ✅ Flexible validation modes: compile-time, runtime, or ignore
• ✅ JSON encoding support for Document structs (JSON/Jason protocols)
• ⚡ Backed by Rust for fast parsing and validation

Quick Start

Installation

Add graphql_query to your dependencies in mix.exs:

def deps do
  [
    {:graphql_query, "~> 0.3"}
  ]
end

Fetch deps:

mix deps.get

No Rust installation required — precompiled binaries are used.

Examples

You can find more examples in the Cheatsheet, here is a little compilation.

Example: Compile-time Document Validation

import GraphqlQuery

# Valid query
~GQL"""
query GetUser($id: ID!) {
  user(id: $id) {
    name
  }
}
"""

# Invalid query → compile-time warning
~GQL"""
query GetUser($unused: String!) {
  user {
    name
  }
}
"""
# warning: GraphQL validation errors:
# Error: unused variable: `$unused` at file.ex:10:1 - variable is never used

Example: Schema Validation

defmodule MyApp.Schema do
  use GraphqlQuery.Schema, schema_path: "priv/graphql/schema.graphql"
end

defmodule MyApp.Queries do
  use GraphqlQuery, schema: MyApp.Schema

  def get_user_query do
    ~GQL"""
    query GetUser($id: ID!) {
      user(id: $id) {
        id
        name
        email
      }
    }
    """
  end
end

Example: Usage in requests

query = gql [fragments: [@user_fragment]], """
query { ... }
"""

user = "1"
user_query = GraphqlQuery.Document.add_variable(query, :id, user)
Req.post!("/api", json: user_query)

Usage

~GQL Sigil

• For static queries only (no interpolation).
• Validates at compile time.
• Optional formatter plugin.
• Supports modifiers, the modifiers are applied at the end of the string: ~GQL""rf:
  • i → Ignore warnings
  • r -> Validate on runtime
  • s → Parse as schema
  • q → Parse as query (this is the default behaviour)
  • f → Parse as fragment

import GraphqlQuery

# Valid query
~GQL"""
query GetUser($id: ID!) {
  user(id: $id) {
    name
  }
}
"""

# Ignore warnings
~GQL"""
query GetUser($id: ID!, $unused: String) {
  user(id: $id) { name }
}
"""i

# Parse schema
~GQL"""
type User {
  id: ID!
  name: String!
}
"""s

# Parse fragment
~GQL"""
fragment UserData on User {
  id
  name
}
"""f

# Delegate validation to runtime
# Try not to use it, but if you need it you have the option
~GQL"""
query GetUser($id: ID!) {
  user(id: $id) {
    ...UserData
  }
}
"""r |> GraphqlQuery.Document.add_fragment(user_data)

gql_from_file Macro

• Load queries or schemas from .graphql or .gql files.
• Validates at compile time.
• Tracks file changes for recompilation.
• Options:
  • ignore: true → skip validation

  • type: :query | :schema | :fragment → Specify if the content shall be validated as query, schema or fragment

  • schema: SchemaModule → Specify the schema module to validate the query or fragment with
  • fragments: [GraphqlQuery.Fragment.t()] → Add reusable fragments to queries

Example project structure:

priv/
├── graphql/
|   ├── schema.graphql
|   ├── get_user.graphql
|   └── create_user.gql
|   └── user_fragment.gql

defmodule MyApp.Schema do
  use GraphqlQuery.Schema, schema_path: "priv/graphql/schema.graphql"
end

defmodule MyApp.Queries do
  use GraphqlQuery, schema: MyApp.Schema

  @user_fragment gql_from_file "priv/graphql/user_fragment.gql", type: :fragment

  def get_user_query do
    gql_from_file "priv/graphql/get_user.graphql", fragments: [@user_fragment]
  end

  def create_user_mutation do
    gql_from_file "priv/graphql/create_user.gql", schema: MyApp.Schema
  end
end

gql Macro

• Supports dynamic queries with interpolation.
• Options:
  • evaluate: true → expand module calls at compile time
  • runtime: true → validate at runtime instead of compile time
  • ignore: true → skip validation

  • type: :query | :schema | :fragment → Specify if the content shall be validated as query, schema or fragment

  • schema: SchemaModule → Specify the schema module to validate the query or fragment with
  • fragments: [GraphqlQuery.Fragment.t()] → Add reusable fragments to queries

defmodule Example do
  use GraphqlQuery

  @fields "name email"

  # Expand module attributes
  def query do
    gql """
    query {
      user { #{@fields} }
    }
    """
  end

  # Expand other module calls
  def query_with_eval do
    gql [evaluate: true], """
    query {
      ...#{OtherModule.fragment_name()}
      #{OtherModule.more_fields()}
    }
    #{OtherModule.fragment()}
    """
  end

  # Specify fragments for the query
  def query_with_fragments do
    gql [fragments: [OtherModule.fragment()]], """
    query {
      users {
        ...UserFragment
      }
    }
    """
  end

  # Runtime validation for local variables
  def query_runtime(user_id) do
    gql [runtime: true], """
    query {
      user(id: #{user_id}) { name }
    }
    """
  end
end

document_with_options Macro

• Apply common options to all GraphqlQuery macros and sigils within a block
• Key feature: Enables the ~GQL sigil to work with complex options like :schema and :fragments
• Supports all the same options as individual macros

• Options are merged with precedence ((explicit macro options | sigil modifiers) > document_with_options > module defaults)

The main use case for the macro document_with_options is to use fragments and schema validation with sigils. The ~GQL sigil doesn't support schema or fragments options directly, but document_with_options enables it:

# This won't work - sigils don't support schema options
~GQL"""
query GetUser { user { id name } }
"""[schema: MySchema]  # ❌ Invalid syntax

# This works perfectly
document_with_options schema: MySchema do
  ~GQL"""
  query GetUser { user { ...UserFragment } }
  """  # ✅ Schema validation applied
end

defmodule MyApp.Schema do
  use GraphqlQuery.Schema, schema_path: "priv/schema.graphql"
end

defmodule MyApp.Queries do
  use GraphqlQuery, schema: MyApp.Schema

  @user_fragment ~GQL"""
  fragment UserFragment on User {
    id
    name
  }
  """f

  def user_query do
    document_with_options fragments: [@user_fragment] do
      ~GQL"""
      query GetUser($id: ID!) {
        user(id: $id) {
          ...UserFragment
        }
      }
      """
    end
  end
end

Use the documents in HTTP requests

At the end, we want to build GraphQL queries to do requests to the GraphQL server.

To make it easy, the GraphQL.Document struct returned by ~GQL, gql_from_file and gql implement the protocol for the standard library JSON and for Jason.

To use queries in requests, you can directly put the query document in the body if the library supports JSON encoding, or manually call JSON.encode!(query) or Jason.encode!(query) to get the request body as a string.

The encoding build a json such as {"query": "document", "variables": {}}. The document is the query or mutation with the fragments (if any) at the end.

Example with Req and GraphQLZero mock server:

base_query = ~GQL"""
query($id: ID!) {
  user(id: $id) {
    id
    username
    email
    address {
      geo {
        lat
        lng
      }
    }
  }
}
"""
# base_query is a %GraphqlQuery.Document{} struct

# We add variables to create a new document with that information
user_query = GraphqlQuery.Document.add_variable(base_query, :id, "1")

Req.post!("https://graphqlzero.almansi.me/api", json: user_query).body

# %{
#   "data" => %{
#     "user" => %{
#       "address" => %{"geo" => %{"lat" => -37.3159, "lng" => 81.1496}},
#       "email" => "Sincere@april.biz",
#       "id" => "1",
#       "username" => "Bret"
#     }
#   }
# }

Fragment support

You can define your fragments and use them with the macros.

Define fragments

# With sigil
fragment = ~GQL"""
fragment UserFragment on User { id name }
"""f

# With macro
fragment = gql [type: :fragment], """
fragment UserFragment on User { id name }
"""f

# From file
fragment = gql_from_file "fragment.graphql", type: :fragment

Use fragments

# With sigils you have to use the global module registration, or manually set them and validate on runtime:

defmodule UserQuery do
  use GraphqlQuery, fragments: [MyFragments.user_fragment()], schema: UserSchema

  # Use the fragments registered for the module.
  def query do
    ~GQL"""
    query GetUser($id: ID!) {
      user(id: $id) {
        ...UserFragment
      }
    }
    """
  end

  # Evaluate at runtime, and add the fragments later instead of using the global ones
  def runtime_query do
    query = ~GQL"""
    query GetUser($id: ID!) {
      user(id: $id) {
        ...UserFragment
      }
    }
    """r

    GraphqlQuery.Document.add_fragment(query, MyFragments.user_fragment())
  end
end


# With the gql and gql_from_file macros, you can use the module fragments, or per-query fragments:

gql [fragments: [MyFragments.user_fragment()]], """
    query GetUser($id: ID!) {
      user(id: $id) {
        ...UserFragment
      }
    }
"""

gql_from_file "query.graphql", fragments: [MyFragments.user_fragment()]

Schema Support

Parsing and Validating Schemas

With macros:

schema = gql [type: :schema], """
type User { id: ID! name: String! }
type Query { user(id: ID!): User }
"""

schema = gql_from_file "path/to/schema.graphql", type: :schema

Or with sigil:

~GQL"""
type User { id: ID! name: String! }
type Query { user(id: ID!): User }
"""s

Schema Modules

• Parses and validates schema at compile time
• Provides schema/0 and schema_path/0
• Recompiles when schema file changes

Automatically implement the behaviour with a schema file:

defmodule MyApp.Schema do
  use GraphqlQuery.Schema, schema_path: "priv/graphql/schema.graphql"
end

Or manually implement the behaviour:

defmodule MyApp.Schema do
  use GraphqlQuery.Schema

  @impl GraphqlQuery.Schema
  def schema do
    ~GQL"""
    type User { id: ID! name: String! }
    type Query { user(id: ID!): User }
    """s
  end

  @impl GraphqlQuery.Schema
  def schema_path, do: nil
end

Document Validation Against Schema

You can validate against the schema any document (queries, mutations or fragments)

Per-document validation:

gql [schema: MyApp.Schema], """
query GetUser($id: ID!) {
  user(id: $id) { name email }
}
"""

gql_from_file "path.graphql", [schema: MyApp.Schema]

Module-level schema:

defmodule MyApp.Queries do
  use GraphqlQuery, schema: MyApp.Schema

  def get_users do
    ~GQL"""
    query { users { id name } }
    """
  end

  def get_user(user_id) do
    # It is recommended to use GraphQL variables, this is just an example to showcase runtime validation with schema
    gql [runtime: true], """
    query GetUserById { user(id: "#{user_id}") { name } }
    """
  end
end

Formatter Integration

Add to .formatter.exs:

[
  inputs: ["{lib,test,priv}/**/*.{ex,exs,graphql,gql}"],
  plugins: [GraphqlQuery.Formatter],
  import_deps: [:graphql_query]
]

Now mix format will:

• Format .graphql and .gql files
• Format ~GQL sigils in Elixir code

Manual API

You shouldn't need to use the manual API, but if you need to, you can do everything yourself.

Check the documentation of these modules if you want to know more about the manual API:

• GraphqlQuery.Document
• GraphqlQuery.Fragment
• GraphqlQuery.Validator
• GraphqlQuery.Format

Roadmap

Planned

• [ ] When validation error, try to detect if it's in a fragment, and if it's an "imported" fragment, print the error in the fragment's location
• [ ] Configure schemas with remote URLs to fetch, and have a mix task to check if the content differs
• [ ] Optional compile-time validation via Mix task
• [ ] Do we need gql? It might lead to bad habits
• [ ] If we want gql, fix line reporting on expanded queries

Done

• [x] Validate queries with sigil
• [x] Format queries with formatter plugin
• [x] gql macro for dynamic queries
• [x] gql_from_file macro for file-based queries
• [x] Schema parsing and validation
• [x] Custom Document and Fragment representation, with implementation for to_string and json with JSON and Jason
• [x] Allow to set fragments in individual queries or per-module (document_with_options macro)
• [x] Extract document info, and calculate if possible name and signature
• [x] Improve non-compile time options detection and fallback to runtime/ignore

License

Beerware 🍺 — do whatever you want with it, but if we meet, buy me a beer. (This is essentially MIT-like. Use it freely, but if we meet, buy me a beer)

Links

• GitHub
• Hex.pm
• Docs