diff --git a/serverless/images/copy-connection-details.png b/serverless/images/copy-connection-details.png new file mode 100644 index 0000000000..f989c83597 Binary files /dev/null and b/serverless/images/copy-connection-details.png differ diff --git a/serverless/images/create-an-api-key.png b/serverless/images/create-an-api-key.png new file mode 100644 index 0000000000..8d9898c9ba Binary files /dev/null and b/serverless/images/create-an-api-key.png differ 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 0000000000..fa46a1dde1 Binary files /dev/null and b/serverless/images/get-started-create-an-index.png differ diff --git a/serverless/images/getting-started-page.png b/serverless/images/getting-started-page.png new file mode 100644 index 0000000000..7589d7276b Binary files /dev/null and b/serverless/images/getting-started-page.png differ diff --git a/serverless/index-serverless-elasticsearch.asciidoc b/serverless/index-serverless-elasticsearch.asciidoc index c8375cab19..97f104f1c7 100644 --- a/serverless/index-serverless-elasticsearch.asciidoc +++ b/serverless/index-serverless-elasticsearch.asciidoc @@ -11,6 +11,8 @@ include::./pages/pricing.asciidoc[leveloffset=+2] include::./pages/get-started.asciidoc[leveloffset=+2] +include::./pages/connecting-to-es-endpoint.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/connecting-to-es-endpoint.asciidoc b/serverless/pages/connecting-to-es-endpoint.asciidoc new file mode 100644 index 0000000000..02069ee83d --- /dev/null +++ b/serverless/pages/connecting-to-es-endpoint.asciidoc @@ -0,0 +1,91 @@ +[[elasticsearch-connecting-to-es-serverless-endpoint]] += Connecting to your Elasticsearch Serverless endpoint + +[TIP] +==== +This page assumes you have already <>. +==== + +Learn how to securely connect to your Elasticsearch Serverless instance. + +To connect to your Elasticsearch instance from your applications, client libraries, or tools like `curl`, you'll need two key pieces of information: an API key and your endpoint URL. This guide shows you how to get these connection details and verify they work. + +[discrete] +[[elasticsearch-get-started-create-api-key]] +== Create a new API key + +Create an API key to authenticate your requests to the {es} APIs. You'll need an API key for all API requests and client connections. + +To create a new API key: + +. On the **Getting Started** page, scroll to **Add an API Key** and select **New**. You can also search for *API keys* in the https://www.elastic.co/guide/en/kibana/current/kibana-concepts-analysts.html#_finding_your_apps_and_objects[global search field]. ++ +image::images/create-an-api-key.png[Create an API key.] +. 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. +==== + +[discrete] +[[elasticsearch-get-started-endpoint]] +== Get your {es} endpoint URL + +The endpoint URL is the address for your {es} instance. +You'll use this URL together with your API key to make requests to the {es} APIs. +To find the endpoint 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. + +image::images/copy-connection-details.png[Copy your Elasticsearch endpoint.] + +[discrete] +[[elasticsearch-get-started-test-connection]] +== Test connection + +Use https://curl.se[`curl`] to verify your connection to {es}. + +`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: + +[source,bash] +---- +curl "${ES_URL}" \ + -H "Authorization: ApiKey ${API_KEY}" \ + -H "Content-Type: application/json" +---- + +You should receive a response similar to the following: + +[source,json] +---- +{ + "name" : "serverless", + "cluster_name" : "dda7de7f1d264286a8fc9741c7741690", + "cluster_uuid" : "ws0IbTBUQfigmYAVMztkZQ", + "version" : { ... }, + "tagline" : "You Know, for Search" +} +---- + +Now you're ready to start adding data to your {es-serverless} project. \ No newline at end of file diff --git a/serverless/pages/get-started.asciidoc b/serverless/pages/get-started.asciidoc index 5d8a180794..8acd015c71 100644 --- a/serverless/pages/get-started.asciidoc +++ b/serverless/pages/get-started.asciidoc @@ -6,246 +6,99 @@ preview:[] -Follow along to set up your {es-serverless} project and get started with some sample documents. -Then, choose how to continue with your own data. +On this page, you will learn how to: + +- <>. + +- Get started with {es}: + * <>: + Follow the step-by-step tutorial provided in the UI to create an index and ingest data. + + * <>: + Use the Getting Started page's instructions to ingest data and perform your first search. + + * <>: + If you're already familiar with {es}, retrieve your connection details, select an ingest method that suits your needs, and start searching. [discrete] [[elasticsearch-get-started-create-project]] -== Create project +== Create an {es-serverless} project -Use your {ecloud} account to create a fully-managed {es-serverless} project: +Use your {ecloud} account to create a fully-managed {es} project: . Navigate to {ess-console}[cloud.elastic.co] and create a new account or log in to your existing account. . Within **Serverless Projects**, choose **Create project**. -. Choose the {es-serverless} project type. +. Choose the {es} project type. . Select a **configuration** for your project, based on your use case. + -** **General purpose**. For general search use cases across various data types. -** **Optimized for Vectors**. For search use cases using vectors and near real-time retrieval. +** **General purpose**: For general search use cases across various data types. +** **Optimized for Vectors**: For search use cases using vectors and near real-time retrieval. . Provide a name for the project and optionally edit the project settings, such as the cloud platform <>. Select **Create project** to continue. . Once the project is ready, select **Continue**. -You should now see **Get started with {es-serverless}**, and you're ready to continue. - -include::../partials/minimum-vcus-detail.asciidoc[] - -[discrete] -[[elasticsearch-get-started-create-api-key]] -== Create API key - -Create an API key, which will enable you to access the {es-serverless} 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] +[TIP] ==== -You can't recover or retrieve a lost API key. Instead, you must delete the key and create a new one. +Learn how billing works for your project in <>. ==== -[discrete] -[[elasticsearch-get-started-copy-url]] -== Copy URL - -Next, copy the URL of your API endpoint. -You'll send all {es-serverless} API requests to this URL. - -. On the **Getting Started** page, scroll to **Copy your connection details** section, and find the **{es} endpoint** field. -. Copy the URL for the {es} endpoint. - -Store this value along with your `encoded` API key. -You'll use both values in the next step. +Now your project is ready to start creating indices, adding data, and performing searches. You can choose one of the following options to proceed. [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 {es} 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: - -[source,bash] ----- -curl "${ES_URL}" \ - -H "Authorization: ApiKey ${API_KEY}" \ - -H "Content-Type: application/json" ----- +[[elasticsearch-follow-guided-index-flow]] +== Option 1: Follow the guided index flow -You should receive a response similar to the following: +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. -[source,json] ----- -{ - "name" : "serverless", - "cluster_name" : "dda7de7f1d264286a8fc9741c7741690", - "cluster_uuid" : "ws0IbTBUQfigmYAVMztkZQ", - "version" : { ... }, - "tagline" : "You Know, for Search" -} ----- - -Now you're ready to ingest and search some sample documents. +. 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 through the command line. ++ +image::images/get-started-create-an-index.png[Create an index.] -[discrete] -[[elasticsearch-get-started-ingest-data]] -== Ingest data +. You’ll be directed to the *Index Management* page. Here, copy and save the following: +- Elasticsearch URL +- API key [NOTE] ==== -This example uses {es} APIs to ingest data. If you'd prefer to upload a file using the UI, refer to <>. +You won’t be able to view this API key again. If needed, refer to <> to generate a new one. ==== -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: - -[source,json] ----- -{ - "errors" : false, - "took" : 1260, - "items" : [ ... ] -} ----- +The UI provides ready-to-use code examples for ingesting data via the REST API. +Choose your preferred tool for making these requests: -[discrete] -[[elasticsearch-get-started-search-data]] -== 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`: - -[source,bash] ----- -curl -X POST "${ES_URL}/books/_search?pretty" \ - -H "Authorization: ApiKey ${API_KEY}" \ - -H "Content-Type: application/json" \ - -d ' -{ - "query": { - "query_string": { - "query": "snow" - } - } -} -' ----- - -You should receive a response with the results: - -[source,json] ----- -{ - "took" : 24, - "timed_out" : false, - "_shards" : { - "total" : 1, - "successful" : 1, - "skipped" : 0, - "failed" : 0 - }, - "hits" : { - "total" : { - "value" : 1, - "relation" : "eq" - }, - "max_score" : 1.5904956, - "hits" : [ - { - "_index" : "books", - "_id" : "Z3hf_IoBONQ5TXnpLdlY", - "_score" : 1.5904956, - "_source" : { - "name" : "Snow Crash", - "author" : "Neal Stephenson", - "release_date" : "1992-06-01", - "page_count" : 470 - } - } - ] - } -} ----- +* <> in your project's UI +* Python +* JavaScript +* cURL [discrete] -[[elasticsearch-get-started-continue-on-your-own]] -== Continue on your own +[[elasticsearch-follow-in-product-getting-started]] +== Option 2: Follow the Getting Started guide -Congratulations! -You've set up an {es-serverless} project, and you've ingested and searched some sample data. -Now you're ready to continue on your own. +To get started using the in-product tutorial, navigate to the *Getting Started* page and follow the on-screen steps. + +image::images/getting-started-page.png[Getting Started page.] [discrete] -[[elasticsearch-get-started-explore]] -=== Explore +[[elasticsearch-explore-on-your-own]] +== Option 3: Explore on your own -Want to explore the sample documents or your own data? +If you're already familiar with Elasticsearch, you can jump right into setting up a connection and ingesting data as per your needs. -By creating a data view, you can explore data using several UI tools, such as Discover or Dashboards. Or, use {es} aggregations to explore your data using the API. Find more information in <>. +. Retrieve your <>. +. Ingest your data. Elasticsearch provides several methods for ingesting data: +* <> +* <> +* <> +* <> +* <> +* https://github.com/elastic/crawler[Elastic Open Web Crawler] [discrete] -[[elasticsearch-get-started-build]] -=== Build - -Ready to build your own solution? - -To learn more about sending and syncing data to {es-serverless}, or the search API and its query DSL, check <> and <>. +[[elasticsearch-next-steps]] +== Next steps -//// -/* -- -- -*/ -//// +* Once you've added data to your {es-serverless} project, you can use {kibana-ref}/playground.html[Playground] to test and tweak {es} queries and chat with your data, using GenAI. +* You can also try our hands-on {ref}/quickstart.html#quickstart-list[quick start tutorials] in the core {es} documentation. \ No newline at end of file