Skip to content
Merged
Show file tree
Hide file tree
Changes from 19 commits
Commits
Show all changes
49 commits
Select commit Hold shift + click to select a range
81aa97c
Create 101 section
leemthompo Sep 2, 2024
4682400
- **intro.asciidoc**:
leemthompo Sep 2, 2024
dcdcffb
Merge main
leemthompo Sep 2, 2024
ec87abb
Add link
leemthompo Sep 2, 2024
cfbe986
Tweak ql table, mini nav shuffle
leemthompo Sep 3, 2024
c3984ea
Fix typos, links
leemthompo Sep 3, 2024
1c57ecd
Move what's new page
leemthompo Sep 3, 2024
143b0eb
Move some nav items
leemthompo Sep 3, 2024
dadd793
Add couple links
leemthompo Sep 3, 2024
fa818e3
Update landing page getting started link
leemthompo Sep 3, 2024
4e815e4
Fix link
leemthompo Sep 3, 2024
e85565e
Apply suggestions from feedback
leemthompo Sep 5, 2024
3f13270
Rename to Elasticsearch basics
leemthompo Sep 5, 2024
5251740
Refactorings
leemthompo Sep 5, 2024
1c729db
Merge main
leemthompo Sep 10, 2024
755e4fd
Little fixes
leemthompo Sep 10, 2024
03500ef
The term -we you- is not a thing
leemthompo Sep 10, 2024
cdef9f5
Use attributes
leemthompo Sep 10, 2024
b758ff8
Adds links to API bullet
leemthompo Sep 10, 2024
98a9780
Apply suggestions from code review
leemthompo Sep 11, 2024
00daf2b
Apply suggestions from code review
leemthompo Sep 11, 2024
e3fea62
Updates per review
leemthompo Sep 11, 2024
0df8cbe
Refactor search and analyze section, add back QL table
leemthompo Sep 11, 2024
ddfdf1c
Stop saying -our- all the time
leemthompo Sep 11, 2024
8314217
Add semantic search to use cases
leemthompo Sep 16, 2024
a2d8d66
Merge branch 'main' into 101-section
leemthompo Sep 19, 2024
ec62068
Merge branch 'main' into 101-section
leemthompo Sep 19, 2024
9629a55
Delete duplicated include
leemthompo Sep 19, 2024
4686858
Some updates based on Serena feedback
leemthompo Sep 23, 2024
303109f
Rename quickstart section, add vector example
leemthompo Sep 23, 2024
754ddaa
Add snippet test teardown, uniformize quick start term
leemthompo Sep 23, 2024
d30b432
Keep search your data where it is in nav for now
leemthompo Sep 23, 2024
3a5dca6
Make it clear esql has new goodness every release
leemthompo Sep 23, 2024
216bede
API quick starts is better name
leemthompo Sep 23, 2024
3395671
Apply suggestions from code review
leemthompo Sep 24, 2024
dfb5916
Move sample data to tip
leemthompo Sep 24, 2024
085625f
Remove vectors from first quick start, update local dev verbiage
leemthompo Sep 24, 2024
c9fa2f0
Add short definition of timestamped data
leemthompo Sep 24, 2024
6da5180
Mention quick starts use queryDSL unless otherwise noted
leemthompo Sep 24, 2024
90e5ac0
Fix url
leemthompo Sep 24, 2024
e96aac0
fix typo
leemthompo Sep 24, 2024
bcadaa3
Update query languages section
leemthompo Sep 24, 2024
09a4120
An -> a
leemthompo Sep 24, 2024
b1f5144
Tweaky McTweakface
leemthompo Sep 24, 2024
a4d934c
Clarify file uploader use case
leemthompo Sep 25, 2024
f655978
Delegate file format info to uploader docs, pdf support is coming soo…
leemthompo Sep 25, 2024
a272bf7
Local dev-elopment
leemthompo Sep 25, 2024
0a0a074
Apply suggestions
leemthompo Sep 25, 2024
a25b908
Future proof quick start section title
leemthompo Sep 25, 2024
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions docs/reference/index.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -6,12 +6,14 @@ include::links.asciidoc[]

include::landing-page.asciidoc[]

include::intro.asciidoc[]

include::release-notes/highlights.asciidoc[]

include::intro.asciidoc[]

include::quickstart/index.asciidoc[]
Comment on lines 9 to 13
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this order feels off to me:

  1. need to install ES in some way before you can do the quickstart
  2. what's new being up so high doesn't feel like a value add

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  1. intro.asciidoc (basics) contains "run elasticsearch" options and having running instance is prerequisite for quickstarts
    • there's going to be a lot more "quick starts" here so we need to decouple installation and these guides
  2. this is asciidoc weirdness wanted to move it beside release notes but was too much fussiness to add to this pile of fussiness

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

wanted basics and quick starts to be beside each other rather than have what's new in between as it is today


include::search/search-your-data/search-your-data.asciidoc[]

include::setup.asciidoc[]

include::upgrade.asciidoc[]
Expand All @@ -30,8 +32,6 @@ include::ingest.asciidoc[]

include::alias.asciidoc[]

include::search/search-your-data/search-your-data.asciidoc[]

include::query-dsl.asciidoc[]

include::aggregations.asciidoc[]
Expand Down
252 changes: 173 additions & 79 deletions docs/reference/intro.asciidoc

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion docs/reference/landing-page.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -62,7 +62,7 @@
Elasticsearch is the search and analytics engine that powers the Elastic Stack.
</p>
<p>
<a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/getting-started.html">
<a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/elasticsearch-intro.html">
<button class="btn btn-primary">Get started</button>
</a>
</p>
Expand Down
77 changes: 10 additions & 67 deletions docs/reference/quickstart/getting-started.asciidoc
Original file line number Diff line number Diff line change
@@ -1,47 +1,20 @@
[[getting-started]]
== Quick start guide
== Quick start: First steps with {es}
++++
<titleabbrev>First steps with {es}</titleabbrev>
++++

This guide helps you learn how to:
In this quickstart guide you'll learn how to:

* Run {es} and {kib} (using {ecloud} or in a local Docker dev environment),
* 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-ref-dir}/tab-widgets/code.asciidoc[]
include::{es-ref-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-ref-dir}/tab-widgets/api-call-widget.asciidoc[]
* Add a small (non-timestamped) dataset to {es} using the REST API and the <<query-dsl,query DSL>>
* Run basic searches

[discrete]
[[add-data]]
=== Add data

You add data to {es} as JSON objects called documents. {es} stores these
You add data to {es} as JSON objects called documents.
{es} stores these
documents in searchable indices.

[discrete]
Expand Down Expand Up @@ -251,34 +224,4 @@ GET books/_search
}
}
----
// 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

* <<search-with-elasticsearch>>. Jump here to learn about exact value search, full-text search, vector search, and more, using the <<search-search,search API>>.

[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].
// TEST[continued]
28 changes: 23 additions & 5 deletions docs/reference/quickstart/index.asciidoc
Original file line number Diff line number Diff line change
@@ -1,10 +1,28 @@
[[quickstart]]
= Quickstart
= Quickstarts

Get started quickly with {es}.
Use these quickstarts to get hands-on experience with {es}.

* Learn how to run {es} (and {kib}) for <<run-elasticsearch-locally,local development>>.
* Follow our <<getting-started,Quickstart guide>> to add data to {es} and query it.
[discrete]
[[quickstart-requirements]]
== Requirements

You'll need a running {es} cluster, together with {kib} to use the Dev Tools API Console.
Get started quickly with a <<run-elasticsearch-locally,local dev environment>> in Docker, or see our <<elasticsearch-intro-deploy,other deployment options>>.

[discrete]
[[quickstart-list]]
== Quickstarts

* <<getting-started,First steps with {es}>>. Learn how to add data to {es} and perform basic searches.

[discrete]
[[quickstart-python-links]]
== Working in Python

If you're interested in using {es} with Python, check out Elastic Search Labs:

* https://github.com/elastic/elasticsearch-labs[`elasticsearch-labs` repository]. 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].
* 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 using Flask.

include::run-elasticsearch-locally.asciidoc[]
include::getting-started.asciidoc[]
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
[[run-elasticsearch-locally]]
== Run {es} locally in Docker (without security)
== Run {es} locally in Docker
++++
<titleabbrev>Local dev setup (Docker)</titleabbrev>
<titleabbrev>Start in local dev</titleabbrev>
++++

[WARNING]
Expand All @@ -12,21 +12,8 @@ The instructions on this page are for *local development only*. Do not use these
While this approach is convenient for experimenting and learning, you should never run the service in this way in a production environment.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

line 9 is quite yelly. I'd kill the caps

Copy link
Contributor

@shainaraskas shainaraskas Sep 23, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
While this approach is convenient for experimenting and learning, you should never run the service in this way in a production environment.
While this approach is convenient for experimenting and learning, you should never run the Elasticsearch in this way in a production environment.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

hmm one of us edited this to make it grammatically incorrect - "the Elasticsearch"

====

The following commands help you very quickly spin up a single-node {es} cluster, together with {kib} in Docker.
Note that if you don't need the {kib} UI, you can skip those instructions.

[discrete]
[[local-dev-why]]
=== When would I use this setup?

Use this setup if you want to quickly spin up {es} (and {kib}) for local development or testing.

For example you might:

* Want to run a quick test to see how a feature works.
* Follow a tutorial or guide that requires an {es} cluster, like our <<getting-started,quick start guide>>.
* Experiment with the {es} APIs using different tools, like the Dev Tools Console, cURL, or an Elastic programming language client.
* Quickly spin up an {es} cluster to test an executable https://github.com/elastic/elasticsearch-labs/tree/main/notebooks#readme[Python notebook] locally.
Use this setup if you want to quickly spin up {es} (and {kib}) in Docker for local development or testing.
(If you don't need the {kib} UI, you can skip those instructions.)

[discrete]
[[local-dev-prerequisites]]
Expand Down Expand Up @@ -116,12 +103,12 @@ docker run -p 127.0.0.1:5601:5601 -d --name kibana --network elastic-net \

[NOTE]
====
The service is started with a trial license. The trial license enables all features of Elasticsearch for a trial period of 30 days. After the trial period expires, the license is downgraded to a basic license, which is free forever. If you prefer to skip the trial and use the basic license, set the value of the `xpack.license.self_generated.type` variable to basic instead. For a detailed feature comparison between the different licenses, refer to our https://www.elastic.co/subscriptions[subscriptions page].
The service is started with a trial license. The trial license enables all features of Elasticsearch for a trial period of 30 days. After the trial period expires, the license is downgraded to a basic license, which is free forever.
====

[discrete]
[[local-dev-connecting-clients]]
== Connecting to {es} with language clients
=== Connecting to {es} with language clients

To connect to the {es} cluster from a language client, you can use basic authentication with the `elastic` username and the password you set in the environment variable.

Expand Down Expand Up @@ -170,12 +157,11 @@ curl -u elastic:$ELASTIC_PASSWORD \
[[local-dev-next-steps]]
=== Next steps

Use our <<getting-started,quick start guide>> to learn the basics of {es}: how to add data and query it.
Use our <<quickstart,quick start guides>> to learn the basics of {es}.

[discrete]
[[local-dev-production]]
=== Moving to production

This setup is not suitable for production use. For production deployments, we recommend using our managed service on Elastic Cloud. https://cloud.elastic.co/registration[Sign up for a free trial] (no credit card required).

Otherwise, refer to https://www.elastic.co/guide/en/elasticsearch/reference/current/install-elasticsearch.html[Install {es}] to learn about the various options for installing {es} in a self-managed production environment, including using Docker.
This setup is not suitable for production use.
Refer to <<elasticsearch-intro-deploy, deployment options>> for more information.
2 changes: 2 additions & 0 deletions docs/reference/setup.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,8 @@ the only resource-intensive application on the host or container. For example,
you might run {metricbeat} alongside {es} for cluster statistics, but a
resource-heavy {ls} deployment should be on its own host.

include::run-elasticsearch-locally.asciidoc[]

include::setup/install.asciidoc[]

include::setup/configuration.asciidoc[]
Expand Down
8 changes: 4 additions & 4 deletions docs/reference/tab-widgets/api-call.asciidoc
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
// tag::cloud[]
**Use {kib}**
**Option 1: Use {kib}**

//tag::kibana-api-ex[]
. Open {kib}'s main menu ("*☰*" near Elastic logo) and go to **Dev Tools > Console**.
Expand All @@ -16,17 +16,17 @@ GET /
//end::kibana-api-ex[]
**Use curl**
**Option 2: Use `curl`**
To communicate with {es} using curl or another client, you need your cluster's
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
. To submit an example API request, run the following `curl` command in a new
terminal session. Replace `<password>` with the password for the `elastic` user.
Replace `<elasticsearch_endpoint>` with your endpoint.
+
Expand Down