diff --git a/serverless/images/get-started-create-an-index.png b/serverless/images/get-started-create-an-index.png new file mode 100644 index 00000000..fa46a1dd Binary files /dev/null and b/serverless/images/get-started-create-an-index.png differ diff --git a/serverless/index-serverless-elasticsearch.asciidoc b/serverless/index-serverless-elasticsearch.asciidoc index 17c141ec..b9d1274d 100644 --- a/serverless/index-serverless-elasticsearch.asciidoc +++ b/serverless/index-serverless-elasticsearch.asciidoc @@ -16,6 +16,8 @@ include::./pages/pricing.asciidoc[leveloffset=+2] include::./pages/get-started.asciidoc[leveloffset=+2] +include::./pages/create-new-api-key.asciidoc[leveloffset=+2] + include::./pages/clients.asciidoc[leveloffset=+2] include::./pages/clients-go-getting-started.asciidoc[leveloffset=+3] include::./pages/clients-java-getting-started.asciidoc[leveloffset=+3] diff --git a/serverless/pages/create-new-api-key.asciidoc b/serverless/pages/create-new-api-key.asciidoc new file mode 100644 index 00000000..3c50cf8b --- /dev/null +++ b/serverless/pages/create-new-api-key.asciidoc @@ -0,0 +1,19 @@ +[[elasticsearch-create-new-api-key]] += Create a new API key + +Create an API key, which will enable you to access the {es} API to ingest and search data. + +. On the **Getting Started** page, scroll to **Add an API Key** and select **New**. +. In **Create API Key**, enter a name for your key and (optionally) set an expiration date. +. (Optional) Under **Control Security privileges**, you can set specific access permissions for this API key. By default, it has full access to all APIs. +. (Optional) The **Add metadata** section allows you to add custom key-value pairs to help identify and organize your API keys. +. Select **Create API Key** to finish. + +After creation, you'll see your API key displayed as an encoded string. +Store this encoded API key securely. It is displayed only once and cannot be retrieved later. +You will use this encoded API key when sending API requests. + +[NOTE] +==== +You can't recover or retrieve a lost API key. Instead, you must delete the key and create a new one. +==== \ No newline at end of file diff --git a/serverless/pages/get-started.asciidoc b/serverless/pages/get-started.asciidoc index 2f7357b1..e48837f2 100644 --- a/serverless/pages/get-started.asciidoc +++ b/serverless/pages/get-started.asciidoc @@ -26,136 +26,68 @@ Use your {ecloud} account to create a fully-managed {es} project: Select **Create project** to continue. . Once the project is ready, select **Continue**. -You should now see the **Home page**. To proceed with the next steps, navigate to the *Getting Started* page. - include::../partials/minimum-vcus-detail.asciidoc[] [discrete] -[[elasticsearch-get-started-create-api-key]] -== Create API key +[[elasticsearch-get-started-create-index]] +== Create an index -Create an API key, which will enable you to access the {es} API to ingest and search data. +Once your project is set up, you'll be directed to a page where you can create your first index. +An index is where documents are stored and organized, making it possible to search and retrieve data. -. On the **Getting Started** page, scroll to **Add an API Key** and select **New**. -. In **Create API Key**, enter a name for your key and (optionally) set an expiration date. -. (Optional) Under **Control Security privileges**, you can set specific access permissions for this API key. By default, it has full access to all APIs. -. (Optional) The **Add metadata** section allows you to add custom key-value pairs to help identify and organize your API keys. -. Select **Create API Key** to finish. +. Enter a name for your index. +. Click *Create my index*. You can also create the index by clicking on *Code* to view and run code examples through the command line. ++ +image::images/get-started-create-an-index.png[Create an index.] -After creation, you'll see your API key displayed as an encoded string. -Store this encoded API key securely. It is displayed only once and cannot be retrieved later. -You will use this encoded API key when sending API requests. +. You’ll be directed to the *Index Management* page. Here, copy and save the following: +- Elasticsearch URL +- API key [NOTE] ==== -You can't recover or retrieve a lost API key. Instead, you must delete the key and create a new one. +You won’t be able to view this API key again. If needed, refer to <> to generate a new one. ==== [discrete] -[[elasticsearch-get-started-copy-url]] -== Copy URL - -Next, copy the URL of your API endpoint. -You'll send all {es} API requests to this URL. - -. On the **Getting Started** page, scroll to **Copy your connection details** section, and find the **Elasticsearch endpoint** field. -. Copy the URL for the Elasticsearch endpoint. - -Store this value along with your `encoded` API key. -You'll use both values in the next step. - -[discrete] -[[elasticsearch-get-started-test-connection]] -== Test connection - -We'll use the `curl` command to test your connection and make additional API requests. -(See https://everything.curl.dev/get[Install curl] if you need to install this program.) - -`curl` will need access to your Elasticsearch Endpoint and `encoded` API key. -Within your terminal, assign these values to the `ES_URL` and `API_KEY` environment variables. - -For example: - -[source,bash] ----- -export ES_URL="https://dda7de7f1d264286a8fc9741c7741690.es.us-east-1.aws.elastic.cloud:443" -export API_KEY="ZFZRbF9Jb0JDMEoxaVhoR2pSa3Q6dExwdmJSaldRTHFXWEp4TFFlR19Hdw==" ----- - -Then run the following command to test your connection: +[[elasticsearch-get-started-ingest-data]] +== Ingest data -[source,bash] ----- -curl "${ES_URL}" \ - -H "Authorization: ApiKey ${API_KEY}" \ - -H "Content-Type: application/json" ----- +You can now ingest data in several ways: using Python, cURL, JavaScript, or Run in Console directly in Elasticsearch. +If you'd prefer to upload a file using the UI, refer to <>. -You should receive a response similar to the following: +In this section, we walk you through the ingest process using the Console. +. Click *Run in Console*. +. Run the first API call to create the index mapping. ++ [source,json] ---- +PUT /search-test/_mapping { - "name" : "serverless", - "cluster_name" : "dda7de7f1d264286a8fc9741c7741690", - "cluster_uuid" : "ws0IbTBUQfigmYAVMztkZQ", - "version" : { ... }, - "tagline" : "You Know, for Search" + "properties": { + "vector": { + "type": "dense_vector", + "dims": 3 + }, + "text": { + "type": "text" + } + } } ---- -Now you're ready to ingest and search some sample documents. - -[discrete] -[[elasticsearch-get-started-ingest-data]] -== Ingest data - -[NOTE] -==== -This example uses {es} APIs to ingest data. If you'd prefer to upload a file using the UI, refer to <>. -==== - -To ingest data, you must create an index and store some documents. -This process is also called "indexing". - -You can index multiple documents using a single `POST` request to the `_bulk` API endpoint. -The request body specifies the documents to store and the indices in which to store them. - -{es} will automatically create the index and map each document value to one of its data types. -Include the `?pretty` option to receive a human-readable response. - -Run the following command to index some sample documents into the `books` index: - -[source,bash] ----- -curl -X POST "${ES_URL}/_bulk?pretty" \ - -H "Authorization: ApiKey ${API_KEY}" \ - -H "Content-Type: application/json" \ - -d ' -{ "index" : { "_index" : "books" } } -{"name": "Snow Crash", "author": "Neal Stephenson", "release_date": "1992-06-01", "page_count": 470} -{ "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} -' ----- - -You should receive a response indicating there were no errors: +. Run the second API call to ingest documents. [source,json] ---- -{ - "errors" : false, - "took" : 1260, - "items" : [ ... ] -} +POST /_bulk?pretty +{ "index": { "_index": "search-test" } } +{"vector":[2.542,5.807,9.735],"text":"Example text 1"} +{ "index": { "_index": "search-test" } } +{"vector":[5.879,8.179,9.932],"text":"Example text 2"} +{ "index": { "_index": "search-test" } } +{"vector":[6.534,7.155,3.236],"text":"Example text 3"} ---- [discrete] @@ -163,55 +95,81 @@ You should receive a response indicating there were no errors: == Search data To search, send a `POST` request to the `_search` endpoint, specifying the index to search. -Use the {es} query DSL to construct your request body. -Run the following command to search the `books` index for documents containing `snow`: +Run the following command to search the `search-test` index for documents containing `Example` in the text field: [source,bash] ---- -curl -X POST "${ES_URL}/books/_search?pretty" \ - -H "Authorization: ApiKey ${API_KEY}" \ - -H "Content-Type: application/json" \ - -d ' +POST /search-test/_search?pretty { "query": { - "query_string": { - "query": "snow" + "match": { + "text": "Example" } } } -' ---- -You should receive a response with the results: +This query will use the match query, which is designed to search for full-text fields. + +You should receive a response that includes the documents matching your search term. +Here’s an example of what the response might look like: [source,json] ---- { - "took" : 24, - "timed_out" : false, - "_shards" : { - "total" : 1, - "successful" : 1, - "skipped" : 0, - "failed" : 0 + "took": 6, + "timed_out": false, + "_shards": { + "total": 3, + "successful": 3, + "skipped": 0, + "failed": 0 }, - "hits" : { - "total" : { - "value" : 1, - "relation" : "eq" + "hits": { + "total": { + "value": 3, + "relation": "eq" }, - "max_score" : 1.5904956, - "hits" : [ + "max_score": 0.2876821, + "hits": [ { - "_index" : "books", - "_id" : "Z3hf_IoBONQ5TXnpLdlY", - "_score" : 1.5904956, - "_source" : { - "name" : "Snow Crash", - "author" : "Neal Stephenson", - "release_date" : "1992-06-01", - "page_count" : 470 + "_index": "search-test", + "_id": "NJZmIJMBSZbIKcD1sOUO", + "_score": 0.2876821, + "_source": { + "vector": [ + 2.352, + 4.133, + 1.718 + ], + "text": "Example text 2" + } + }, + { + "_index": "search-test", + "_id": "M5ZmIJMBSZbIKcD1sOUO", + "_score": 0.18232156, + "_source": { + "vector": [ + 6.407, + 1.821, + 0.404 + ], + "text": "Example text 1" + } + }, + { + "_index": "search-test", + "_id": "NZZmIJMBSZbIKcD1sOUO", + "_score": 0.18232156, + "_source": { + "vector": [ + 4.959, + 5.986, + 3.873 + ], + "text": "Example text 3" } } ] @@ -219,6 +177,11 @@ You should receive a response with the results: } ---- +In this response: + +- `hits`: This section contains the matching documents. Each document includes the `_source` field with the original vector and text fields. +- `_score`: This field indicates the relevance score of each document to the search query. A higher score means a closer match. + [discrete] [[elasticsearch-get-started-continue-on-your-own]] == Continue on your own diff --git a/serverless/pages/ingest-your-data-ingest-data-through-integrations-beats.asciidoc b/serverless/pages/ingest-your-data-ingest-data-through-integrations-beats.asciidoc index d9af7cc1..c2a1003b 100644 --- a/serverless/pages/ingest-your-data-ingest-data-through-integrations-beats.asciidoc +++ b/serverless/pages/ingest-your-data-ingest-data-through-integrations-beats.asciidoc @@ -42,7 +42,7 @@ can further process and enhance the data before visualizing it in {kib}. [NOTE] ==== When you use {beats} to export data to an {es} project, the {beats} require an API key to authenticate with {es}. -Refer to <> for the steps to set up your API key, +Refer to <> for the steps to set up your API key, and to https://www.elastic.co/guide/en/beats/filebeat/current/beats-api-keys.html[Grant access using API keys] in the Filebeat documentation for an example of how to configure your {beats} to use the key. ====