From d44e05d2c24c77932f8895cadc715c6afdbaa6ee Mon Sep 17 00:00:00 2001 From: Liam Thompson <32779855+leemthompo@users.noreply.github.com> Date: Fri, 24 Nov 2023 15:27:41 +0100 Subject: [PATCH] [DOCS] Add ES quickstart (#102226) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * [DOCS] TEST restore quickstart * Use up to date Docker instructions, minor user-friendly modifications * Use books dataset, update verbiage, add examples * Update verbiage * Updated Elasticsearch 'Getting Started' docs: added SSL, Docker setup, Python resources, and expanded next steps * minor formatting * Collapse responses, TODO comment tests * Add request tests * Edit superfluities * Apply suggestions Co-authored-by: István Zoltán Szabó * Update docs/reference/tab-widgets/quick-start-install.asciidoc Co-authored-by: István Zoltán Szabó --------- Co-authored-by: István Zoltán Szabó --- docs/reference/getting-started.asciidoc | 285 ++++++++++++++++++ docs/reference/index.asciidoc | 2 + docs/reference/redirects.asciidoc | 5 - .../tab-widgets/api-call-widget.asciidoc | 40 +++ docs/reference/tab-widgets/api-call.asciidoc | 57 ++++ docs/reference/tab-widgets/code.asciidoc | 163 ++++++++++ .../quick-start-install-widget.asciidoc | 40 +++ .../tab-widgets/quick-start-install.asciidoc | 71 +++++ 8 files changed, 658 insertions(+), 5 deletions(-) create mode 100644 docs/reference/getting-started.asciidoc create mode 100644 docs/reference/tab-widgets/api-call-widget.asciidoc create mode 100644 docs/reference/tab-widgets/api-call.asciidoc create mode 100644 docs/reference/tab-widgets/code.asciidoc create mode 100644 docs/reference/tab-widgets/quick-start-install-widget.asciidoc create mode 100644 docs/reference/tab-widgets/quick-start-install.asciidoc diff --git a/docs/reference/getting-started.asciidoc b/docs/reference/getting-started.asciidoc new file mode 100644 index 000000000000..3e474953a72f --- /dev/null +++ b/docs/reference/getting-started.asciidoc @@ -0,0 +1,285 @@ +[chapter] +[[getting-started]] += Quick start + +This guide helps you learn how to: + +* install and run {es} and {kib} (using {ecloud} or Docker), +* add simple (non-timestamped) dataset to {es}, +* run basic searches. + +[TIP] +==== +If you're interested in using {es} with Python, check out Elastic Search Labs. This is the best place to explore AI-powered search use cases, such as working with embeddings, vector search, and retrieval augmented generation (RAG). + +* https://www.elastic.co/search-labs/tutorials/search-tutorial/welcome[Tutorial]: this walks you through building a complete search solution with {es}, from the ground up. +* https://github.com/elastic/elasticsearch-labs[`elasticsearch-labs` repository]: it contains a range of Python https://github.com/elastic/elasticsearch-labs/tree/main/notebooks[notebooks] and https://github.com/elastic/elasticsearch-labs/tree/main/example-apps[example apps]. +==== + +[discrete] +[[run-elasticsearch]] +=== Run {es} + +The simplest way to set up {es} is to create a managed deployment with {ess} on +{ecloud}. If you prefer to manage your own test environment, install and +run {es} using Docker. + +include::{es-repo-dir}/tab-widgets/code.asciidoc[] +include::{es-repo-dir}/tab-widgets/quick-start-install-widget.asciidoc[] + +[discrete] +[[send-requests-to-elasticsearch]] +=== Send requests to {es} + +You send data and other requests to {es} using REST APIs. This lets you interact +with {es} using any client that sends HTTP requests, such as +https://curl.se[curl]. You can also use {kib}'s Console to send requests to +{es}. + +include::{es-repo-dir}/tab-widgets/api-call-widget.asciidoc[] + +[discrete] +[[add-data]] +=== Add data + +You add data to {es} as JSON objects called documents. {es} stores these +documents in searchable indices. + +[discrete] +[[add-single-document]] +==== Add a single document + +Submit the following indexing request to add a single document to the +`books` index. +The request automatically creates the index. + +//// +[source,console] +---- +PUT books +---- +// TESTSETUP +//// + +[source,console] +---- +POST books/_doc +{"name": "Snow Crash", "author": "Neal Stephenson", "release_date": "1992-06-01", "page_count": 470} +---- +// TEST[s/_doc/_doc?refresh=wait_for/] + +The response includes metadata that {es} generates for the document including a unique `_id` for the document within the index. + +.Expand to see example response +[%collapsible] +=============== +[source,console-result] +---- +{ + "_index": "books", + "_id": "O0lG2IsBaSa7VYx_rEia", + "_version": 1, + "result": "created", + "_shards": { + "total": 2, + "successful": 2, + "failed": 0 + }, + "_seq_no": 0, + "_primary_term": 1 +} +---- +// TEST[skip:TODO] +=============== + +[discrete] +[[add-multiple-documents]] +==== Add multiple documents + +Use the `_bulk` endpoint to add multiple documents in one request. Bulk data +must be newline-delimited JSON (NDJSON). Each line must end in a newline +character (`\n`), including the last line. + +[source,console] +---- +POST /_bulk +{ "index" : { "_index" : "books" } } +{"name": "Revelation Space", "author": "Alastair Reynolds", "release_date": "2000-03-15", "page_count": 585} +{ "index" : { "_index" : "books" } } +{"name": "1984", "author": "George Orwell", "release_date": "1985-06-01", "page_count": 328} +{ "index" : { "_index" : "books" } } +{"name": "Fahrenheit 451", "author": "Ray Bradbury", "release_date": "1953-10-15", "page_count": 227} +{ "index" : { "_index" : "books" } } +{"name": "Brave New World", "author": "Aldous Huxley", "release_date": "1932-06-01", "page_count": 268} +{ "index" : { "_index" : "books" } } +{"name": "The Handmaids Tale", "author": "Margaret Atwood", "release_date": "1985-06-01", "page_count": 311} +---- +// TEST[continued] + +You should receive a response indicating there were no errors. + +.Expand to see example response +[%collapsible] +=============== +[source,console-result] +---- +{ + "errors": false, + "took": 29, + "items": [ + { + "index": { + "_index": "books", + "_id": "QklI2IsBaSa7VYx_Qkh-", + "_version": 1, + "result": "created", + "_shards": { + "total": 2, + "successful": 2, + "failed": 0 + }, + "_seq_no": 1, + "_primary_term": 1, + "status": 201 + } + }, + { + "index": { + "_index": "books", + "_id": "Q0lI2IsBaSa7VYx_Qkh-", + "_version": 1, + "result": "created", + "_shards": { + "total": 2, + "successful": 2, + "failed": 0 + }, + "_seq_no": 2, + "_primary_term": 1, + "status": 201 + } + }, + { + "index": { + "_index": "books", + "_id": "RElI2IsBaSa7VYx_Qkh-", + "_version": 1, + "result": "created", + "_shards": { + "total": 2, + "successful": 2, + "failed": 0 + }, + "_seq_no": 3, + "_primary_term": 1, + "status": 201 + } + }, + { + "index": { + "_index": "books", + "_id": "RUlI2IsBaSa7VYx_Qkh-", + "_version": 1, + "result": "created", + "_shards": { + "total": 2, + "successful": 2, + "failed": 0 + }, + "_seq_no": 4, + "_primary_term": 1, + "status": 201 + } + }, + { + "index": { + "_index": "books", + "_id": "RklI2IsBaSa7VYx_Qkh-", + "_version": 1, + "result": "created", + "_shards": { + "total": 2, + "successful": 2, + "failed": 0 + }, + "_seq_no": 5, + "_primary_term": 1, + "status": 201 + } + } + ] +} +---- +// TEST[skip:TODO] +=============== + +[discrete] +[[qs-search-data]] +=== Search data + +Indexed documents are available for search in near real-time. + +[discrete] +[[search-all-documents]] +==== Search all documents + +Run the following command to search the `books` index for all documents: +[source,console] +---- +GET books/_search +---- +// TEST[continued] + +The `_source` of each hit contains the original +JSON object submitted during indexing. + +[discrete] +[[qs-match-query]] +==== `match` query + +You can use the `match` query to search for documents that contain a specific value in a specific field. +This is the standard query for performing full-text search, including fuzzy matching and phrase searches. + +Run the following command to search the `books` index for documents containing `brave` in the `name` field: +[source,console] +---- +GET books/_search +{ + "query": { + "match": { + "name": "brave" + } + } +} +---- +// TEST[continued] + +[discrete] +[[whats-next]] +=== Next steps + +Now that {es} is up and running and you've learned the basics, you'll probably want to test out larger datasets, or index your own data. + +[discrete] +[[whats-next-search-learn-more]] +==== Learn more about search queries + +* <>. Jump here to learn about exact value search, full-text search, vector search, and more, using the <>. + +[discrete] +[[whats-next-more-data]] +==== Add more data + +* Learn how to {kibana-ref}/sample-data.html[install sample data] using {kib}. This is a quick way to test out {es} on larger workloads. +* Learn how to use the {kibana-ref}/connect-to-elasticsearch.html#upload-data-kibana[upload data UI] in {kib} to add your own CSV, TSV, or JSON files. +* Use the https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-bulk.html[bulk API] to ingest your own datasets to {es}. + +[discrete] +[[whats-next-client-libraries]] +==== {es} programming language clients + +* Check out our https://www.elastic.co/guide/en/elasticsearch/client/index.html[client library] to work with your {es} instance in your preferred programming language. +* If you're using Python, check out https://www.elastic.co/search-labs[Elastic Search Labs] for a range of examples that use the {es} Python client. This is the best place to explore AI-powered search use cases, such as working with embeddings, vector search, and retrieval augmented generation (RAG). +** This extensive, hands-on https://www.elastic.co/search-labs/tutorials/search-tutorial/welcome[tutorial] +walks you through building a complete search solution with {es}, from the ground up. +** https://github.com/elastic/elasticsearch-labs[`elasticsearch-labs`] contains a range of executable Python https://github.com/elastic/elasticsearch-labs/tree/main/notebooks[notebooks] and https://github.com/elastic/elasticsearch-labs/tree/main/example-apps[example apps]. \ No newline at end of file diff --git a/docs/reference/index.asciidoc b/docs/reference/index.asciidoc index 828a3e4d1d01..b09d67e99063 100644 --- a/docs/reference/index.asciidoc +++ b/docs/reference/index.asciidoc @@ -17,6 +17,8 @@ include::intro.asciidoc[] include::release-notes/highlights.asciidoc[] +include::getting-started.asciidoc[] + include::setup.asciidoc[] include::upgrade.asciidoc[] diff --git a/docs/reference/redirects.asciidoc b/docs/reference/redirects.asciidoc index f065c2deeae7..e0568f500f26 100644 --- a/docs/reference/redirects.asciidoc +++ b/docs/reference/redirects.asciidoc @@ -1720,11 +1720,6 @@ See <>. See <>. -[role="exclude",id="getting-started"] -=== Quick start - -See {estc-welcome}/getting-started-general-purpose.html[Set up a general purpose Elastic deployment]. - [role="exclude",id="getting-started-index"] === Index some documents diff --git a/docs/reference/tab-widgets/api-call-widget.asciidoc b/docs/reference/tab-widgets/api-call-widget.asciidoc new file mode 100644 index 000000000000..adc2aa86f1c0 --- /dev/null +++ b/docs/reference/tab-widgets/api-call-widget.asciidoc @@ -0,0 +1,40 @@ +++++ +
+
+ + +
+
+++++ + +include::api-call.asciidoc[tag=cloud] + +++++ +
+ +
+++++ \ No newline at end of file diff --git a/docs/reference/tab-widgets/api-call.asciidoc b/docs/reference/tab-widgets/api-call.asciidoc new file mode 100644 index 000000000000..ecbd49eae7f8 --- /dev/null +++ b/docs/reference/tab-widgets/api-call.asciidoc @@ -0,0 +1,57 @@ +// tag::cloud[] +**Use {kib}** + +//tag::kibana-api-ex[] +. Open {kib}'s main menu ("*☰*" near Elastic logo) and go to **Dev Tools > Console**. ++ +[role="screenshot"] +image::images/kibana-console.png[{kib} Console,align="center"] + +. Run the following test API request in Console: ++ +[source,console] +---- +GET / +---- + +//end::kibana-api-ex[] + +**Use curl** + +To communicate with {es} using curl or another client, you need your cluster's +endpoint. + +. Open {kib}'s main menu and click **Manage this deployment**. + +. From your deployment menu, go to the **Elasticsearch** page. Click **Copy +endpoint**. + +. To submit an example API request, run the following curl command in a new +terminal session. Replace `` with the password for the `elastic` user. +Replace `` with your endpoint. ++ +[source,sh] +---- +curl -u elastic: / +---- +// NOTCONSOLE + +// end::cloud[] + +// tag::self-managed[] +**Use {kib}** + +include::api-call.asciidoc[tag=kibana-api-ex] + +**Use curl** + +To submit an example API request, run the following curl command in a new +terminal session. + +[source,sh] +---- +curl --cacert http_ca.crt -u elastic:$ELASTIC_PASSWORD https://localhost:9200 +---- +// NOTCONSOLE + +// end::self-managed[] \ No newline at end of file diff --git a/docs/reference/tab-widgets/code.asciidoc b/docs/reference/tab-widgets/code.asciidoc new file mode 100644 index 000000000000..a6949b681edc --- /dev/null +++ b/docs/reference/tab-widgets/code.asciidoc @@ -0,0 +1,163 @@ +// Defining styles and script here for simplicity. +++++ + + +++++ \ No newline at end of file diff --git a/docs/reference/tab-widgets/quick-start-install-widget.asciidoc b/docs/reference/tab-widgets/quick-start-install-widget.asciidoc new file mode 100644 index 000000000000..f3ff804ade25 --- /dev/null +++ b/docs/reference/tab-widgets/quick-start-install-widget.asciidoc @@ -0,0 +1,40 @@ +++++ +
+
+ + +
+
+++++ + +include::quick-start-install.asciidoc[tag=cloud] + +++++ +
+ +
+++++ \ No newline at end of file diff --git a/docs/reference/tab-widgets/quick-start-install.asciidoc b/docs/reference/tab-widgets/quick-start-install.asciidoc new file mode 100644 index 000000000000..b8daf62dad63 --- /dev/null +++ b/docs/reference/tab-widgets/quick-start-install.asciidoc @@ -0,0 +1,71 @@ + +// tag::cloud[] +include::{docs-root}/shared/cloud/ess-getting-started.asciidoc[tag=generic] + +. Click **Continue** to open {kib}, the user interface for {ecloud}. + +. Click **Explore on my own**. +// end::cloud[] + +// tag::self-managed[] +*Start a single-node cluster* + +We'll use a single-node {es} cluster in this quick start, which makes sense for testing and development. +Refer to <> for advanced Docker documentation. + +. Run the following Docker commands: ++ +[source,sh,subs="attributes"] +---- +docker network create elastic +docker pull {docker-image} +docker run --name es01 --net elastic -p 9200:9200 -p 9300:9300 -e "discovery.type=single-node" -t {docker-image} +---- + +. Copy the generated `elastic` password and enrollment token, which are output to your terminal. +You'll use these to enroll {kib} with your {es} cluster and log in. +These credentials are only shown when you start {es} for the first time. ++ +We recommend storing the `elastic` password as an environment variable in your shell. Example: ++ +[source,sh] +---- +export ELASTIC_PASSWORD="your_password" +---- ++ +. Copy the `http_ca.crt` SSL certificate from the container to your local machine. ++ +[source,sh] +---- +docker cp es01:/usr/share/elasticsearch/config/certs/http_ca.crt . +---- ++ +. Make a REST API call to {es} to ensure the {es} container is running. ++ +[source,sh] +---- +curl --cacert http_ca.crt -u elastic:$ELASTIC_PASSWORD https://localhost:9200 +---- +// NOTCONSOLE + +*Run {kib}* + +{kib} is the user interface for Elastic. +It's great for getting started with {es} and exploring your data. +We'll be using the Dev Tools *Console* in {kib} to make REST API calls to {es}. + +In a new terminal session, start {kib} and connect it to your {es} container: + +[source,sh,subs="attributes"] +---- +docker pull {kib-docker-image} +docker run --name kibana --net elastic -p 5601:5601 {kib-docker-image} +---- + +When you start {kib}, a unique URL is output to your terminal. +To access {kib}: + +. Open the generated URL in your browser. +. Paste the enrollment token that you copied earlier, to connect your {kib} instance with {es}. +. Log in to {kib} as the `elastic` user with the password that was generated when you started {es}. +// end::self-managed[] \ No newline at end of file