Manticore 允许创建分布式表，它们的行为类似普通的普通表或实时表，但实际上是用于搜索的子表集合。当向分布式表发送查询时，查询会被分配到集合中的所有表。服务器随后收集并处理响应，必要时对聚合值进行排序和重新计算。

从客户端的角度来看，感觉就像是在查询一个单一的表。

table foo {
    type = distributed
    local = bar
    local = bar1, bar2
    agent = 127.0.0.1:9312:baz
    agent = host1|host2:tbl
    agent = host1:9301:tbl1|host2:tbl2 [ha_strategy=random retry_count=10]
    ...
}

CREATE TABLE distributed_index type='distributed'
  local='local_index'
  agent='127.0.0.1:9312:remote_table';

分布式表的核心在于其所指向的子表列表。分布式表中有两种类型的子表：

1. 本地表：这些是与分布式表处于同一服务器上的表。要枚举本地表，使用语法 local =。你可以通过多行 local = 列出多个本地表，或者用逗号分隔将它们合并到一行列表中。

2. 远程表：这些是部署在服务器外部的表。要枚举远程表，使用语法 agent =。每一行代表一个端点或代理。每个代理可以包含多个外部位置和选项以决定其工作方式。更多详情见这里。需要注意的是，服务器对正在处理的表的类型不拥有任何信息。例如，如果你对一个不是 percolate 表的远程表 'foo' 发出 CALL PQ，可能会导致错误。

Manticore Search 中的远程表通过分布式表定义中的 agent 前缀表示。分布式表可以包含本地表和远程表的组合。如果没有提供本地表，分布式表将纯粹是远程的，仅作为代理。例如，您可能有一个监听多个端口并服务不同协议的 Manticore 实例，然后重定向查询到仅通过 Manticore 内部二进制协议接受连接的后端服务器，使用持久连接以减少建立连接的开销。 尽管纯远程分布式表本身不提供本地表，但它仍然消耗机器资源，因为它仍需要执行最终计算，如合并结果和计算最终的聚合值。

agent = address1 [ | address2 [...] ][:table-list]
agent = address1[:table-list [ | address2[:table-list [...] ] ] ]

agent 指令声明了每次搜索包含该分布式表时搜索的远程代理。这些代理本质上是指向网络表的指针。指定的值包括地址，还可以包括地址或地址和表列表的多个替代方案（代理镜像）。有关镜像语法，请参阅 镜像，有关如何选择镜像代理，请参阅 负载均衡。

地址规范必须是以下之一：

address = hostname[:port] # eg. server2:9312
address = /absolute/unix/socket/path # eg. /var/run/manticore2.sock

hostname 是远程主机名，port 是远程 TCP 端口号，table-list 是逗号分隔的表名列表，方括号 [] 表示可选子句。对于 TCP 连接，此端口是远程代理/API 端口（通常为 9312），而不是 MySQL 端口（9306）。

如果省略表名，假定为定义该行的同一表。换句话说，当为分布式表 'mycoolindex' 定义代理时，可以简单指向地址，默认查询该代理端点上的 mycoolindex 表。

如果省略端口号，默认是 9312。如果定义但无效（例如 70000），则跳过该代理。

可以将每个代理指向一个或多个位于一个或多个网络服务器上的远程表，没有限制。这使得几种不同的使用模式成为可能：

• 在多个代理服务器上分片并创建任意的集群拓扑
• 在多个代理服务器上分片以实现高可用性和负载均衡（请参阅 镜像 和 负载均衡）
• 在本地主机中分片以利用多个核心（不过，更简单的是使用多个本地表）

为了避免混淆：

• 一个 agent='host1|host2:table' 条目表示一个具有镜像后端的远程分片。
• 多个 agent='...' 条目表示多个远程分片。

所有代理都是并行搜索的。索引列表直接传递给远程代理。该列表在代理内具体如何搜索（顺序或并行）完全取决于代理的配置（参见threads设置）。主控无法远程控制此行为。

需要注意的是，代理查询中会忽略 LIMIT 选项。这是因为每个代理可能包含不同的表，因此客户端负责在最终结果集上应用限制。这就是为何对物理表的查询与对分布式表的查询在查询日志中体现不同。查询不能简单复制原始查询，否则不会产生正确结果。

例如，如果客户端执行查询 SELECT ... LIMIT 10, 10，且有两个代理，第二个代理只有 10 条文档，广播原始 LIMIT 10, 10 查询会导致第二个代理返回 0 条文档。然而，LIMIT 10,10 应该返回结果集中的第10到20条。为解决此问题，必须向代理发送更宽松限制的查询，例如默认 max_matches 值 1000。

比如，若有分布式表 dist 指向远程表 user，客户端查询 SELECT * FROM dist LIMIT 10,10 会被转换为 SELECT * FROM user LIMIT 0,1000 并发送至远程表 user。一旦分布式表收到结果，它将应用 LIMIT 10,10，返回请求的 10 条文档。

SELECT * FROM dist LIMIT 10,10;

查询将被转换为：

SELECT * FROM user LIMIT 0,1000

另外，值可以为每个单独代理指定选项，例如：

• ha_strategy - random, roundrobin, nodeads, noerrors（覆盖特定代理的全局 ha_strategy 设置；另请参阅 镜像）
• conn - pconn，持久连接（相当于在表级设置 agent_persistent）
• blackhole 0,1（与代理的 agent_blackhole 设置相同）
• retry_count 整数值（对应 agent_retry_count ，但提供的值不会乘以镜像数量）

agent = address1:table-list[[ha_strategy=value, conn=value, blackhole=value]]

示例：

# config on box1
# sharding a table over 3 servers
agent = box2:9312:shard1
agent = box3:9312:shard2
# config on box2
# sharding a table over 3 servers
agent = box1:9312:shard2
agent = box3:9312:shard3
# config on box3
# sharding a table over 3 servers
agent = box1:9312:shard1
agent = box2:9312:shard3
# per agent options
agent = box1:9312:shard1[ha_strategy=nodeads]
agent = box2:9312:shard2[conn=pconn]
agent = box2:9312:shard2[conn=pconn,ha_strategy=nodeads]
agent = test:9312:any[blackhole=1]
agent = test:9312|box2:9312|box3:9312:any2[retry_count=2]
agent = test:9312|box2:9312:any2[retry_count=2,conn=pconn,ha_strategy=noerrors]

table products_dist {
  type  = distributed
  agent = 127.0.0.1:9312|127.0.0.1:9313:products
}

CREATE TABLE products_dist type='distributed'
  agent='127.0.0.1:9312:products|127.0.0.1:9313:products';

CREATE TABLE products_dist type='distributed'
  agent='127.0.0.1:9312:products|127.0.0.1:9313:products'
  ha_strategy='roundrobin'
  agent_connect_timeout='200ms'
  agent_query_timeout='500ms'
  mirror_retry_count='2';

SELECT id, title, node FROM products_dist;
SHOW CREATE TABLE products_dist;

+------+------------+-------+
| id   | title      | node  |
+------+------------+-------+
|    1 | same title | node1 |
+------+------------+-------+
+---------------+----------------------------------------------------------------------------------+
| Table         | Create Table                                                                     |
+---------------+----------------------------------------------------------------------------------+
| products_dist | CREATE TABLE products_dist type='distributed' agent='127.0.0.1:9312:products|... |
+---------------+----------------------------------------------------------------------------------+

为了获得最佳性能，建议将位于同一服务器上的远程表置于相同记录中。例如，不要：

agent = remote:9312:idx1
agent = remote:9312:idx2

建议使用：

agent = remote:9312:idx1,idx2

agent_persistent = remotebox:9312:index2

agent_persistent 选项允许你持久连接到代理，即查询执行后连接不会断开。该指令语法与 agent 指令相同。但不同的是，主控不会为每个查询打开新连接然后关闭，而是保持连接并重用以进行后续查询。每个代理主机的最大持久连接数由 searchd 部分的 persistent_connections_limit 选项定义。

需要注意的是，必须将 persistent_connections_limit 设置为大于 0 的值才能使用持久代理连接。如果未定义，默认为 0，agent_persistent 指令的行为将与 agent 指令相同。

使用持久主从代理连接可以减少 TCP 端口压力，节省连接握手时间，从而提高效率。

agent_blackhole = testbox:9312:testindex1,testindex2

并非所有与远程代理相关的选项都在相同的作用域中得到支持。本页重点介绍远程表和每代理语义。有关镜像特定行为的信息，请参阅 镜像 和 负载均衡。有关完整的守护进程级别行为，请使用 Searchd 设置 中的链接参考页面。

agent_connect_timeout = 300ms

CREATE TABLE products_dist type='distributed'
  agent='127.0.0.1:9312:products|127.0.0.1:9313:products'
  agent_connect_timeout='300ms';

agent_query_timeout = 10000 # our query can be long, allow up to 10 sec

SELECT * FROM products_dist OPTION agent_query_timeout=750;

agent_retry_count 指定了 Manticore 在分布式表中尝试连接和查询远程代理的次数，直到报告致命查询错误。名称根据作用域而变化：使用

• agent_retry_count 作为实例范围的设置，
• 在分布式表中使用 agent_retry_count 或其别名 mirror_retry_count，
• 每个查询使用 OPTION retry_count=...，
• 以及在单个 agent=... 声明中使用 [retry_count=...]。

完整的守护进程级别详情请参见 Searchd: agent_retry_count。

如果您使用 agent mirrors，服务器会在每次连接尝试之前根据 ha_strategy 选择不同的镜像，并且 agent_retry_count 会在镜像之间汇总。

table products_dist {
  type = distributed
  agent = 127.0.0.1:9312|127.0.0.1:9313:products[retry_count=2]
}

SELECT * FROM products_dist OPTION retry_count=1;

agent_retry_delay = 500ms

SELECT * FROM products_dist OPTION retry_count=2, retry_delay=300;

client_timeout = 1h

hostname_lookup 选项定义了主机名的更新策略。默认情况下，代理主机名的 IP 地址在服务器启动时缓存，以避免频繁访问 DNS。然而，在某些情况下（例如云托管环境），IP 会动态变化，可能希望不缓存 IP。将此选项设置为 request 可禁用缓存，每次查询时都会查询 DNS。IP 地址也可以通过 FLUSH HOSTNAMES 命令手动刷新。

listen_tfo 选项允许对所有监听器使用 TCP_FASTOPEN 标志。默认情况下，该选项由系统管理，但可以通过将其设置为 '0' 显式关闭。

有关 TCP Fast Open 扩展的更多信息，请参阅 Wikipedia。简而言之，它允许在建立连接时消除一次 TCP 往返。

在实际应用中，使用 TFO 可以优化客户端与代理之间的网络效率，类似于使用 agent_persistent 时，但无需保持活动连接，也没有最大连接数的限制。

大多数现代操作系统都支持 TFO。Linux（作为较为先进的系统之一）自 2011 年起支持它，内核版本从 3.7 开始支持（服务器端）。Windows 自 Windows 10 的某些版本开始支持该功能。其他系统，如 FreeBSD 和 MacOS，也在支持范围内。

对于 Linux 系统，服务器会检查变量 /proc/sys/net/ipv4/tcp_fastopen 并据此行为。位 0 管理客户端，位 1 管理监听器。默认情况下，系统将此参数设置为 1，即客户端启用，监听器禁用。

persistent_connections_limit = 29 # assume that each host of agents has max_connections = 30 (or 29).

persistent_connections_limit 选项定义了与远程持久代理的最大同时持久连接数。这是一个实例级别的设置，必须在 searchd 配置部分中定义。每当连接到在 agent_persistent 下定义的代理时，我们会尝试重用现有连接（如果存在），或创建新连接并保存以便将来使用。然而，在某些情况下可能需要限制持久连接的数量。该指令定义了限制，并影响所有分布式表中每个代理主机的连接数。

建议将此值设置为不大于代理配置中的 max_connections 选项。

分布式表的一个特殊情况是一张本地表和多张远程表，这种情况专门用于 分布式片段创建，当片段源自文件时。在这种情况下，本地表可作为“模板”表，提供构建片段时的分词设置。

snippets_file_prefix = /mnt/common/server1/

snippets_file_prefix 是一个可选的前缀，可以在生成片段时添加到本地文件名。默认值为当前工作文件夹。

如需了解更多关于分布式片段创建的信息，请参阅 CALL SNIPPETS。

您可以从多个 percolate 表创建一个分布式表。构造此类表的语法与其他分布式表相同，可以包含多个 local 表以及 agents。

对于 DPQ，列出存储查询和通过它们搜索（使用 CALL PQ）操作是透明的，且表现得如同所有表合并成一个本地表。然而，诸如 insert、replace、truncate 之类的数据操作语句不可用。

如果您在代理列表中包含了非预查询表，其行为将无法定义。如果错误代理与 PQ 表的外层架构（id、query、tags、filters）相同，在列出存储的 PQ 规则时不会引发错误，并且可能会用其非 PQ 字符串污染 PQ 表中实际存储的 PQ 规则列表。因此，务必谨慎，并意识到这可能带来的混淆。对该错误代理执行 CALL PQ 将引发错误。

有关对分布式预查询表进行查询的更多信息，请参阅 对分布式预查询表进行查询。

注意：自动分片需要 Manticore Buddy。如果自动分片不起作用，请确认 Buddy 已安装并正在运行。

Manticore 支持创建 分片表，这是一种特殊表类型（type='shard'），可以透明地将读写分发到多个底层物理分片上。在扩展数据规模时，这个特性非常有价值。你既可以在单台服务器上创建本地分片表，也可以在多节点复制集群上创建复制分片表，以优化数据分布。

分片表为高性能应用提供了几个关键优势：

• 通过将数据并行写入多个分片，充分利用系统资源，从而带来更强的写入性能。与单个大表相比，这种并行写入能力可以带来更高的索引吞吐量。
• 分片表内置支持复制能力，提升高可用性。你无需手动处理复制。只需在创建分片表时设置复制因子，系统会自动管理一切。这种内置复制可确保即使部分节点失败，数据仍然持续可访问。

• shards='N' — 要创建的物理分片数量。必填。必须是正整数，最大为 3000。
• rf='M' — 复制因子：每个分片保留的副本数。必填。在单节点上必须为 1；在复制集群上必须介于 1 和集群节点数之间。
• timeout='S' — 创建期间等待分片准备完成的时间（单位：秒）。默认值为 30。当在多个节点上创建大量分片时，可以适当增大该值。

值必须加引号（shards='10'，而不是 shards=10）。选项名称不区分大小写。

要创建本地分片表，像平常一样创建表，并添加 shards='N' 和 rf='1'。shards 是将会在表后端创建的物理分片数量。rf 是复制因子。在单台服务器上它必须为 1。

下面是一个创建包含 10 个分片的表的示例，数据会自动分布到这些分片上：

CREATE TABLE local_sharded shards='10' rf='1'

执行这条查询后，你会得到一个分片表，且所有分片都已完成设置。底层物理分片位于 system 数据库下，并且不会在 SHOW TABLES 中显示；你通过分片表的对外名称进行操作，系统会自动把请求路由到相应的分片。

要防止服务器宕机，请在你希望参与的各个节点上搭建复制集群。在本文档中，我们默认你创建的集群名为 c。请按照 replication 说明添加所有需要的节点，然后按所需复制因子创建表。

例如，假设你有一个 3 节点复制集群，并希望创建一个被拆分为 10 个分片的表，每个节点上都保留每个分片的一份副本。由于有三个节点参与，你应设置 rf='3'：

CREATE TABLE c:cluster_sharded shards='10' rf='3'

之后，你就可以在任意集群节点上通过表的普通名称来操作它了，INSERT、SELECT、UPDATE 和 DELETE 都不需要集群前缀。集群前缀（c:）只用于 CREATE TABLE 和 DROP TABLE 这类 DDL。

创建过程中等待所有分片准备完成的默认超时时间是 30 秒。有时，在多节点复制集群上创建大量分片时，由于网络延迟，可能需要更长时间。如有需要，可以通过 timeout 选项增加该超时值：

CREATE TABLE c:cluster_sharded shards='10' rf='3' timeout='60'

如果超时被超过，表创建将失败，你需要使用更长的超时值重新尝试。

要删除分片表，请使用标准的 DROP TABLE 命令。在集群环境中，请在表名中指定集群名称，以便正确定位要删除的表。支持 IF EXISTS。

删除本地分片表：

DROP TABLE local_sharded
DROP TABLE IF EXISTS local_sharded

删除复制分片表：

DROP TABLE c:cluster_sharded
DROP TABLE IF EXISTS c:cluster_sharded

DESC <table> 会返回分片表对用户可见的字段模式（也就是你声明的列）。

SHOW CREATE TABLE <table> 会返回对用户可见的定义，其中包含 shards='N' rf='M'，而内部的 type='shard' 拓扑结构（每个分片的 local=/agent= 子句以及以 md5 命名的复制集群）会被有意隐藏。若要查看解析后的内部拓扑以便诊断，请使用 SHOW CREATE TABLE <table> OPTION force=1。

另外还提供了两个命令用于检查分片子系统的状态：

• SHOW SHARDING STATUS [[<cluster>:]<table>] — 列出每个分片的部署位置和健康状态。不带参数时会列出所有分片表；带表名（可选加集群前缀）时，只筛选该表。返回列：table、shard、node、status（active/inactive）、cluster、replication_cluster、rf 和 rf_status（ok/degraded/broken）。

   SHOW SHARDING STATUS
   SHOW SHARDING STATUS cluster_sharded
   SHOW SHARDING STATUS c:cluster_sharded

• SHOW SHARDING MASTER — 显示当前由哪个节点运行分片主进程，以及它是 active 还是 inactive。

   SHOW SHARDING MASTER