Skip to content
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.

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

variable: add document about lazy cursor fetch and its variable #18073

Merged
merged 12 commits into from
Aug 15, 2024
4 changes: 4 additions & 0 deletions best-practices/java-app-best-practices.md
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,10 @@ Java 应用尽管可以选择在不同的框架中封装,但在最底层一般

TiDB 中同时支持两种方式,但更推荐使用第一种将 `FetchSize` 设置为 `Integer.MIN_VALUE` 的方式,比第二种功能实现更简单且执行效率更高。

对于第二种方法,TiDB 会先将所有数据加载到 TiDB 节点上,然后根据 `FetchSize` 依次返回给客户端。因此,通常会比第一种方法使用更多的内存,如果 [`tidb_enable_tmp_storage_on_oom`](/system-variables.md#tidb_enable_tmp_storage_on_oom) 为 `ON` 时,可能会将数据存储到临时磁盘中。

如果系统变量 [`tidb_enable_lazy_cursor_fetch`](/system-variables.md#tidb_enable_lazy_cursor_fetch) 为 `ON`,TiDB 将尝试仅在客户端请求数据时读取部分数据,以使用更少的内存。有关详细信息和限制,请阅读变量 [`tidb_enable_lazy_cursor_fetch`](/system-variables.md#tidb_enable_lazy_cursor_fetch) 的描述。

### MySQL JDBC 参数

JDBC 实现通常通过 JDBC URL 参数的形式来提供实现相关的配置。这里以 MySQL 官方的 Connector/J 来介绍[参数配置](https://dev.mysql.com/doc/connector-j/en/connector-j-reference-configuration-properties.html)(如果使用的是 MariaDB,可以参考 [MariaDB 的类似配置](https://mariadb.com/kb/en/library/about-mariadb-connector-j/#optional-url-parameters))。因为配置项较多,这里主要关注几个可能影响到性能的参数。
Expand Down
4 changes: 4 additions & 0 deletions develop/dev-guide-connection-parameters.md
Original file line number Diff line number Diff line change
Expand Up @@ -138,6 +138,10 @@ Java 应用尽管可以选择在不同的框架中封装,但在最底层一般

TiDB 中同时支持两种方式,但更推荐使用第一种将 **FetchSize** 设置为 `Integer.MIN_VALUE` 的方式,比第二种功能实现更简单且执行效率更高。

对于第二种方法,TiDB 会先将所有数据加载到 TiDB 节点上,然后根据 `FetchSize` 依次返回给客户端。因此,通常会比第一种方法使用更多的内存,如果 [`tidb_enable_tmp_storage_on_oom`](/system-variables.md#tidb_enable_tmp_storage_on_oom) 为 `ON` 时,可能会将数据存储到临时磁盘中。

如果系统变量 [`tidb_enable_lazy_cursor_fetch`](/system-variables.md#tidb_enable_lazy_cursor_fetch) 为 `ON`,TiDB 将尝试仅在客户端请求数据时读取部分数据,以使用更少的内存。有关详细信息和限制,请阅读变量 [`tidb_enable_lazy_cursor_fetch`](/system-variables.md#tidb_enable_lazy_cursor_fetch) 的描述。
lilin90 marked this conversation as resolved.
Show resolved Hide resolved

### MySQL JDBC 参数

JDBC 实现通常通过 JDBC URL 参数的形式来提供实现相关的配置。这里以 MySQL 官方的 Connector/J 来介绍[参数配置](https://dev.mysql.com/doc/connector-j/en/connector-j-reference-configuration-properties.html)(如果使用的是 MariaDB,可以参考 [MariaDB 的类似配置](https://mariadb.com/kb/en/library/about-mariadb-connector-j/#optional-url-parameters))。因为配置项较多,这里主要关注几个可能影响到性能的参数。
Expand Down
21 changes: 21 additions & 0 deletions system-variables.md
Original file line number Diff line number Diff line change
Expand Up @@ -1926,6 +1926,27 @@ mysql> SELECT job_info FROM mysql.analyze_jobs ORDER BY end_time DESC LIMIT 1;
- 可选值:`OFF`,`ON`
- 这个变量用于控制是否支持对分区表创建 `Global index`。`Global index` 当前正处于开发阶段,**不推荐修改该变量值**。

### `tidb_enable_lazy_cursor_fetch` <span class="version-mark">从 v8.3.0 版本开始引入</span>

> **警告:**
>
> 该变量控制的功能为实验特性,不建议在生产环境中使用。该功能可能会在未事先通知的情况下发生变化或删除。如果发现 bug,请在 GitHub 上提 [issue](https://github.com/pingcap/tidb/issues) 反馈。

- 作用域:GLOBAL
- 是否持久化到集群:是
- 是否受 Hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value) 控制:否
- 类型:布尔型
- 默认值:`OFF`
YangKeao marked this conversation as resolved.
Show resolved Hide resolved
- 可选值:`OFF`,`ON`
- 这个变量用于控制 [Cursor Fetch](/develop/dev-guide-connection-parameters.md#使用-streamingresult-流式获取执行结果) 功能的行为。
- 当开启 Cursor Fetch 且该变量设置为 `OFF` 时,TiDB 会在语句开始执行时将所有数据读取完成并保存至 TiDB 内存,在后续客户端读取的过程中会依据客户端指定的 `FetchSize` 返回给客户端。如果结果集过大,可能会触发落盘临时将结果写入硬盘。
- 当开启 Cursor Fetch 且该变量设置为 `ON` 时,TiDB 不会一次把所有数据读取到 TiDB 节点,而是会随着客户端的读取不断将数据读到 TiDB 节点。
- 该变量控制的功能存在以下限制:
- 不支持处于显式事务中的语句。
- 当前仅支持包含且仅包含 `TableReader`、`IndexReader`、`IndexLookUp`、`Projection`、`Selection` 算子的执行计划。
- 对于使用 Lazy Cursor Fetch 的语句,执行信息将不会出现在 [statements summary](/statement-summary-tables.md) 和[慢查询日志](/identify-slow-queries.md)中。
- 对于暂不支持的场景,其行为与将变量设置为 `OFF` 时一致。

### `tidb_enable_non_prepared_plan_cache`

- 作用域:SESSION | GLOBAL
Expand Down
Loading