▄██████▄ ▄████████ ▄████████ ▄███████▄ ▄█ █▄ ████████▄ ▄█ ███ ███ ███ ███ ███ ███ ███ ███ ███ ███ ███ ███ ███ ███ █▀ ███ ███ ███ ███ ███ ███ ███ ███ ███ ███ ███ ▄███ ▄███▄▄▄▄██▀ ███ ███ ███ ███ ▄███▄▄▄▄███▄▄ ███ ███ ███ ▀▀███ ████▄ ▀▀███▀▀▀▀▀ ▀███████████ ▀█████████▀ ▀▀███▀▀▀▀███▀ ███ ███ ███ ███ ███ ▀███████████ ███ ███ ███ ███ ███ ███ ███ ███ ███ ███ ███ ███ ███ ███ ███ ███ ███ ███ ▀ ███ ███▌ ▄ ████████▀ ███ ███ ███ █▀ ▄████▀ ███ █▀ ▀██████▀▄█ █████▄▄██ ███ ███ ▀

A GraphQL server implementation for Ruby

Queries — Executing Queries

You can execute queries with your GraphQL::Schema at get a Ruby Hash as a result. For example, to execute a query from a string:

query_string = "{ ... }"
MySchema.execute(query_string)
# {
#   "data" => { ... }
# }

There are also several options you can use:

  • variables: provides values for $-named query variables
  • context: accepts application-specific data to pass to resolve functions
  • root_value: will be provided to root-level resolve functions as obj
  • operation_name: picks a named operation from the incoming string to execute
  • document: accepts an already-parsed query (instead of a string), see GraphQL.parse
  • validate: may be false to skip static validation for this query
  • max_depth: and max_complexity: may override schema-level values

Some of these options are described in more detail below, see GraphQL::Query#initialize for more information.

Variables

GraphQL provides query variables as a way to parameterize query strings. If your query string contains variables, you can provide values in a hash of { String => value } pairs. The keys should not contain "$".

For example, to provide variables to a query:

query_string = "
  query getPost($postId: ID!) {
    post(id: $postId) {
      title
    }
  }"

variables = { "postId" => "1" }

MySchema.execute(query_string, variables: variables)

If the variable is a GraphQL::InputObjectType, you can provide a nested hash, for example:

query_string = "
mutation createPost($postParams: PostInput!, $createdById: ID!){
  createPost(params: $postParams, createdById: $createdById) {
    id
    title
    createdBy { name }
  }
}
"

variables = {
  "postParams" => {
    "title" => "...",
    "body" => "..."
  },
  "createdById" => "5",
}

MySchema.execute(query_string, variables: variables)

Context

You can provide application-specific values to GraphQL as context:. This is available in many places:

  • resolve functions
  • Schema#resolve_type hook
  • ID generation & fetching

Common uses for context: include the current user or auth token. To provide a context: value, pass a hash to Schema#execute:

context = {
  current_user: session[:current_user],
  current_organization: session[:current_organization],
}

MySchema.execute(query_string, context: context)

Then, you can access those values during execution:

resolve ->(obj, args,  ctx) {
  ctx[:current_user] # => #<User id=123 ... >
  # ...
}

Note that ctx is not the hash that you passed it. It’s an instance of GraphQL::Query::Context, but it delegates #[](key) to the hash you provide.

Root Value

You can provide a root obj value with root_value:. For example, to base the query off of the current organization:

current_org = session[:current_organization]
MySchema.execute(query_string, root_value: current_org)

That value will be provided to root-level fields, such as mutation fields. For example:

MutationType = GraphQL::ObjectType.define do
  name "Mutation"
  field :createPost, types.Post do
    resolve ->(obj, args, ctx) {
      obj # => #<Organization id=456 ...>
      # ...
    }
  end
end

GraphQL::Relay::Mutation fields will also receive root_value: as obj (assuming they’re attached directly to your MutationType).