or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

dataloader-performance.mdindex.mdquery-execution.mdschema-definition.mdtype-system.md
tile.json

tessl/gem-graphql

A Ruby implementation of GraphQL for building GraphQL schemas and executing queries.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes

pkg:gem/graphql@2.5.x

To install, run

npx @tessl/cli install tessl/gem-graphql@2.5.0

index.mddocs/

GraphQL Ruby

A Ruby implementation of GraphQL, providing a complete framework for building GraphQL schemas and executing queries. GraphQL Ruby offers idiomatic Ruby APIs for schema definition, query execution, and advanced features like subscriptions, authorization, and performance optimization.

Package Information

  • Package Name: graphql
  • Package Type: gem
  • Language: Ruby
  • Installation: gem install graphql or add gem 'graphql' to Gemfile

Core Imports

require 'graphql'

Common imports for schema building:

require 'graphql'

class MySchema < GraphQL::Schema
  # Schema definition
end

Basic Usage

Simple Schema Definition

require 'graphql'

# Define an object type
class UserType < GraphQL::Schema::Object
  description "A user in the system"
  
  field :id, ID, null: false
  field :name, String, null: true
  field :email, String, null: false
end

# Define the query root
class QueryType < GraphQL::Schema::Object
  field :user, UserType, null: true do
    argument :id, ID, required: true
  end
  
  def user(id:)
    # Resolver logic - fetch user by ID
    { id: id, name: "Alice", email: "alice@example.com" }
  end
end

# Create the schema
class MySchema < GraphQL::Schema
  query QueryType
end

# Execute a query
result = MySchema.execute('
  query {
    user(id: "1") {
      id
      name
      email
    }
  }
')

puts result.to_json

Rails Integration

# Generate GraphQL setup
rails generate graphql:install

# This creates:
# - app/graphql/ directory structure
# - GraphqlController for handling requests  
# - Base classes and schema file

Architecture

GraphQL Ruby follows a class-based schema definition approach built around several key components:

Schema Definition Layer

  • Schema Class - Root schema definition inheriting from GraphQL::Schema
  • Object Types - Data structures inheriting from GraphQL::Schema::Object
  • Field Definitions - Individual field specifications with types and resolvers
  • Type System - Built-in scalars, enums, interfaces, unions, and input objects

Execution Engine

  • Query Parser - Converts GraphQL strings into Abstract Syntax Trees
  • Interpreter - Executes queries against the schema with lazy evaluation
  • Context System - Passes request-scoped data through the execution pipeline
  • DataLoader - Batches database queries to prevent N+1 problems

Advanced Features

  • Subscriptions - Real-time updates via WebSockets or Server-Sent Events
  • Authorization - Field and object-level access control
  • Analysis & Validation - Query complexity and depth limits
  • Tracing Integration - Performance monitoring with APM tools

This architecture enables GraphQL Ruby to serve as both a simple query layer for small applications and a robust API framework for large-scale production systems, with seamless Rails integration and extensive customization options.

Capabilities

Schema Definition

Core classes and methods for defining GraphQL schemas, including object types, fields, arguments, and type relationships.

# Base schema class
class GraphQL::Schema
  def self.query(query_type)
  def self.mutation(mutation_type)  
  def self.subscription(subscription_type)
  def self.execute(query_string, variables: {}, context: {}, operation_name: nil)
end

# Object type definition
class GraphQL::Schema::Object
  def self.field(name, type, null:, description: nil, &block)
  def self.description(text)
end

# Field definition  
class GraphQL::Schema::Field
  def initialize(name, type, null:)
  def argument(name, type, required: false, default_value: nil)
end

Schema Definition

Query Execution

Query parsing, execution engine, and context management for running GraphQL operations.

# Query execution
class GraphQL::Query
  def initialize(schema, query_string, variables: {}, context: {})
  def result
  def static_errors
  def valid?
end

# Main execution interface
def GraphQL.parse(graphql_string, trace: GraphQL::Tracing::NullTrace)
def GraphQL.parse_file(filename)

Query Execution

Type System

Built-in scalar types, custom scalars, enums, interfaces, unions, and input objects.

# Built-in scalar types
GraphQL::Types::String
GraphQL::Types::Int  
GraphQL::Types::Float
GraphQL::Types::Boolean
GraphQL::Types::ID
GraphQL::Types::BigInt
GraphQL::Types::JSON
GraphQL::Types::ISO8601Date
GraphQL::Types::ISO8601DateTime

# Custom scalar definition
class GraphQL::Schema::Scalar
  def self.coerce_input(input_value, context)
  def self.coerce_result(ruby_value, context)
end

# Enum definition
class GraphQL::Schema::Enum
  def self.value(name, description = nil, value: name)
end

Type System

DataLoader & Performance

Batch loading system for preventing N+1 queries and optimizing database access patterns.

# DataLoader source
class GraphQL::Dataloader::Source  
  def fetch(keys)
  def load(key)
  def load_many(keys)
end

# Schema integration
class GraphQL::Schema
  def self.use(plugin, **options)
end

# Usage in resolvers
def dataloader
def dataloader.with(source_class, *args)

DataLoader & Performance

Key Types

# Schema execution result
class GraphQL::Query::Result
  def to_h
  def to_json
  def [] (key)
  def dig(*keys)
end

# Context object for request-scoped data
class GraphQL::Query::Context
  def [] (key)
  def []= (key, value)
  def fetch(key, default = nil)
  def merge(hash)
end

# Field argument definition
class GraphQL::Schema::Argument
  def initialize(name, type, description: nil, required: false, default_value: nil)
  def type
  def required?
  def default_value
end

# Execution errors
class GraphQL::ExecutionError < GraphQL::Error
  def initialize(message, ast_node: nil, options: {})
  def path
  def extensions
end