> ## 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.

> 该引擎支持将应用程序日志文件作为记录流进行处理。

# FileLog 表引擎

该引擎支持将应用程序日志文件作为记录流进行处理。

`FileLog` 可让您：

* 订阅日志文件。
* 在新记录追加到已订阅的日志文件时对其进行处理。

<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 = FileLog('path_to_logs', 'format_name') SETTINGS
    [poll_timeout_ms = 0,]
    [poll_max_batch_size = 0,]
    [max_block_size = 0,]
    [max_threads = 0,]
    [poll_directory_watch_events_backoff_init = 500,]
    [poll_directory_watch_events_backoff_max = 32000,]
    [poll_directory_watch_events_backoff_factor = 2,]
    [handle_error_mode = 'default']
```

引擎参数：

* `path_to_logs` – 要订阅的日志文件路径。可以是包含日志文件的目录路径，也可以是单个日志文件的路径。请注意，ClickHouse 只允许使用 `user_files` 目录内的路径。
* `format_name` - 记录格式。请注意，FileLog 会将文件中的每一行视为一条单独的记录，因此并非所有数据格式都适用。

可选参数：

* `poll_timeout_ms` - 从日志文件执行单次轮询的超时时间。默认值：[stream\_poll\_timeout\_ms](/zh/reference/settings/session-settings#stream_poll_timeout_ms)。
* `poll_max_batch_size` — 单次轮询可拉取的最大记录数。默认值：[max\_block\_size](/zh/reference/settings/session-settings#max_block_size)。
* `max_block_size` — 轮询的最大批次大小 (按记录数计) 。默认值：[max\_insert\_block\_size](/zh/reference/settings/session-settings#max_insert_block_size)。
* `max_threads` - 用于解析文件的最大线程数，默认值为 0，这表示该值将为 max(1, physical\_cpu\_cores / 4)。
* `poll_directory_watch_events_backoff_init` - 目录监视线程的初始休眠时间。默认值：`500`。
* `poll_directory_watch_events_backoff_max` - 目录监视线程的最大休眠时间。默认值：`32000`。
* `poll_directory_watch_events_backoff_factor` - 退避速度，默认采用指数退避。默认值：`2`。
* `handle_error_mode` — FileLog engine 的错误处理方式。可能的值：default (如果消息解析失败，将抛出异常) ，stream (异常消息和原始消息将保存在虚拟列 `_error` 和 `_raw_message` 中) 。

<div id="description">
  ## 说明
</div>

已传递的记录会被自动跟踪，因此日志文件中的每条记录都只会被统计一次。

`SELECT` 并不特别适合用来读取记录 (`调试` 除外) ，因为每条记录只能读取一次。更实用的做法是使用 [materialized views](/zh/reference/statements/create/view) 创建实时流。为此，请执行以下操作：

1. 使用该引擎创建一个 FileLog 表，并将其视为数据流。
2. 创建一个具有所需结构的表。
3. 创建一个 materialized view，对来自该引擎的数据进行转换，并将其写入前面创建的表中。

当 `MATERIALIZED VIEW` 连接到该引擎后，它会开始在后台收集数据。这样，你就可以持续接收来自日志文件的记录，并使用 `SELECT` 将其转换为所需的格式。
一个 FileLog 表可以拥有任意多个 materialized views；它们不会直接从该表读取数据，而是接收新记录 (以块的形式) 。这样，你就可以将数据写入多个明细程度不同的表中 (带分组/aggregation 和不带分组) 。

示例：

```sql theme={null}
  CREATE TABLE logs (
    timestamp UInt64,
    level String,
    message String
  ) ENGINE = FileLog('user_files/my_app/app.log', 'JSONEachRow');

  CREATE TABLE daily (
    day Date,
    level String,
    total UInt64
  ) ENGINE = SummingMergeTree(day, (day, level), 8192);

  CREATE MATERIALIZED VIEW consumer TO daily
    AS SELECT toDate(toDateTime(timestamp)) AS day, level, count() AS total
    FROM logs GROUP BY day, level;

  SELECT level, sum(total) FROM daily GROUP BY level;
```

如需停止接收流数据或更改转换逻辑，请分离该 materialized view：

```sql theme={null}
  DETACH TABLE consumer;
  ATTACH TABLE consumer;
```

如果要使用 `ALTER` 修改目标表，我们建议先禁用materialized view，以避免目标表与视图数据之间出现不一致。

<div id="virtual-columns">
  ## 虚拟列
</div>

* `_filename` - 日志文件名称。数据类型：`LowCardinality(String)`。
* `_offset` - 日志文件中的偏移量。数据类型：`UInt64`。

当 `handle_error_mode='stream'` 时，还会有以下附加虚拟列：

* `_raw_record` - 无法成功解析的原始记录。数据类型：`Nullable(String)`。
* `_error` - 解析失败期间产生的异常消息。数据类型：`Nullable(String)`。

注意：只有在解析过程中发生异常时，才会填充 `_raw_record` 和 `_error` 这两个虚拟列；如果消息解析成功，它们始终为 `NULL`。