You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: solutions/search/get-started/elasticsearch-basics-quickstart.md
+85-91Lines changed: 85 additions & 91 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,28 +3,33 @@ applies_to:
3
3
stack:
4
4
serverless:
5
5
---
6
-
# Basics quickstart [getting-started]
6
+
# Index and search basics
7
7
8
-
9
-
This quick start guide is a hands-on introduction to the fundamental concepts of Elasticsearch: [indices, documents, and field type mappings](../../../manage-data/data-store/index-basics.md). You’ll learn how to create an index, add data as documents, work with dynamic and explicit mappings, and perform your first basic searches.
8
+
This quick start guide is a hands-on introduction to the fundamental concepts of Elasticsearch: indices, documents, and field type mappings.
9
+
You'll learn how to create an index, add data as documents, work with dynamic and explicit mappings, and perform your first basic searches.
10
10
11
11
::::{tip}
12
-
The code examples in this tutorial are in [Console](../../../explore-analyze/query-filter/tools/console.md) syntax by default. You can [convert into other programming languages](../../../explore-analyze/query-filter/tools/console.md#import-export-console-requests) in the Console UI.
12
+
The code examples are in [Console](/explore-analyze/query-filter/tools/console.md) syntax by default. You can [convert into other programming languages](/explore-analyze/query-filter/tools/console.md#import-export-console-requests) in the Console UI.
13
13
14
14
::::
15
15
16
16
## Requirements [getting-started-requirements]
17
17
18
-
You can follow this guide using any {{es}} deployment. If you already have a deployment up and running, you can skip ahead to the [first step](#getting-started-index-creation).
18
+
You can follow this guide using any {{es}} deployment.
19
+
If you already have a deployment up and running, refer to [choose your deployment type](/deploy-manage/deploy.md#choosing-your-deployment-type) for your options.
20
+
To get started quickly, you can spin up a cluster [locally in Docker](/solutions/search/get-started.md).
19
21
20
-
If not, refer to [choose your deployment type](/deploy-manage/deploy.md#choosing-your-deployment-type) for your options. To get started quickly, you can spin up a cluster [locally in Docker](../get-started.md):
22
+
## Add data to {{es}}
21
23
22
-
```sh
23
-
curl -fsSL https://elastic.co/start-local | sh
24
-
```
24
+
::::{tip}
25
+
This quick start uses {{es}} APIs, but there are many other ways to [add data to {{es}}](/solutions/search/ingest-for-search.md).
26
+
::::
25
27
28
+
You add data to {{es}} as JSON objects called documents.
29
+
{{es}} stores these documents in searchable indices.
26
30
27
-
## Step 1: Create an index [getting-started-index-creation]
31
+
:::::{stepper}
32
+
::::{step} Create an index
28
33
29
34
Create a new index named `books`:
30
35
@@ -34,7 +39,8 @@ PUT /books
34
39
35
40
The following response indicates the index was created successfully.
36
41
37
-
::::{dropdown} Example response
42
+
:::{dropdown} Example response
43
+
38
44
```console-result
39
45
{
40
46
"acknowledged": true,
@@ -43,30 +49,11 @@ The following response indicates the index was created successfully.
43
49
}
44
50
```
45
51
52
+
:::
46
53
::::
54
+
::::{step} Add a single document
47
55
48
-
49
-
50
-
## Step 2: Add data to your index [getting-started-add-documents]
51
-
52
-
::::{tip}
53
-
This tutorial uses {{es}} APIs, but there are many other ways to [add data to {{es}}](../ingest-for-search.md).
54
-
55
-
::::
56
-
57
-
58
-
You add data to {{es}} as JSON objects called documents. {{es}} stores these documents in searchable indices.
59
-
60
-
61
-
### Add a single document [getting-started-add-single-document]
62
-
63
-
Submit the following indexing request to add a single document to the `books` index.
64
-
65
-
::::{tip}
66
-
If the index didn’t already exist, this request would automatically create it.
67
-
68
-
::::
69
-
56
+
Submit the following indexing request to add a single document to the `books` index:
70
57
71
58
```console
72
59
POST books/_doc
@@ -78,9 +65,14 @@ POST books/_doc
78
65
}
79
66
```
80
67
68
+
:::{tip}
69
+
If the index didn't already exist, this request would automatically create it.
70
+
:::
71
+
81
72
The response includes metadata that {{es}} generates for the document, including a unique `_id` for the document within the index.
82
73
83
-
::::{dropdown} Example response
74
+
:::{dropdown} Example response
75
+
84
76
```console-result
85
77
{
86
78
"_index": "books", <1>
@@ -101,21 +93,19 @@ The response includes metadata that {{es}} generates for the document, including
101
93
2. The `_id` field is the unique identifier for the document.
102
94
3. The `_version` field indicates the version of the document.
103
95
4. The `result` field indicates the result of the indexing operation.
104
-
5. The `_shards` field contains information about the number of [shards](../../../deploy-manage/index.md) that the indexing operation was executed on and the number that succeeded.
96
+
5. The `_shards` field contains information about the number of [shards](/deploy-manage/index.md) that the indexing operation was executed on and the number that succeeded.
105
97
6. The `total` field indicates the total number of shards for the index.
106
98
7. The `successful` field indicates the number of shards that the indexing operation was executed on.
107
99
8. The `failed` field indicates the number of shards that failed during the indexing operation. *0* indicates no failures.
108
100
9. The `_seq_no` field holds a monotonically increasing number incremented for each indexing operation on a shard.
109
101
10. The `_primary_term` field is a monotonically increasing number incremented each time a primary shard is assigned to a different node.
Use the [`_bulk` endpoint](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-bulk) to add multiple documents in one request. Bulk data must be formatted as newline-delimited JSON (NDJSON).
107
+
Use the [`_bulk` endpoint]({{es-apis}}operation/operation-bulk) to add multiple documents in one request.
108
+
Bulk data must be formatted as newline-delimited JSON (NDJSON).
119
109
120
110
```console
121
111
POST /_bulk
@@ -133,7 +123,8 @@ POST /_bulk
133
123
134
124
You should receive a response indicating there were no errors.
135
125
136
-
::::{dropdown} Example response
126
+
:::{dropdown} Example response
127
+
137
128
```console-result
138
129
{
139
130
"errors": false,
@@ -223,20 +214,15 @@ You should receive a response indicating there were no errors.
223
214
}
224
215
```
225
216
217
+
:::
226
218
::::
219
+
::::{step} Use dynamic mapping
227
220
221
+
[Mappings](/manage-data/data-store/index-basics.md#elasticsearch-intro-documents-fields-mappings) define how data is stored and indexed in {{es}}, like a schema in a relational database.
228
222
229
-
230
-
## Step 3: Define mappings and data types [getting-started-mappings-and-data-types]
231
-
232
-
[Mappings](../../../manage-data/data-store/index-basics.md#elasticsearch-intro-documents-fields-mappings) define how data is stored and indexed in {{es}}, like a schema in a relational database.
233
-
234
-
235
-
### Use dynamic mapping [getting-started-dynamic-mapping]
236
-
237
-
When using dynamic mapping, {{es}} automatically creates mappings for new fields by default. The documents we’ve added so far have used dynamic mapping, because we didn’t specify a mapping when creating the index.
238
-
239
-
To see how dynamic mapping works, add a new document to the `books` index with a field that doesn’t appear in the existing documents.
223
+
If you use dynamic mapping, {{es}} automatically creates mappings for new fields.
224
+
The documents we've added so far have used dynamic mapping, because we didn't specify a mapping when creating the index.
225
+
To see how dynamic mapping works, add a new document to the `books` index with a field that doesn't appear in the existing documents:
240
226
241
227
```console
242
228
POST /books/_doc
@@ -251,14 +237,15 @@ POST /books/_doc
251
237
252
238
1. The new field.
253
239
254
-
255
-
View the mapping for the `books` index with the [Get mapping API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-get-mapping). The new field `language` has been added to the mapping with a `text` data type.
240
+
View the mapping for the `books` index with the [get mapping API]({{es-apis}}operation/operation-indices-get-mapping).
241
+
The new field `language` has been added to the mapping with a `text` data type.
Create an index named `my-explicit-mappings-books` with explicit mappings. Pass each field’s properties as a JSON object. This object should contain the [field data type](elasticsearch://reference/elasticsearch/mapping-reference/field-data-types.md) and any additional [mapping parameters](elasticsearch://reference/elasticsearch/mapping-reference/mapping-parameters.md).
297
+
Create an index named `my-explicit-mappings-books` with explicit mappings. Pass each field's properties as a JSON object. This object should contain the [field data type](elasticsearch://reference/elasticsearch/mapping-reference/field-data-types.md) and any additional [mapping parameters](elasticsearch://reference/elasticsearch/mapping-reference/mapping-parameters.md).
313
298
314
299
```console
315
300
PUT /my-explicit-mappings-books
@@ -326,11 +311,11 @@ PUT /my-explicit-mappings-books
326
311
}
327
312
```
328
313
329
-
1. Disables dynamic mapping for the index. Fields not defined in the mapping will still be stored in the document's `_source` field, but they won’t be indexed or searchable.
314
+
1. Disables dynamic mapping for the index. Fields not defined in the mapping will still be stored in the document's `_source` field, but they won't be indexed or searchable.
330
315
2. The `properties` object defines the fields and their data types for documents in this index.
331
316
317
+
:::{dropdown} Example response
332
318
333
-
::::{dropdown} Example response
334
319
```console-result
335
320
{
336
321
"acknowledged": true,
@@ -339,31 +324,29 @@ PUT /my-explicit-mappings-books
339
324
}
340
325
```
341
326
342
-
::::
343
-
344
-
345
-
346
-
### Combine dynamic and explicit mappings [getting-started-combined-mapping]
347
-
348
-
Explicit mappings are defined at index creation, and documents must conform to these mappings. You can also use the [Update mapping API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-put-mapping). When an index has the `dynamic` flag set to `true`, you can add new fields to documents without updating the mapping.
349
-
350
-
This allows you to combine explicit and dynamic mappings. Learn more about [managing and updating mappings](../../../manage-data/data-store/mapping.md#mapping-manage-update).
351
-
327
+
:::
352
328
353
-
## Step 4: Search your index [getting-started-search-data]
329
+
Explicit mappings are defined at index creation and documents must conform to these mappings. You can also use the [update mapping API]({{es-apis}}operation/operation-indices-put-mapping) to change the mappings.
330
+
When an index has the `dynamic` flag set to `true`, you can add new fields to documents without updating the mapping.
331
+
This allows you to combine explicit and dynamic mappings. Learn more about [managing and updating mappings](/manage-data/data-store/mapping.md#mapping-manage-update).
332
+
::::
333
+
:::::
354
334
355
-
Indexed documents are available for search in near real-time, using the [`_search` API](../querying-for-search.md).
335
+
## Search your index [getting-started-search-data]
356
336
337
+
Indexed documents are available for search in near real-time, using the [`_search` API](/solutions/search/querying-for-search.md).
357
338
358
-
### Search all documents [getting-started-search-all-documents]
339
+
:::::{stepper}
340
+
::::{step} Search all documents
359
341
360
342
Run the following command to search the `books` index for all documents:
361
343
362
344
```console
363
345
GET books/_search
364
346
```
365
347
366
-
::::{dropdown} Example response
348
+
:::{dropdown} Example response
349
+
367
350
```console-result
368
351
{
369
352
"took": 2, <1>
@@ -405,16 +388,13 @@ GET books/_search
405
388
5. The `total` object provides information about the total number of matching documents
406
389
6. The `max_score` field indicates the highest relevance score among all matching documents
407
390
7. The `_index` field indicates the index the document belongs to
408
-
8. The `_id` field is the document’s unique identifier
391
+
8. The `_id` field is the document's unique identifier
409
392
9. The `_score` field indicates the relevance score of the document
410
393
10. The `_source` field contains the original JSON object submitted during indexing
411
394
412
-
395
+
:::
413
396
::::
414
-
415
-
416
-
417
-
### `match` query [getting-started-match-query]
397
+
::::{step} Try a match query
418
398
419
399
You can use the [`match` query](elasticsearch://reference/query-languages/query-dsl/query-dsl-match-query.md) to search for documents that contain a specific value in a specific field. This is the standard query for full-text searches.
420
400
@@ -431,7 +411,12 @@ GET books/_search
431
411
}
432
412
```
433
413
434
-
::::{dropdown} Example response
414
+
:::{tip}
415
+
This example uses [Query DSL](/explore-analyze/query-filter/languages/querydsl.md), which is the primary query language for {{es}}.
416
+
:::
417
+
418
+
:::{dropdown} Example response
419
+
435
420
```console-result
436
421
{
437
422
"took": 9,
@@ -467,16 +452,16 @@ GET books/_search
467
452
468
453
1. The `max_score` is the score of the highest-scoring document in the results. In this case, there is only one matching document, so the `max_score` is the score of that document.
469
454
470
-
455
+
:::
471
456
::::
457
+
:::::
472
458
459
+
## Delete your indices [getting-started-delete-indices]
473
460
461
+
When following along with examples, you might want to delete an index to start from scratch.
462
+
You can delete indices using the [delete index API]({{es-apis}}operation/operation-indices-delete).
474
463
475
-
## Step 5: Delete your indices (optional) [getting-started-delete-indices]
476
-
477
-
When following along with examples, you might want to delete an index to start from scratch. You can delete indices using the [Delete index API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-delete).
478
-
479
-
For example, run the following command to delete the indices created in this tutorial:
464
+
For example, run the following command to delete the indices created in this quick start:
0 commit comments