stats:​documents

Returns statistics related to the list of documents you provide. Typically, the count of documents in the referenced stage. An optional matches element may contain the total hit count and information whether the total is approximate or exact.

{
  "type": "stats:documents",
  "documents": {
    "type": "documents:reference",
    "auto": true
  }
}

For example, this request asks for an exact count of documents matching the query photon:

{
  "stages": {
    "stats": {
      "type": "stats:documents",
      "documents": {
        "type": "documents:byQuery",
        "query": {
          "type": "query:string",
          "query": "photon"
        },
        "limit": 10,
        "accurateHitCount": true
      }
    }
  }
}

The response for the above request contains the number of documents contained by the nested documents:​by​Query stage (10, as per the requested limit) and the total number of matches in the index:

{
  "result" : {
    "stats" : {
      "count" : 10,
      "matches" : {
        "value" : 13718,
        "relation" : "EXACT"
      }
    }
  }
}

The document count returned by the stats:​documents stage is particularly useful when the number of documents cannot be determined in advance. For example, consider this request, which displays statistics for the documents:​sample stage:

{
  "stages": {
    "stats": {
      "type": "stats:documents",
      "documents": {
        "type": "documents:sample",
        "query": {
          "type": "query:string",
          "query": "photon"
        },
        "randomSeed": 1,
        "samplingRatio": 0.1,
        "limit": "unlimited"
      }
    }
  }
}

In this case, both the number of matching documents, and the number of documents returned within the sample, are hard to predict. The output for this request reveals both:

{
  "result" : {
    "stats" : {
      "count" : 1371,
      "matches" : {
        "value" : 13718,
        "relation" : "EXACT"
      }
    }
  }
}