The join query syntax takes two attributes, to and from, both of which accept field names as their values. The from field is used to link matching documents (those that matched the join query) to documents that match the to field. Not surprisingly, the join parser also requires a query. This query parser also supports joining across cores through its fromIndex option. As an example, let's say we'd like to fetch a set of documents from the mbartists core, where the artist has a certain release from the mbreleases core:

http://localhost:8983/solr/mbartists/select?q={!join from=r_a_id to=a_id fromIndex=mbreleases}r_id:139850&fl=type,a_id

The following is the syntax:

{!join from=r_a_id to=a_id fromIndex=mbreleases}r_id:139850

The resulting documents would be something like:

<result name="response" numFound="1" start="0">
  <doc>
    <str name="type">Artist</str>
    <long name="a_id">11650</long>
  </doc>
</result>

For completeness, here's the same query using SQL:

SELECT type,a_id FROM mbartists a where a.a_id IN (SELECT r.r_a_id FROM mbreleases r where r.r_id = 139850);

The field type of the from and to fields should be the same.

Here's another example showing a join between more than one core/index within the same query. This also makes use of the special local-params v attribute (the query):

fq={!join from=childId1 to=primaryCoreId fromIndex=childCore1 v=$childQ1} AND {!join from=childId2 to=primaryCoreId fromIndex=childCore2 v=$childQ2}&childQ1=(field1:abc AND field2:[0 TO 1234])&childQ2=(field3:xyz)

One use of the Solr join is to put your volatile data in one core, and the more static in another core, using joins to associate records at query time.

Join queries have no influence on relevancy or document scores. If you're up for customizing Solr though, the Lucene join module contains a scoring join query, which could be used with little effort.

It should be noted that join queries can be slow; the more matching IDs there are, the longer the response time will become. In many cases, a carefully designed schema can satisfy most requirements by making good use of denormalization instead of joining.

Block-join is called as such because it requires subdocuments to be indexed together in one block with the parent, which trickles down to the underlying index. You can even have a nested hierarchy. But this index requirement is a big limitation—you can't update any one document without updating an entire tree from a parent, and you can't use atomic updates. But for this trade-off, you get very fast joins.

Chapter 4, Indexing Data, covers the details on nested documents, but we'll provide a simple example here. Our sample nested-docs.json file contains the following JSON:

{
  "add": [{
    "id": "1",
    "title_t": "Node A",
    "relType_s": "parent",
    "_childDocuments_": [{
      "id": "2",
      "title_t": "Node A:A"
    }]
  }, {
    "id": "3",
    "title_t": "Node B",
    "relType_s": "parent",
    "_childDocuments_": [{
      "id": "4",
      "title_t": "Node B:B"
    }]
  }]
}

As you can see, the relationships are all self-contained within the special childDocuments_ array field. To index, we can simply use curl:

curl -H 'content-type: application/json' -X POST "http://127.0.0.1:8983/solr/collection1/update?commit=true" --data-binary @nested-docs.json

Now that we have our nested documents indexed, we can query them using the block-join query parsers. There are actually two: block-join-parent and block-join-children. These parsers are quite different from the aforementioned join parser. Instead of returning documents matching a field-based foreign key, we use a query to identify parent/child documents to which we then apply a query to fetch the related results.

http://localhost:8983/solr/collection1/select?q={!child of="relType_s:parent"}title_t:"Node A"&wt=json&omitHeader=true

{!child of="relType_s:parent"}title_t:"Node A"

{
  "response": {
    "numFound": 1,
    "start": 0,
    "docs": [
      {
        "id": "2",
        "title_t": "Node A:A"
      }
    ]
  }
}

http://localhost:8983/solr/collection1/select?q={!parent which="relType_s:parent"}title_t:"Node A:A"&wt=json&omitHeader=true

{!parent which="relType_s:parent"}title_t:"Node A:A"

{
  "response": {
    "numFound": 1,
    "start": 0,
      "docs": [
        {
            "id": "1",
            "title_t": "Node A",
            "relType_s": "parent",
            "_version_": 1492571473528750000
        }
    ]
  }
}