Skip to content

Commit 98e775f

Browse files
lcawllcawl
authored
Move Elasticsearch basics to Get started (#2245)
1 parent 9058bff commit 98e775f

File tree

5 files changed

+82
-91
lines changed

5 files changed

+82
-91
lines changed

‎explore-analyze/query-filter.md

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -26,8 +26,7 @@ You’ll use a combination of an API endpoint and a query language to interact w
2626

2727
- A number of [tools](/explore-analyze/query-filter/tools.md) are available for you to save, debug, and optimize your queries.
2828

29-
% todo: update link to the best target
30-
If you're just getting started with Elasticsearch, try the hands-on [API quickstart](/solutions/search/elasticsearch-basics-quickstart.md) to learn how to add data and run basic searches using Query DSL and the `_search` endpoint.
29+
If you're just getting started with {{es}}, try the hands-on [](/solutions/search/get-started/index-basics.md) to learn how to add data and run basic searches using Query DSL and the `_search` endpoint.
3130

3231
## Filtering
3332

‎redirects.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -308,3 +308,5 @@ redirects:
308308
'solutions/security/configure-elastic-defend/enable-access-for-macos-monterey.md': 'solutions/security/configure-elastic-defend/enable-access-for-macos.md'
309309
'solutions/security/configure-elastic-defend/enable-access-for-macos-ventura-higher.md': 'solutions/security/configure-elastic-defend/enable-access-for-macos.md'
310310

311+
# Related to https://github.com/elastic/docs-content/pull/2245/
312+
'solutions/search/elasticsearch-basics-quickstart.md': 'solutions/search/get-started/index-basics.md'

‎solutions/search/api-quickstarts.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ Prefer working in Python? Check out our executable [Python notebooks](https://gi
1515

1616
Use the following quickstarts to get hands-on experience with Elasticsearch APIs and tools:
1717

18-
- [Index and search data using Elasticsearch APIs](elasticsearch-basics-quickstart.md): Learn about indices, documents, and mappings, and perform a basic search using the Query DSL.
18+
- [Index and search data using Elasticsearch APIs](get-started/index-basics.md): Learn about indices, documents, and mappings, and perform a basic search using the Query DSL.
1919
- [Basic full-text search and filtering in Elasticsearch](querydsl-full-text-filter-tutorial.md): Learn about different options for querying data, including full-text search and filtering, using the Query DSL.
2020
- [Analyze eCommerce data with aggregations using Query DSL](/explore-analyze/query-filter/aggregations/tutorial-analyze-ecommerce-data-with-aggregations-using-query-dsl.md): Learn how to analyze data using different types of aggregations, including metrics, buckets, and pipelines.
2121
% - [Getting started with {{esql}}](esql-getting-started.md): Learn how to query and aggregate your data using {{esql}}.

‎solutions/search/elasticsearch-basics-quickstart.md renamed to ‎solutions/search/get-started/index-basics.md

Lines changed: 77 additions & 87 deletions
Original file line numberDiff line numberDiff line change
@@ -3,26 +3,32 @@ applies_to:
33
stack:
44
serverless:
55
---
6-
# Basics quickstart [getting-started]
6+
# Index and search basics
77

8-
9-
This quickstart provides a hands-on introduction to the fundamental concepts of {{es}}: [indices, documents, and field type mappings](../../manage-data/data-store/index-basics.md). You'll learn how to create an index, add documents, work with dynamic and explicit mappings, and perform your first basic searches.
8+
This quickstart provides a hands-on introduction to the fundamental concepts of {{es}}: [indices, documents, and field type mappings](../../../manage-data/data-store/index-basics.md). You'll learn how to create an index, add documents, work with dynamic and explicit mappings, and perform your first basic searches.
109

1110
::::{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.
13-
11+
The code examples are in [Console](/explore-analyze/query-filter/tools/console.md) syntax by default.
12+
You can [convert into other programming languages](/explore-analyze/query-filter/tools/console.md#import-export-console-requests) in the Console UI.
1413
::::
1514

1615
## Requirements [getting-started-requirements]
1716

18-
You can follow this guide using any {{es}} deployment. If you have a deployment ready, skip ahead to the [first step](#getting-started-index-creation). If not, refer to [choose your deployment type](/deploy-manage/deploy.md#choosing-your-deployment-type) to see all deployment options. To get started quickly, spin up a cluster [locally in Docker](run-elasticsearch-locally.md):
17+
You can follow this guide using any {{es}} deployment.
18+
To see all deployment options, refer to [](/deploy-manage/deploy.md#choosing-your-deployment-type).
19+
To get started quickly, spin up a cluster [locally in Docker](/solutions/search/run-elasticsearch-locally.md).
1920

20-
```sh
21-
curl -fsSL https://elastic.co/start-local | sh
22-
```
21+
## Add data to {{es}} [getting-started-index-creation]
2322

23+
::::{tip}
24+
This quickstart uses {{es}} APIs, but there are many other ways to [add data to {{es}}](/solutions/search/ingest-for-search.md).
25+
::::
26+
27+
You add data to {{es}} as JSON objects called documents.
28+
{{es}} stores these documents in searchable indices.
2429

25-
## Step 1: Create an index [getting-started-index-creation]
30+
:::::{stepper}
31+
::::{step} Create an index
2632

2733
Create a new index named `books`:
2834

@@ -32,7 +38,8 @@ PUT /books
3238

3339
The following response indicates the index was created successfully.
3440

35-
::::{dropdown} Example response
41+
:::{dropdown} Example response
42+
3643
```console-result
3744
{
3845
"acknowledged": true,
@@ -41,29 +48,13 @@ The following response indicates the index was created successfully.
4148
}
4249
```
4350

51+
:::
4452
::::
45-
46-
## Step 2: Add data to your index [getting-started-add-documents]
47-
48-
::::{tip}
49-
This tutorial uses {{es}} APIs, but there are many other ways to [add data to {{es}}](ingest-for-search.md).
50-
51-
::::
52-
53-
54-
You add data to {{es}} as JSON objects called documents. {{es}} stores these documents in searchable indices.
55-
56-
57-
### Add a single document [getting-started-add-single-document]
53+
::::{step} Add a single document
5854

5955
Use the following request to add a single document to the `books` index.
60-
61-
::::{note}
6256
If the index doesn't already exist, this request will automatically create it.
6357

64-
::::
65-
66-
6758
```console
6859
POST books/_doc
6960
{
@@ -76,7 +67,8 @@ POST books/_doc
7667

7768
The response includes metadata that {{es}} generates for the document, including a unique `_id` for the document within the index.
7869

79-
::::{dropdown} Example response
70+
:::{dropdown} Example response
71+
8072
```console-result
8173
{
8274
"_index": "books", <1>
@@ -97,19 +89,18 @@ The response includes metadata that {{es}} generates for the document, including
9789
2. `_id`: The unique identifier for the document.
9890
3. `_version`: The version of the document.
9991
4. `result`: The result of the indexing operation.
100-
5. `_shards`: Information about the number of [shards](../../deploy-manage/distributed-architecture/clusters-nodes-shards.md) that the indexing operation was executed on and the number that succeeded.
92+
5. `_shards`: Information about the number of [shards](/deploy-manage/distributed-architecture/clusters-nodes-shards.md) that the indexing operation was executed on and the number that succeeded.
10193
6. `total`: The total number of shards for the index.
10294
7. `successful`: The number of shards that the indexing operation was performed on.
10395
8. `failed`: The number of shards that failed during the indexing operation. *0* indicates no failures.
10496
9. `_seq_no`: A monotonically increasing number incremented for each indexing operation on a shard.
10597
10. `_primary_term`: A monotonically increasing number incremented each time a primary shard is assigned to a different node.
106-
107-
98+
:::
10899
::::
100+
::::{step} Add multiple documents
109101

110-
### Add multiple documents [getting-started-add-multiple-documents]
111-
112-
Use the [`_bulk` endpoint](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-bulk) to add multiple documents in a single request. Bulk data must be formatted as newline-delimited JSON (NDJSON).
102+
Use the [`_bulk` endpoint]({{es-apis}}operation/operation-bulk) to add multiple documents in a single request.
103+
Bulk data must be formatted as newline-delimited JSON (NDJSON).
113104

114105
```console
115106
POST /_bulk
@@ -124,9 +115,11 @@ POST /_bulk
124115
{ "index" : { "_index" : "books" } }
125116
{"name": "The Handmaids Tale", "author": "Margaret Atwood", "release_date": "1985-06-01", "page_count": 311}
126117
```
118+
127119
You should receive a response indicating there were no errors.
128120

129-
::::{dropdown} Example response
121+
:::{dropdown} Example response
122+
130123
```console-result
131124
{
132125
"errors": false,
@@ -216,18 +209,14 @@ You should receive a response indicating there were no errors.
216209
}
217210
```
218211

212+
:::
219213
::::
214+
::::{step} Use dynamic mapping
220215

216+
[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.
221217

222-
223-
## Step 3: Define mappings [getting-started-mappings-and-data-types]
224-
225-
[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.
226-
227-
228-
### Use dynamic mapping [getting-started-dynamic-mapping]
229-
230-
When you use dynamic mapping, {{es}} automatically creates mappings for new fields by default. The documents you’ve added so far have used dynamic mapping, because you didn’t specify a mapping while creating the index.
218+
If you use dynamic mapping, {{es}} automatically creates mappings for new fields.
219+
The documents you've added so far have used dynamic mapping, because you didn't specify a mapping while creating the index.
231220

232221
To see how dynamic mapping works, add a new document to the `books` index with a field that isn't available in the existing documents.
233222

@@ -244,13 +233,15 @@ POST /books/_doc
244233

245234
1. The new field.
246235

247-
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.
236+
View the mapping for the `books` index with the [get mapping API]({{es-apis}}operation/operation-indices-get-mapping).
237+
The new field `language` has been added to the mapping with a `text` data type.
248238

249239
```console
250240
GET /books/_mapping
251241
```
242+
252243
The following response displays the mappings that were created by {{es}}.
253-
::::{dropdown} Example response
244+
:::{dropdown} Example response
254245

255246
```console-result
256247
{
@@ -295,14 +286,13 @@ The following response displays the mappings that were created by {{es}}.
295286
}
296287
}
297288
```
298-
289+
:::
299290
::::
291+
::::{step} Define explicit mapping
300292

301-
302-
303-
### Define explicit mapping [getting-started-explicit-mapping]
304-
305-
Create an index named `my-explicit-mappings-books` and specify the mappings yourself. 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).
293+
Create an index named `my-explicit-mappings-books` and specify the mappings yourself.
294+
Pass each field's properties as a JSON object.
295+
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).
306296

307297
```console
308298
PUT /my-explicit-mappings-books
@@ -319,44 +309,41 @@ PUT /my-explicit-mappings-books
319309
}
320310
```
321311

322-
1. `dynamic`: Disables dynamic mapping for the index. If you don't define fields in the mapping, they'll still be stored in the document's `_source` field, but you can't index or search them.
312+
1. `dynamic`: Turns off dynamic mapping for the index. If you don't define fields in the mapping, they'll still be stored in the document's `_source` field, but you can't index or search them.
323313
2. `properties`: Defines the fields and their corresponding data types.
324314

325315
The following response indicates a successful operation.
326-
::::{dropdown} Example response
316+
:::{dropdown} Example response
327317
```console-result
328318
{
329319
"acknowledged": true,
330320
"shards_acknowledged": true,
331321
"index": "my-explicit-mappings-books"
332322
}
333323
```
324+
:::
334325

326+
Explicit mappings are defined at index creation, and documents must conform to these mappings.
327+
You can also use the [update mapping API]({{es-apis}}operation/operation-indices-put-mapping).
328+
When an index has the `dynamic` flag set to `true`, you can add new fields to documents without updating the mapping, which allows you to combine explicit and dynamic mappings.
329+
Learn more about [managing and updating mappings](/manage-data/data-store/mapping.md#mapping-manage-update).
335330
::::
331+
:::::
336332

333+
## Search your data [getting-started-search-data]
337334

335+
Indexed documents are available for search in near real-time, using the [`_search` API](/solutions/search/querying-for-search.md).
338336

339-
### Combine dynamic and explicit mappings [getting-started-combined-mapping]
340-
341-
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.
342-
343-
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).
344-
345-
346-
## Step 4: Search your data [getting-started-search-data]
347-
348-
Indexed documents are available for search in near real-time, using the [`_search` API](querying-for-search.md).
349-
350-
351-
### Search all documents [getting-started-search-all-documents]
337+
:::::{stepper}
338+
::::{step} Search all documents
352339

353340
Use the following request to search all documents in the `books` index:
354341

355342
```console
356343
GET books/_search
357344
```
358345

359-
::::{dropdown} Example response
346+
:::{dropdown} Example response
360347
```console-result
361348
{
362349
"took": 2, <1>
@@ -398,14 +385,13 @@ GET books/_search
398385
5. `total`: Information about the total number of matching documents
399386
6. `max_score`: The highest relevance score among all matching documents
400387
7. `_index`: The index the document belongs to
401-
8. `_id`: The document’s unique identifier
388+
8. `_id`: The document's unique identifier
402389
9. `_score`: The relevance score of the document
403390
10. `_source`: The original JSON object submitted during indexing
404391

405-
392+
:::
406393
::::
407-
408-
### Search using `match` query [getting-started-match-query]
394+
::::{step} Search with a match query
409395

410396
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.
411397

@@ -422,7 +408,11 @@ GET books/_search
422408
}
423409
```
424410

425-
::::{dropdown} Example response
411+
:::{tip}
412+
This example uses [Query DSL](/explore-analyze/query-filter/languages/querydsl.md), which is the primary query language for {{es}}.
413+
:::
414+
415+
:::{dropdown} Example response
426416
```console-result
427417
{
428418
"took": 9,
@@ -457,17 +447,15 @@ GET books/_search
457447
```
458448

459449
1. `max_score`: 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.
460-
461-
450+
:::
462451
::::
452+
:::::
463453

454+
## Delete your indices [getting-started-delete-indices]
464455

456+
If you want to delete an index to start from scratch at any point, use the [delete index API]({{es-apis}}operation/operation-indices-delete).
465457

466-
## Step 5: Delete your indices [getting-started-delete-indices]
467-
468-
If you want to delete an index to start from scratch at any point, use the [Delete index API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-delete).
469-
470-
For example, use the following request to delete the indices created in this tutorial:
458+
For example, use the following request to delete the indices created in this quickstart:
471459

472460
```console
473461
DELETE /books
@@ -479,11 +467,13 @@ Deleting an index permanently deletes its documents, shards, and metadata.
479467

480468
::::
481469

482-
## Learn more [full-text-filter-tutorial-learn-more]
470+
## Next steps
483471

484-
This tutorial introduced the basics of creating indices, adding data and performing basic searches with {{es}}. The following resources will help you understand {{es}} concepts better and dive into the basics of query languages for searching data:
472+
This quickstart introduced the basics of creating indices, adding data, and performing basic searches with {{es}}.
473+
To try out similar steps from the {{es}} Python client, go to [](/solutions/search/get-started/keyword-search-python.md).
474+
The following resources will help you understand {{es}} concepts better and dive into the basics of query languages for searching data:
485475

486-
* [Fundamentals of Elasticsearch](../../manage-data/data-store.md)
487-
* [Search and filter with Query DSL](querydsl-full-text-filter-tutorial.md)
488-
* [Search using ES|QL](esql-search-tutorial.md)
476+
* [Fundamentals of Elasticsearch](/manage-data/data-store.md)
477+
* [Search and filter with Query DSL](/solutions/search/querydsl-full-text-filter-tutorial.md)
478+
* [Search using ES|QL](/solutions/search/esql-search-tutorial.md)
489479

‎solutions/toc.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,11 +10,11 @@ toc:
1010
- file: search/search-connection-details.md
1111
- file: search/get-started/quickstarts.md
1212
children:
13+
- file: search/get-started/index-basics.md
1314
- file: search/get-started/keyword-search-python.md
1415
- file: search/get-started/semantic-search.md
1516
- file: search/api-quickstarts.md
1617
children:
17-
- file: search/elasticsearch-basics-quickstart.md
1818
- file: search/querydsl-full-text-filter-tutorial.md
1919
- file: search/esql-search-tutorial.md
2020
- file: search/ingest-for-search.md

0 commit comments

Comments
 (0)