Class: GraphQL::Field

Inherits:
Object
  • Object
show all
Includes:
Define::InstanceDefinable
Defined in:
lib/graphql/field.rb,
lib/graphql/field/resolve.rb

Overview

Fields belong to ObjectTypes and InterfaceTypes.

They're usually created with the field helper. If you create it by hand, make sure #name is a String.

A field must have a return type, but if you want to defer the return type calculation until later, you can pass a proc for the return type. That proc will be called when the schema is defined.

For complex field definition, you can pass a block to the field helper, eg field :name do ... end. This block is equivalent to calling GraphQL::Field.define { ... }.

Resolve

Fields have resolve functions to determine their values at query-time. The default implementation is to call a method on the object based on the field name.

You can specify a custom proc with the resolve helper.

There are some shortcuts for common resolve implementations:

  • Provide property: to call a method with a different name than the field name
  • Provide hash_key: to resolve the field by doing a key lookup, eg obj[:my_hash_key]

Arguments

Fields can take inputs; they're called arguments. You can define them with the argument helper.

They can have default values which will be provided to resolve if the query doesn't include a value.

Only certain types maybe used for inputs:

  • Scalars
  • Enums
  • Input Objects
  • Lists of those types

Input types may also be non-null -- in that case, the query will fail if the input is not present.

Complexity

Fields can have complexity values which describe the computation cost of resolving the field. You can provide the complexity as a constant with complexity: or as a proc, with the complexity helper.

Examples:

Lazy type resolution

# If the field's type isn't defined yet, you can pass a proc
field :city, -> { TypeForModelName.find("City") }

Defining a field with a block

field :city, CityType do
  # field definition continues inside the block
end

Create a field which calls a method with the same name.

GraphQL::ObjectType.define do
  field :name, types.String, "The name of this thing "
end

Create a field that calls a different method on the object

GraphQL::ObjectType.define do
  # use the `property` keyword:
  field :firstName, types.String, property: :first_name
end

Create a field looks up with [hash_key]

GraphQL::ObjectType.define do
  # use the `hash_key` keyword:
  field :firstName, types.String, hash_key: :first_name
end

Create a field with an argument

field :students, types[StudentType] do
  argument :grade, types.Int
  resolve ->(obj, args, ctx) {
    Student.where(grade: args[:grade])
  }
end

Argument with a default value

field :events, types[EventType] do
  # by default, don't include past events
  argument :includePast, types.Boolean, default_value: false
  resolve ->(obj, args, ctx) {
    args[:includePast] # => false if no value was provided in the query
    # ...
  }
end

Custom complexity values

# Complexity can be a number or a proc.

# Complexity can be defined with a keyword:
field :expensive_calculation, !types.Int, complexity: 10

# Or inside the block:
field :expensive_calculation_2, !types.Int do
  complexity ->(ctx, args, child_complexity) { ctx[:current_user].staff? ? 0 : 10 }
end

Calculating the complexity of a list field

field :items, types[ItemType] do
  argument :limit, !types.Int
  # Mulitply the child complexity by the possible items on the list
  complexity ->(ctx, args, child_complexity) { child_complexity * args[:limit] }
end

Creating a field, then assigning it to a type

name_field = GraphQL::Field.define do
  name("Name")
  type(!types.String)
  description("The name of this thing")
  resolve ->(object, arguments, context) { object.name }
end

NamedType = GraphQL::ObjectType.define do
  # The second argument may be a GraphQL::Field
  field :name, name_field
end

Defined Under Namespace

Modules: DefaultLazyResolve, Resolve

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Define::InstanceDefinable

#define, #metadata, #redefine

Constructor Details

#initialize ⇒ Field 



200
201
202
203
204
205
206
207
208
 
# File 'lib/graphql/field.rb', line 200

def initialize
  @complexity = 1
  @arguments = {}
  @resolve_proc = build_default_resolver
  @lazy_resolve_proc = DefaultLazyResolve
  @relay_node_field = false
  @connection = false
  @connection_max_page_size = nil
end

Instance Attribute Details

#arguments ⇒ Hash<String => GraphQL::Argument> 



164
165
166
 
# File 'lib/graphql/field.rb', line 164

def arguments
  @arguments
end

#complexity ⇒ Numeric, Proc 



170
171
172
 
# File 'lib/graphql/field.rb', line 170

def complexity
  @complexity
end

#connection=(value) ⇒ Object (writeonly)

Sets the attribute connection



181
182
183
 
# File 'lib/graphql/field.rb', line 181

def connection=(value)
  @connection = value
end

#connection_max_page_size ⇒ nil, Integer 



198
199
200
 
# File 'lib/graphql/field.rb', line 198

def connection_max_page_size
  @connection_max_page_size
end

#deprecation_reason ⇒ String? 



161
162
163
 
# File 'lib/graphql/field.rb', line 161

def deprecation_reason
  @deprecation_reason
end

#description ⇒ String? 



158
159
160
 
# File 'lib/graphql/field.rb', line 158

def description
  @description
end

#edge_class ⇒ nil, Class

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



190
191
192
 
# File 'lib/graphql/field.rb', line 190

def edge_class
  @edge_class
end

#function ⇒ Object, GraphQL::Function 



179
180
181
 
# File 'lib/graphql/field.rb', line 179

def function
  @function
end

#hash_key ⇒ Object? 



176
177
178
 
# File 'lib/graphql/field.rb', line 176

def hash_key
  @hash_key
end

#lazy_resolve_proc ⇒ <#call(obj, args, ctx)> (readonly) 



152
153
154
 
# File 'lib/graphql/field.rb', line 152

def lazy_resolve_proc
  @lazy_resolve_proc
end

#mutation ⇒ GraphQL::Relay::Mutation? 



167
168
169
 
# File 'lib/graphql/field.rb', line 167

def mutation
  @mutation
end

#name ⇒ String 



155
156
157
 
# File 'lib/graphql/field.rb', line 155

def name
  @name
end

#property ⇒ Symbol? 



173
174
175
 
# File 'lib/graphql/field.rb', line 173

def property
  @property
end

#relay_node_field ⇒ Boolean 



143
144
145
 
# File 'lib/graphql/field.rb', line 143

def relay_node_field
  @relay_node_field
end

#relay_nodes_field ⇒ Boolean 



146
147
148
 
# File 'lib/graphql/field.rb', line 146

def relay_nodes_field
  @relay_nodes_field
end

#resolve_proc ⇒ <#call(obj, args, ctx)> (readonly) 



149
150
151
 
# File 'lib/graphql/field.rb', line 149

def resolve_proc
  @resolve_proc
end

Instance Method Details

#connection? ⇒ Boolean 



184
185
186
 
# File 'lib/graphql/field.rb', line 184

def connection?
  @connection
end

#edges? ⇒ Boolean 



193
194
195
 
# File 'lib/graphql/field.rb', line 193

def edges?
  !!@edge_class
end

#initialize_copy(other) ⇒ Object 



210
211
212
213
 
# File 'lib/graphql/field.rb', line 210

def initialize_copy(other)
  super
  @arguments = other.arguments.dup
end

#lazy_resolve(obj, args, ctx) ⇒ Object

If #resolve returned and object which should be handled lazily, this method will be called later force the object to return its value.



276
277
278
 
# File 'lib/graphql/field.rb', line 276

def lazy_resolve(obj, args, ctx)
  @lazy_resolve_proc.call(obj, args, ctx)
end

#lazy_resolve=(new_lazy_resolve_proc) ⇒ Object

Assign a new resolve proc to this field. Used for #lazy_resolve



281
282
283
 
# File 'lib/graphql/field.rb', line 281

def lazy_resolve=(new_lazy_resolve_proc)
  @lazy_resolve_proc = new_lazy_resolve_proc
end

#prepare_lazy(obj, args, ctx) ⇒ GraphQL::Execution::Lazy

Prepare a lazy value for this field. It may be then-ed and resolved later.



287
288
289
290
291
 
# File 'lib/graphql/field.rb', line 287

def prepare_lazy(obj, args, ctx)
  GraphQL::Execution::Lazy.new {
    lazy_resolve(obj, args, ctx)
  }
end

#resolve(object, arguments, context) ⇒ Object

Get a value for this field

Examples:

resolving a field value

field.resolve(obj, args, ctx)


222
223
224
 
# File 'lib/graphql/field.rb', line 222

def resolve(object, arguments, context)
  resolve_proc.call(object, arguments, context)
end

#resolve=(new_resolve_proc) ⇒ Object

Provide a new callable for this field's resolve function. If nil, a new resolve proc will be build based on its #name, #property or #hash_key.



229
230
231
 
# File 'lib/graphql/field.rb', line 229

def resolve=(new_resolve_proc)
  @resolve_proc = new_resolve_proc || build_default_resolver
end

#to_s ⇒ Object 



266
267
268
 
# File 'lib/graphql/field.rb', line 266

def to_s
  "<Field name:#{name || "not-named"} desc:#{description} resolve:#{resolve_proc}>"
end

#type ⇒ Object

Get the return type for this field.



239
240
241
 
# File 'lib/graphql/field.rb', line 239

def type
  @clean_type ||= GraphQL::BaseType.resolve_related_type(@dirty_type)
end

#type=(new_return_type) ⇒ Object 



233
234
235
236
 
# File 'lib/graphql/field.rb', line 233

def type=(new_return_type)
  @clean_type = nil
  @dirty_type = new_return_type
end