feat: Index associations as nested child documents and search them with block joins

[njakobsen]

Summary

Adds Solr nested documents (block join) to Sunspot, so a search can require that one associated record meet several conditions together. With flat multivalued fields on the parent, "a design milestone started in Q1" also matches a parent with a design milestone and a different milestone started in Q1.

Sunspot.setup(Project) do
  nested :milestones do
    string :name
    time :started_at
  end
end

Sunspot.search(Project) do
  with_child :milestones do
    with :name, 'design'
    with(:started_at).between(Time.utc(2026, 1, 1)...Time.utc(2026, 4, 1))
  end
end

• Indexing. Each record of a nested association becomes a child document inside its parent's block. A child has the fields declared in the block, an id derived from its parent's ("<parent id>/<association>/<child index id or position>"), and a _sunspot_nested_path_s marker naming the association. It has no type or class_name. Children are indexed only as part of their parent, so the parent has to be reindexed when they change.

• Searching. with_child and without_child render as a {!parent} block join embedded with _query_. They work anywhere a restriction does: filter queries, any_of/all_of, query facet rows, and delete-by-query.

  • Block mask: every document without the marker, so documents of other classes indexed between blocks are never treated as children.
  • Child query: always requires the marker, and each restriction in the block is joined directly to that condition. A negated restriction therefore can't match documents outside the association, and a block of only negations still matches.

• Removal. Deleting a nested class's records also deletes their children:

  • After a delete by id, by _root_, in batches of 500 ids to stay under Solr's boolean clause limit. Solr 6 leaves children behind on a delete by id; Solr 9 removes them.
  • remove_all(Class) and remove_by_scope send one query, (query) OR _query_:"{!child …}", so parents and children go together even when the scope has a with_child condition. The children clause is added only when the removed class, an ancestor's setup it inherits, or a registered subclass declares a nested association.

• Several classes, and subclasses.

  • A with_child search of several classes covers every searched class that declares the association. Child fields resolve the way CompositeSetup resolves parent fields: a field is usable when every declaring class agrees on its Solr field name and type, and raises UnrecognizedFieldError when they conflict.
  • A subclass that declares an association again keeps its superclass's _sunspot_nested_path_s value, so a search of the superclass finds the subclass's children. That search resolves child fields from the superclass's own nested setup, as a superclass search does for parent fields.

• Limits.

  • Atomic updates raise ArgumentError for a class with nested associations.
  • A nested block rejects boosts, id prefixes, joins and further nesting, and with(record) / without(record) inside with_child raise ArgumentError.
  • Nested documents need an RSolr that defines RSolr::Document::CHILD_DOCUMENT_KEY; indexing raises NestedDocumentsNotSupportedError otherwise.
  • A subclass that declares an association again replaces its fields rather than adding to them, so a superclass search reaches its children only through fields both declare the same way. The nested docs say so.
  • Reindexing a parent replaces its old block only on Solr 8 or later. Solr before 8 replaces a document with children by _root_ and one without by id, so a parent whose children went from some to none keeps its old children there, and one whose children went from none to some is indexed twice. The nested docs say so, and the two specs for those cases skip on Solr before 8. That includes the Solr 5.3.1 that sunspot_solr bundles and CI runs, so those two specs skip in every CI job; they pass locally on Solr 9.10.1.

• Schema. The bundled configset gains _root_. Solr refuses a document with children unless the schema defines _root_ with the same field type as the unique key. On Solr 9.10.1 the error is "Unable to index docs with children: the schema must include definitions for both a uniqueKey field and the 'root' field, using the exact same fieldType".

• README. A new "Nested Documents (Block Joins)" section, after "Joins", covers the setup, with_child / without_child, the _root_ schema field and the reindex it needs, and the limits above.

Base

Built on #5, which merged upstream master into the fork and pinned json < 3 for the Rails 6.1/7.0 appraisals. #5 has merged, and this PR now targets master.

Test plan

• spec/api/nested_documents_spec.rb and spec/integration/nested_documents_spec.rb (61 examples): pass on Solr 9.10.1 and 6.6.6 with UPDATE_FORMAT xml and json, in several random orders. On 6.6.6 the two Solr-8 reindex specs skip. The bundled configset doesn't load on Solr 9 (StandardFilterFactory, LatLonType, Trie* fields and defaultSearchField were removed), so the 9.10.1 runs used a local copy with those swapped for their Solr 9 equivalents. That copy isn't part of this PR.
• Under the rsolr-1.x appraisal (27 examples): the child-document specs skip, and indexing a parent with children raises NestedDocumentsNotSupportedError.
• Full suite under both appraisals on Solr 6.6.6: every failure also fails on Merge upstream master into the fork, and keep json below 3 for old Rails #5's branch (upstream master) against the same core.
• Review: a review of the first version found two bugs and four gaps, and two re-reviews found problems in the fixes. Each finding has a spec that failed before its fix: delete by a with_child scope leaving parents on Solr 9; removal through a subclass or superclass leaving children; a subclass's redeclared association invisible to a superclass search; multi-class searches matching or resolving fields by class order; with(record) inside a child block; the _root_ delete passing the boolean clause limit; a subclass's redeclaration breaking superclass searches.
• Glint's suite (https://github.com/culturecode/glint/pull/140) passes against this branch.
• CI on a15caa2: 56 jobs pass.
• Delete-by-id behaviour, checked by hand: on Solr 6.6.6 a child survives its parent's delete by id; on 9.10.1 both are removed.

🤖 Generated with Claude Code

https://claude.ai/code/session_01TAYgm5SknHTiRNTgGA6LBY