Foundational Workshop 1 — Elasticsearch: An Index, a Document, a GET Query

Duration

20 min

Module

1/7

Prerequisites

the lab is running (etat shows (healthy) everywhere), Kibana Dev Tools open

You will build

an index of your own, pratique-mini, with two documents that you will read, complete, search, then delete

Deliverable

the response of GET pratique-mini/_doc/1 after step 5, with its three fields

How to read this page. Eight steps, one query at a time. For each: the query to type, the exact response from the lab, and what to look at inside it. Type each query yourself (no copy-paste): it is by writing PUT, GET, _doc that the words sink in. The "To understand better" blocks are optional; open them if a step leaves you in doubt. If the lab is not started, go back to the guided practice: the In Brief section gives the commands, kit included (https://github.com/hrhouma2/aiopsatlas-recherche-graphes-labo-fr).

Objective

The guided practice had you load 504 courses, 609 reviews, and 12,000 log lines in one go, with a script. You saw the numbers, but you have not written anything yourself yet. Here, you start from zero: an empty index that you create, a first record that you file in it, that you read back, that you complete, then a second one, a search, a deletion. At the end, you know what an index and a document are because you built one, not because you were told.

The Vocabulary in One Image

An index is a filing cabinet. A document is a card filed in the cabinet: a small JSON text with fields. Each card has a number, its _id, which lets you retrieve it directly without searching. You do not have to declare the columns in advance: the first card filed creates the mapping (the cabinet's blueprint) by itself.

Where to Type, and How to Read a Query

Open http://localhost:5601, ☰ menu → Management → Dev Tools. The left panel receives the queries, the right one displays the response. You send with Ctrl + Enter (Cmd + Enter on macOS) or the ▶ button to the right of the line.

Every query has the same shape: a verb, a path, and sometimes a JSON body underneath.

The path says what we act on: pratique-mini (the cabinet), pratique-mini/_doc/1 (card number 1 of the cabinet), pratique-mini/_search (search in the cabinet). Words that start with _ are Elasticsearch commands, not names of yours.

Step 1 — Create the Cabinet, Empty

PUT pratique-mini

What the query asks: create an index named pratique-mini. Nothing else: no columns, no content.

{
  "acknowledged": true,
  "shards_acknowledged": true,
  "index": "pratique-mini"
}

What to look at: "acknowledged": true, "done", and the name echoed back. The badge at the top right of the response says 200 - OK.

Step 2 — See It, and Fix Its Color

GET _cat/indices/pratique-mini?v

What the query asks: one summary line about this index, with the header line (?v, verbose).

health status index         uuid                   pri rep docs.count docs.deleted store.size pri.store.size dataset.size
yellow open   pratique-mini YHjAfGXBTwSZcl7CLcc2jw   1   1          0            0       227b           227b         227b

What to look at: docs.count 0, the cabinet is empty. And health yellow with rep 1: Elasticsearch has planned a backup copy (a replica) of your index on a second machine, and the lab has only one. The copy cannot be placed anywhere, hence the yellow. The kit's three indexes are green because their mapping sets number_of_replicas: 0. Do the same, in one query:

PUT pratique-mini/_settings
{
  "index": { "number_of_replicas": 0 }
}

{
  "acknowledged": true
}

Retype GET _cat/indices/pratique-mini?v:

health status index         uuid                   pri rep docs.count docs.deleted store.size pri.store.size dataset.size
green  open   pratique-mini YHjAfGXBTwSZcl7CLcc2jw   1   0          0            0       227b           227b         227b

What to look at: green, rep 0. Your uuid will be different: it is the index's internal identifier, drawn at random on creation.

Step 3 — File a First Card

PUT pratique-mini/_doc/1
{
  "titre": "Mon premier document"
}

What the query asks: in the pratique-mini cabinet, file a card (_doc) number 1 that contains a titre field.

{
  "_index": "pratique-mini",
  "_id": "1",
  "_version": 1,
  "result": "created",
  "_shards": {
    "total": 1,
    "successful": 1,
    "failed": 0
  },
  "_seq_no": 0,
  "_primary_term": 1
}

What to look at: "result": "created" and "_version": 1: first version of card 1. SQL equivalent: INSERT INTO pratique_mini (id, titre) VALUES (1, 'Mon premier document'), except that no CREATE TABLE was necessary.

Step 4 — Read the Card Back

GET pratique-mini/_doc/1

What the query asks: give me card number 1 of pratique-mini, directly, without searching.

{
  "_index": "pratique-mini",
  "_id": "1",
  "_version": 1,
  "_seq_no": 0,
  "_primary_term": 1,
  "found": true,
  "_source": {
    "titre": "Mon premier document"
  }
}

What to look at: "found": true, and _source, your card exactly as you wrote it, to the character. SQL equivalent: SELECT * FROM pratique_mini WHERE id = 1.

Try a card that does not exist: GET pratique-mini/_doc/3.

{
  "_index": "pratique-mini",
  "_id": "3",
  "found": false
}

No error, no _source: "found": false, badge 404 - Not Found. Elasticsearch understood the question; the answer is "there is nothing at this number".

Step 5 — Add Values to the Card

POST pratique-mini/_update/1
{
  "doc": {
    "auteur": "Alice",
    "note": 5
  }
}

What the query asks: update (_update) card 1 by adding these two fields. What is not mentioned (titre) stays as it is.

{
  "_index": "pratique-mini",
  "_id": "1",
  "_version": 2,
  "result": "updated",
  "_shards": {
    "total": 1,
    "successful": 1,
    "failed": 0
  },
  "_seq_no": 1,
  "_primary_term": 1
}

What to look at: "result": "updated", "_version": 2. Read the card back with GET pratique-mini/_doc/1:

{
  "_index": "pratique-mini",
  "_id": "1",
  "_version": 2,
  "_seq_no": 1,
  "_primary_term": 1,
  "found": true,
  "_source": {
    "titre": "Mon premier document",
    "note": 5,
    "auteur": "Alice"
  }
}

Three fields. The title is still there. SQL equivalent: UPDATE pratique_mini SET auteur = 'Alice', note = 5 WHERE id = 1, with the difference that in SQL the auteur and note columns would have had to exist beforehand. This is your deliverable response: keep it.

Step 6 — The Trap: PUT Replaces Everything

Send exactly the query of step 3 again:

PUT pratique-mini/_doc/1
{
  "titre": "Mon premier document"
}

{
  "_index": "pratique-mini",
  "_id": "1",
  "_version": 3,
  "result": "updated",
  "_shards": {
    "total": 1,
    "successful": 1,
    "failed": 0
  },
  "_seq_no": 3,
  "_primary_term": 1
}

What to look at: "result": "updated" (not created: card 1 existed) and "_version": 3. Then read it back:

{
  "_index": "pratique-mini",
  "_id": "1",
  "_version": 3,
  "_seq_no": 3,
  "_primary_term": 1,
  "found": true,
  "_source": {
    "titre": "Mon premier document"
  }
}

auteur and note are gone. PUT _doc/1 does not modify card 1: it replaces it with what you send. To complete without losing anything, use POST _update/1 with doc. Remember the rule with the two verbs: PUT replaces, _update completes. Put the two fields back with the query of step 5 before continuing (you get _version: 4).

Step 7 — A Second Card, Count, Search

PUT pratique-mini/_doc/2
{
  "titre": "Deuxième document, écrit par Bob",
  "auteur": "Bob",
  "note": 3
}

Response: "_id": "2", "result": "created", "_version": 1. Then count:

GET pratique-mini/_count

{
  "count": 2,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  }
}

SQL equivalent: SELECT COUNT(*) FROM pratique_mini. Now, see everything that is in it:

GET pratique-mini/_search

What the query asks: search in pratique-mini, with no criterion, so everything.

{
  "took": 2,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 2,
      "relation": "eq"
    },
    "max_score": 1.0,
    "hits": [
      {
        "_index": "pratique-mini",
        "_id": "2",
        "_score": 1.0,
        "_source": {
          "titre": "Deuxième document, écrit par Bob",
          "auteur": "Bob",
          "note": 3
        }
      },
      {
        "_index": "pratique-mini",
        "_id": "1",
        "_score": 1.0,
        "_source": {
          "titre": "Mon premier document",
          "note": 5,
          "auteur": "Alice"
        }
      }
    ]
  }
}

What to look at: hits.total.value: 2 (how many cards match) then hits.hits, the list of cards, each with its _id and its _source. The order of the two may vary: with no criterion, all have the same _score of 1.0. SQL equivalent: SELECT * FROM pratique_mini.

Finally, search for a word:

GET pratique-mini/_search
{
  "query": {
    "match": {
      "titre": "premier"
    }
  }
}

What the query asks: the cards whose titre field contains the word premier.

{
  "took": 1,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "max_score": 0.3788134,
    "hits": [
      {
        "_index": "pratique-mini",
        "_id": "1",
        "_score": 0.3788134,
        "_source": {
          "titre": "Mon premier document",
          "note": 5,
          "auteur": "Alice"
        }
      }
    ]
  }
}

What to look at: a single card, number 1, and a _score that is no longer 1.0: this is relevance, "how well this card answers the question". Module 3 is devoted to this number. Approximate SQL equivalent: SELECT * FROM pratique_mini WHERE titre LIKE '%premier%', except that match would also find Premier with a capital letter, and module 2 will explain why.

Step 8 — Delete a Card, Then the Cabinet

DELETE pratique-mini/_doc/2

{
  "_index": "pratique-mini",
  "_id": "2",
  "_version": 2,
  "result": "deleted",
  "_shards": {
    "total": 1,
    "successful": 1,
    "failed": 0
  },
  "_seq_no": 4,
  "_primary_term": 1
}

What to look at: "result": "deleted". GET pratique-mini/_count returns 1 (after one second). SQL equivalent: DELETE FROM pratique_mini WHERE id = 2.

Then delete the entire cabinet, cards included:

DELETE pratique-mini

{
  "acknowledged": true
}

Proof that it no longer exists, GET pratique-mini/_doc/1:

{
  "error": {
    "root_cause": [
      {
        "type": "index_not_found_exception",
        "reason": "no such index [pratique-mini]",
        "resource.type": "index_or_alias",
        "resource.id": "pratique-mini",
        "index_uuid": "_na_",
        "index": "pratique-mini"
      }
    ],
    "type": "index_not_found_exception",
    "reason": "no such index [pratique-mini]",
    "resource.type": "index_or_alias",
    "resource.id": "pratique-mini",
    "index_uuid": "_na_",
    "index": "pratique-mini"
  },
  "status": 404
}

What to look at: the difference with step 4. Missing card in an existing cabinet: "found": false, no error. Missing cabinet: index_not_found_exception, 404. Both are normal responses from a running service. SQL equivalent: DROP TABLE pratique_mini.

Final Check

GET _cat/indices/pratique-*?v

Expected response: the header line alone. Nothing of yours is left lying around in the cluster, and GET _cat/indices/cours,avis,acces?v still shows 504, 609, 12000.

• You created pratique-mini and you know why it was yellow, then green.
• You filed card 1 with PUT _doc/1 and read it back with GET _doc/1.
• You added auteur and note with POST _update/1 without losing titre.
• You saw PUT _doc/1 erase the two fields, and you can state the rule: PUT replaces, _update completes.
• _count said 2, _search listed both cards, match kept only one.
• You deleted card 2 then the index, and pratique-* is empty.
• You kept the three-field response of GET pratique-mini/_doc/1 (step 5) as the deliverable.

If Something Goes Wrong