Turns out that I was using NestedChildren wrong. Here is the answer I get from Matt Chaput in Google Groups:
I'm making a search index which must support nested hierarchies of data.
The second parameter to NestedChildren isn't what you think it is.
TL;DR: you're using the wrong query type. Let me know what you're trying to do, and I can tell you how to do it :)
ABOUT NESTED CHILDREN
(Note, I found a bug, see the end)
NestedChildren is hard to understand, but hopefully I can try to explain it better.
NestedChildren is about searching for certain PARENTS, but getting their CHILDREN as the hits.
The first argument is a query that matches all documents of the "parent" class (e.g. "type:book"). The second argument is a query that matches all documents of the parent class that match your search criteria (e.g. "type:book AND name:dark").
In you example, this would mean searching for a certain book, but getting its chapters as the search results.
This isn't super useful on its own, but you can combine it with queries on the children to do complex queries like "show me chapters with 'hunt' in their names that are in books with 'dark' in their names":
# Find the children of books matching the book criterion
all_parents = query.Term("type", "book")
wanted_parents = query.Term("name", "dark")
children_of_wanted_parents = query.NestedChildren(all_parents, wanted_parents)
# Find the children matching the chapter criterion
wanted_chapters = query.And([query.Term("type", "chapter"),
query.Term("name", "hunted")])
# The intersection of those two queries are the chapters we want
complex_query = query.And([children_of_wanted_parents,
wanted_children])
OR, at least, that's how it SHOULD work. But I just found a bug in the implementation of NestedChildren's skip_to() method that makes the above example not work :( :( :( The bug is now fixed on Bitbucket, I'll have to make a new release.
Cheers,
Matt