elasticgraph-graphql 0.18.0.0

data/lib/elastic_graph/graphql/query_adapter/requested_fields.rb

@@ -0,0 +1,124 @@
+# Copyright 2024 Block, Inc.
+#
+# Use of this source code is governed by an MIT-style
+# license that can be found in the LICENSE file or at
+# https://opensource.org/licenses/MIT.
+#
+# frozen_string_literal: true
+
+module ElasticGraph
+  class GraphQL
+    class QueryAdapter
+      # Query adapter that populates the `requested_fields` attribute of an `DatastoreQuery` in
+      # order to limit what fields we fetch from the datastore to only those that we actually
+      # need to satisfy the GraphQL query. This results in more efficient datastore queries,
+      # similar to doing `SELECT f1, f2, ...` instead of `SELECT *` for a SQL query.
+      class RequestedFields
+        def initialize(schema)
+          @schema = schema
+        end
+
+        def call(field:, query:, lookahead:, args:, context:)
+          return query if field.type.unwrap_fully.indexed_aggregation?
+
+          attributes = query_attributes_for(field: field, lookahead: lookahead)
+          query.merge_with(**attributes)
+        end
+
+        def query_attributes_for(field:, lookahead:)
+          attributes =
+            if field.type.relay_connection?
+              {
+                individual_docs_needed: pagination_fields_need_individual_docs?(lookahead),
+                requested_fields: requested_fields_under(relay_connection_node_from(lookahead))
+              }
+            else
+              {
+                requested_fields: requested_fields_under(lookahead)
+              }
+            end
+
+          attributes.merge(total_document_count_needed: query_needs_total_document_count?(lookahead))
+        end
+
+        private
+
+        # Identifies the fields we need to fetch from the datastore by looking for the fields
+        # under the given `node`.
+        #
+        # For nested relation fields, it is important that we start with this method, instead of
+        # `requested_fields_for`, because they need to be treated differently if we are building
+        # an `DatastoreQuery` for the nested relation field, or for a parent type.  When we determine
+        # requested fields for a nested relation field, we need to look at its child fields, and we
+        # can ignore its foreign key; but when we are determining requested fields for a parent type,
+        # we need to identify the foreign key to request from the datastore, without recursing into
+        # its children.
+        def requested_fields_under(node, path_prefix: "")
+          fields = node.selections.flat_map do |child|
+            requested_fields_for(child, path_prefix: path_prefix)
+          end
+
+          fields << "#{path_prefix}__typename" if field_for(node.field)&.type&.abstract?
+          fields
+        end
+
+        # Identifies the fields we need to fetch from the datastore for the given node,
+        # and recursing into the fields under it as needed.
+        def requested_fields_for(node, path_prefix:)
+          return [] if graphql_dynamic_field?(node)
+
+          # @type var field: Schema::Field
+          field = _ = field_for(node.field)
+
+          if field.type.embedded_object?
+            requested_fields_under(node, path_prefix: "#{path_prefix}#{field.name_in_index}.")
+          else
+            field.index_field_names_for_resolution.map do |name|
+              "#{path_prefix}#{name}"
+            end
+          end
+        end
+
+        def field_for(field)
+          return nil unless field
+          @schema.field_named(field.owner.graphql_name, field.name)
+        end
+
+        def pagination_fields_need_individual_docs?(lookahead)
+          # If the client wants cursors, we need to request docs from the datastore so we get back the sort values
+          # for each node, which we can then encode into a cursor.
+          return true if lookahead.selection(@schema.element_names.edges).selects?(@schema.element_names.cursor)
+
+          # Most subfields of `page_info` also require us to fetch documents from the datastore. For example,
+          # we cannot compute `has_next_page` or `has_previous_page` correctly if we do not fetch a full page
+          # of documents from the datastore.
+          lookahead.selection(@schema.element_names.page_info).selections.any?
+        end
+
+        def relay_connection_node_from(lookahead)
+          node = lookahead.selection(@schema.element_names.nodes)
+          return node if node.selected?
+
+          lookahead
+            .selection(@schema.element_names.edges)
+            .selection(@schema.element_names.node)
+        end
+
+        # total_hits_count is needed when the connection explicitly specifies `total_edge_count` to
+        # be returned in the part of the GraphQL query we are processing. Note that the aggregation
+        # query adapter can also set it to true based on its needs.
+        def query_needs_total_document_count?(lookahead)
+          # If total edge count is explicitly specified in page_info, we have to return the total count
+          lookahead.selects?(@schema.element_names.total_edge_count)
+        end
+
+        def graphql_dynamic_field?(node)
+          # As per https://spec.graphql.org/October2021/#sec-Objects,
+          # > All fields defined within an Object type must not have a name which begins with "__"
+          # > (two underscores), as this is used exclusively by GraphQL’s introspection system.
+          node.field.name.start_with?("__")
+        end
+      end
+    end
+  end
+end

data/lib/elastic_graph/graphql/query_adapter/sort.rb

@@ -0,0 +1,32 @@
+# Copyright 2024 Block, Inc.
+#
+# Use of this source code is governed by an MIT-style
+# license that can be found in the LICENSE file or at
+# https://opensource.org/licenses/MIT.
+#
+# frozen_string_literal: true
+
+module ElasticGraph
+  class GraphQL
+    class QueryAdapter
+      # Note: This class is not tested directly but indirectly through specs on `QueryAdapter`
+      Sort = Data.define(:order_by_arg_name) do
+        # @implements Sort
+        def call(query:, args:, field:, lookahead:, context:)
+          sort_clauses = field.sort_clauses_for(args[order_by_arg_name])
+
+          if sort_clauses.empty?
+            # When there are multiple search index definitions, we just need to pick one as the
+            # source of the default sort clauses. It doesn't really matter which (if the client
+            # really cared, they would have provided an `order_by` argument...) but we want our
+            # logic to be consistent and deterministic, so we just use the alphabetically first
+            # index here.
+            sort_clauses = (_ = query.search_index_definitions.min_by(&:name)).default_sort_clauses
+          end
+
+          query.merge_with(sort: sort_clauses)
+        end
+      end
+    end
+  end
+end

data/lib/elastic_graph/graphql/query_details_tracker.rb

@@ -0,0 +1,60 @@
+# Copyright 2024 Block, Inc.
+#
+# Use of this source code is governed by an MIT-style
+# license that can be found in the LICENSE file or at
+# https://opensource.org/licenses/MIT.
+#
+# frozen_string_literal: true
+
+require "elastic_graph/graphql/client"
+require "elastic_graph/support/hash_util"
+require "graphql"
+
+module ElasticGraph
+  class GraphQL
+    # Class used to track details of what happens during a single GraphQL query for the purposes of logging.
+    # Here we use `Struct` instead of `Data` specifically because it is designed to be mutable.
+    class QueryDetailsTracker < Struct.new(
+      :hidden_types,
+      :shard_routing_values,
+      :search_index_expressions,
+      :query_counts_per_datastore_request,
+      :datastore_query_server_duration_ms,
+      :datastore_query_client_duration_ms,
+      :mutex
+    )
+      def self.empty
+        new(
+          hidden_types: ::Set.new,
+          shard_routing_values: ::Set.new,
+          search_index_expressions: ::Set.new,
+          query_counts_per_datastore_request: [],
+          datastore_query_server_duration_ms: 0,
+          datastore_query_client_duration_ms: 0,
+          mutex: ::Thread::Mutex.new
+        )
+      end
+
+      def record_datastore_queries_for_single_request(queries)
+        mutex.synchronize do
+          shard_routing_values.merge(queries.flat_map { |q| q.shard_routing_values || [] })
+          search_index_expressions.merge(queries.map(&:search_index_expression))
+          query_counts_per_datastore_request << queries.size
+        end
+      end
+
+      def record_hidden_type(type)
+        mutex.synchronize do
+          hidden_types << type
+        end
+      end
+
+      def record_datastore_query_duration_ms(client:, server:)
+        mutex.synchronize do
+          self.datastore_query_client_duration_ms += client
+          self.datastore_query_server_duration_ms += server if server
+        end
+      end
+    end
+  end
+end

data/lib/elastic_graph/graphql/query_executor.rb

@@ -0,0 +1,200 @@
+# Copyright 2024 Block, Inc.
+#
+# Use of this source code is governed by an MIT-style
+# license that can be found in the LICENSE file or at
+# https://opensource.org/licenses/MIT.
+#
+# frozen_string_literal: true
+
+require "elastic_graph/graphql/client"
+require "elastic_graph/graphql/query_details_tracker"
+require "elastic_graph/support/hash_util"
+require "graphql"
+
+module ElasticGraph
+  class GraphQL
+    # Responsible for executing queries.
+    class QueryExecutor
+      # @dynamic schema
+      attr_reader :schema
+
+      def initialize(schema:, monotonic_clock:, logger:, slow_query_threshold_ms:, datastore_search_router:)
+        @schema = schema
+        @monotonic_clock = monotonic_clock
+        @logger = logger
+        @slow_query_threshold_ms = slow_query_threshold_ms
+        @datastore_search_router = datastore_search_router
+      end
+
+      # Executes the given `query_string` using the provided `variables`.
+      #
+      # `timeout_in_ms` can be provided to limit how long the query runs for. If the timeout
+      # is exceeded, `RequestExceededDeadlineError` will be raised. Note that `timeout_in_ms`
+      # does not provide an absolute guarantee that the query will take no longer than the
+      # provided value; it is only used to halt datastore queries. In process computation
+      # can make the total query time exceeded the specified timeout.
+      #
+      # `context` is merged into the context hash passed to the resolvers.
+      def execute(
+        query_string,
+        client: Client::ANONYMOUS,
+        variables: {},
+        timeout_in_ms: nil,
+        operation_name: nil,
+        context: {},
+        start_time_in_ms: @monotonic_clock.now_in_ms
+      )
+        # Before executing the query, prune any null-valued variable fields. This means we
+        # treat `foo: null` the same as if `foo` was unmentioned. With certain clients (e.g.
+        # code-gen'd clients in a statically typed language), it is non-trivial to avoid
+        # mentioning variable fields they aren't using. It makes it easier to evolve the
+        # schema if we ignore null-valued fields rather than potentially returning an error
+        # due to a null-valued field referencing an undefined schema element.
+        variables = ElasticGraph::Support::HashUtil.recursively_prune_nils_from(variables)
+
+        query_tracker = QueryDetailsTracker.empty
+
+        query, result = build_and_execute_query(
+          query_string: query_string,
+          variables: variables,
+          operation_name: operation_name,
+          client: client,
+          context: context.merge({
+            monotonic_clock_deadline: timeout_in_ms&.+(start_time_in_ms),
+            elastic_graph_schema: @schema,
+            schema_element_names: @schema.element_names,
+            elastic_graph_query_tracker: query_tracker,
+            datastore_search_router: @datastore_search_router
+          }.compact)
+        )
+
+        unless result.to_h.fetch("errors", []).empty?
+          @logger.error <<~EOS
+            Query #{query.operation_name}[1] for client #{client.description} resulted in errors[2].
+
+            [1] #{full_description_of(query)}
+
+            [2] #{::JSON.pretty_generate(result.to_h.fetch("errors"))}
+          EOS
+        end
+
+        unless query_tracker.hidden_types.empty?
+          @logger.warn "#{query_tracker.hidden_types.size} GraphQL types were hidden from the schema due to their backing indices being inaccessible: #{query_tracker.hidden_types.sort.join(", ")}"
+        end
+
+        duration = @monotonic_clock.now_in_ms - start_time_in_ms
+
+        # Note: I also wanted to log the sanitized query if `result` has `errors`, but `GraphQL::Query#sanitized_query`
+        # returns `nil` on an invalid query, and I don't want to risk leaking PII by logging the raw query string, so
+        # we don't log any form of the query in that case.
+        if duration > @slow_query_threshold_ms
+          @logger.warn "Query #{query.operation_name} for client #{client.description} with shard routing values " \
+            "#{query_tracker.shard_routing_values.sort.inspect} and search index expressions #{query_tracker.search_index_expressions.sort.inspect} took longer " \
+            "(#{duration} ms) than the configured slow query threshold (#{@slow_query_threshold_ms} ms). " \
+            "Sanitized query:\n\n#{query.sanitized_query_string}"
+        end
+
+        unless client == Client::ELASTICGRAPH_INTERNAL
+          @logger.info({
+            "message_type" => "ElasticGraphQueryExecutorQueryDuration",
+            "client" => client.name,
+            "query_fingerprint" => fingerprint_for(query),
+            "query_name" => query.operation_name,
+            "duration_ms" => duration,
+            # Here we log how long the datastore queries took according to what the datastore itself reported.
+            "datastore_server_duration_ms" => query_tracker.datastore_query_server_duration_ms,
+            # Here we log an estimate for how much overhead ElasticGraph added on top of how long the datastore took.
+            # This is based on the duration, excluding how long the datastore calls took from the client side
+            # (e.g. accounting for network latency, serialization time, etc)
+            "elasticgraph_overhead_ms" => duration - query_tracker.datastore_query_client_duration_ms,
+            # According to https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/FilterAndPatternSyntax.html#metric-filters-extract-json,
+            # > Value nodes can be strings or numbers...If a property selector points to an array or object, the metric filter won't match the log format.
+            # So, to allow flexibility to deal with cloud watch metric filters, we coerce these values to a string here.
+            "unique_shard_routing_values" => query_tracker.shard_routing_values.sort.join(", "),
+            # We also include the count of shard routing values, to make it easier to search logs
+            # for the case of no shard routing values.
+            "unique_shard_routing_value_count" => query_tracker.shard_routing_values.count,
+            "unique_search_index_expressions" => query_tracker.search_index_expressions.sort.join(", "),
+            # Indicates how many requests we sent to the datastore to satisfy the GraphQL query.
+            "datastore_request_count" => query_tracker.query_counts_per_datastore_request.size,
+            # Indicates how many individual datastore queries there were. One datastore request
+            # can contain many queries (since we use `msearch`), so these counts can be different.
+            "datastore_query_count" => query_tracker.query_counts_per_datastore_request.sum,
+            "over_slow_threshold" => (duration > @slow_query_threshold_ms).to_s,
+            "slo_result" => slo_result_for(query, duration)
+          })
+        end
+
+        result
+      end
+
+      private
+
+      # Note: this is designed so that `elasticgraph-query_registry` can hook into this method. It needs to be able
+      # to override how the query is built and executed.
+      def build_and_execute_query(query_string:, variables:, operation_name:, context:, client:)
+        query = ::GraphQL::Query.new(
+          @schema.graphql_schema,
+          query_string,
+          variables: variables,
+          operation_name: operation_name,
+          context: context
+        )
+
+        [query, execute_query(query, client: client)]
+      end
+
+      # Executes the given query, providing some extra logging if an exception occurs.
+      def execute_query(query, client:)
+        # Log the query before starting to execute it, in case there's a lambda timeout, in which case
+        # we won't get any other logged messages for the query.
+        @logger.info "Starting to execute query #{fingerprint_for(query)} for client #{client.description}."
+
+        query.result
+      rescue => ex
+        @logger.error <<~EOS
+          Query #{query.operation_name}[1] for client #{client.description} failed with an exception[2].
+
+          [1] #{full_description_of(query)}
+
+          [2] #{ex.class}: #{ex.message}
+        EOS
+
+        raise ex
+      end
+
+      # Returns a string that describes the query as completely as we can.
+      # Note that `query.sanitized_query_string` is quite complete, but can be nil in
+      # certain situations (such as when the query string itself is invalid!); we include
+      # the fingerprint to make sure that we at least have some identification information
+      # about the query.
+      def full_description_of(query)
+        "#{fingerprint_for(query)} #{query.sanitized_query_string}"
+      end
+
+      def fingerprint_for(query)
+        query.query_string ? query.fingerprint : "(no query string)"
+      end
+
+      def slo_result_for(query, duration)
+        latency_slo = directives_from_query_operation(query)
+          .dig(schema.element_names.eg_latency_slo, schema.element_names.ms)
+
+        if latency_slo.nil?
+          nil
+        elsif duration <= latency_slo
+          "good"
+        else
+          "bad"
+        end
+      end
+
+      def directives_from_query_operation(query)
+        query.selected_operation&.directives&.to_h do |dir|
+          arguments = dir.arguments.to_h { |arg| [arg.name, arg.value] }
+          [dir.name, arguments]
+        end || {}
+      end
+    end
+  end
+end

data/lib/elastic_graph/graphql/resolvers/get_record_field_value.rb

@@ -0,0 +1,49 @@
+# Copyright 2024 Block, Inc.
+#
+# Use of this source code is governed by an MIT-style
+# license that can be found in the LICENSE file or at
+# https://opensource.org/licenses/MIT.
+#
+# frozen_string_literal: true
+
+require "elastic_graph/graphql/datastore_response/document"
+require "elastic_graph/graphql/resolvers/relay_connection/array_adapter"
+require "elastic_graph/support/hash_util"
+
+module ElasticGraph
+  class GraphQL
+    module Resolvers
+      # Responsible for fetching a single field value from a document.
+      class GetRecordFieldValue
+        def initialize(schema_element_names:)
+          @schema_element_names = schema_element_names
+        end
+
+        def can_resolve?(field:, object:)
+          object.is_a?(DatastoreResponse::Document) || object.is_a?(::Hash)
+        end
+
+        def resolve(field:, object:, args:, context:, lookahead:)
+          field_name = field.name_in_index.to_s
+          data =
+            case object
+            when DatastoreResponse::Document
+              object.payload
+            else
+              object
+            end
+
+          value = Support::HashUtil.fetch_value_at_path(data, field_name) do
+            field.type.list? ? [] : nil
+          end
+
+          if field.type.relay_connection?
+            RelayConnection::ArrayAdapter.build(value, args, @schema_element_names, context)
+          else
+            value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/elastic_graph/graphql/resolvers/graphql_adapter.rb

@@ -0,0 +1,114 @@
+# Copyright 2024 Block, Inc.
+#
+# Use of this source code is governed by an MIT-style
+# license that can be found in the LICENSE file or at
+# https://opensource.org/licenses/MIT.
+#
+# frozen_string_literal: true
+
+require "elastic_graph/graphql/resolvers/query_adapter"
+
+module ElasticGraph
+  class GraphQL
+    module Resolvers
+      # Adapts the GraphQL gem's resolver interface to the interface implemented by
+      # our resolvers. Responsible for routing a resolution request to the appropriate
+      # resolver.
+      class GraphQLAdapter
+        def initialize(schema:, datastore_query_builder:, datastore_query_adapters:, runtime_metadata:, resolvers:)
+          @schema = schema
+          @query_adapter = QueryAdapter.new(
+            datastore_query_builder: datastore_query_builder,
+            datastore_query_adapters: datastore_query_adapters
+          )
+
+          @resolvers = resolvers
+
+          scalar_types_by_name = runtime_metadata.scalar_types_by_name
+          @coercion_adapters_by_scalar_type_name = ::Hash.new do |hash, name|
+            scalar_types_by_name.fetch(name).load_coercion_adapter.extension_class
+          end
+        end
+
+        # To be a valid resolver, we must implement `call`, accepting the 5 arguments listed here.
+        #
+        # See https://graphql-ruby.org/api-doc/1.9.6/GraphQL/Schema.html#from_definition-class_method
+        # (specifically, the `default_resolve` argument) for the API documentation.
+        def call(parent_type, field, object, args, context)
+          schema_field = @schema.field_named(parent_type.graphql_name, field.name)
+
+          # Extract the `:lookahead` extra that we have configured all fields to provide.
+          # See https://graphql-ruby.org/api-doc/1.10.8/GraphQL/Execution/Lookahead.html for more info.
+          # It is not a "real" arg in the schema and breaks `args_to_schema_form` when we call that
+          # so we need to peel it off here.
+          lookahead = args[:lookahead]
+          # Convert args to the form they were defined in the schema, undoing the normalization
+          # the GraphQL gem does to convert them to Ruby keyword args form.
+          args = schema_field.args_to_schema_form(args.except(:lookahead))
+
+          resolver = resolver_for(schema_field, object) do
+            raise <<~ERROR
+              No resolver yet implemented for this case.
+
+              parent_type: #{schema_field.parent_type}
+
+              field: #{schema_field}
+
+              obj: #{object.inspect}
+
+              args: #{args.inspect}
+
+              ctx: #{context.inspect}
+            ERROR
+          end
+
+          result = resolver.resolve(field: schema_field, object: object, args: args, context: context, lookahead: lookahead) do
+            @query_adapter.build_query_from(field: schema_field, args: args, lookahead: lookahead, context: context)
+          end
+
+          # Give the field a chance to coerce the result before returning it. Initially, this is only used to deal with
+          # enum value overrides (e.g. so that if `DayOfWeek.MONDAY` has been overridden to `DayOfWeek.MON`, we can coerce
+          # a `MONDAY` value being returned by a painless script to `MON`), but this is designed to be general purpose
+          # and we may use it for other coercions in the future.
+          #
+          # Note that coercion of scalar values is handled by the `coerce_result` callback below.
+          schema_field.coerce_result(result)
+        end
+
+        # In order to support unions and interfaces, we must implement `resolve_type`.
+        def resolve_type(supertype, object, context)
+          # If `__typename` is available, use that to resolve. It should be available on any embedded abstract types...
+          # (See `Inventor` in `config/schema.graphql` for an example of this kind of type union.)
+          if (typename = object["__typename"])
+            @schema.graphql_schema.possible_types(supertype).find { |t| t.graphql_name == typename }
+          else
+            # ...otherwise infer the type based on what index the object came from. This is the case
+            # with unions/interfaces of individually indexed types.
+            # (See `Part` in `config/schema/widgets.rb` for an example of this kind of type union.)
+            @schema.document_type_stored_in(object.index_definition_name).graphql_type
+          end
+        end
+
+        def coerce_input(type, value, ctx)
+          scalar_coercion_adapter_for(type).coerce_input(value, ctx)
+        end
+
+        def coerce_result(type, value, ctx)
+          scalar_coercion_adapter_for(type).coerce_result(value, ctx)
+        end
+
+        private
+
+        def scalar_coercion_adapter_for(type)
+          @coercion_adapters_by_scalar_type_name[type.graphql_name]
+        end
+
+        def resolver_for(field, object)
+          return object if object.respond_to?(:can_resolve?) && object.can_resolve?(field: field, object: object)
+          resolver = @resolvers.find { |r| r.can_resolve?(field: field, object: object) }
+          resolver || yield
+        end
+      end
+    end
+  end
+end

data/lib/elastic_graph/graphql/resolvers/list_records.rb

@@ -0,0 +1,29 @@
+# Copyright 2024 Block, Inc.
+#
+# Use of this source code is governed by an MIT-style
+# license that can be found in the LICENSE file or at
+# https://opensource.org/licenses/MIT.
+#
+# frozen_string_literal: true
+
+require "elastic_graph/graphql/resolvers/query_source"
+require "elastic_graph/graphql/resolvers/relay_connection"
+
+module ElasticGraph
+  class GraphQL
+    module Resolvers
+      # Responsible for fetching a a list of records of a particular type
+      class ListRecords
+        def can_resolve?(field:, object:)
+          field.parent_type.name == :Query && field.type.collection?
+        end
+
+        def resolve(field:, context:, lookahead:, **)
+          query = yield
+          response = QuerySource.execute_one(query, for_context: context)
+          RelayConnection.maybe_wrap(response, field: field, context: context, lookahead: lookahead, query: query)
+        end
+      end
+    end
+  end
+end

data/lib/elastic_graph/graphql/resolvers/nested_relationships.rb

@@ -0,0 +1,74 @@
+# Copyright 2024 Block, Inc.
+#
+# Use of this source code is governed by an MIT-style
+# license that can be found in the LICENSE file or at
+# https://opensource.org/licenses/MIT.
+#
+# frozen_string_literal: true
+
+require "elastic_graph/graphql/resolvers/relay_connection"
+
+module ElasticGraph
+  class GraphQL
+    module Resolvers
+      # Responsible for loading nested relationships that are stored as separate documents
+      # in the datastore. We use `QuerySource` for the datastore queries to avoid
+      # the N+1 query problem (giving us one datastore query per layer of our graph).
+      #
+      # Most of the logic for this lives in ElasticGraph::Schema::RelationJoin.
+      class NestedRelationships
+        def initialize(schema_element_names:, logger:)
+          @schema_element_names = schema_element_names
+          @logger = logger
+        end
+
+        def can_resolve?(field:, object:)
+          !!field.relation_join
+        end
+
+        def resolve(object:, field:, context:, lookahead:, **)
+          log_warning = ->(**options) { log_field_problem_warning(field: field, **options) }
+          join = field.relation_join
+          id_or_ids = join.extract_id_or_ids_from(object, log_warning)
+          filters = [
+            build_filter(join.filter_id_field_name, nil, join.foreign_key_nested_paths, Array(id_or_ids)),
+            join.additional_filter
+          ].reject(&:empty?)
+          query = yield.merge_with(filters: filters)
+
+          response =
+            case id_or_ids
+            when nil, []
+              join.blank_value
+            else
+              initial_response = QuerySource.execute_one(query, for_context: context)
+              join.normalize_documents(initial_response) do |problem|
+                log_warning.call(document: {"id" => id_or_ids}, problem: "got #{problem} from the datastore search query")
+              end
+            end
+
+          RelayConnection.maybe_wrap(response, field: field, context: context, lookahead: lookahead, query: query)
+        end
+
+        private
+
+        def log_field_problem_warning(field:, document:, problem:)
+          id = document.fetch("id", "<no id>")
+          @logger.warn "#{field.parent_type.name}(id: #{id}).#{field.name} had a problem: #{problem}"
+        end
+
+        def build_filter(path, previous_nested_path, nested_paths, ids)
+          if nested_paths.empty?
+            path = path.delete_prefix("#{previous_nested_path}.") if previous_nested_path
+            {path => {@schema_element_names.equal_to_any_of => ids}}
+          else
+            next_nested_path, *rest_nested_paths = nested_paths
+            sub_filter = build_filter(path, next_nested_path, rest_nested_paths, ids)
+            next_nested_path = next_nested_path.delete_prefix("#{previous_nested_path}.") if previous_nested_path
+            {next_nested_path => {@schema_element_names.any_satisfy => sub_filter}}
+          end
+        end
+      end
+    end
+  end
+end