Skip to main content

​
Overview

Rails GraphQL extends Ruby’s GlobalID with GraphQL-specific functionality for caching, object location, and schema-aware operations. It uses a custom URI::GQL scheme for GraphQL object identification.

​
GlobalID Class

Inherits from ::GlobalID with GraphQL-specific enhancements.

​
Class Methods

​
create

Rails::GraphQL::GlobalID.create(user)
# => #<Rails::GraphQL::GlobalID:0x00...>

Rails::GraphQL::GlobalID.create(user_type, scope: :admin)
# => #<Rails::GraphQL::GlobalID:0x00...>
​
object
Object
required
The object to create a Global ID for. Must include Helpers::WithGlobalID.
​
options
Hash
Additional options for the Global ID.
​
scope
Symbol
Override the scope. By default, inferred from the object’s schema type if the object’s base class includes Helpers::WithSchemaFields.
Create a new GraphQL Global identifier. Returns a Rails::GraphQL::GlobalID instance.

​
scope_of

Rails::GraphQL::GlobalID.scope_of(user_type)
# => :public_schema
​
object
Object
required
The object to find the scope for.
Find the scope on which the object is applied to. Returns the schema type if the object’s base class includes Helpers::WithSchemaFields.

​
Instance Methods

​
initialize

gid = Rails::GraphQL::GlobalID.new(uri_gql_instance)
gid = Rails::GraphQL::GlobalID.new('gql://...')
​
gid
URI::GQL | String
required
A URI::GQL instance or a string that can be parsed into one.
​
options
Hash
default:"{}"
Additional options (reserved for future use).
Initialize a new GlobalID instance.

​
Delegated Methods

The following methods are delegated to the underlying URI::GQL:
​
namespace
Symbol
The namespace of the object (e.g., :base, :v2).
​
class_name
String
The class name of the object (e.g., 'User', 'StringScalar').
​
scope
Symbol
The schema scope (e.g., :admin_schema, :public_schema).
​
name
String
The GraphQL name of the object.
​
instantiate?
Boolean
Whether the object should be instantiated when found.
gid = Rails::GraphQL::GlobalID.create(user_type)

gid.namespace   # => :base
gid.class_name  # => "User"
gid.scope       # => :public_schema
gid.name        # => "User"

​
find

gid = Rails::GraphQL::GlobalID.create(user_type)
user_type = gid.find
# => UserType

gid.find(some_option: true)
​
options
Hash
default:"{}"
Options passed to the base class’s find_by_gid method.
Find the object using the GlobalID. Calls find_by_gid on the base class if it responds to that method.

​
base_class

gid = Rails::GraphQL::GlobalID.create(user_type)
gid.base_class
# => Rails::GraphQL::Type
Get the base class of the object referenced by this GlobalID:
  • If class_name is 'Schema', 'Directive', or 'Type', returns the corresponding Rails::GraphQL constant
  • Otherwise, fetches from the type map using the class name and namespace

​
==

gid1 = Rails::GraphQL::GlobalID.create(user_type)
gid2 = Rails::GraphQL::GlobalID.create(user_type)

gid1 == gid2  # => true
gid1.eql?(gid2)  # => true
​
other
Rails::GraphQL::GlobalID
required
Another GlobalID to compare.
Compare two GlobalIDs for equality. Two GlobalIDs are equal if their URIs are equal.

​
Serializer

The GlobalID::Serializer adds support for ActiveJob serialization, allowing GraphQL objects to be passed to jobs and deserialized for subscriptions.

​
Class Methods

​
serialize?

Rails::GraphQL::GlobalID::Serializer.serialize?(user_type)
# => true

Rails::GraphQL::GlobalID::Serializer.serialize?("string")
# => false
​
argument
Object
required
The argument to check.
Determines if an argument should be serialized by this serializer. Returns true if the argument is an instance or class that includes Helpers::WithGlobalID.

​
serialize

Rails::GraphQL::GlobalID::Serializer.serialize(user_type)
# => { "_gql_globalid" => "gql://..." }
​
argument
Object
required
The argument to serialize. Must include Helpers::WithGlobalID.
Serializes an argument to a JSON primitive type. Returns a hash with the key "_gql_globalid" containing the Global ID string.

​
deserialize

Rails::GraphQL::GlobalID::Serializer.deserialize({ "_gql_globalid" => "gql://..." })
# => UserType
​
argument
Hash
required
The serialized argument with a "_gql_globalid" key.
Deserializes an argument from a JSON primitive type. Calls GlobalID.find to locate and return the object.

​
Usage Examples

​
Creating and Finding Objects

# Create a GlobalID for a GraphQL type
user_type = UserType
gid = Rails::GraphQL::GlobalID.create(user_type)

# Convert to string
gid.to_s
# => "gql://base/Type/User"

# Find the object later
found_type = gid.find
# => UserType

# Or parse and find from string
gid = Rails::GraphQL::GlobalID.new('gql://base/Type/User')
found_type = gid.find

​
With Scopes and Namespaces

# Create with explicit scope
gid = Rails::GraphQL::GlobalID.create(admin_user_type, scope: :admin)

# Access metadata
gid.namespace   # => :v2
gid.class_name  # => "AdminUser"
gid.scope       # => :admin

​
ActiveJob Integration

# In a job
class ProcessUserTypeJob < ApplicationJob
  def perform(user_type)
    # user_type is automatically serialized/deserialized
    puts user_type.gql_name
  end
end

# Enqueue with a GraphQL type
ProcessUserTypeJob.perform_later(UserType)

# The serializer handles conversion:
# UserType -> { "_gql_globalid" => "gql://..." } -> UserType

​
Comparing GlobalIDs

gid1 = Rails::GraphQL::GlobalID.create(UserType)
gid2 = Rails::GraphQL::GlobalID.create(UserType)
gid3 = Rails::GraphQL::GlobalID.create(PostType)

gid1 == gid2  # => true
gid1 == gid3  # => false

Build docs developers (and LLMs) love

Get started for freeTalk to us