https://www.elastic.co/guide/en/elasticsearch/reference/current ElasticSearch官方文档
命令选项
- elasticsearch
- -d 后台运行
- -p 指定pid文件
- -E 配置属性
<KeyValuePair> - -v --verbose
- -q --quiet
- -s --silent
启动停止
- 启动
- 直接启动
bin/elasticsearch [-d] [-E <KeyValuePair>] [-p pidfile] - 服务管理命令启动
- 直接启动
- 停止 （正常停止 从集群中移除--sync事务日志到磁盘--执行其他相关清理活动）（SIGTERM信号 control-C）
- 直接启动停止 kill [-15|-SIGTERM] pid
- 服务管理命令停止
- Elasticsearch虚拟机出现重大错误（包括OOM，虚拟机内部错误以及严重IO错误）时，Elasticsearch会尝试记入日志并且停止虚拟机，会返回致命错误性质的状态码
- 128 JVM内部错误
- 127 OOM
- 126 栈溢出
- 125 未知虚拟机错误
- 124 严重IO错误
- 1 未知严重错误
GET
_cat 查看集群状态
-
_cat/health 集群健康状态
-
_cat/nodes 集群节点及其状态
-
_cat/indices 集群索引及其状态
-
_nodes 可以查看节点信息
-
_nodes/stats 查看节点状态
-
_nodes/stats/process 查看节点运行状态
-
/index_name[/_doc]/_search 搜索api
- /index_name/_search?sort=field:acs&pretty rest请求url方式 参数名=参数值 ， &分割
- response
- took 执行搜索毫秒数
- timed_out 是否超时 超时会将已经获取的结果聚合返回
- _shards 搜索分片信息
- total 搜索总分片数
- skipped
- 失败分片数
- hits 搜索结果
- total 匹配搜索条件的总命中数
- max_score 最高相关性得分
- hits 实际搜索结果数组
- _index 文档索引
- _type 文档类型
- _id 文档id元数据
- sort 排序
- _score 相关性得分
- _source 文档元数据
- /index_name/_search {searchBody} 请求体搜索 (domain-specific language)DSL 请求体
-
GET /index_name/_doc/id 检索api
- types 在新的ElasticSearch版本中已经准备移除，ElasticSearch之后的版本会将 GET /index_name/type/id api改为 GET /index_name/_doc/id
POST (Http Header:"Content-Type:application/json")
- /index_name/_doc {body} 索引文档，自行生成文档id
- /index_name/_doc/id/_update 更新文档（应用更改部分，重新索引)
- /index_name/_update_by_query {update[Script],searchBody} 根据查询条件更新文档
- /index_name/_delete_by_query {searchBody} 根据条件删除文档
- /index_name/_doc/_bulk {opt1}{body1}{opt2}{body2}... 批量操作bulk
PUT
- /index_name [{body}] 创建索引api [索引内容 配置、字段]
- /index_name/_doc/id {body} 指定id索引文档
DELETE
- DELETE /index_name 删除索引api
- DELETE /index/_doc/id 删除id对应文档
参数
v vv vvv 详细输出
pretty 格式化输出
refresh 将缓存内容更新到索引
filter_path 可以过滤处指定信息
查询请求体
-
query 查询
- match_all 查询全部文档
- match 将查询输入标准化后进行匹配
- match_phrase 短语匹配 查询包含有序的term的文档
- bool
- must 布尔查询，必须
- should 布尔查询，符合加相关性得分
- must_not 排除
- range 范围搜索 （如数值、日期）
- gt
- gte
- lt
- lte
- ranges[{range1},{range2}...] 按范围分组 aggs中
-
filter 过滤 可以嵌入到查询条件中
-
aggs/aggregations 聚合 {"aggs":{"agg1":{"agg_fun1":{{"fun1"},"order":{"agg2":"asc/desc"}},"aggs":{"agg2":{{"agg_fun2"}}}}}}
- terms 以字段term聚合
- avg 求平均值
-
size 返回搜索结果条数
-
from 搜索结果偏移量 从0开始 （各分片获取前 from+size个文档，返回一个简单文档信息给调用节点，该节点聚合结果，然后向各分片获取详细文档，然后返回给客户端)
-
sort 排序
-
_source ["field1","field2"]返回文档字段
-
field
-
order
配置 一般可以在运行时使用集群设置更新api设定 配置文件中一般只要包含节点制定的配置（如node.name）及加入集群用的配置（如cluster.name）
环境变量配置
- 系统配置文件 Debian /etc/default/elasticsearch , RPM /etc/sysconfig/elasticsearch
- $ES_HOME ElasticSearch解压根目录
- $ES_HOME/bin 默认bin目录
- $ES_PATH_CONF $ES_HOME/config 配置文件目录
- $ES_HOME/plugins 插件目录位置
elasticsearch.yml Elasticsearch配置 yaml格式 可用${...}使用环境变量 使用${prompt.text}/${prompt.secret}在启动Elasticsearch时输入设定值（后台启动时不可用）
- path.data $ES_HOME/data 数据目录
- 数据文件可以存储到多个路径（单个分片的文件会全部存储到同一路径），用法
-
path: -
data: -
- path1 -
- path2 -
- path3
-
- 数据文件可以存储到多个路径（单个分片的文件会全部存储到同一路径），用法
- path.logs $ES_HOME/logs 日志目录
- path.repo 共享文件系统位置
- path.scripts $ES_HOME/scripts script文件目录
- cluster.name 集群名称 节点会加入同名称的节点
- node.name 节点名称
- network.host Elasticsearch监听地址 默认监听本地回路，（可以使用同一个Elasticsearch启动多个节点测试Elasticsearch集群能力）
- discover.zen.ping.unicast.hosts 完成节点间发现和主节点选举(默认会扫描本地回路的9300-9305端口发现同主机其他节点自动完成集群)
-
discover.zen.ping.unicast.hosts: - (host1/domian1)[:port] - (host2/domian2)[:port] （没有指定端口时，将默认端口为transport.profiles.default.port 返回到transport.tcp.port） (解析到多个ip地址的主机名称会尝试所有被解析的地址) - discovery.zen.minimum_master_nodes 指定组成集群必须能发现的能成为主节点的最小节点数量，用来防止数据丢失，没有这个设定时，在集群出现网络问题时有脑裂为两个独立集群的风险，脑裂会导致数据丢失，为避免脑裂，应设为
-
discovery.zen.minimum_master_nodes:(master_eligible_nodes / 2) + 1 - discovery.type 发现集群其他节点方式
- index.unassigned.node_left.delayed_timeout 当一个节点关闭时，分配进程开始分配复制分片到集群其他节点的等待时间。
keystore 对支持的属性，可以在启动Elasticsearch的用户下使用keystore方式设置属性，对其他用户进行隐藏，keystore修改的属性在下次重启Elasticsearch时才会生效
- elasticsearch-keystore
- create
- list
- add (可以使用--stdin使用管道输入)
- remove
jvm.options Elasticsearch JVM配置
- 每行分割配置
- 只有空格的行忽略
- 以#开始的为注释
- 以-开始的会单独作为JVM参数应用
- 以数字开头，接冒号 num:/num-:/num1-num2: 在JVM版本匹配数字时应用
- 其他的行无效
- 也可以通过 ES_JAVA_OPTS环境变量设置JVM选项(不支持JAVA_OPTS环境变量)
- 生产环境较推荐的JVM参数设定规则
- 最小堆大小Xms和最大堆大小Xmx设为相同
- Elasticsearch分配了越大的堆空间，就有越大的缓存可用，但是过大的堆大小同样会产生过长的垃圾回收暂停问题
- 设置最大堆大小不要超过物理内存的50%，确保核心系统缓存有足够的物理内存来进行缓存
- 设置的最大堆大小不要超过JVM压缩指针截止点，确切的截止点在接近32G处变化。
- 保持处于零基压缩的阈值以下会更好，确切的阈值不同，在大多数系统上，26G是安全的，而在一些系统上能超过30G，可以通过在启动Elasticsearch时使用JVM选项 -XX:+UnlockDiagnosticVMOptions -XX:+PrintCompressedOopsMode进行验证。
- -XX:HeapDumpPath 设置OOM时适合的的堆dump文件存储位置，默认没有配置，会将堆存到Elasticsearch进程的工作目录。
- jvm.options中默认配置的gc日志在64M时进行轮替，保留32个日志文件（2G多）
- es.enforce.bootstrap.checks 强制启动检测
log4j2.properties Elasticsearch日志配置 log4j 2
- ${sys:es.logs.baes_path} path.logs
- ${sys:es.logs.cluster_name} cluster.name
- ${sys:es.logs.logs.node_name} node.name(若存在)
- 配置首尾不能有空格
- 配置日志级别
- 命令行输入
-E <name of logging hierarchy>=<level> - elasticsearch.yml配置
<name of logging hierarchy>: <level> - 集群设定
PUT /_cluster/settings {"transient":{"<name of logging hierarchy>": "<level>" }} - log4j2.properties配置
logger.<unique_identifier>.name = <name of logging hierarchy>logger.<unique_identifier>.level = <level>
- 命令行输入
系统配置 理想状态下，Elasticsearch可以单独在一台服务器上运行，能够独占服务器的所有资源，需要对操作系统进行一些配置使Elasticsearch能够比默认情况下获取更多的资源，在应用这些设置之前应该经过慎重考虑
- 文件句柄限制（pam模组）：
- 解压安装：临时设置ulimit，长久设置/etc/security/limits.conf
- 包管理工具安装RPM/Debian：服务配置文件：/etc/sysconfig/elasticsearch(RPM)|/etc/default/elasticsearch(Debian)|systemd架构的服务配置文件
- 不使用交换区：交换区使用磁盘缓存，一旦使用到交换区，极大影响程序运行效率，对于Elasticsearch，可能引起垃圾回收时间长，节点响应缓慢，甚至断开集群连接。配置文件中可以使用bootstrap.memory_lock: true使用mlockall阻止Elasticsearch使用交换区，进行配置以后，当尝试分配超过可用内存时，可能导致JVM或shell session退出(可能失败原因有用户没有锁内存的权限|临时文件目录文件系统挂载时使用了noexec标记)。
- Elasticsearch使用了大量的文件描述符/文件句柄(Linux/Windows)，超过可用的文件描述符会导致有很大可能会造成数据丢失，需要确保Elasticsearch可用的文件描述符为65536或者更高(/proc/pid/fd/)
- Elasticsearch使用内存文件映射（mmapfs(/proc/pid/map_files|/proc/pid/maps)）（像linux缓存常用文件一样），虚拟内存映射max_map_count系统预设值过低，容易引起OOM,需要增大系统max_map_count到262144，使用systemctl指令或sysctl.conf配置文件设置vm.max_map_count=262144
- Elasticsearch对不同的操作类型使用了大量的线程池，一旦有需要时就能创建新的线程很重要。需要确保启动Elasticsearch的用户最少能够创建4096个线程。
- 同时启动Java security manager时，JVM默认会缓存解析的主机名称，当环境中的DNS解析变更时，希望能改变默认JVM行为，可以通过添加
networkaddress.cache.ttl=<timeout>到Java security policy中。启动Java security manager时，当主机名称解析失败时，默认会缓存10秒，可以通过添加networkaddress.cache.negative.ttl=<timeout>到Java security policy中修改。<timeout>为0不缓存，为-1永久缓存。 - 这些配置不正确时(除了文件句柄配置)，开发环境下会在日志文件中输出警告，并且仍然允许启动，一旦修改了如network.host这样的网络配置，Elasticsearch就会判断进入了生产环境，前面的警告会变为异常，这些异常会阻止节点的启动，这是保证你不会由于一个配置不当的服务器丢失数据的重要安全措施。
启动检验
- 在Elasticsearch之前的版本中，不适当的重要配置会在日志中输出警告，为了确保这些设置受到应有的关注，Elasticsearch在启动时进行检查。检查会比较Elasticsearch变量和系统设置与操作安全的值比较，如果处于开发模式，任何失败的检测会在日志输出警告，如果处于生产模式，任何检测失败会导致Elasticsearch启动失败。这些检查总是强制阻止Elasticsearch运行在一个不正确的配置下。
- 堆大小检查 当设置不相等的初始堆大小和最大堆大小，在系统使用过程中，容易因为调整对大小造成停顿。另外，如果bootstrap.memory_lock内存锁启用，JVM在启动时会锁上初始堆的大小。如果初始堆大小与最大堆大小不等，在改变大小堆大小后不是所有的JVM堆内存都被锁上。
- 文件描述符检查 在Unix中，一切都是文件，构建文件描述符追踪打开的文件，Elasticsearch需要大量的文件描述符。
- 内存锁检查 在JVM进行主垃圾回收时，会涉及到堆中的每一页，如果有任何内存页被交换到磁盘交换区，都必须被交换回内存，这会导致大量磁盘和实体内存间的数据交换。一种禁止使用交换区的方式是使用mlockall，可以在Elasticsearch设置bootstrap.memory_lock使JVM锁上堆内存，但是实际没有锁上时也会通过检测，检测节点bootstrap.memory_lock是否实际启用。
- 最小线程数检查 在Elasticsearch的请求进入阶段，会分割为多个请求，并在阶段完成时在不同的线程池处理。Elasticsearch用不同的线程池执行不用的任务。最少要保证Elasticsearch进程能创建4096个线程（可能还需要增加root用户的限制）。
- 最大虚拟内存检查 Elasticsearch符合Lucene使用mmap将索引数据的部分直接映射到Elasticsearch的地址空间，所以能够直接通过内存而不是JVM堆快速访问确定的索引数据。为了使其生效，Elasticsearch应该具有不被限制的地址空间，需要设置limits.conf的as（address space limit）为unlimited。
- 最大文件大小检查 片段文件组成独立的分片，事物日志可以变得很大（超过几个GB）。在限制了最大文件大小的系统上，这会导致写入失败。最安全的方法是解除最大文件大小的限制。
- 虚拟内存映射打开上限检查 使用mmap是有效的，Elasticsearch同样需要创建大量内存映射区域的能力，Elasticsearch需要至少262144的内存映射区域（个数，不是大小），需要设置vm.max_map_count。
- JVM检查 （对于OpenJDK）从OpenJDK能获取到两种JVM：the client JVM 、the server JVM。对于同样的Java字节码，他们会使用不同的编译器产生不同的机器码。The client JVM 针对启动时间和内存使用进行了调整，而 the server JVM 做了最大性能优化。两个虚拟机之间的差异是巨大的。不能在 the client JVM 中运行Elasticsearch。（也支持OracleJDK）。在现代系统中，默认是 the server VM。
- 使用串行收集器检查 OpenJDK对不同的工作负荷提供了多种垃圾回收器。串行收集器最适合于单逻辑CPU或极小的堆，他们都不适合运行Elasticsearch。使用串行收集器会给Elasticsearch的性能产生毁灭性的影响。串行收集器检测会确保Elasticsearch没有配置使用串行收集器。要通过串行收集器检测，不能使用串行收集器启动Elasticsearch（无论是来自你使用的JVM的默认收集器还是通过使用 -XX:+UseSerialGC 明确指定）。Elasticsearch的jvm配置默认使用CMS收集器(jvm.options)。
- 系统调用过滤器检查 Elasticsearch 根据操作系统安装各种风格的系统调用过滤器（如Linux上的seccomp安全计算模式secure computing mode）。安装这些系统调用过滤器是为了防止执行系统调用相关的防御机制的仍以代码选择执行阻止Elasticsearch fork的能力。系统调用过滤器检测确保系统调用过滤器可用，并且被成功安装。要通过系统调用过滤器检测，必须同时修复所有阻止安装的系统调用过滤器的错误系统配置（通过检查日志），或者设置bootstrap.system_call_filter为false并自负风险。
- 错误时及OOM错误时检查 JVM选项 OnError 和 OnOutOfMemoryError 允许在JVM发生重大错误OnError或一个OutOfMemoryError时执行任意命令。而默认情况下，Elasticsearch系统调用过滤器（seccomp）被启用并且这些过滤器阻止fork。使用 OnError 和 OnOutOfMemoryError 与系统调用过滤器是兼容的。OnError 和 OnOutOfMemoryError 检测会在这些JVM参数中的任一个使用同时启用系统调用过滤器时阻止Elasticsearch启动。通过检测的方式是不启用OnError或OnOutOfMemoryError，取代的，在Java 8u92版本使用JVM 标记 ExitOnOutOfMemoryError ，在seccomp启用时，任意forking都不被支持。
- 先行版检查 OpenJDK提供即将发布的发行版的先行可获取快照版本。这些发行版不适用于生产环境。先行版检测侦测先行快照。为了通过检测，必须使用JVM的发行版来启动Elasticsearch
- G1GC检查 JDK8 HotSpot JVM 的早期版本使用G1收集器时会导致索引损坏，早于JDK 8u40的HotSpot版本会受到影响。
- all permission检查 确保不会将 java.security.AllPermission 授予Elasticsearch。授予 all permission 权限相当于禁用了安全管理器。
开发模式和生产模式
- 使用非单节点发现的非回路地址会判别为生产模式。默认Elasticsearch使用回路地址的http和（内部）通信传输，这方便于日常开发，而对于生产环境，是无用的。为了加入一个集群，Elasticsearch必须能通过传输通信访问。一个节点需要bind到一个非回路地址，并且不使用单节点发现来加入一个非回路地址集群。http和传输（tcp）地址使用http.host和transport.host指定，出于测试目的，使用一个通过http可访问的单节点而不触发生产模式是很有效的。
- 单节点模式：一些用户需要bind到外部tcp端口来测试他们的 transport client的用法，为了这种情形，Elasticsearch提供了single-node的发现模式 discovery.type = single-node ，这种情形下，一个节点会选举自身为主节点并且不会加入一个有其他任何节点的集群。在生产环境使用单节点而能够避过强制启动检查时，可以设定JVM选项 es.enforce.bootstrap.checks=true 强制执行启动检查。当处于这种特殊情形时，强烈鼓励启动检查（为了生产环境的稳定）。
API交互
- Elasticsearch REST API 在HTTP上使用JSON进行交互
- 除非特别指定，可以通过REST API使用以下的API：
- Multiple Indices
- Date math support in index names
- Common options
- URL-based access control
Multiple Indices
- 多数APIs通过执行multiple indices支持
index参数，使用简单的test1,test2,test3标记（或者_all代表全部索引）。也支持通配符，例如：test*、*test、te*t或*test*，并且可以进行排除（-），如：test*,-test3。 - 所有的multi indices API支持下面的url query string参数
ignore_unavailable控制当有任何指定的索引不可用（包括不存在的或关闭的索引）时，是否忽略。可以指定为true|falseallow_no_indices控制一个索引通配表达式没有实际的索引时，是否失败。可以指定为true|false。例如使用通配表达式foo并且没有以foo开始的可用索引会根据这个设定决定请求是否为fail。这个设定同样适用于_all，或没有指定索引。在一个别名指向一个关闭的索引时，这个设定同样可以应用到别名expand_wildcards控制索引通配表达式拓展的具体类型。如果指定为open则通配表达式仅在打开的索引上拓展，如果指定为closed则通配表达式仅在关闭的索引上拓展，同时指定（open,closed）指定拓展到全部索引。如果指定为none，关闭通配，如果指定为all通配表达式拓展到全部索引（与指定为open,closed相同）- 以上参数的默认值取决于使用的api
- 单索引APIs如Document APIs和single-index alias APIs不支持 multiple indices
Date math support in index names
- 日期计算索引名称解析允许你搜索一个时间序列范围内的索引，而不是搜索所有时间序列索引并在结果中过滤，或者维护别名。限定索引数量减少集群搜索负载，并且提高搜索性能。例如，如果搜索你每日的错误日志，可以使用一个 date math name template 来限定搜索到两天内。
- 几乎所有具有 index 参数的索引，在
index参数中支持时间序列。一个时间序列索引名通过以下形式获得
<static_name{date_math_expr{date_format|time_zone}}>static_name为名称的静态文本部分date_math_expr为动态计算时间的动态时间表达式date_format为日期计算应该使用的格式选项，默认为YYYY.MM.ddtime_zone时区选项，默认为utc
- 你必须使用方括号包围你的date math index name expressions，并且所有特殊字符应该被URI encoded，例如
# GET /<logstash-{now/d}>/_search
GET /%3Clogstash-%7Bnow%2Fd%7D%3E/_search
{
"query" : {
"match": {
"test": "data"
}
}
}
- 日期数值字符URI编码
| < | %3C |
| > | %3E |
| / | %2F |
| { | %7B |
| } | %7D |
| + | %2B |
| : | %3A |
| , | %2C |
- 下面的形式显示解析 22rd March 2024 noon utc 为当前时间，解析到不同日期数值索引名格式和最终解析的索引名
|Expression|Resolves to|
|-|-|
|<logstash-{now/d}>|logstash-2024.03.22|
|<logstash-{now/M}>|logstash-2024.03.01|
|<logstash-{now/M{YYYY.MM}}>|logstash-2024.03|
|<logstash-{now/M-1M{YYYY.MM}}>|logstash-2024.02|
|<logstash-{now/d{YYYY.MM.dd|+12:00}}>|logstash-2024.03.23| - 为了在索引名称模板的静态部分使用字符
{和}，使用反斜杠\来escape，如<elastic\\{ON\\}-{now/M}>解析到elastic{ON}-2024.03.01 - 下面是一个搜索过去三天Logstash索引的搜索请求例子，嘉定索引使用默认Logstash索引名称格式
logstash-YYYY.MM.dd
# GET /<logstash-{now/d-2d}>,<logstash-{now/d-1d}>,<logstash-{now/d}>/_search
GET /%3Clogstash-%7Bnow%2Fd-2d%7D%3E%2C%3Clogstash-%7Bnow%2Fd-1d%7D%3E%2C%3Clogstash-%7Bnow%2Fd%7D%3E/_search
{
"query" : {
"match": {
"test": "data"
}
}
}
Common options
- 下列选项可以应用到REST APIs
Pretty Results当进行任何请求时附加一个?pretty=true，返回的JSON将会格式化梅花（只在调试时使用）。另一个选项是设置?format=yaml将会使返回值使用一个（有时）可读性更好的yaml格式Human readable output将返回更适合人类的统计值（如"exists_time": "1h"或"size": "1kb"）和社和计算机的（如"exists_time_in_millis": 3600000或"size_in_bytes":1024）。人类可读的值可以在query string中添加?human=false来关闭。当统计结果被一个监控工具消费而不是被人类消费时，这是有意义的。默认的human标记为falseDate Math多数参数接受一个格式化的时间值，例如在range queries中的gt和lt，或daterange aggregations中的from和to会理解日期计算。表达式以一个指定时间开始，包括now或者一个以||结尾的日期字符串。固定时间可以使用以下一个或多个计算表达式：+1h- 加一小时-1d- 减一天/d- 取整到最近一天- 支持的时间单位和持续时间的时间单位不同，支持的时间单位为：
|||
|-|-|
|y|年|
|M|月|
|w|周|
|d|天|
|h|时|
|H|时|
|m|分|
|s|秒| - 假设
now为2001-01-01 12:00:00，一些例子为：
now+1h
now in milliseconds plus one hour. Resolves to: 2001-01-01 13:00:00
now-1h
now in milliseconds minus one hour. Resolves to: 2001-01-01 11:00:00
now-1h/d
now in milliseconds minus one hour, rounded down to UTC 00:00. Resolves to: 2001-01-01 00:00:00
2001.02.01\|\|+1M/d
2001-02-01 in milliseconds plus one month. Resolves to: 2001-03-01 00:00:00
Response Filtering所有REST APIs接受一个filter_path参数用来减少Elasticsearch返回的响应。这个参数使用逗号分割使用.标记的过滤表达式列表：
GET /_search?q=elasticsearch&filter_path=took,hits.hits._id,hits.hits._score
Responds:
{
"took" : 3,
"hits" : {
"hits" : [
{
"_id" : "0",
"_score" : 1.6375021
}
]
}
}
* 同样支持使用*通配符匹配全部字段或字段名的部分
GET /_cluster/state?filter_path=metadata.indices.*.stat*
{
"metadata" : {
"indices" : {
"twitter": {"state": "open"}
}
}
}
* `**`通配符用来包含不知道字段确切路径时的字段名。例如，我们可以使用以下请求返回Lucene版本的每个片段：
GET /_cluster/state?filter_path=routing_table.indices.**.state
Responds:
{
"routing_table": {
"indices": {
"twitter": {
"shards": {
"0": [{"state": "STARTED"}, {"state": "UNASSIGNED"}],
"1": [{"state": "STARTED"}, {"state": "UNASSIGNED"}],
"2": [{"state": "STARTED"}, {"state": "UNASSIGNED"}],
"3": [{"state": "STARTED"}, {"state": "UNASSIGNED"}],
"4": [{"state": "STARTED"}, {"state": "UNASSIGNED"}]
}
}
}
}
}
* 同样可以使用前缀`-`排除一个或多个字段：`GET /_count?filter_path=-_shards`
Responds:
{
"count" : 5
}
* 为了更多的控制，可以在一个表达式中同时使用包含和排除过滤。这种情况下，会先应用排除过滤，然后再进行包含过滤
GET /_cluster/state?filter_path=metadata.indices.*.state,-metadata.indices.logstash-*
Responds：
{
"metadata" : {
"indices" : {
"index-1" : {"state" : "open"},
"index-2" : {"state" : "open"},
"index-3" : {"state" : "open"}
}
}
}
* 注意Elasticsearch有时直接返回字段未加工的值，就像`_source`字段。如果你想要过滤`_source`字段，你应该考虑结合已经存在的`_source`参数与`filter_path`参数：
POST /library/book?refresh
{"title": "Book #1", "rating": 200.1}
POST /library/book?refresh
{"title": "Book #2", "rating": 1.7}
POST /library/book?refresh
{"title": "Book #3", "rating": 0.1}
GET /_search?filter_path=hits.hits._source&_source=title&sort=rating:desc
{
"hits" : {
"hits" : [ {
"_source":{"title":"Book #1"}
}, {
"_source":{"title":"Book #2"}
}, {
"_source":{"title":"Book #3"}
} ]
}
}
Flat Settingsflat_settings标记影响设定列表的翻译。当flat_settings标记为true，设定会返回扁平化格式：GET twitter/_settings?flat_settings=true
Returns:
{
"twitter" : {
"settings": {
"index.number_of_replicas": "1",
"index.number_of_shards": "1",
"index.creation_date": "1474389951325",
"index.uuid": "n6gzFZTgS664GUfx0Xrpjw",
"index.version.created": ...,
"index.provided_name" : "twitter"
}
}
}
* 当`flat_settings`标记为`false`时，settings会返回更人类可读的结构化格式：`GET twitter/_settings?flat_settings=false`
Returns:
{
"twitter" : {
"settings" : {
"index" : {
"number_of_replicas": "1",
"number_of_shards": "1",
"creation_date": "1474389951325",
"uuid": "n6gzFZTgS664GUfx0Xrpjw",
"version": {
"created": ...
},
"provided_name" : "twitter"
}
}
}
}
* `flat_settings`默认设定为`false`
ParametersREST参数（当使用HTTP，map to HTTP URL parameters）遵从使用下划线风格的约定Boolean Values所有的REST APIs参数（包括请求参数和JSON body）支持使用"true"和"false"指定布尔值true|false。所有其他的值会引起一个错误。Number Values所有的REST APIs支持数值参数为字符串，支持JSON天然数值类型。Time units在任何需要指定持续时间时，例如timeout参数，持续时间必须指定单位，如2d为两天，支持的单位如下：
|||
|-|-|
|d|天|
|h|小时|
|m|分|
|s|秒|
|ms|毫秒|
|micros|微秒|
|nanos|纳秒|Byte size units当需要指定数据字节大小时，如设定一个buffer size 参数时，必须指定值的单位，如10kb。注意单位使用1024进位，支持的单位为：
|||
|-|-|
|b|Bytes|
|kb|Kilobytes|
|mb|Megabytes|
|gb|Gigabytes|
|tb|Terabytes|
|pb|Petabytes|Unit-less quantities无数量单位意味着使用单位"bytes"或"Hertz"或"meter"或"long tonne"，如果数量过大，ELasticsearch将会输出像10m为10,000,000或者7k为7,000。这意味着当87时，仍会输出87。这些是支持的乘数：
|||
|-|-|
|‘’|Single|
|k|Kilo|
|m|Mega|
|g|Giga|
|t|Tera|
|p|Peta|Distance Units但需要指定距离时（如Geo Distance Query中的distance参数）如果没有指定时默认单位为米。距离可以指定为其他单位，如"1km"或"2mi"（2miles）。单位列表为：
|||
|-|-|
|Mile|mi|miles|
|Yard|yd|yards|
|Feet|ft|feet|
|Inch|in|inch|
|Kilometer|km|kilometers|
|Meter|m|meters|
|Centimeter|cm|centimeters|
|Millimeter|mm|millimeters|
|Nautical mile|NM,nmi|natuicalmiles|Fuzziness一些queries和APIs支持运行模糊匹配的参数，使用fuzziness参数，当queryingtext或keyword字段，fuzziness会解释为Levenshtein Edit Distance——使一个字符串与另一个字符串相同需要改变的字符数。fuzziness参数可以像这样指定：0，1，2最大允许的修改数量，AUTO局域term长度生成一个edit distance。可以选择AUTO:[low],[high]指定low and high distance arguments，如果没有指定，默认值为3和6，即AUTO:3,6，在以下长度将会：0..2必须完全匹配3..5允许单个edit>5允许两个edits- 通常偏向与用
AUTO作为fuzziness的值
Enabling stack trances当请求返回一个错误时，Elasticsearch默认不会包含错误的stack trace，你可以通过设置error_traceurl参数为true来开启这个行为。例如，当发送一个非法的size参数到_search API：
POST /twitter/_search?size=surprise_me
响应会像这样
{
"error" : {
"root_cause" : [
{
"type" : "illegal_argument_exception",
"reason" : "Failed to parse int parameter [size] with value [surprise_me]"
}
],
"type" : "illegal_argument_exception",
"reason" : "Failed to parse int parameter [size] with value [surprise_me]",
"caused_by" : {
"type" : "number_format_exception",
"reason" : "For input string: \"surprise_me\""
}
},
"status" : 400
}
* 但是当设置`error_trace=true`时
POST /twitter/_search?size=surprise_me&error_trace=true
响应为
{
"error": {
"root_cause": [
{
"type": "illegal_argument_exception",
"reason": "Failed to parse int parameter [size] with value [surprise_me]",
"stack_trace": "Failed to parse int parameter [size] with value [surprise_me]]; nested: IllegalArgumentException..."
}
],
"type": "illegal_argument_exception",
"reason": "Failed to parse int parameter [size] with value [surprise_me]",
"stack_trace": "java.lang.IllegalArgumentException: Failed to parse int parameter [size] with value [surprise_me]\n at org.elasticsearch.rest.RestRequest.paramAsInt(RestRequest.java:175)...",
"caused_by": {
"type": "number_format_exception",
"reason": "For input string: \"surprise_me\"",
"stack_trace": "java.lang.NumberFormatException: For input string: \"surprise_me\"\n at java.lang.NumberFormatException.forInputString(NumberFormatException.java:65)..."
}
},
"status": 400
}
Request body in query string对于不接受非POST请求的库，可以通过设置请求体为sourcequery string 参数代替。当使用这种方式，source_content_type参数也应该传递一个媒体类型的值，来制定source的格式，如application/jsonContent-Type Requirements请求体发送的内容类型必须使用Content-Type头指定，请求头的值必须映射到该API支持的一种格式。多数API支持JSON，YAML，CBOR和SMILE。bulk和multi-searchAPIs支持NDJSON（Newline delimited JSON），JSON和SMILE，而其他类型将会导致错误响应。另外，当使用sourcequery string参数时内容类型必须使用source_content_typequery string参数指定。
URL-based access conrtol
- 许多用户使用一个基于URL的访问控制代理来安全的访问Elasticsearch索引，对于multi-search，multi-get和bulk请求，用户可以选择在URL中指定一个索引，也可以在每个请求体中的单独请求中指定。这让基于URL的访问控制受到挑战。防止用户覆盖URL中指定的索引，在
elasticsearch.yml文件中添加设置rest.action.multi.allow_explicit_index: false，默认值为true当指定为false时，Elasticsearch将拒绝在请求体中指定一个确定索引的请求
