Field extensions for composable query builders

[mroach]

Our root query has many fields, nearly all backed by Rails models. Many models implement common functionality by way of traits or what Rails calls "concerns".

For example, models may implement the Publishable trait and have a status of "draft" or "published".

Currently our fields and resolvers are not very DRY since we're repeating argument definitions and resolver logic for each field. As a simple example:

field :posts, Post.connection_type, null: true do
  argument :is_published, Boolean, required: false
end
def posts(is_published: nil)
  scope = Post.all
  unless is_published.nil?
    scope = scope.where(is_published:)
  end
  scope
end

We have sort of tidied it up by moving the logic of each trait's scopes somewhere else. The result then looks like:

def posts(**args)
  scope = Post.all
  scope = Publishable::QueryFilter.apply(scope, **args)
  # ... other traits
  scope
end

But this still isn't very DRY since you have to add the field extension for the argument and add a line to the resolver body. Ideally each field would reference each trait just once.

I took a shot at implementing this as a field extension:

module Publishable
  class FieldExtension < GraphQL::Schema::FieldExtension
    ARG_NAME = :is_published

    def apply
      field.argument(ARG_NAME, Boolean, required: false)
    end

    def after_resolve(value:, arguments:, **rest)
      case arguments[ARG_NAME]
      in nil
        value
      in true | false => is_published
        value.where(is_published:)
      end
    end
  end
end

And then in the root query type:

field :posts, Post.connection_type, null: true, extensions: [Publishable::FieldExtension]
def posts(**args)
  Post.all
end

But this fails with an error:

NoMethodError:
  undefined method 'where' for an instance of GraphQL::Pro::PostgresStableRelationConnection

Is using after_resolve not compatible with stable pagination?

[rmosolgo]

Yes, that's right -- after_resolve won't work with GraphQL-Ruby's built-in connection system (stable or otherwise). This is because connection wrappers are applied during after_resolve themselves:

graphql-ruby/lib/graphql/schema/field/connection_extension.rb

Lines 24 to 29 in 4c32e90

	def after_resolve(value:, object:, arguments:, context:, memo:)
	original_arguments = memo
	context.query.after_lazy(value) do |resolved_value|
	context.schema.connections.populate_connection(field, object.object, resolved_value, original_arguments, context)
	end
	end

What they return is connection instance, not the list object (eg ActiveRecord scope). Hence the error message here: your code expected a scope, but received a connection object.

So, I'd suggest a different integration points. Some options are:

• generating resolver methods on the type definition
• generating resolver classes and attaching them with resolver: ...
• generating methods in another module and including it in the type class
• using def resolve on a field extension instead, assuming that the scope will be returned from yield (ie, no GraphQL-Batch).

I'd be happy to help explore one of those options if one of them stands out to you. Let me know what you think!

[mroach]

Thanks for the insights and quick reply!

I realise now that I had misunderstood and misused the yield inside of #resolve on the field extension. Now I understand that the return value of that is the return value from the "main" or "root" resolver method itself so I can access that and manipulate it. This is exactly the middleware-style approach I was after!

def resolve(object:, arguments, **rest)
  scope = yield(object, arguments)
  case arguments[ARG_NAME]
  in nil
    scope
  in true | false => is_published
    scope.where(is_published:)
  end
end

I do also like the idea of having a separate resolver class, or moving the resolver method to the type definition. Or a completely portable field definition class for that type?
Some types are used in multiple contexts. For example, you could have users scoped to a specific Group or Project but have the exact same interface.

I believe this is the approach you're outlining in Resolver docs with HasRecommendedItems which looks real close to what I have in mind. That approach looks real similar to defining a Resolver class. For a situation like this, is there any benefit to having a Resolver class versus the included module approach seen with HasRecommendedItems?

[rmosolgo]

I'd say generating a method and generating a resolver class are basically equivalent. A resolver will have a hair more overhead, but unless you're in a list-of-list-of-lists, it wouldn't amount to much.

[mroach]

While doing some refactoring I ran into an issue you hinted at:

assuming that the scope will be returned from yield (ie, no GraphQL-Batch).

Resolver methods on the root query are returning scopes, while resolvers on other types are doing batching to avoid N+1. I had a similar issue with a field that does filtering but then the last step in the resolver is calls aggregate function e.g. scope.count or scope.sum(:amount).

I'm trying to think of a way to solve for this generically if possible. Something like:

def my_field_resolver
  # 1. Seed value. Similar to the `0` in a `reduce(0)`
  scope = ::User.all
 
  # 2. Apply all extension resolvers. Something like:
  scope = yield(scope)

  # 3. Optional: apply a final operation. Batch loading, aggregate, or just return the value
  scope.maximum(:amount)
end

Am I thinking of this about right? Is there a decent way to do this with graphql-ruby or should I be thinking of plain old Ruby to solve for this?

For my two fields that were doing scope.count but using other extensions, I created an extension to run last in the stack. That worked, but doesn't quite feel right.

class Extensions::RecordCount < GraphQL::Schema::FieldExtension
  def resolve(object:, arguments:, **rest)
    scope = yield(object, arguments)
    scope.count
  end
end

[rmosolgo]

plain old Ruby

Always your best bet, IMO -- something that you can test in isolation (without touching any GraphQL surfaces), then call from GraphQL.

Promises can make that tough, since usually it's handled inside GraphQL. But you can call GraphQL::Batch directly in your tests to simulate that: https://github.com/Shopify/graphql-batch#unit-testing

I'd be happy to suggest a kind of Ruby data structure that might work for this if you could you share an example of a resolver that uses GraphQL-Batch as part of this flow. That's the trickiest one, since it requires .then somewhere, depending on how batch loaders fit in.

Personally, I'm not a huge fan of field extensions. GraphQL-Ruby uses them for some magic but they just have never worked really smoothly. In Execution::Next I had to hard-code some of the behaviors that were previously implemented in Field Extensions to get them to work right 🤷

[mroach]

We've been using a home-rolled batch loader subclassing from GraphQL::Dataloader::Source. Checking the git log, we created that 6 years ago, so perhaps that is no longer state of the art and GraphQL::Batch is worth a look.

Our loader may share a similar approach with what GraphQL::Batch is doing. Nearly all resolvers outside of the root query will build-up an AR relation with filters and sorting, and then the final step in the resolver is to defer loading. Resolvers on the root query don't do deferred loading, although I suppose they could or even should?

An example is a comments field that is included by an interface on numerous types that support commenting via a polymorphic relation to a Comment model.

field :comments, Comment.connection_type, null: false do
  # extensions, arguments for filtering and sorting
end
def comments(**args)
  # 1.
  scope = ::Comment.all

  # 2.
  # some resolvers have many pieces of "middleware" here to filter
  scope = Filtering::Visibility.apply(scope, context)
  scope = Filtering::ExactMatch.apply(scope, args.slice(:lang))
  scope = Filtering::TimeRange.apply(scope, args.slice(:created_at, :updated_at))
  scope = Comment::TextSearch.apply(scope, args[:search])
  scope = Sorting.apply(scope, args[:sort])

  # 3.
  defer_load_has_many(scope, :record, object)
end

That method defer_load_has_many is a simple wrapper around using the dataloader

def defer_load_has_many(scope, fk_attribute, parent_ref)
  dataloader.with(Sources::ActiveRecordForeignObjects, scope, fk_attribute).load(parent_ref)
end

With some of these arguments present, you may end up with a SQL query like:

SELECT *
FROM comments
WHERE record_type = 'Post'
  AND record_id in (1,2,3,4,5) -- built-up by the batch loader
  AND lang = 'en'
  AND created_at BETWEEN '2026-01-01' AND '2026-12-31'
  AND (body ILIKE '%foo%' OR title ILIKE '%foo%')
ORDER BY created_at DESC

Jumping back to the resolver method body:

Step 1 is often the same. There have been some edge cases where we force a filter in a certain context or need to add a join to reach the table.

Step 2 is the part that remains constant regardless of whether there's an aggregate, batched loading, or just a plain return. This part is also dependent on arguments, some of which are generic and shared across many types such as with the Publishable example from earlier on.

Step 3 depends on the context.

• On the root query type, this step isn't there. We just return the scope.
• On other types, we batch load and include criteria to match-up with the current object

Since you're kindly offering, I'd be happy and grateful to hear your suggestion on a Ruby structure!

My original goal was DRY-ing up the relation between arguments and their implementation in the resolver. Having the field be portable/reusable between the root query and other types would be a bonus.

Thanks for the dialogue and support on this. This schema has grown rather organically over the past half decade and I'm excited to spend time making it a happier place for developers to live.

[rmosolgo]

Ok, cool to know you're using Dataloader, not GraphQL-Batch. That makes it simpler because we don't have to worry about whether these methods return Promises or not. For unit testing, you can wrap the code with GraphQL::Dataloader.with_dataloading { ... } (doc) to create a batch-loading context.

I think the first thing I would try is to generate Resolver classes that could be tested apart from GraphQL queries. Here's a take on that:

Generate Resolver classes based on scope, resolves_to, and filters

class FilteredRelationResolver < GraphQL::Schema::Resolver # or your app's base resolver if relevant
  class << self
    # Class-level configuration, assigned with `.generate`
    attr_accessor :filters, :resolves_to, :scope

    # Create a new Resolver based on this one,
    # and pass along the class-level configuration to it
    def generate(filters:, resolves_to:, scope:)
      resolver_class = Class.new(self)
      resolver_class.filters = filters
      # TODO in your app: could each filter define `def self.add_graphql_arguments`
      # for attaching the associated arguments to the resolver class? For example:
      #
      #   Module Filtering::ExactMatch
      #     def self.add_graphql_arguments(resolver)
      #       resolver.argument(:lang, Types::LangEnum, null: true, default_value: "EN")
      #     end
      #   end
      #
      filters.each do |filter|
        filter.add_graphql_arguments(resolver_class)
      end
      resolver_class.resolves_to = resolves_to
      resolver_class.scope = scope
      resolver_class
    end

    # Produce an ActiveRecord scope based on the configuration
    def create_scope
      if scope.is_a?(Proc)
        # Support dynamic scopes if necessary:
        scope.call(object, arguments, context)
      elsif scope.is_a?(Class)
        scope.all
      else
        raise ArgumentError, "wrong `scope:` for #{self}: #{scope.inspect}"
      end
    end

    # Since all the configuration is on the class anyway,
    # we can put the resolution in class method.
    # This will also make it easy to test -- no GraphQL query required.
    def resolve_with_filters(object, args, context)
      # Step 1
      scope = create_scope

      # Step 2
      filters.each do |filter|
        # TODO in your app: can you add an `apply_from_resolver` method
        # to each module which passes the right GraphQL info to `.apply(...)` ?
        # That would provide a simple API for GraphQL code to call
        # while each filter can use exactly what it needs (args hash, one argument, context, whatever)
        # For example:
        #   module Filtering::ExactMatch
        #     def self.apply_from_resolver(scope, args, context)
        #       apply(scope, args.slice(:lang))
        #     end
        #   end
        scope = filter.apply_from_resolver(scope, args, context)
      end

      # Step 3, switch on configuration
      case resolves_to
      when :has_many
        context[:dataloader].with(Sources::ActiveRecordForeignObjects, scope, :record).load(object)
      when :count
        # ...
      # Other cases here?
      else
        raise ArgumentError, "Unexpected resolves_to: #{resolves_to.inspect}"
      end
    end
  end

  def resolve(**args)
    self.class.resolve_with_filters(object, args, context)
  end
end

# Example usage:
field :comments, Types::Comment.connection_type, null: false,
  resolver: FilteredRelationResolver.generate(
    scope: ::Comment,
    filters: [Filtering::Visibility, Filtering::ExactMatch, Filtering::TimeRange, Comment::TextSearch, Sorting],
    resolves_to: :has_many
  )

# Example test:
comments_resolver = MySchema.get_field("Query", "comments").resolver
# TODO: create test helper that includes `with_dataloading` and prepares a mocked graphql context
comments = GraphQL::Dataloader.with_dataloading do |dataloader|
  comments_resolver.resolve_with_filters(nil, { lang: "FR" }, { dataloader: dataloader })
end

# Check the return value of the resolver:
assert_something_about comments

What do you think of that approach?

grown rather organically ... making it a happier place

This is the real work! 🤘

[mroach]

I like this approach very much! I had also been looking at resolvers and started thinking along these lines. Building objects like this is an approach I quite like and use in other places. A source of uncertainty for me was that field extensions felt like they came close to solving this problem and I didn't want to re-invent a wheel that may already exist but I didn't know how to use it yet.

This kind of approach makes it quite clear how all the parts work and makes it easy to customise and test, so I like it! I'm going to have a try migrating some fields over to this and perhaps even making the whole field a portable and configurable object.

Thanks again for helping work out some ideas here. It's very much appreciated! 🚀