Skip to content
44 changes: 25 additions & 19 deletions tiflash/use-tiflash.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,8 +59,6 @@ ALTER TABLE `tpch50`.`lineitem` SET TIFLASH REPLICA 0

* 不推荐同步 1000 张以上的表,这会降低 PD 的调度性能。这个限制将在后续版本去除。

* TiFlash 中保留了数据库 system,用户不能为 TiDB 中名字为 system 数据库下的表创建 TiFlash 副本。如果强行创建,结果行为未定义(暂时性限制)。

## 查看表同步进度

可通过如下 SQL 语句查看特定表(通过 WHERE 语句指定,去掉 WHERE 语句则查看所有表)的 TiFlash 副本的状态:
Expand Down Expand Up @@ -119,13 +117,22 @@ explain analyze select count(*) from test.t;

`cop[tiflash]` 表示该任务会发送至 TiFlash 进行处理。如果没有选择 TiFlash 副本,可尝试通过 `analyze table` 语句更新统计信息后,再查看 `explain analyze` 结果。

需要注意的是,如果表仅有单个 TiFlash 副本且相关节点无法服务,智能选择模式下的查询会不断重试,需要指定 Engine 或者手工 Hint 来读取 TiKV。
需要注意的是,如果表仅有单个 TiFlash 副本且相关节点无法服务,智能选择模式下的查询会不断重试,需要指定 Engine 或者手工 Hint 来读取 TiKV 副本

### Engine 隔离

Engine 隔离是通过配置变量来指定所有的查询均使用指定 engine 的副本,可选 engine 为 tikv 和 tiflash,分别有 2 个配置级别:
Engine 隔离是通过配置变量来指定所有的查询均使用指定 engine 的副本,可选 engine 为 "tikv"、"tidb" 和 "tiflash"(其中 "tidb" 表示 TiDB 内部的内存表区,主要用于存储一些 TiDB 系统表,用户不能主动使用),分别有 2 个配置级别:

1. TiDB 实例级别,即 INSTANCE 级别。在 TiDB 的配置文件添加如下配置项:

```
[isolation-read]
engines = ["tikv", "tidb", "tiflash"]
```

**实例级别的默认配置为 `["tikv", "tidb", "tiflash"]`。**

1. 会话级别,即 SESSION 级别。设置语句:
2. 会话级别,即 SESSION 级别。设置语句:

{{< copyable "sql" >}}

Expand All @@ -141,24 +148,19 @@ Engine 隔离是通过配置变量来指定所有的查询均使用指定 engine
set SESSION tidb_isolation_read_engines = "逗号分隔的 engine list";
```

会话级别的默认配置继承自 TiDB 实例级别的配置,见 2。

2. TiDB 实例级别,即 INSTANCE 级别,和会话级别配置是交集关系。比如实例级别配置了 "tikv, tiflash",而会话级别配置了 "tikv",则只会读取 TiKV。
**会话级别的默认配置继承自 TiDB 实例级别的配置。**

在 TiDB 的配置文件添加如下配置项:
最终的 engine 配置为会话级别配置,即会话级别配置会覆盖实例级别配置。比如实例级别配置了 "tikv",而会话级别配置了 "tiflash",则会读取 TiFlash 副本。当 engine 配置为 "tikv, tiflash",即可以同时读取 TiKV 和 TiFlash 副本,优化器会自动选择。

```
[isolation-read]
engines = ["tikv", "tiflash"]
```

实例级别的默认配置为 `["tikv", "tiflash"]`。
> **注意:**
>
> 由于 TiDB Dashboard 等组件需要读取一些存储于 TiDB 内存表区的系统表,因此建议实例级别 engine 配置中始终加入 "tidb" engine。

engine 配置为 "tikv, tiflash",即可以同时读取 TiKV 和 TiFlash 副本,优化器会自动选择。指定了 engine 后,对于查询中的表没有对应 engine 副本的情况(因为 TiKV 副本是必定存在的,因此只有配置了 engine 为 tiflash TiFlash 副本不存在这一种情况),查询会报该表不存在该 engine 副本的错。
如果查询中的表没有对应 engine 的副本,比如配置了 engine 为 "tiflash" 而该表没有 TiFlash 副本,则查询会报该表不存在该 engine 副本的错。

### 手工 Hint

手工 Hint 可以强制 TiDB 对于某张或某几张表使用 TiFlash 副本,其优先级低于 engine 隔离,如果 Hint 中指定的引擎不在 engine 列表中,会返回 warning,使用方法为:
手工 Hint 可以在满足 engine 隔离的前提下,强制 TiDB 对于某张或某几张表使用指定的副本,使用方法为:

{{< copyable "sql" >}}

Expand All @@ -174,14 +176,18 @@ select /*+ read_from_storage(tiflash[table_name]) */ ... from table_name;
select /*+ read_from_storage(tiflash[alias_a,alias_b]) */ ... from table_name_1 as alias_a, table_name_2 as alias_b where alias_a.column_1 = alias_b.column_2;
```

更多关于该 Hint 语句的语法可以参考 [READ_FROM_STORAGE](/optimizer-hints.md#read_from_storagetiflasht1_name--tl_name--tikvt2_name--tl_name-)。
其中 `tiflash[]` 是提示优化器读取 TiFlash 副本,亦可以根据需要使用 `tikv[]` 来提示优化器读取 TiKV 副本。更多关于该 Hint 语句的语法可以参考 [READ_FROM_STORAGE](/optimizer-hints.md#read_from_storagetiflasht1_name--tl_name--tikvt2_name--tl_name-)。

Engine 隔离的优先级高于 CBO 与 HintHint 优先级高于代价估算,即代价估算仅会选取指定 engine 的副本
如果 Hint 指定的表在指定的引擎上不存在副本,则 Hint 会被忽略,并产生 warning。另外 Hint 必须在满足 engine 隔离的前提下才会生效,如果 Hint 中指定的引擎不在 engine 隔离列表中,Hint 同样会被忽略,并产生 warning

> **注意:**
>
> MySQL 命令行客户端在 5.7.7 版本之前默认清除了 Optimizer Hints。如果需要在这些早期版本的客户端中使用 `Hint` 语法,需要在启动客户端时加上 `--comments` 选项,例如 `mysql -h 127.0.0.1 -P 4000 -uroot --comments`。

### 三种方式之间关系的总结

上述三种读取 TiFlash 副本的方式中,Engine 隔离规定了总的可使用副本 engine 的范围,手工 Hint 可以在该范围内进一步实现语句级别及表级别的细粒度的 engine 指定,最终由 CBO 在指定的 engine 范围内根据代价估算最终选取某个 engine 上的副本。

## 使用 TiSpark 读取 TiFlash

TiSpark 目前提供类似 TiDB 中 engine 隔离的方式读取 TiFlash,方式是通过配置参数 `spark.tispark.use.tiflash` 为 `true`(或 `false`)。
Expand Down