lighthouse-graphql 0.9.0 → 0.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8545d3d90944dac8ea9e55b6fc19064b1895b160e2c2bd9459264456eed12dc8
-  data.tar.gz: eb9631fdd402f4e699a0976ee6f8c5592b6a3231a7fc52d883c40ed7ea2b0a7a
+  metadata.gz: 16b866dbbae1192cb051baae53de5a7938f9bb16c1f176a5112d8b1893cef78c
+  data.tar.gz: b0a9ed4c1fdfe4e6d22b7ebb5d07ff192ea661dbaaf7751cc726854edbbdb4b7
 SHA512:
-  metadata.gz: b443a6a974eaf9fad8ceab3eb3037a8fc03fc7de0d1d4944c5ffd26205fafed5137a12a680823dad5b74f5f2094d217ab2d9002abac44de4981352631e193c82
-  data.tar.gz: 929747b79b50bdeca4da61a47eecbab7c09a41a95ec3eea3797fc7e8d2e93a5c509105f0edd35873a007988eb1971c79690c1a76a411bc1133d24c5620f0caee
+  metadata.gz: 485c2dcd6ade1ff9f1c62be69544114784c18ebedf2e25609791d9113eccdf97ef6b41824fb7b6bf6d0fffa86a95d14aac6f43eab91c21109bf3ec592ffb8192
+  data.tar.gz: 14a7e8b8718f655c53e9c7594099ba9060b9b34c60eb23a08a258c36856fa459c4da5aaa38ec99c74f32248cc365131a06176928ace9aa46cfbf65cc0e8458ec

data/CHANGELOG.md

@@ -6,6 +6,21 @@ project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.9.1] - 2026-10-30
+
+### Added
+
+- **`@search` over several models**: a field of a union or an interface (`everything(search: String!
+  @search): [SearchResult!]! @paginate`) searches the models of its types together, one ranked list with an
+  exact total, each record answered as its model's type. Searchkick searches their indices in one request,
+  each model's `search_where` and hidden records holding in its own index only (`_index`), each model's hits
+  loading through its own scopes; pg_search searches its multisearch documents, each one counted only when
+  its model's relation selects its record. The schema is refused when the field is not a root `@all` or
+  `@paginate`, has no non-null `@search` argument, has a type that is no model's or models no one engine
+  searches together, or asks for what one model's search applies (`scopes:`, `@builder`, `@whereAuth`,
+  `@orderBy(column:)`, `@trashed`). An adapter of its own opts in with `searchable_together?` and
+  `together_error`. See [filtering-and-ordering.md](docs/filtering-and-ordering.md#searching-several-models-together).
+
 ## [0.9.0] - 2026-10-30
 
 ### Added
@@ -1016,7 +1031,8 @@ had been running inside a private monorepo as a path gem before being extracted.
 - Config-driven extension seams: `Lighthouse.configure`, `resolver_namespaces`,
   `on_error`, and `DirectiveRegistry.register` for app-defined directives.
 
-[Unreleased]: https://github.com/Vaz-Innovation/lighthouse-graphql/compare/v0.9.0...HEAD
+[Unreleased]: https://github.com/Vaz-Innovation/lighthouse-graphql/compare/v0.9.1...HEAD
+[0.9.1]: https://github.com/Vaz-Innovation/lighthouse-graphql/compare/v0.9.0...v0.9.1
 [0.9.0]: https://github.com/Vaz-Innovation/lighthouse-graphql/compare/v0.8.2...v0.9.0
 [0.8.2]: https://github.com/Vaz-Innovation/lighthouse-graphql/compare/v0.8.1...v0.8.2
 [0.8.1]: https://github.com/Vaz-Innovation/lighthouse-graphql/compare/v0.8.0...v0.8.1

data/docs/directives.md

@@ -694,6 +694,10 @@ each engine up.
   filters the database can apply too (`@trashed`'s, `@eq` on a column), so a stale index never
   answers one that no longer matches.
 
+On a field of a union or an interface (`[SearchResult!]! @paginate`), the search runs over the models
+of its types together, one ranked list: [Searching several models
+together](filtering-and-ordering.md#searching-several-models-together).
+
 A model's `search_results` scope, when it has one, is what a search of it may return:
 Searchkick loads the records it finds through it, so a record the index still holds after it
 should have left is not returned. A search counts only what it can load: a Searchkick model

data/docs/filtering-and-ordering.md

@@ -684,6 +684,85 @@ class Found
 end
 ```
 
+### Searching several models together
+
+A field of a union or an interface searches the models of its types together, in one search: a
+global search box that finds posts and users at once, the best matches of both first. PHP Lighthouse
+has no such search (Scout searches one model).
+
+```graphql
+union SearchResult = Post | User
+
+type Query {
+  everything(search: String! @search): [SearchResult!]! @paginate
+}
+```
+
+```graphql
+{
+  everything(search: "rails", first: 10) {
+    data { __typename ... on Post { title } ... on User { name } }
+    paginatorInfo { total }
+  }
+}
+```
+
+The models are those of the union's types, or of the object types that implement the interface: each
+type is a model's (`@model(class:)`, or its name). Each record answers as its model's type. One search
+over all of them answers one ranked list, paged as any search (`@all`, `@paginate` of any type), with an
+exact total.
+
+- **Searchkick** searches the models' indices in one request (`Searchkick.search(models: [...])`). What
+  narrows a model holds in its own index only, through the engine's `_index` (which Elasticsearch and
+  OpenSearch match against the alias Searchkick names): its `search_where`, and the records its default
+  scope hides. Each model's hits load through its own default scope, `search_results` scope and the
+  conditions the database applies alike, as for a search of it alone, so a model with a default scope or
+  `search_results` still needs `search_where`.
+- **pg_search** searches its [multisearch](https://github.com/Casecommons/pg_search#multi-search)
+  documents (`pg_search_documents`), which each `multisearchable` model keeps, ranked together by
+  `PgSearch.multisearch_options`. A document counts only when its record is one its model's relation
+  selects (its default scope, its `search_results` scope, the field's `@eq`), narrowed in the database, so
+  a page and its total hold only what loads, whatever documents are left behind (a record deleted without
+  its callbacks).
+
+  ```ruby
+  class Post < ApplicationRecord
+    include PgSearch::Model
+    multisearchable against: %i[title body], if: :published?
+  end
+
+  class User < ApplicationRecord
+    include PgSearch::Model
+    multisearchable against: :name
+  end
+
+  # config/initializers/pg_search.rb
+  PgSearch.multisearch_options = { using: { tsearch: { prefix: true } } }
+  ```
+
+The field's other arguments narrow every model alike: `@eq` holds in each index (or each model's
+relation), and matches nothing in one that does not have the column. `@builder` on an argument writes to
+the search as for one model (with pg_search, it may not set Searchkick's options). `@canQuery` checks each
+record the search finds by its own policy.
+
+The schema is refused when it is built, as `nothing applies` would be, where such a field:
+
+- is not a root field with `@all` or `@paginate` (a `model:` on the directive searches that one model,
+  as any field);
+- has no search to run: there is no table to list without one, so it takes one `@search`, on a top-level,
+  non-null argument (`search: String!`), with no `within:`, which names one model's index or scope;
+- has a type that is no model's, or models no one engine searches together (a Searchkick model and a
+  pg_search one; a pg_search model that is not `multisearchable`), or a model the engine cannot search as
+  it is (Searchkick's `search_where`, above);
+- asks for what one model's search would apply, and a search of several cannot: `scopes:`, `@builder`,
+  `@whereAuth` or `@orderBy(column:)` on the field, `@trashed` (each model has its own soft deletes),
+  `scopes:` on `@canQuery`, or a default value for a directive the engine cannot apply.
+
+An adapter of your own searches models together when it answers `searchable_together?(model)`,
+`together_error(model)` (why the model cannot be searched with others as it is, or nil) and `page` for a
+`Lighthouse::Search::Query` that has `models` (and no `model`); `query.for(model)` is the same search of
+one of them.
+
 ### Choosing the engine
 
 By default the engine is detected per model: Searchkick if it calls `searchkick`, else pg_search if it

data/lib/lighthouse/directive_resolvers/all_resolver.rb

@@ -33,10 +33,10 @@ class Lighthouse::GraphQL::DirectiveResolvers::AllDirectiveResolver < Lighthouse
   private
 
   def resolve_all(model_class, arguments, ctx)
+    args = arguments.respond_to?(:to_h) ? arguments.to_h : {}
+    return search_records(search_together(args, ctx), args, ctx) if searched_together
     return [] unless model_class
 
-    # apply simple pagination args if present
-    args = arguments.respond_to?(:to_h) ? arguments.to_h : {}
     relation = apply_scopes(model_class.all)
 
     relation = apply_where_filters(relation, args, ctx, search: :model)

data/lib/lighthouse/directive_resolvers/base.rb

@@ -149,6 +149,23 @@ class Lighthouse::GraphQL::DirectiveResolvers::BaseDirectiveResolver
     Lighthouse::Search::Enhancer.new(arguments, relation, search: search, context: ctx, field: field).enhance
   end
 
+  public
+
+  # The models the field searches together (a union's or an interface's types': Search.together),
+  # or nil for a field of one model.
+  def searched_together = Lighthouse::Search.together(@field_def)
+
+  # The search of the models the field searches together, narrowed by the field's argument
+  # filters: a Search::Result. Its errors fail the field, as the filters' (Support::Failures).
+  def search_together(args, ctx)
+    Lighthouse::Support::Failures.strictly(ctx) do
+      builders = @field_def.ast_node ? arg_builders(args_hash(args)) : []
+      unconstrained!(apply_search(nil, builders, ctx, searched_together))
+    end
+  end
+
+  private
+
   # Does the field have an argument or input field with @search? Known when the schema is built.
   def searching?
     @field_def.ast_node && Lighthouse::Search.searching?(@field_def)

data/lib/lighthouse/directive_resolvers/can_resolvers.rb

@@ -67,7 +67,7 @@ module Lighthouse::GraphQL::DirectiveResolvers
       # A field whose model cannot be told fails the build, not a query. On an
       # argument, the model is looked for only when the client gives it a value:
       # an input type may be shared with fields that have no model.
-      model_class if self.class.model? && !@opts[:argument]
+      model_class if self.class.model? && !@opts[:argument] && !searched_together
       me = self
       inner = capture_inner(target_type_class)
       install(target_type_class, lambda do |obj, args, ctx|
@@ -225,7 +225,7 @@ module Lighthouse::GraphQL::DirectiveResolvers
     # most, and more that a page could reach is an error (Search::Result#every_record).
     # Answers the Search::Result it checked, else nil.
     def authorize_before(_obj, args, ctx)
-      found = apply_where_filters(scoped(model_class.all), args, ctx, search: :model)
+      found = searched_together ? search_together(args, ctx) : apply_where_filters(scoped(model_class.all), args, ctx, search: :model)
       searched = found.is_a?(Lighthouse::Search::Result)
       authorize_each!(ctx, searched ? found.every_record : found.to_a, args)
       found if searched

data/lib/lighthouse/directive_resolvers/paginate_resolver.rb

@@ -93,6 +93,8 @@ class Lighthouse::GraphQL::DirectiveResolvers::PaginateDirectiveResolver < Light
   # the other parents' when the Dataloader can; otherwise, or with `model:`,
   # the model's whole table.
   def page_list(obj, args, ctx)
+    return search_together(args, ctx) if searched_together
+
     name = Lighthouse::Support::Naming.attribute(@field_def.name)
     return decorate_relation(model_class.all, args, ctx, search: :model) unless nested?(obj, name)
 

data/lib/lighthouse/graphql/version.rb

@@ -2,6 +2,6 @@
 
 module Lighthouse
   module GraphQL
-    VERSION = '0.9.0'
+    VERSION = '0.9.1'
   end
 end

data/lib/lighthouse/rb_lighthouse.rb

@@ -116,6 +116,7 @@ require_relative 'namespaces'
   search/auto
   search/enhancer
   search/field_check
+  search/together_check
   relation_batch
   relation_counts
   nested_mutations

data/lib/lighthouse/schema_generator.rb

@@ -134,6 +134,8 @@ module Lighthouse::GraphQL::SchemaGenerator
   # `bases`: { root kind => the base class its fields' classes inherit from } (ResolverBases).
   def post_process(schema, _impl, bases: {}, **_opts)
     root_kinds = root_kinds(schema)
+    # A field of a union or an interface with @search searches its types' models together.
+    Lighthouse::Search::TogetherCheck.check_schema!(schema, root_kinds)
 
     # Inspect types and fields for directives and attach generated resolvers
     schema.types.each_value do |type|

data/lib/lighthouse/search/auto.rb

@@ -18,4 +18,9 @@ class Lighthouse::Search::Auto
   end
 
   def searchable?(model, index = nil) = !adapter_for(model, index).nil?
+
+  # The first adapter that searches every one of `models` together, or nil.
+  def adapter_together(models)
+    @adapters.find { |adapter| adapter.respond_to?(:together_error) && models.all? { |model| adapter.searchable_together?(model) } }
+  end
 end

data/lib/lighthouse/search/enhancer.rb

@@ -11,6 +11,8 @@
 #   write to a Search::Query (Contracts::SearchBuilder), and the answer is a
 #   Search::Result instead of a relation. Any other argument directive the client
 #   sends is an error, as is a second @search.
+# - For models searched together (`models`: a union's or an interface's), there is no
+#   relation: the search is one over all of them, a Search::Result, whatever the adapter.
 class Lighthouse::Search::Enhancer
   # An argument directive of the field: its AST nodes, the builder class (or :builder), the client's value.
   Argument = Struct.new(:node, :directive, :builder, :value, :present)
@@ -28,18 +30,21 @@ class Lighthouse::Search::Enhancer
   # nil, a relation only; :model, a Search::Result for the model's own relation it
   # built (with the `scopes:` Search::FieldCheck refuses for an engine), searched
   # whole without a check; :given, one for a relation the app's code gave, checked.
-  # `field`: "Type.field", for the client's errors.
+  # `field`: "Type.field", for the client's errors. `search` is the models searched together, in
+  # place of a relation (nil), for a field of a union's or an interface's (Search.together).
   def initialize(arguments, relation, search:, context:, field: 'the field')
     @arguments = arguments
     @relation = relation
     @search = search
     @context = context
     @field = field
+    @models = search if search.is_a?(Array)
   end
 
   # The relation, searched; or a Search::Result. The relation itself if the client sent no search.
   def enhance
     search = the_search
+    return together(search) if @models
     return @relation unless search
 
     model = @relation.klass
@@ -73,6 +78,25 @@ class Lighthouse::Search::Enhancer
 
     searchable!(adapter, query.model)
     whole_index!(adapter) if @search == :given
+    narrowed(adapter, query)
+  end
+
+  # The search of the models, together: the field's argument is non-null (Search::FieldCheck), so
+  # the client always sends one.
+  def together(search)
+    raise ::GraphQL::ExecutionError, "#{@field} searches #{@models.map(&:name).join(', ')} together: it needs a search." unless search
+
+    adapter = Lighthouse::Search.adapter_together(@models) ||
+              raise(Lighthouse::DefinitionError, "@search: no engine searches #{@models.map(&:name).join(', ')} together.")
+    @models.each do |model|
+      error = adapter.together_error(model)
+      raise Lighthouse::DefinitionError, "@search: #{error}." if error
+    end
+    narrowed(adapter, Lighthouse::Search::Query.new(nil, search.value, models: @models))
+  end
+
+  # The search, narrowed by the other arguments the client sent, which the engine must take.
+  def narrowed(adapter, query)
     reject_incompatible
     query = @arguments.reject { |argument| search?(argument) }.reduce(query) { |narrowed, argument| narrow(narrowed, argument) }
     Lighthouse::Search::Result.checked(adapter, query, @field) || Lighthouse::Search::Result.new(adapter, query, context: @context, field: @field)

data/lib/lighthouse/search/field_check.rb

@@ -18,6 +18,8 @@
 #   user must not see. A relational adapter (pg_search) applies them.
 # - An @canQuery, which runs the search to check the records it finds, searches
 #   a searchable model, and without `scopes:` when the engine cannot apply them.
+#
+# A field of a union or an interface whose models are searched together is TogetherCheck's.
 class Lighthouse::Search::FieldCheck
   HINT = 'it needs searchkick or pg_search, or an adapter in Config.search'
   def self.check!(...) = new(...).check!
@@ -33,7 +35,7 @@ class Lighthouse::Search::FieldCheck
 
   def check!
     searches = Lighthouse::Search.directives(@field_def)
-    return if searches.empty?
+    return if searches.empty? || Lighthouse::Search.together(@field_def)
 
     searches.each { |path, directive| within_string!(path, directive) }
     applied!(searches.first.first)

data/lib/lighthouse/search/pg_search.rb

@@ -13,6 +13,14 @@
 # The model's `search_results` scope, if it has one, narrows the search too
 # (Lighthouse::Search).
 #
+# Models searched together (Search::Together) are searched through pg_search's
+# multisearch, the documents each `multisearchable` model keeps in one table
+# (PgSearch::Document, `pg_search_documents`), ranked together. A document counts only
+# when its record is one its model's relation selects (the model's default scope, its
+# search_results scope, the field's @eq on a column of its): the documents are narrowed
+# in the database, so pages and totals hold only what loads. Each page loads its records
+# through the same relations, a query per model.
+#
 # The gem is not a dependency of Lighthouse: the adapter is used when the
 # model includes PgSearch::Model.
 class Lighthouse::Search::PgSearch
@@ -42,8 +50,70 @@ class Lighthouse::Search::PgSearch
     orders.empty? ? searched : searched.reorder(*orders)
   end
 
+  # Models searched together: those that include PgSearch::Model, which must keep multisearch
+  # documents (`multisearchable`), whether or not they have a pg_search scope of their own.
+  def searchable_together?(model) = !!(defined?(::PgSearch::Model) && model.include?(::PgSearch::Model))
+
+  def together_error(model)
+    return nil if model.respond_to?(:pg_search_multisearchable_options)
+
+    "#{model.name} keeps no pg_search multisearch documents, which models searched together are searched through: " \
+      'call `multisearchable against: [...]` in it'
+  end
+
+  # Models searched together: [one entry per document at `offset`, `limit` of them, in rank
+  # order: its record, or nil for one that did not load; how many documents match].
+  def page(query, offset:, limit:)
+    options!(query)
+    documents = documents(query)
+    found = limit.zero? ? [] : documents.offset(offset).limit(limit).to_a
+    [records(query, found), documents.unscope(:order, :select).count]
+  end
+
+  # pg_search has no result window.
+  def result_window(_query) = nil
+
   private
 
+  # The documents that match, in rank order, each one's record selected by its model's relation.
+  def documents(query)
+    kept = query.models.map do |model|
+      ::PgSearch::Document.where(searchable_type: model.polymorphic_name, searchable_id: relation(query.for(model)).select(model.primary_key))
+    end
+    ::PgSearch.multisearch(query.term).where(id: kept.reduce(:or).select(:id))
+  end
+
+  # The model's records a search of it may answer: its relation and search_results scope, with the
+  # field's @eq conditions; none where a condition names a column the model does not have.
+  def relation(query)
+    model = query.model
+    query.wheres.reduce(Lighthouse::Search.results(model.all)) do |relation, (column, value)|
+      model.column_names.include?(column) ? relation.where(column => value) : relation.none
+    end
+  end
+
+  # The records of `documents`, in their order, nil for one its model's relation no longer selects.
+  # The models that share a document type (an STI class and its subclasses) each load theirs.
+  def records(query, documents)
+    loaded = documents.group_by(&:searchable_type).to_h do |type, typed|
+      ids = typed.map(&:searchable_id)
+      found = query.models.select { |model| model.polymorphic_name == type }.flat_map do |model|
+        relation(query.for(model)).where(model.primary_key => ids).to_a
+      end
+      [type, found.index_by { |record| record.id.to_s }]
+    end
+    documents.map { |document| loaded.dig(document.searchable_type, document.searchable_id.to_s) }
+  end
+
+  # An @builder's Searchkick options, which multisearch cannot take: one that narrows what loads
+  # (`scope_results:`) would be dropped.
+  def options!(query)
+    return if query.options.empty?
+
+    raise Lighthouse::DefinitionError,
+          "@search: pg_search's multisearch takes no option of Searchkick's, which an @builder set: #{query.options.keys.join(', ')}"
+  end
+
   def scope_name(index) = (index || DEFAULT_SCOPE).to_sym
 
   # Is the model's class method `name` a pg_search scope? pg_search keeps no list

data/lib/lighthouse/search/query.rb

@@ -4,10 +4,16 @@
 # what narrows it. The directives of the other arguments write to it
 # (Contracts::SearchBuilder), and the adapter runs it (Search::Searchkick#page).
 # Directives never know which engine is behind it.
+#
+# A search of several models together (a union's or an interface's: Search::Together) has
+# `models` and no `model`; `for(model)` is the same search of one of them.
 class Lighthouse::Search::Query
   # The model searched, the `@search` argument's value, the `within:` index (nil: the model's own).
   attr_reader :model, :term, :index
 
+  # The models searched together, or nil for a search of one.
+  attr_reader :models
+
   # [[column, value], ...], from @eq (and @builder), in order: all of them hold,
   # the same column twice too (a list of inputs), as the database applies them.
   attr_reader :wheres
@@ -18,15 +24,28 @@ class Lighthouse::Search::Query
   # :with, :only or :without, from @trashed; nil: the client did not say.
   attr_accessor :trashed
 
-  def initialize(model, term, index = nil)
+  def initialize(model, term, index = nil, models: nil)
     @model = model
     @term = term
     @index = index
+    @models = models
     @wheres = []
     @options = {}
     @trashed = nil
   end
 
+  # The model's name, or the names of the models searched together, for errors.
+  def name = models ? models.map(&:name).join(', ') : model.name
+
+  # The same search of `model` alone: its term, conditions and options.
+  def for(model)
+    self.class.new(model, term, index).tap do |one|
+      wheres.each { |column, value| one.where(column, value) }
+      one.options.merge!(options)
+      one.trashed = trashed
+    end
+  end
+
   # The column equals the value, as Scout's `where`.
   def where(column, value)
     @wheres << [column.to_s, value]

data/lib/lighthouse/search/result.rb

@@ -142,7 +142,7 @@ class Lighthouse::Search::Result
   # Is it the search of `field` that `adapter` runs for `query`? Its options aside,
   # which may hold an @builder's procs, made again for each search.
   def same_search?(adapter, query, field)
-    @adapter.equal?(adapter) && @field == field && query.model.equal?(@query.model) &&
+    @adapter.equal?(adapter) && @field == field && query.model.equal?(@query.model) && query.models == @query.models &&
       [query.term, query.index, query.wheres, query.trashed] == [@query.term, @query.index, @query.wheres, @query.trashed]
   end
 
@@ -176,6 +176,6 @@ class Lighthouse::Search::Result
 
     raise ::GraphQL::ExecutionError,
           "The search reads no further than its first #{result_window} matches (the index.max_result_window of " \
-          "#{@query.model.name}), so offset #{offset} is past them. Narrow the search instead."
+          "#{@query.name}), so offset #{offset} is past them. Narrow the search instead."
   end
 end

data/lib/lighthouse/search/searchkick.rb

@@ -53,16 +53,20 @@ class Lighthouse::Search::Searchkick
   # [one entry per hit at `offset`, `limit` of them, in relevance order: the
   # record, or nil for a hit that did not load; the total that match].
   def page(query, offset:, limit:)
-    response = query.model.searchkick_search(query.term, **search_options(query), offset: offset, limit: limit)
+    response = search(query, offset, limit)
     exact_total!(query, response)
     [entries(response), response.total_count]
   rescue StandardError => e
     raise unless past_window?(e)
 
     # The index's window is smaller than the model's options say: set on the server.
-    raise ::GraphQL::ExecutionError, "The search reads no further than the index.max_result_window of #{query.model.name}. Narrow the search instead."
+    raise ::GraphQL::ExecutionError, "The search reads no further than the index.max_result_window of #{query.name}. Narrow the search instead."
   end
 
+  # Models searched together: those it searches alone, and why one cannot be as it is (model_error).
+  def searchable_together?(model) = searchable?(model)
+  def together_error(model) = model_error(model)
+
   # How many of the matches the index the search reads pages through
   # (Search::Result): its index.max_result_window, read from the engine
   # (Searchkick::Index). When the settings cannot be read, the model's own index
@@ -70,6 +74,8 @@ class Lighthouse::Search::Searchkick
   # its index `settings:`, whatever their keys; a billion with `deep_paging:
   # true`), and any index the engines' default, 10,000.
   def result_window(query)
+    return query.models.map { |model| result_window(query.for(model)) }.min if query.models
+
     @index.result_window(query.model, index_name(query)) ||
       (own_index?(query) && options_window(query.model)) || Lighthouse::Search::Result::MAX_WINDOW
   end
@@ -133,7 +139,7 @@ class Lighthouse::Search::Searchkick
     return unless total.is_a?(Hash) && total['relation'] && total['relation'] != 'eq'
 
     raise Lighthouse::DefinitionError,
-          "@search on #{query.model.name}: the engine counted #{total['relation']} #{total['value']} matches, not every one, " \
+          "@search on #{query.name}: the engine counted #{total['relation']} #{total['value']} matches, not every one, " \
           'which totals, pages and @canQuery need (track_total_hits)'
   end
 
@@ -154,14 +160,51 @@ class Lighthouse::Search::Searchkick
     defined?(::Searchkick::InvalidQueryError) && error.is_a?(::Searchkick::InvalidQueryError) && error.message.include?('max_result_window')
   end
 
+  # The engine's response to the search, `limit` hits from `offset`: of the model, or of the
+  # models searched together, in one request over their indices.
+  def search(query, offset, limit)
+    return query.model.searchkick_search(query.term, **search_options(query), offset: offset, limit: limit) unless query.models
+
+    ::Searchkick.search(query.term, models: query.models, **together_options(query), offset: offset, limit: limit)
+  end
+
   def search_options(query)
     options = Lighthouse::Search::Searchkick::Options.builder!(query)
     wheres = query.wheres.map { |column, value| { column => value } }
     options[:where] = all_of(options[:where], engine_where(query), *wheres, trashed_filter(query))
     options[:index_name] = query.index if query.index
+    loaded(options, results_scope(query, options[:scope_results]))
+  end
+
+  # The options of a search of several models, in one request over their indices. What narrows
+  # each model holds in its own index only (`_index`, which the engines match against the
+  # alias Searchkick names): its search_where, and the records its default scope hides; what the
+  # client sends (@eq) holds in every index, matching nothing in one that does not hold the
+  # column. Each model's records load through its own narrowing (results_scope), which Searchkick
+  # calls with each model's relation.
+  def together_options(query)
+    options = Lighthouse::Search::Searchkick::Options.builder!(query)
+    wheres = query.wheres.map { |column, value| { column => value } }
+    each_own = query.models.map { |model| own_where(query.for(model)) }
+    options[:where] = all_of(options[:where], *wheres, { _or: each_own })
+    loads = query.models.index_with { |model| results_scope(query.for(model), options[:scope_results]) }.compact
+    loaded(options, loads.empty? ? nil : ->(records) { (loads[model_of(records)] || :itself.to_proc).call(records) })
+  end
+
+  # What Searchkick loads a model's hits through: the model itself, or a relation of it.
+  def model_of(records) = records.respond_to?(:klass) ? records.klass : records
+
+  # What one model's hits must hold in a search of several: being in its index, and what its own
+  # search would have the engine apply.
+  def own_where(query)
+    all_of({ _index: query.model.searchkick_index.name }, engine_where(query), trashed_filter(query))
+  end
+
+  # The options Lighthouse sets whatever the search: the records load, through `loading` (the
+  # `scope_results:` that narrows them) if any, and every match is counted.
+  def loaded(options, loading)
     options[:load] = true
     options[:body_options] = Lighthouse::Search::Searchkick::Options.counting(options)
-    loading = results_scope(query, options[:scope_results])
     options[:scope_results] = loading if loading
     options
   end

data/lib/lighthouse/search/together_check.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+# A field of a union or an interface (with @all or @paginate, and no `model:`) whose @search
+# searches the models of its types together, in one search, checked when the schema is built
+# (SchemaGenerator, before FieldCheck, which leaves the field to it), as FieldCheck checks a
+# field of one model. It keeps the models for the field's resolvers (Search.together!).
+#
+# Each type is a model's (@model, or its name), one engine searches them all
+# (`adapter_together`, `together_error`), the @search argument is a top-level, non-null one,
+# with no `within:`, on a root field; and nothing a model would apply alone, but the engine
+# across them cannot, is asked for: `scopes:`, @builder, @whereAuth, @orderBy(column:),
+# @trashed, a default value the engine cannot apply, an @canQuery's `scopes:`.
+class Lighthouse::Search::TogetherCheck < Lighthouse::Search::FieldCheck
+  # Every field of the schema's object types (`root_kinds`: SchemaGenerator#root_kinds).
+  def self.check_schema!(schema, root_kinds)
+    schema.types.each_value do |type|
+      next unless type.kind.object?
+
+      type.fields.each_value { |field_def| check!(schema, type, field_def, root_kinds[type.graphql_name]) if field_def.owner == type }
+    end
+  end
+
+  def self.check!(schema, type, field_def, root_kind)
+    return unless field_def.ast_node
+
+    new(schema, type, field_def, root_kind).check!
+  end
+
+  def initialize(schema, type, field_def, root_kind)
+    super(type, field_def, field_def.ast_node.directives || [], root_kind)
+    @schema = schema
+  end
+
+  def check!
+    searches = Lighthouse::Search.directives(@field_def)
+    together!(searches) if searches.any? && together?
+  end
+
+  private
+
+  # Does the field search the models of a union's or an interface's types together? One that a
+  # data directive resolves without a `model:` of its own.
+  def together?
+    !resolving_directive.nil? && returned&.kind&.abstract? &&
+      Lighthouse::Support::DirectiveArgs.literal(resolving_directive, 'model').nil?
+  end
+
+  # The type of what the field returns: of its items, for a paginated field (`PostPaginator`'s Post).
+  def returned
+    type = @field_def.type.unwrap
+    return type unless resolving_directive.name == 'paginate'
+
+    @schema.get_type(type.graphql_name.sub(Lighthouse::Support::ModelResolver::PAGINATION_SUFFIX, ''))
+  end
+
+  def together!(searches)
+    path = searches.first.first
+    searches.each { |each_path, directive| within_string!(each_path, directive) }
+    applied!(path)
+    together_field!(path, searches)
+    models = together_models(path)
+    adapter = together_adapter!(path, models)
+    together_constraints!(path, adapter)
+    can_queries.each { |can_query| together_can_query!(path, can_query) }
+    Lighthouse::Search.together!(@field_def, models)
+  end
+
+  # On a root field, with @all or @paginate, and one @search: a top-level, non-null argument
+  # (with no models to list, a field of several models answers a search, always), with no `within:`.
+  def together_field!(path, searches)
+    unless @root_kind && %w[all paginate].include?(resolving_directive.name)
+      fail!(path, "#{abstract_name} has several models, which only @all or @paginate on a root field search together " \
+                  '(or give the directive the `model:` it searches)')
+    end
+    one_search!(path, searches)
+    return if Lighthouse::Support::DirectiveArgs.literal(searches.first.last, 'within').nil?
+
+    fail!(path, "`within:` names one model's index or scope, and #{abstract_name}'s models are searched together")
+  end
+
+  def one_search!(path, searches)
+    return if searches.size == 1 && @field_def.arguments[path]&.type&.non_null?
+
+    fail!(path, "a field that searches #{abstract_name}'s models together needs its search: one @search, on a non-null argument " \
+                '(`search: String!`), which there is no table to list without')
+  end
+
+  # The models of the union's or the interface's object types: each must be a model's.
+  def together_models(path)
+    types = @schema.possible_types(returned).sort_by(&:graphql_name)
+    types.map do |type|
+      Lighthouse::GraphQL::Directives::ModelDirective.model_for(type) ||
+        fail!(path, "#{abstract_name}'s type #{type.graphql_name} is no model's: give it @model(class:), or remove it")
+    end
+  end
+
+  def together_adapter!(path, models)
+    adapter = Lighthouse::Search.adapter_together(models) || no_engine!(path, models)
+    models.each do |model|
+      error = adapter.together_error(model)
+      fail!(path, error) if error
+    end
+    adapter
+  end
+
+  # What one model's search would apply, and a search of several cannot: the field's own query
+  # directives and `scopes:`, @trashed (each model has its own soft-delete column) and default
+  # values the engine cannot apply.
+  def together_constraints!(path, adapter)
+    name = adapter.class.name.demodulize
+    dropped = dropped_constraints
+    fail!(path, "#{name} cannot apply #{dropped.join(', ')} to models searched together; remove them") unless dropped.empty?
+    trashed = Lighthouse::Support::ArgumentWalk.field_definitions(@field_def).find do |_, argument|
+      Lighthouse::Support::ArgumentWalk.directives(argument).any? { |directive| directive.name == 'trashed' }
+    end
+    fail!(path, "@trashed on #{trashed.first} cannot filter models searched together, each with its own soft deletes") if trashed
+    defaulted_constraints.each do |constraint|
+      fail!(path, "#{name} cannot apply #{constraint}, whose default value would apply to every search; remove the default")
+    end
+  end
+
+  def no_engine!(path, models)
+    engines = models.map { |model| "#{model.name} (#{engine_name(model)})" }
+    fail!(path, "no engine searches #{abstract_name}'s models together: #{engines.join(', ')}. One engine searches them " \
+                'all: Searchkick, or pg_search through its multisearch documents')
+  end
+
+  def engine_name(model) = Lighthouse::Search.adapter_for(model)&.class&.name&.demodulize || 'not searchable'
+
+  def together_can_query!(path, can_query)
+    return if Lighthouse::Support::DirectiveArgs.literal(can_query, 'scopes').blank?
+
+    fail!(path, 'the `scopes:` of @canQuery cannot narrow models searched together; remove them')
+  end
+
+  def abstract_name = returned.graphql_name
+end

data/lib/lighthouse/search.rb

@@ -8,6 +8,12 @@
 #   relational?                       is the search a scope on the model's relation (pg_search)?
 #   scope(relation, query)            relational: the relation narrowed to the matches, ranked
 #   page(query, offset:, limit:)      otherwise: [records, total] of the engine's response
+#   searchable_together?(model)       can it search the model with others (optional, with together_error)?
+#   together_error(model)             why it cannot search the model with others as it is, or nil
+#
+# Models searched together (a field of a union or an interface: FieldCheck) are one search
+# over all of them, a Query with `models`, which the adapter answers with `page`, whatever it
+# is: Searchkick over their indices, pg_search through its multisearch documents.
 #
 # `query` is a Search::Query. A relational adapter lets every other directive of
 # the field apply on top of the scope; the others (Searchkick) answer on their own
@@ -75,4 +81,21 @@ module Lighthouse::Search
 
   # Does the field have an argument or input field with @search?
   def searching?(field_def) = directives(field_def).any?
+
+  # The models the field searches together (Search::FieldCheck keeps them when the schema is
+  # built: the models of its union's or interface's types), or nil for a field of one model.
+  def together(field_def) = Lighthouse::Support::Memo.on(field_def, :searched_together) { nil }
+
+  def together!(field_def, models)
+    field_def.instance_variable_set(:@lighthouse_searched_together, models.freeze)
+  end
+
+  # The adapter that searches `models` together (`searchable_together?` each of them, and
+  # `together_error`), or nil when none does.
+  def adapter_together(models)
+    adapter = self.adapter
+    return adapter.adapter_together(models) if adapter.respond_to?(:adapter_together)
+
+    adapter if adapter.respond_to?(:together_error) && models.all? { |model| adapter.searchable_together?(model) }
+  end
 end

data/sig/lighthouse/search.rbs

@@ -21,9 +21,18 @@ module Lighthouse
     # Does the field have an argument or input field with @search? Walked once per field.
     def self.searching?: (_FieldDefinition field_def) -> bool
 
+    # The models the field searches together (a union's or an interface's), kept when the schema is built; nil for one model.
+    def self.together: (_FieldDefinition field_def) -> Array[Class]?
+    def self.together!: (_FieldDefinition field_def, Array[Class] models) -> Array[Class]
+    # The adapter that searches the models together, or nil.
+    def self.adapter_together: (Array[Class] models) -> _TogetherSearchAdapter?
+
     # What a search holds: the model, the term and what narrows it.
     class Query
-      attr_reader model: Class
+      # nil for models searched together.
+      attr_reader model: Class?
+      # The models searched together, or nil for a search of one.
+      attr_reader models: Array[Class]?
       attr_reader term: String
       attr_reader index: String?
       # [column, value] pairs, from @eq, all of which hold.
@@ -33,8 +42,12 @@ module Lighthouse
       # :with, :only or :without, from @trashed; nil: not given.
       attr_accessor trashed: (:with | :only | :without)?
 
-      def initialize: (Class model, String term, ?String? index) -> void
+      def initialize: (Class? model, String term, ?String? index, ?models: Array[Class]?) -> void
       def where: (String | Symbol column, untyped value) -> self
+      # The model's name, or the names of the models searched together.
+      def name: () -> String
+      # The same search of one model.
+      def for: (Class model) -> Query
     end
 
     # A search an engine answers: the page it is asked for and its total.
@@ -74,6 +87,7 @@ module Lighthouse
     # Searchkick (Elasticsearch / OpenSearch), outside the database.
     class Searchkick
       include _EngineSearchAdapter
+      include _TogetherSearchAdapter
 
       DEFAULT_TRASHED_COLUMN: String
       DEEP_PAGING_WINDOW: Integer
@@ -114,9 +128,14 @@ module Lighthouse
     # pg_search (PostgreSQL full-text search), in the database.
     class PgSearch
       include _RelationalSearchAdapter
+      include _EngineSearchAdapter
+      include _TogetherSearchAdapter
 
       DEFAULT_SCOPE: Symbol
 
+      # Models searched together, through multisearch's documents (page), which have no result window.
+      def result_window: (Query query) -> nil
+
       # Does `index` name one of the model's pg_search scopes?
       def named?: (Class model, String? index) -> bool
     end
@@ -127,6 +146,8 @@ module Lighthouse
 
       def initialize: (?Array[_SearchAdapter]? adapters) -> void
       def searchable?: (Class model, ?String? index) -> bool
+      # The first adapter that searches every one of the models together, or nil.
+      def adapter_together: (Array[Class] models) -> _TogetherSearchAdapter?
     end
   end
 end

data/sig/lighthouse.rbs

@@ -280,6 +280,14 @@ module Lighthouse
     def adapter_for: (Class model, ?String? index) -> _SearchAdapter?
   end
 
+  # An adapter that searches models together (a union's or an interface's): its `page` (as
+  # _EngineSearchAdapter's) answers a Search::Query with `models`, and `together_error(model)`
+  # why one cannot be searched with others as it is (a schema error).
+  interface _TogetherSearchAdapter
+    def searchable_together?: (Class model) -> boolish
+    def together_error: (Class model) -> String?
+  end
+
   # What DirectiveRegistry#register_manipulator takes: it transforms the SDL
   # before the schema is built.
   interface _SdlManipulator

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lighthouse-graphql
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.9.1
 platform: ruby
 authors:
 - Vaz Innovation
@@ -245,6 +245,7 @@ files:
 - lib/lighthouse/search/searchkick.rb
 - lib/lighthouse/search/searchkick_index.rb
 - lib/lighthouse/search/searchkick_options.rb
+- lib/lighthouse/search/together_check.rb
 - lib/lighthouse/server_directives.rb
 - lib/lighthouse/subscription.rb
 - lib/lighthouse/support/argument_walk.rb