Apache Doris LOCAL表值函数详解

概述

Apache Doris的LOCAL表值函数(TVF)是一种强大的功能，它允许用户像访问关系型数据库表一样直接读取和访问BE节点上的本地文件内容。该功能特别适用于需要快速分析本地日志文件、临时数据文件等场景，为数据分析师和开发人员提供了极大的便利。

核心功能特性

LOCAL TVF支持多种常见文件格式，包括：

• CSV格式（支持带列名和不带列名）
• JSON格式
• Parquet格式
• ORC格式

基本语法结构

LOCAL(
  "file_path" = "<file_path>", 
  "backend_id" = "<backend_id>",
  "format" = "<format>"
  [, "<optional_property_key>" = "<optional_property_value>" [, ...] ]
);

参数详解

必需参数

1. file_path
   文件路径，相对于user_files_secure_path目录。需要注意：

   • 路径中不能包含..上级目录引用
   • 支持glob语法进行模式匹配，例如logs/*.log可以匹配logs目录下所有.log文件

2. backend_id
   文件所在的BE节点ID，可通过show backends命令获取。在2.1.1版本之前，Doris仅支持指定单个BE节点读取本地数据文件。

3. format
   文件格式，支持：csv/csv_with_names/csv_with_names_and_types/json/parquet/orc

可选参数

1. shared_storage
   默认为false。如果设置为true，表示文件位于共享存储（如NAS）上。从2.1.2版本开始支持。

2. 文件格式相关参数
   根据不同的文件格式，支持多种参数配置：

   • CSV格式：column_separator、line_delimiter、trim_double_quotes等
   • JSON格式：read_json_by_line、strip_outer_array、json_root等
   • 通用参数：compress_type支持多种压缩格式

3. path_partition_keys
   指定文件路径中携带的分区列名，例如/path/to/city=beijing/date="2023-07-09"，可以设置path_partition_keys="city,date"来自动提取分区信息。

安全与权限

使用LOCAL TVF需要具备ADMIN_PRIV全局权限，这是出于数据安全考虑的重要限制。

典型应用场景

1. 日志文件分析

-- 分析指定BE节点上的日志文件
select * from local(
        "file_path" = "log/be.out",
        "backend_id" = "10006",
        "format" = "csv")
       where c1 like "%start_time%" limit 10;

2. 本地CSV文件读取

-- 读取BE节点上的CSV文件
select * from local(
      "file_path" = "student.csv", 
      "backend_id" = "10003", 
      "format" = "csv");

3. 共享存储文件访问

-- 访问NAS共享存储上的文件
select * from local(
        "file_path" = "/mnt/doris/prefix_*.txt",
        "format" = "csv",
        "column_separator" =",",
        "shared_storage" = "true");

4. 查看文件结构

-- 使用desc function查看文件结构
desc function local(
      "file_path" = "student.csv", 
      "backend_id" = "10003", 
      "format" = "csv");

性能优化建议

1. 共享存储利用
   对于NAS等共享存储，设置shared_storage=true可以让Doris利用多个BE节点并行读取文件，显著提高查询性能。

2. 文件格式选择

   • 对于结构化数据，Parquet和ORC格式通常比CSV/JSON有更好的性能
   • 对于日志类文本数据，CSV格式更为合适

3. 压缩使用
   对于大文件，使用适当的压缩格式（如GZIP、LZ4）可以减少I/O开销。

注意事项

1. 文件路径安全性：确保文件路径在安全目录下，避免路径遍历漏洞
2. 版本兼容性：不同Doris版本对LOCAL TVF的支持程度可能不同，特别是共享存储功能在2.1.2版本才引入
3. 资源消耗：大文件处理可能消耗较多内存和CPU资源，建议适当控制查询范围

LOCAL表值函数为Apache Doris用户提供了灵活的文件数据访问能力，是数据分析和ETL处理中的实用工具。通过合理配置参数和优化查询，可以充分发挥其性能优势。