Query DSL TrainerBETA
Course contents
How Elasticsearch works · 2 / 28

Documents, indices and APIs

Learn document addressing and search responses. An Elasticsearch index is a collection with a shared mapping, not an individual SQL index.

4 sectionsElasticsearch 9.4.3Not read yet

What you will learn

  • The search unit
  • The HTTP contract
  • Reading hits

Learn document addressing and search responses. An Elasticsearch index is a collection with a shared mapping, not an individual SQL index.

course-products examples use the teaching mapping and product from chapter 5, “Mapping and field types”. Exercise walkthroughs below use the trainer’s separate public dataset.

Chapter map
  • The search unit
  • The HTTP contract
  • Reading hits

Learn document addressing and search responses. An Elasticsearch index is a collection with a shared mapping, not an individual SQL index.

The course targets Elasticsearch 9.4.3. Exercise examples use the public products dataset; other requests illustrate separate teaching indices and may require setup or privileges unavailable in the trainer. Responses are shortened fragments; scores may vary. Check deployment and license requirements for advanced features.

01 / 04

The search unit

A document contains JSON fields and an index defines how to interpret them. An _id is unique within an index, not across indices. _source holds the document representation, not the searchable index itself. Stable product identifiers make repeated delivery update the same entity rather than create duplicates.

Check your understanding
02 / 04

The HTTP contract

GET /products/_doc/sku-1 retrieves a document by ID; POST /products/_search searches. PUT with an ID indexes a new representation, while _update has a separate contract. HTTP status describes the request outcome, but a bulk request can return 200 while individual operations fail. Always inspect the response body.

Check your understanding
03 / 04

Reading hits

hits.hits contains the current page; hits.total describes the match count. relation=eq is exact while gte is a lower bound. took measures server-side search work, not the full user-visible network latency. _shards and timed_out reveal incomplete execution: HTTP 200 alone does not prove completeness.

A single-document response has no hits wrapper.

GET /course-products/_doc/sku-1
Elasticsearch response
Shortened response · JSON
{
  "_index": "course-products",
  "_id": "sku-1",
  "found": true,
  "_source": {
    "name": "Running headphones",
    "price": 99
  }
}

How to read this result

A single-document response has no hits wrapper.

Check your understanding
04 / 04

Catalog reasoning example

Suppose size=10 returns ten hits and total={value:10000, relation:"gte"}. This does not establish exactly ten thousand matches. The UI can display “10,000+”; an exact count requires a deliberate track_total_hits=true decision and its cost. A failed shard can leave a plausible partial response. Decide whether partial results are allowed and check that contract independently of HTTP status.

Check your understanding

Check your understanding

Answer before expanding each explanation.

1. Where is _id unique?

Within one index.

2. What does _source contain?

The document representation, not the inverted index.

3. Why can hits.hits be shorter than hits.total?

One is a page; the other is a count or lower bound.

4. What does gte mean?

The actual count is at least the reported value.

5. Is HTTP 200 sufficient?

No: inspect timeouts, shard failures and individual bulk results.

Key takeaways

  • Within one index.
  • The document representation, not the inverted index.
  • One is a page; the other is a count or lower bound.
  • The actual count is at least the reported value.
  • No: inspect timeouts, shard failures and individual bulk results.

Official reference

Ready to put this into practice?

Confirm reading to save your place. Reading and exercise progress are tracked separately in this browser using your guest cookie.