elastic/elasticsearch

来源：https://github.com/elastic/elasticsearch

= Elasticsearch

Elasticsearch 是一个分布式搜索与分析引擎、可扩展的数据存储和向量数据库，针对生产级工作负载的速度和相关性进行了优化。Elasticsearch 是 Elastic 开源 Stack 平台的基础。对海量数据集进行近实时搜索、执行向量搜索、集成生成式 AI 应用程序，以及更多功能。

Elasticsearch 支持的应用场景包括：

• https://www.elastic.co/search-labs/blog/articles/retrieval-augmented-generation-rag[检索增强生成（RAG）]
• https://www.elastic.co/search-labs/blog/categories/vector-search[向量搜索]
• 全文搜索
• 日志
• 指标
• 应用性能监控（APM）
• 安全日志

\… 等等！

要了解 Elasticsearch 的更多特性和能力，请参阅我们的 https://www.elastic.co/products/elasticsearch[产品页面]。

要获取关于 https://www.elastic.co/search-labs/blog/categories/ml-research[机器学习创新] 以及 Elastic 对 https://www.elastic.co/search-labs/blog/categories/lucene[Lucene 的最新贡献] 的信息，可访问 https://www.elastic.co/search-labs[Search Labs] 了解更多。

[[get-started]] == 入门

设置 Elasticsearch 的最简单方式是创建一个托管部署，使用 https://www.elastic.co/cloud/as-a-service[Elastic Cloud 上的 Elasticsearch Service]。

如果您更倾向于自行安装和管理 Elasticsearch，可以从 https://www.elastic.co/downloads/elasticsearch[elastic.co/downloads/elasticsearch] 下载最新版本。

=== 在本地运行 Elasticsearch

//// 重要：此内容已复制到 Elasticsearch 仓库中。请参阅 run-elasticsearch-locally.asciidoc。 确保两个文件同步。

https://github.com/elastic/start-local 是权威来源。 ////

[WARNING]

请勿将这些说明用于生产环境部署。

此设置仅适用于本地开发与测试。

使用 https://github.com/elastic/start-local?tab=readme-ov-file#-try-elasticsearch-and-kibana-locally[start-local 脚本] 在 Docker 中快速搭建 Elasticsearch 和 Kibana，用于本地开发或测试。

i️ 关于 start-local 设置的更详细信息，请参考 https://github.com/elastic/start-local[GitHub 上的 README]。

==== 前提条件

• 如果尚未安装 Docker，请根据您的操作系统 https://www.docker.com/products/docker-desktop[下载并安装 Docker Desktop]。
• 如果您使用 Microsoft Windows，请安装 https://learn.microsoft.com/en-us/windows/wsl/install[适用于 Linux 的 Windows 子系统（WSL）]。

==== 试用许可证 此设置附带一个月的试用许可证，包含所有 Elastic 功能。

试用期结束后，许可证将恢复为 Free and open - Basic。 更多信息请参阅 https://www.elastic.co/subscriptions[Elastic 订阅]。

==== 运行 start-local

要在本地搭建 Elasticsearch 和 Kibana，请运行 start-local 脚本：

[source,sh]

curl -fsSL https://elastic.co/start-local | sh

// NOTCONSOLE

此脚本会创建一个包含配置文件的 elastic-start-local 文件夹，并使用 Docker 启动 Elasticsearch 和 Kibana。

脚本运行后，您可以通过以下端点访问 Elastic 服务：

• Elasticsearch: http://localhost:9200
• Kibana: http://localhost:5601

脚本会为 elastic 用户生成一个随机密码，该密码会在安装结束时显示并保存在 .env 文件中。

[CAUTION]

此设置仅用于本地测试。HTTPS 已禁用，Elasticsearch 使用基本身份验证。出于安全考虑，Elasticsearch 和 Kibana 仅可通过 localhost 访问。

==== API 访问

Elasticsearch 的 API 密钥已生成并保存在 .env 文件中，变量名为 ES_LOCAL_API_KEY。 使用此密钥，通过 https://www.elastic.co/guide/en/elasticsearch/client/index.html[编程语言客户端] 或 https://www.elastic.co/guide/en/elasticsearch/reference/current/rest-apis.html[REST API] 连接到 Elasticsearch。

在 elastic-start-local 文件夹中，使用 curl 检查与 Elasticsearch 的连接：

[source,sh]

source .env curl $ES_LOCAL_URL -H “Authorization: ApiKey ${ES_LOCAL_API_KEY}”

要使用 elastic 用户的密码，请设置并导出 ES_LOCAL_PASSWORD 环境变量。例如：

[source,sh]

source .env export ES_LOCAL_PASSWORD

// NOTCONSOLE

=== 向 Elasticsearch 发送请求

您通过 REST API 向 Elasticsearch 发送数据和其他请求。您可以使用任何发送 HTTP 请求的客户端与 Elasticsearch 交互，例如 https://www.elastic.co/guide/en/elasticsearch/client/index.html[Elasticsearch 语言客户端] 和 https://curl.se[curl]。

==== 使用 curl

以下是一条使用基本身份验证创建新 Elasticsearch 索引的示例 curl 命令：

[source,sh]

curl -u elastic:$ES_LOCAL_PASSWORD
-X PUT
http://localhost:9200/my-new-index
-H ‘Content-Type: application/json’

// NOTCONSOLE

==== 使用语言客户端

要使用语言客户端连接到本地开发 Elasticsearch 集群，您可以使用基本身份验证，用户名 elastic，密码存储在 ES_LOCAL_PASSWORD 环境变量中。

您将使用以下连接信息：

• Elasticsearch 端点：http://localhost:9200
• 用户名：elastic
• 密码：$ES_LOCAL_PASSWORD（您在环境变量中设置的值）

例如，使用 Python 的 elasticsearch 客户端连接：

[source,python]

import os from elasticsearch import Elasticsearch

username = ‘elastic’ password = os.getenv(‘ES_LOCAL_PASSWORD’) # 您在环境变量中设置的值

client = Elasticsearch( “http://localhost:9200”, basic_auth=(username, password) )

print(client.info())

==== 使用 Dev Tools 控制台

Kibana 的开发者控制台提供了一个方便的实验和测试请求的方式。要访问控制台，请打开 Kibana，然后转到 Management > Dev Tools。

添加数据

您通过 REST API 发送 JSON 对象（文档）将数据索引到 Elasticsearch。无论您拥有结构化或非结构化文本、数值数据还是地理空间数据，Elasticsearch 都能高效地存储和索引它们，以支持快速搜索。

对于时间戳数据（如日志和指标），您通常会将文档添加到由多个自动生成的后备索引组成的数据流中。

要向索引添加单个文档，请提交一个针对该索引的 HTTP POST 请求。

POST /customer/_doc/1 { “firstname”: “Jennifer”, “lastname”: “Walters” }

如果 customer 索引不存在，此请求会自动创建它，添加一个 ID 为 1 的新文档，并存储和索引 firstname 和 lastname 字段。

新文档会立即在集群中的任何节点上可用。您可以通过指定文档 ID 的 GET 请求来检索它：

GET /customer/_doc/1

要在一个请求中添加多个文档，请使用 _bulk API。批量数据必须采用换行符分隔的 JSON（NDJSON）格式。每行必须以换行符（\n）结尾，包括最后一行。

PUT customer/_bulk { “create”: { } } { “firstname”: “Monica”,“lastname”:“Rambeau”} { “create”: { } } { “firstname”: “Carol”,“lastname”:“Danvers”} { “create”: { } } { “firstname”: “Wanda”,“lastname”:“Maximoff”} { “create”: { } }

搜索

索引后的文档几乎可以实时用于搜索。以下搜索在 customer 索引中匹配所有名字为 Jennifer 的客户。

GET customer/_search { “query” : { “match” : { “firstname”: “Jennifer” } } }

探索

您可以使用 Kibana 中的 Discover 交互式搜索和过滤数据。从那里，您可以开始创建可视化并构建和分享仪表板。

首先，创建一个连接到单个或多个 Elasticsearch 索引、数据流或索引别名的 数据视图。

. 转到 Management > Stack Management > Kibana > Data Views。 . 选择 Create data view。 . 输入数据视图的名称和匹配一个或多个索引的模式，例如 customer。 . 选择 Save data view to Kibana。

要开始探索，请转到 Analytics > Discover。

[[upgrade]] == 升级

要从较早版本的 Elasticsearch 升级，请参阅 https://www.elastic.co/guide/en/elasticsearch/reference/current/setup-upgrade.html[Elasticsearch 升级文档]。

[[build-source]] == 从源码构建

Elasticsearch 使用 https://gradle.org[Gradle] 作为其构建系统。

要为本地操作系统构建分发版，并在完成后打印其输出位置，请运行：

./gradlew localDistro

要为另一个平台构建分发版，请运行相关命令：

./gradlew :distribution:archives:linux-tar:assemble ./gradlew :distribution:archives:darwin-tar:assemble ./gradlew :distribution:archives:windows-zip:assemble

分发版输出到 distribution/archives。

要运行测试套件，请参阅 TESTING。

[[docs]] == 文档

如需完整的 Elasticsearch 文档，请访问 https://www.elastic.co/guide/en/elasticsearch/reference/current/index.html[elastic.co]。

有关我们文档流程的信息，请参阅 docs README。

[[examples]] == 示例与指南

https://github.com/elastic/elasticsearch-labs[elasticsearch-labs] 仓库包含可执行的 Python 笔记本、示例应用程序和资源，可用于测试 Elasticsearch 在向量搜索、混合搜索和生成式 AI 应用场景下的表现。

[[contribute]] == 贡献

有关贡献指南，请参阅 CONTRIBUTING。

[[questions]] == 有问题？遇到困难？有建议？

• 要报告错误或请求功能，请创建一个 https://github.com/elastic/elasticsearch/issues/new/choose[GitHub Issue]。请确保其他人尚未针对同一主题创建 issue。

• 需要 Elasticsearch 使用帮助？请通过 https://discuss.elastic.co[Elastic 论坛] 或 https://ela.st/slack[Slack] 联系我们。社区成员或 Elastic 工程师很乐意帮助您。