Support for nested documents (closes #210)

Thanks to @efagerberg, @msokolov, and @thisisstephenbetts for the patch!

Author: acdha

README.rst

@@ -7,7 +7,6 @@ interface that queries the server and returns results based on the query.
 
 .. _`Apache Solr`: http://lucene.apache.org/solr/
 
-
 Status
 ======
 
@@ -64,12 +63,21 @@ Basic usage looks like:
         {
             "id": "doc_2",
             "title": "The Banana: Tasty or Dangerous?",
+            "_doc": [
+                { "id": "child_doc_1", "title": "peel" },
+                { "id": "child_doc_2", "title": "seed" },
+            ]
         },
     ])
     
     # Note that the add method has commit=True by default, so this is 
     # immediately committed to your index.
 
+    # You can index a parent/child document relationship by
+    # associating a list of child documents with the special key '_doc'. This
+    # is helpful for queries that join together conditions on children and parent
+    # documents.
+
     # Later, searching is easy. In the simple case, just a plain Lucene-style
     # query is fine.
     results = solr.search('bananas')

pysolr.py

@@ -824,6 +824,11 @@ def _build_doc(self, doc, boost=None, fieldUpdates=None):
                 if self._is_null_value(bit):
                     continue
 
+                if key == '_doc':
+                    child = self._build_doc(bit, boost)
+                    doc_elem.append(child)
+                    continue
+
                 attrs = {'name': key}
 
                 if fieldUpdates and key in fieldUpdates:

tests/test_client.py

@@ -544,6 +544,37 @@ def test__build_doc(self):
         self.assertTrue('<field name="id">doc_1</field>' in doc_xml)
         self.assertEqual(len(doc_xml), 152)
 
+    def test__build_doc_with_sub_docs(self):
+        sub_docs = [
+            {
+                'id': 'sub_doc_1',
+                'title': 'Example sub doc ☃ 1',
+                'price': 1.59,
+                'popularity': 4
+            },
+            {
+                'id': 'sub_doc_2',
+                'title': 'Example sub doc ☃ 2',
+                'price': 21.13,
+                'popularity': 1
+            },
+        ]
+        doc = {
+            'id': 'doc_1',
+            'title': 'Example doc ☃ 1',
+            'price': 12.59,
+            'popularity': 10,
+            '_doc': sub_docs
+        }
+        doc_xml = self.solr._build_doc(doc)
+        self.assertEqual(doc_xml.find("*[@name='id']").text, doc['id'])
+
+        children_docs = doc_xml.findall('doc')
+        self.assertEqual(len(children_docs), len(sub_docs))
+
+        self.assertEqual(children_docs[0].find("*[@name='id']").text, sub_docs[0]['id'])
+        self.assertEqual(children_docs[1].find("*[@name='id']").text, sub_docs[1]['id'])
+
     def test_add(self):
         self.assertEqual(len(self.solr.search('doc')), 3)
         self.assertEqual(len(self.solr.search('example')), 2)