Skip to content

Define and disambiguate Elasticsearch in glossary #4031

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 3 commits into
base: main
Choose a base branch
from
Draft

Define and disambiguate Elasticsearch in glossary #4031

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
7fb4958
Define and disambiguate Elasticsearch in glossary
leemthompo Nov 21, 2025
86d9ad5
precision, use glossary link for spaces
leemthompo Nov 21, 2025
366e74e
precision
leemthompo Nov 21, 2025
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
22 changes: 21 additions & 1 deletion reference/glossary/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -264,6 +264,26 @@
$$$glossary-elastic-stack$$$ {{stack}}
: Also known as the *ELK Stack*, the {{stack}} is the combination of various Elastic products that integrate for a scalable and flexible way to manage your data.

$$$glossary-elasticsearch$$$ {{es}}
: The open source search and analytics engine, data store, and vector database which is the core of the [{{stack}}](#glossary-elastic-stack) and powers the Elastic platform.
Copy link
Collaborator

@shainaraskas shainaraskas Nov 21, 2025

Choose a reason for hiding this comment

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

🤔 what if this glossary definition just had all of the disambiguation stuff in it? elasticsearch might mean any of these things: ...

:::{admonition} Disambiguation
Copy link
Collaborator

@shainaraskas shainaraskas Nov 21, 2025

Choose a reason for hiding this comment

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

nitpick: disambiguation is a big word. how does "What else can Elasticsearch mean?" or something a little friendlier strike you?

The term "{{es}}" has several meanings depending on the context in which it is used.

**The standalone software**
- The [`elasticsearch` open source project](https://github.com/elastic/elasticsearch) is a standalone piece of software. Pre-built artifacts are available for download and installation from [elastic.co](https://www.elastic.co/downloads/elasticsearch), or you can build from source. Learn more about [deploying a self-managed cluster](/deploy-manage/deploy/self-managed.md).
Copy link
Contributor

@lcawl lcawl Nov 21, 2025

Choose a reason for hiding this comment

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

Is project intentional here?

Suggested change
- The [`elasticsearch` open source project](https://github.com/elastic/elasticsearch) is a standalone piece of software. Pre-built artifacts are available for download and installation from [elastic.co](https://www.elastic.co/downloads/elasticsearch), or you can build from source. Learn more about [deploying a self-managed cluster](/deploy-manage/deploy/self-managed.md).
- The [`elasticsearch` open source product](https://github.com/elastic/elasticsearch) is a standalone piece of software. Pre-built artifacts are available for download and installation from [elastic.co](https://www.elastic.co/downloads/elasticsearch), or you can build from source. Learn more about [deploying a self-managed cluster](/deploy-manage/deploy/self-managed.md).

Copy link
Contributor Author

@leemthompo leemthompo Nov 21, 2025

Choose a reason for hiding this comment

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

it was intentional, but maybe we don't need to mention either project or product here

Copy link
Collaborator

@shainaraskas shainaraskas Nov 21, 2025

Choose a reason for hiding this comment

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

is it important that we hint about methods of installation at this stage? for our own disambiguation needs, I think we need to get across that it is:

  • an analytics engine/data store/vector DB
  • an installable piece of software
  • a component of our platform / the elastic stack

- An `elasticsearch` [node](#glossary-node) is a running instance of the software, which can be part of a [cluster](#glossary-cluster) and exposes REST API endpoints. Refer to the [reference documentation](elasticsearch://reference/elasticsearch/index.md) for usage details.
Copy link
Collaborator

@shainaraskas shainaraskas Nov 21, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

I don't think we refer to nodes as "elasticsearch". we're more likely to refer to a cluster as "elasticsearch". would suggest removing this, and, in the definition above, we could say that it is distributable and link out to the architecture docs

also think that throwing to the reference docs does not help the user at this stage


<br>
**The project type / solution view**
- {{es}} is the name of a [project type (or solution view)](/solutions/search.md) that includes UI features tailored for general-purpose search use cases:
Copy link
Collaborator

@shainaraskas shainaraskas Nov 21, 2025

Choose a reason for hiding this comment

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

do we need to specify that what it brings is UI features? could we just say "that is tailored for x"?

consider splitting this in two and defining them separately to reduce mental load

Copy link
Collaborator

@shainaraskas shainaraskas Nov 21, 2025

Choose a reason for hiding this comment

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

looking at this again, I see what you wrapped them together (to connect them well to the search solution section). I still think we should split them and just link to the search section on general-purpose search use cases or something instead in each definition perhaps

- {{es}} is the name of a **project** type on {{serverless-full}}.
- {{es}} is the name of a **solution** in {{stack}} deployments. Each [space](#glossary-space) has its own navigation or "solution view".

<br>
**The platform**
- The {{es}} [platform](https://www.elastic.co/platform) (also known as the Elastic platform or Search AI Platform) refers to various {{stack}} components deployed together with additional management affordances to power Elastic's managed services.
Copy link
Contributor

@lcawl lcawl Nov 21, 2025

Choose a reason for hiding this comment

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

IMO this is the piece that still needs refinement since it's not clear on that site how the "platform" concept overlaps with the Stack or the deployment types.

Suggested change
- The {{es}} [platform](https://www.elastic.co/platform) (also known as the Elastic platform or Search AI Platform) refers to various {{stack}} components deployed together with additional management affordances to power Elastic's managed services.
- The {{es}} [platform](https://www.elastic.co/platform) (also known as the Elastic platform or Search AI Platform) refers to various {{stack}} components deployed together with additional management affordances to power Elastic's managed services.

Copy link
Contributor Author

@leemthompo leemthompo Nov 21, 2025

Choose a reason for hiding this comment

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

yeah we shouldn't link there, this is all mainly food for thought, but perhaps if we define "platform" satisfactorily in the glossary too, we can just link to that definition here and reuse it when we revisit the fundamentals or wherever we explain the platform more thoroughly

Copy link
Collaborator

@shainaraskas shainaraskas Nov 21, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

consider rolling stack into this (another former/current name of the platform, currently the docs name for the versioned platform)

:::

$$$glossary-elasticsearch-service$$$ Elasticsearch Service
: The former name of {{ech}}, which is the official hosted {{stack}} offering, from the makers of {{es}}. Available as a software-as-a-service (SaaS) offering on different cloud platforms, such as AWS, GCP, and Microsoft Azure.

Expand Down Expand Up @@ -543,7 +563,7 @@
: In {{ecloud}}, the application of a rolling update on your deployment without actually applying any configuration changes. This type of update can be useful to resolve certain health warnings.

$$$glossary-node$$$ node
: 1. A single {{es}} server. One or more nodes can form a [cluster](/reference/glossary/index.md#glossary-cluster). See [Clusters, nodes, and shards](/deploy-manage/production-guidance/elasticsearch-in-production-environments.md).
: 1. A single [{{es}}](#glossary-elasticsearch) server. One or more nodes can form a [cluster](/reference/glossary/index.md#glossary-cluster). See [Clusters, nodes, and shards](/deploy-manage/production-guidance/elasticsearch-in-production-environments.md).

Check notice on line 566 in reference/glossary/index.md

View workflow job for this annotation

GitHub Actions / vale 

Elastic.WordChoice: Consider using 'refer to (if it's a document), view (if it's a UI element)' instead of 'See', unless the term is in the UI.
2. In {{eck}}, it can refer to either an [Elasticsearch Node](elasticsearch://reference/elasticsearch/configuration-reference/node-settings.md) or a [Kubernetes Node](https://kubernetes.io/docs/concepts/architecture/nodes/) depending on the context. ECK maps an Elasticsearch node to a Kubernetes Pod which can get scheduled onto any available Kubernetes node that can satisfy the [resource requirements](/deploy-manage/deploy/cloud-on-k8s/manage-compute-resources.md) and [node constraints](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/) defined in the [pod template](/deploy-manage/deploy/cloud-on-k8s/customize-pods.md).

$$$NodeSet$$$NodeSet
Expand Down
Loading