> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-fbfa8bee.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> 该引擎可将 ClickHouse 与 RocksDB 集成

# EmbeddedRocksDB 表引擎

export const CloudNotSupportedBadge = () => {
  return <div className="cloudNotSupportedBadge">
            <div className="cloudNotSupportedIcon">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path strokeWidth="1.5" d="M6.33366 12.6666L12.3739 12.6667C13.6593 12.6667 14.7073 11.6187 14.7073 10.3334C14.7073 9.04804 13.6593 8.00003 12.3739 8.00003C12.3739 8.00003 12.3337 7.66659 12.0003 7.33325M10.667 5.33322C8.00033 2.33325 4.45395 4.78537 4.14195 6.68203C2.55728 6.7627 1.29395 8.06203 1.29395 9.6667C1.29395 11.3234 2.66699 12.6666 4.00033 12.6666" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.5" d="M2.66699 14L12.0003 4.66663" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
            </svg>

        </div>
            ClickHouse Cloud 不支持此功能
        </div>;
};

该引擎可将 ClickHouse 与 [RocksDB](http://rocksdb.org/) 集成。

<div id="creating-a-table">
  ## 创建表
</div>

```sql theme={null}
CREATE TABLE [IF NOT EXISTS] [db.]table_name [ON CLUSTER cluster]
(
    name1 [type1] [DEFAULT|MATERIALIZED|ALIAS expr1],
    name2 [type2] [DEFAULT|MATERIALIZED|ALIAS expr2],
    ...
) ENGINE = EmbeddedRocksDB([ttl, rocksdb_dir, read_only]) PRIMARY KEY(primary_key_name)
[ SETTINGS name=value, ... ]
```

引擎参数：

* `ttl` - 值的生存时间。TTL 以秒为单位。如果 TTL 为 0，则使用常规的 RocksDB 实例 (不启用 TTL) 。
* `rocksdb_dir` - 已存在的 RocksDB 的目录路径，或新创建的 RocksDB 的目标路径。使用指定的 `rocksdb_dir` 打开表。
* `read_only` - 当 `read_only` 设置为 true 时，将使用只读模式。对于启用了 TTL 的存储，不会触发合并整理 (无论手动还是自动) ，因此不会移除任何已过期条目。
* `primary_key_name` – 列列表中的任意列名。
* `primary key` 为必填项，并且主键只支持一列。主键会以二进制形式序列化为 `rocksdb key`。
* 除主键外的列会按对应顺序以二进制形式序列化为 `rocksdb` 值。
* 对 key 使用 `equals` 或 `in` 过滤的查询将被优化为从 `rocksdb` 进行多键查找。

引擎设置：

* `optimize_for_bulk_insert` – 表已针对批量插入进行优化 (插入管道会创建 SST 文件并将其导入 rocksdb 数据库，而不是写入 memtables) ；默认值：`1`。
* `bulk_insert_block_size` - 通过批量插入创建的 SST 文件的最小大小 (以行数计) ；默认值：`1048449`。

示例：

```sql theme={null}
CREATE TABLE test
(
    `key` String,
    `v1` UInt32,
    `v2` String,
    `v3` Float32
)
ENGINE = EmbeddedRocksDB
PRIMARY KEY key
```

<div id="metrics">
  ## 指标
</div>

还有一个 `system.rocksdb` 表，用于提供 RocksDB 统计信息：

```sql theme={null}
SELECT
    name,
    value
FROM system.rocksdb

┌─name──────────────────────┬─value─┐
│ no.file.opens             │     1 │
│ number.block.decompressed │     1 │
└───────────────────────────┴───────┘
```

<div id="configuration">
  ## 配置
</div>

你也可以通过 config 更改任意 [RocksDB 选项](https://github.com/facebook/rocksdb/wiki/Option-String-and-Option-Map)：

```xml theme={null}
<rocksdb>
    <options>
        <max_background_jobs>8</max_background_jobs>
    </options>
    <column_family_options>
        <num_levels>2</num_levels>
    </column_family_options>
    <tables>
        <table>
            <name>TABLE</name>
            <options>
                <max_background_jobs>8</max_background_jobs>
            </options>
            <column_family_options>
                <num_levels>2</num_levels>
            </column_family_options>
        </table>
    </tables>
</rocksdb>
```

默认情况下，简单近似计数优化是关闭的，这可能会影响 `count()` 查询的性能。要启用此优化，
请将 `optimize_trivial_approximate_count_query = 1`。此外，此设置还会影响 EmbeddedRocksDB engine 的 `system.tables`；
启用后，可查看 `total_rows` 和 `total_bytes` 的近似值。

<div id="supported-operations">
  ## 支持的操作
</div>

<div id="inserts">
  ### 插入
</div>

当向 `EmbeddedRocksDB` 插入新行时，如果键已存在，则会更新对应的值；否则会创建新键。

示例：

```sql theme={null}
INSERT INTO test VALUES ('some key', 1, 'value', 3.2);
```

<div id="deletes">
  ### 删除
</div>

可以使用 `DELETE` 查询或 `TRUNCATE` 来删除行。

```sql theme={null}
DELETE FROM test WHERE key LIKE 'some%' AND v1 > 1;
```

```sql theme={null}
ALTER TABLE test DELETE WHERE key LIKE 'some%' AND v1 > 1;
```

```sql theme={null}
TRUNCATE TABLE test;
```

<div id="updates">
  ### 更新
</div>

可以使用 `ALTER TABLE` 查询来更新值。主键不能更新。

```sql theme={null}
ALTER TABLE test UPDATE v1 = v1 * 10 + 2 WHERE key LIKE 'some%' AND v3 > 3.1;
```

<div id="joins">
  ### Joins
</div>

支持一种适用于 EmbeddedRocksDB 表的特殊 `direct` join。
这种 direct join 无需在内存中构建哈希表，而是直接从
EmbeddedRocksDB 读取数据。

对于大型 joins，direct joins 的内存使用量可能会显著降低，
因为不需要创建哈希表。

要启用 direct joins：

```sql theme={null}
SET join_algorithm = 'direct, hash'
```

<Tip>
  当 `join_algorithm` 设置为 `direct, hash` 时，会尽可能使用直接 JOIN，
  否则使用哈希 JOIN。
</Tip>

<div id="example">
  #### 示例
</div>

<div id="create-and-populate-an-embeddedrocksdb-table">
  ##### 创建并向 EmbeddedRocksDB 表插入数据
</div>

```sql theme={null}
CREATE TABLE rdb
(
    `key` UInt32,
    `value` Array(UInt32),
    `value2` String
)
ENGINE = EmbeddedRocksDB
PRIMARY KEY key
```

```sql theme={null}
INSERT INTO rdb
    SELECT
        toUInt32(sipHash64(number) % 10) AS key,
        [key, key+1] AS value,
        ('val2' || toString(key)) AS value2
    FROM numbers_mt(10);
```

<div id="create-and-populate-a-table-to-join-with-table-rdb">
  ##### 创建并填充一个可与表 `rdb` join 的表
</div>

```sql theme={null}
CREATE TABLE t2
(
    `k` UInt16
)
ENGINE = TinyLog
```

```sql theme={null}
INSERT INTO t2 SELECT number AS k
FROM numbers_mt(10)
```

<div id="set-the-join-algorithm-to-direct">
  ##### 将 join 算法设置为 `direct`
</div>

```sql theme={null}
SET join_algorithm = 'direct'
```

<div id="an-inner-join">
  ##### INNER JOIN
</div>

```sql theme={null}
SELECT *
FROM
(
    SELECT k AS key
    FROM t2
) AS t2
INNER JOIN rdb ON rdb.key = t2.key
ORDER BY key ASC
```

```response theme={null}
┌─key─┬─rdb.key─┬─value──┬─value2─┐
│   0 │       0 │ [0,1]  │ val20  │
│   2 │       2 │ [2,3]  │ val22  │
│   3 │       3 │ [3,4]  │ val23  │
│   6 │       6 │ [6,7]  │ val26  │
│   7 │       7 │ [7,8]  │ val27  │
│   8 │       8 │ [8,9]  │ val28  │
│   9 │       9 │ [9,10] │ val29  │
└─────┴─────────┴────────┴────────┘
```

<div id="more-information-on-joins">
  ### JOIN 的更多信息
</div>

* [`join_algorithm` 设置](/zh/reference/settings/session-settings#join_algorithm)
* [JOIN 子句](/zh/reference/statements/select/join)