Class: ElasticGraph::SchemaDefinition::API

Inherits:
Object
  • Object
show all
Defined in:
elasticgraph-schema_definition/lib/elastic_graph/schema_definition/api.rb

Overview

Root API object that provides the schema definition API.

Examples:

ElasticGraph.define_schema do |schema|
  # The `schema` object is an instance of `API`
end

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#factory ⇒ Factory (readonly)

Returns object responsible for instantiating all schema element classes.

Returns:

  • (Factory) —

    object responsible for instantiating all schema element classes



52
53
54
 
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/api.rb', line 52

def factory
  @factory
end

#state ⇒ State (readonly)

Returns object which holds all state for the schema definition.

Returns:

  • (State) —

    object which holds all state for the schema definition



49
50
51
 
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/api.rb', line 49

def state
  @state
end

Instance Method Details

#deleted_type(name) ⇒ void

Note:

In situations where this API applies, ElasticGraph will give you an error message indicating that you need to use this API or SchemaElements::TypeWithSubfields#renamed_from. Likewise, when ElasticGraph no longer needs to know about this, it’ll give you a warning indicating the call to this method can be removed.

This method returns an undefined value.

Registers the name of a type that existed in a prior version of the schema but has been deleted.

Examples:

Indicate that Widget has been deleted

ElasticGraph.define_schema do |schema|
  schema.deleted_type "Widget"
end

Parameters:

  • name (String) —

    name of type that used to exist but has been deleted



262
263
264
265
266
267
268
269
 
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/api.rb', line 262

def deleted_type(name)
  @state.register_deleted_type(
    name,
    defined_at: caller_locations(1, 1).to_a.first, # : ::Thread::Backtrace::Location
    defined_via: %(schema.deleted_type "#{name}")
  )
  nil
end

#enum_type(name) {|SchemaElements::EnumType| ... } ⇒ void

This method returns an undefined value.

Defines a GraphQL enum type. The type is restricted to an enumerated set of values, each with a unique name. Use value or values to define the enum values in the passed block.

Note: if required by your configuration, this may generate a pair of Enum types (an input enum and an output enum).

Examples:

Define an enum type

ElasticGraph.define_schema do |schema|
  schema.enum_type "Currency" do |t|
    t.value "USD" do |v|
      v.documentation "US Dollars."
    end

    t.value "JPY" do |v|
      v.documentation "Japanese Yen."
    end

    # You can define multiple values in one call if you don't care about their docs or directives.
    t.values "GBP", "AUD"
  end
end

Parameters:

  • name (String) —

    name of the enum type

Yields:



194
195
196
197
 
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/api.rb', line 194

def enum_type(name, &block)
  @state.register_enum_type @factory.new_enum_type(name.to_s, &block)
  nil
end

#interface_type(name) {|SchemaElements::InterfaceType| ... } ⇒ void

This method returns an undefined value.

Defines a GraphQL interface. Use it to define an abstract supertype with one or more fields that concrete implementations of the interface must also define. Each implementation can be an SchemaElements::ObjectType or SchemaElements::InterfaceType.

Examples:

Define an interface and implement it

ElasticGraph.define_schema do |schema|
  schema.interface_type "Athlete" do |t|
    t.field "name", "String"
    t.field "team", "String"
  end

  schema.object_type "BaseballPlayer" do |t|
    t.implements "Athlete"
    t.field "name", "String"
    t.field "team", "String"
    t.field "battingAvg", "Float"
  end

  schema.object_type "BasketballPlayer" do |t|
    t.implements "Athlete"
    t.field "name", "String"
    t.field "team", "String"
    t.field "pointsPerGame", "Float"
  end
end

Parameters:

  • name (String) —

    name of the interface

Yields:



163
164
165
166
 
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/api.rb', line 163

def interface_type(name, &block)
  @state.register_object_interface_or_union_type @factory.new_interface_type(name.to_s, &block)
  nil
end

#json_schema_version(version) ⇒ void

Note:

While this is an important part of how ElasticGraph is designed to support schema evolution, it can be annoying constantly have to increment this while rapidly changing the schema during prototyping. You can disable the requirement to increment this on every JSON schema change by setting enforce_json_schema_version to false in your Rakefile.

This method returns an undefined value.

Defines the version number of the current JSON schema. Importantly, every time a change is made that impacts the JSON schema artifact, the version number must be incremented to ensure that each different version of the JSON schema is identified by a unique version number. The publisher will then include this version number in published events to identify the version of the schema it was using. This avoids the need to deploy the publisher and ElasticGraph indexer at the same time to keep them in sync.

Examples:

Set the JSON schema version to 1

ElasticGraph.define_schema do |schema|
  schema.json_schema_version 1
end

Parameters:

  • version (Integer) —

    current version number of the JSON schema artifact

See Also:



402
403
404
405
406
407
408
409
410
411
412
413
414
 
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/api.rb', line 402

def json_schema_version(version)
  if !version.is_a?(Integer) || version < 1
    raise Errors::SchemaError, "`json_schema_version` must be a positive integer. Specified version: #{version}"
  end

  if @state.json_schema_version
    raise Errors::SchemaError, "`json_schema_version` can only be set once on a schema. Previously-set version: #{@state.json_schema_version}"
  end

  @state.json_schema_version = version
  @state.json_schema_version_setter_location = caller_locations(1, 1).to_a.first
  nil
end

#object_type(name) {|SchemaElements::ObjectType| ... } ⇒ void

This method returns an undefined value.

Defines a GraphQL object type Use it to define a concrete type that has subfields. Object types can either be indexed (e.g. directly indexed in the datastore, and available to query from the root Query object) or embedded in other indexed types.

Examples:

Define embedded and indexed object types

ElasticGraph.define_schema do |schema|
  # `Money` is an embedded object type
  schema.object_type "Money" do |t|
    t.field "currency", "String"
    t.field "amount", "JsonSafeLong"
  end

  # `Transaction` is an indexed object type
  schema.object_type "Transaction" do |t|
    t.root_query_fields plural: "transactions"
    t.field "id", "ID"
    t.field "cost", "Money"
    t.index "transactions"
  end
end

Parameters:

  • name (String) —

    name of the object type

Yields:



129
130
131
132
 
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/api.rb', line 129

def object_type(name, &block)
  @state.register_object_interface_or_union_type @factory.new_object_type(name.to_s, &block)
  nil
end

#on_built_in_types {|SchemaElements::EnumType, SchemaElements::InputType, SchemaElements::InterfaceType, SchemaElements::ObjectType, SchemaElements::ScalarType, SchemaElements::UnionType| ... } ⇒ void

This method returns an undefined value.

Registers a customization callback that will be applied to every built-in type automatically provided by ElasticGraph. Provides an opportunity to customize the built-in types (e.g. to add directives to them or whatever).

Examples:

Customize documentation of built-in types

ElasticGraph.define_schema do |schema|
  schema.on_built_in_types do |type|
    type.append_to_documentation "This is a built-in ElasticGraph type."
  end
end

Yields:



428
429
430
431
 
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/api.rb', line 428

def on_built_in_types(&customization_block)
  @state.built_in_types_customization_blocks << customization_block
  nil
end

#on_root_query_type {|SchemaElements::ObjectType| ... } ⇒ void

This method returns an undefined value.

Registers a customization callback that will be applied to the root Query type when it is generated.

Examples:

Customize documentation of built-in types

ElasticGraph.define_schema do |schema|
  schema.on_root_query_type do |type|
    type.append_to_documentation "This schema has been generated by ElasticGraph."
  end
end

Yields:



444
445
446
447
448
449
 
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/api.rb', line 444

def on_root_query_type(&customization_block)
  on_built_in_types do |type|
    customization_block.call(_ = type) if type.name == "Query"
  end
  nil
end

#raw_sdl(string) ⇒ void

This method returns an undefined value.

Defines a raw GraphQL SDL snippet that will be included in the generated schema.graphql artifact. Designed to be an escape hatch, for when ElasticGraph doesn’t provide another way to write some type of GraphQL SDL element that you need. Currently, the only known use case is to define custom GraphQL directives.

Examples:

Define a custom directive and use it

ElasticGraph.define_schema do |schema|
  # Define a directive we can use to annotate what system a data type comes from.
  schema.raw_sdl "directive @sourcedFrom(system: String!) on OBJECT"

  schema.object_type "Transaction" do |t|
    t.directive "sourcedFrom", system: "transaction-processor"
  end
end

Parameters:

  • string (String) —

    Raw snippet of SDL



100
101
102
103
 
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/api.rb', line 100

def raw_sdl(string)
  @state.sdl_parts << string
  nil
end

#register_graphql_extension(extension_module, defined_at:, **extension_config) ⇒ void

This method returns an undefined value.

Registers a GraphQL extension module that will be loaded and used by elasticgraph-graphql. While such extension modules can also be configured in a settings YAML file, it can be useful to register it here when you want to ensure that the extension is used in all environments. For example, an extension library that defines custom schema elements (such as elasticgraph-apollo) may need to ensure its corresponding GraphQL extension module is used since the custom schema elements would not work correctly otherwise.

Examples:

Register elasticgraph-query_registry extension module

require(query_registry_require_path = "elastic_graph/query_registry/graphql_extension")

ElasticGraph.define_schema do |schema|
  schema.register_graphql_extension ElasticGraph::QueryRegistry::GraphQLExtension,
    defined_at: query_registry_require_path
end

Parameters:

  • extension_module (Module) —

    GraphQL extension module

  • defined_at (String) —

    the require path of the extension module

  • extension_config (Hash<Symbol, Object>) —

    configuration options for the extension module



289
290
291
292
 
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/api.rb', line 289

def register_graphql_extension(extension_module, defined_at:, **extension_config)
  @state.graphql_extension_modules << SchemaArtifacts::RuntimeMetadata::Extension.new(extension_module, defined_at, extension_config)
  nil
end

#register_graphql_resolver(name, klass, defined_at:, **resolver_config) ⇒ void

This method returns an undefined value.

Registers a GraphQL resolver that will be loaded and used by elasticgraph-graphql. To use a GraphQL resolver you have registered, set a field’s resolver to the name you provide when registering your resolver.

Examples:

Register a custom resolver for use by a custom Query field

# In `add_resolver.rb`:
class AddResolver
  def initialize(elasticgraph_graphql:, config:)
  end

  def resolve(field:, object:, args:, context:)
    args.fetch("x") + args.fetch("y")
  end
end

# In `config/schema.rb`:
ElasticGraph.define_schema do |schema|
  require(resolver_path = "add_resolver")
  schema.register_graphql_resolver :add, AddResolver, defined_at: resolver_path

  schema.on_root_query_type do |t|
    t.field "add", "Int" do |f|
      f.argument "x", "Int!"
      f.argument "y", "Int!"
      f.resolver = :add
    end
  end
end

Register a custom resolver that uses lookahead


# In `artist_resolver.rb`:
class ArtistResolver
  def initialize(elasticgraph_graphql:, config:)
  end

  def resolve(field:, object:, args:, context:, lookahead:)
    # The extra `lookahead` argument can be used to see what child fields are selected.
    # See https://graphql-ruby.org/queries/lookahead.html for details.
    #
    # Note: there is overhead involved in providing the `lookahead`, so it's best to not
    # request it (by defining it as one of the `resolve` arguments) unless it's really needed.
  end
end

# In `config/schema.rb`:
ElasticGraph.define_schema do |schema|
  require(resolver_path = "artist_resolver")
  schema.register_graphql_resolver :artist, ArtistResolver, defined_at: resolver_path

  schema.object_type "Artist" do |t|
    t.field "name", "String"
    # ...
  end

  schema.on_root_query_type do |t|
    t.field "artist", "Artist" do |f|
      f.resolver = :artist
    end
  end
end

Parameters:

  • name (Symbol) —

    unique name of the resolver

  • klass (Class) —

    resolver class

  • defined_at (String) —

    the require path of the resolver

  • resolver_config (Hash<Symbol, Object>) —

    configuration options for the resolver, to support parameterized resolvers



360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
 
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/api.rb', line 360

def register_graphql_resolver(name, klass, defined_at:, **resolver_config)
  extension = SchemaArtifacts::RuntimeMetadata::Extension.new(klass, defined_at, resolver_config)

  needs_lookahead =
    if extension.verify_against(SchemaArtifacts::RuntimeMetadata::GraphQLResolver::InterfaceWithLookahead).empty?
      true
    else
      extension.verify_against!(SchemaArtifacts::RuntimeMetadata::GraphQLResolver::InterfaceWithoutLookahead)
      false
    end

  resolver = SchemaArtifacts::RuntimeMetadata::GraphQLResolver.new(
    needs_lookahead: needs_lookahead,
    resolver_ref: extension.to_dumpable_hash
  )

  @state.graphql_resolvers_by_name[name] = resolver
  nil
end

#results ⇒ Object

Returns the results of the schema definition.

Returns:

  • the results of the schema definition



381
382
383
 
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/api.rb', line 381

def results
  @results ||= Results.new(@state)
end

#scalar_type(name) {|SchemaElements::ScalarType| ... } ⇒ void

This method returns an undefined value.

Defines a GraphQL scalar type. ElasticGraph itself uses this to define a few common scalar types (e.g. Date and DateTime), but it is also available to you to use to define your own custom scalar types.

Examples:

Define a scalar type

ElasticGraph.define_schema do |schema|
  schema.scalar_type "URL" do |t|
    t.mapping type: "keyword"
    t.json_schema type: "string", format: "uri"
  end
end

Parameters:

  • name (String) —

    name of the scalar type

Yields:



244
245
246
247
 
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/api.rb', line 244

def scalar_type(name, &block)
  @state.register_scalar_type @factory.new_scalar_type(name.to_s, &block)
  nil
end

#union_type(name) {|SchemaElements::UnionType| ... } ⇒ void

This method returns an undefined value.

Defines a GraphQL union type. Use it to define an abstract supertype with one or more concrete subtypes. Each subtype must be an SchemaElements::ObjectType, but they do not have to share any fields in common.

Examples:

Define a union type

ElasticGraph.define_schema do |schema|
  schema.object_type "Card" do |t|
    # ...
  end

  schema.object_type "BankAccount" do |t|
    # ...
  end

  schema.object_type "BitcoinWallet" do |t|
    # ...
  end

  schema.union_type "FundingSource" do |t|
    t.subtype "Card"
    t.subtypes "BankAccount", "BitcoinWallet"
  end
end

Parameters:

  • name (String) —

    name of the union type

Yields:



225
226
227
228
 
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/api.rb', line 225

def union_type(name, &block)
  @state.register_object_interface_or_union_type @factory.new_union_type(name.to_s, &block)
  nil
end