SQLite 表引擎

该引擎支持将数据导入到 SQLite 和从 SQLite 导出数据，也支持直接从 ClickHouse 查询 SQLite 表。

创建表

    CREATE TABLE [IF NOT EXISTS] [db.]table_name
    (
        name1 [type1],
        name2 [type2], ...
    ) ENGINE = SQLite('db_path', 'table')

引擎参数

db_path — SQLite 数据库文件的路径。
table — SQLite 数据库中的表名，或原样传递给 SQLite 的查询 (请参见传递查询而非表名) 。

传递查询而非表名

table 参数除了表名之外，也可以是一个 SELECT 查询，该查询会原样传递给 SQLite。表的结构根据查询结果推断。只有当结果列直接对应某个表中的列时，SQLite 才会报告其声明类型；对于表达式、字面量或聚合，则不报告任何类型。映射到 String 的声明类型 (参见类型映射) 将原样使用。没有声明类型的列会根据查询结果第一行中该列值的存储类来确定类型：INTEGER 值对应 Int64，REAL 值对应 Float64，其他任何值 (TEXT、BLOB、NULL) 以及空结果均对应 String。数值型声明类型同样会根据第一行进行校验，因为 SQLite 对复合 SELECT 也会报告声明类型，而该类型取自其中某一个分支，行数据却来自所有分支。当该值的存储类与声明类型相符时 (整数类型对应 INTEGER，浮点类型对应 INTEGER 或 REAL) ，会保留该声明类型；当该值为 NULL 或结果为空时也会保留，因为二者都不携带任何可能与之矛盾的类型信息；否则，该列会像未声明类型的列一样，根据存储类确定类型。因此，推断出的类型只会放宽，绝不会收窄。推断此类列时会在 SQLite 中启动查询。第一行并不能代表其余各行：SQLite 可以在每一行中返回不同的存储类 (例如 CASE WHEN id = 1 THEN 1 ELSE 1.5 END) ，因此对于以数值类型读取的每一列，基于查询的读取都采用失败即关闭 (fail-closed) 策略——而不仅限于没有声明类型的列。如果某个值的存储类与该类型不匹配，或无法用该类型精确表示 (例如 UInt8 列中值为 300 的 INTEGER 单元，或 Float32 列中值为 16777217 的 REAL 单元) ，读取将直接失败，而不会进行静默的强制转换。若要读取存储类混杂的列，请将其声明为 String，或在 SQLite 查询中将其转换为文本。所有推断出的列均为 Nullable。查询既可以写成子查询，也可以包装在 query 函数中：

CREATE TABLE sqlite_table ENGINE = SQLite('sqlite.db', (SELECT col1, col2 FROM table1 WHERE col2 > 1));
CREATE TABLE sqlite_table ENGINE = SQLite('sqlite.db', query('SELECT col1, col2 FROM table1 WHERE col2 > 1'));

自 26.7 版本起支持传递查询。ClickHouse 会先将该查询包装为 SELECT ... FROM (<query>)，再发送给 SQLite，因此查询末尾不能带分号。此类表为只读表，不允许对其执行 INSERT。sqlite 表函数也支持相同的语法。

子查询形式 (SELECT ...) 会先由 ClickHouse 解析并重新序列化，再发送给 SQLite。因此，它必须是有效的 ClickHouse SQL。若要传递 ClickHouse 无法解析的 SQLite 特有语法，请使用 query('...') 形式，其文本会原样发送给 SQLite。周围 ClickHouse 查询中的任何外层 WHERE、LIMIT、聚合等都不会下推到传入的查询中——而是会在拉取完整查询结果后由 ClickHouse 应用。若要限制从 SQLite 读取的数据，请将过滤条件放在传入的查询内部。启用 external_table_strict_query = 1 时，作用于该表列的外层过滤条件会直接报错拒绝，而不是在本地应用，因为它无法下推到传入的查询中。检查涵盖顶层 WHERE 谓词以及顶层 AND 的每个合取项。作用于该表列的 PREWHERE 不属于此设置的适用情形：此表引擎不支持 PREWHERE，无论该设置如何，此类查询都会因 ILLEGAL_PREWHERE 被拒绝。仅在过滤条件本可被下推的情况下执行检查：当该表是查询中唯一的表、位于 INNER JOIN 的任一侧，或位于外连接的保留侧 (LEFT JOIN 的左侧、RIGHT JOIN 的右侧) 。在 LEFT/RIGHT JOIN 的非保留侧以及 FULL JOIN 的任一侧，不会下推任何内容，也不会进行任何检查，因此即使在严格模式下，作用于该表列的过滤条件也会在连接后于本地应用。在执行检查的情况下，引用周围查询中其他已连接表的谓词不会被下推，也不会纳入检查，无论它仅引用连接侧，还是在一个非 AND 表达式中与该表混合引用 (例如 OR) ；此类谓词会保留其通常的 ClickHouse 求值位置 (连接后的 WHERE、连接前的 PREWHERE) ，且不会被拒绝。

数据类型支持

当在表定义中显式指定 ClickHouse 列类型时，可从 SQLite 的 TEXT 列中解析出以下 ClickHouse 类型：

Date, Date32
DateTime, DateTime64
UUID
Enum8, Enum16
Decimal32, Decimal64, Decimal128, Decimal256
FixedString
所有整数类型 (UInt8, UInt16, UInt32, UInt64, UInt128, UInt256, Int8, Int16, Int32, Int64, Int128, Int256)
Float32, Float64

有关默认类型映射，请参见 SQLite database 引擎。将 SQLite 中的 NULL 读入显式声明为非 Nullable 的 ClickHouse 列时，会引发 CANNOT_INSERT_NULL_IN_ORDINARY_COLUMN 异常。如需读取 NULL 值，请将该列声明为 Nullable。自动推断的 schema 遵循 SQLite 元数据：除非列声明为 NOT NULL，否则均为 Nullable。

使用示例

显示创建 SQLite 表的查询：

SHOW CREATE TABLE sqlite_db.table2;

CREATE TABLE SQLite.table2
(
    `col1` Nullable(Int64),
    `col2` Nullable(String)
)
ENGINE = SQLite('sqlite.db','table2');

返回该表中的数据：

SELECT * FROM sqlite_db.table2 ORDER BY col1;

┌─col1─┬─col2──┐
│    1 │ text1 │
│    2 │ text2 │
│    3 │ text3 │
└──────┴───────┘

另请参见

SQLite 引擎
sqlite 表函数

SQL 参考文档

数据类型

引擎

函数

格式

设置

系统表

数据湖

创建表

传递查询而非表名

数据类型支持

使用示例

​创建表

​传递查询而非表名

​数据类型支持

​使用示例

创建表

传递查询而非表名

数据类型支持

使用示例