local

Name

local

Description

Local表函数(table-valued-function,tvf),可以让用户像访问关系表格式数据一样,读取并访问 be 上的文件内容。目前支持csv/csv_with_names/csv_with_names_and_types/json/parquet/orc文件格式。

该函数需要 ADMIN 权限。

syntax

  1. local(
  2. "file_path" = "path/to/file.txt",
  3. "backend_id" = "be_id",
  4. "format" = "csv",
  5. "keyn" = "valuen"
  6. ...
  7. );

参数说明

  • 访问local文件的相关参数:

    • file_path

      (必填)待读取文件的路径,该路径是一个相对于 user_files_secure_path 目录的相对路径, 其中 user_files_secure_path 参数是 be的一个配置项

      路径中不能包含 ..,可以使用 glob 语法进行模糊匹配,如:logs/*.log

  • 执行方式相关:

    在 2.1.1 之前的版本中,Doris 仅支持指定某一个 BE 节点,读取该节点上的本地数据文件。

    • backend_id:

      1. 文件所在的 be id `backend_id` 可以通过 `show backends` 命令得到。

      从 2.1.2 版本开始,Doris 增加了新的参数 shared_storage

    • shared_storage

      默认为 false。如果为 true,表示指定的文件存在于共享存储上(比如 NAS)。共享存储必须兼容 POXIS 文件接口,并且同时挂载在所有 BE 节点上。

      shared_storage 为 true 时,可以不设置 backend_id,Doris 可能会利用到所有 BE 节点进行数据访问。如果设置了 backend_id,则仍然仅在指定 BE 节点上执行。

  • 文件格式相关参数:

    • format:(必填) 目前支持 csv/csv_with_names/csv_with_names_and_types/json/parquet/orc
    • column_separator:(选填) 列分割符, 默认为,
    • line_delimiter:(选填) 行分割符,默认为\n
    • compress_type: (选填) 目前支持 UNKNOWN/PLAIN/GZ/LZO/BZ2/LZ4FRAME/DEFLATE/SNAPPYBLOCK。 默认值为 UNKNOWN, 将会根据 uri 的后缀自动推断类型。
  • 以下参数适用于json格式的导入,具体使用方法可以参照:Json Load

    • read_json_by_line: (选填) 默认为 "true"
    • strip_outer_array: (选填) 默认为 "false"
    • json_root: (选填) 默认为空
    • json_paths: (选填) 默认为空
    • num_as_string: (选填) 默认为 false
    • fuzzy_parse: (选填) 默认为 false
  • 以下参数适用于csv格式的导入:

    • trim_double_quotes: 布尔类型,选填,默认值为 false,为 true 时表示裁剪掉 csv 文件每个字段最外层的双引号
    • skip_lines: 整数类型,选填,默认值为0,含义为跳过csv文件的前几行。当设置format设置为 csv_with_namescsv_with_names_and_types 时,该参数会失效

Examples

分析指定 BE 上的日志文件:

  1. mysql> select * from local(
  2. "file_path" = "log/be.out",
  3. "backend_id" = "10006",
  4. "format" = "csv")
  5. where c1 like "%start_time%" limit 10;
  6. +--------------------------------------------------------+
  7. | c1 |
  8. +--------------------------------------------------------+
  9. | start time: 2023 08 07 星期一 23:20:32 CST |
  10. | start time: 2023 08 07 星期一 23:32:10 CST |
  11. | start time: 2023 08 08 星期二 00:20:50 CST |
  12. | start time: 2023 08 08 星期二 00:29:15 CST |
  13. +--------------------------------------------------------+

读取和访问位于路径${DORIS_HOME}/student.csv的 csv格式文件:

  1. mysql> select * from local(
  2. "file_path" = "student.csv",
  3. "backend_id" = "10003",
  4. "format" = "csv");
  5. +------+---------+--------+
  6. | c1 | c2 | c3 |
  7. +------+---------+--------+
  8. | 1 | alice | 18 |
  9. | 2 | bob | 20 |
  10. | 3 | jack | 24 |
  11. | 4 | jackson | 19 |
  12. | 5 | liming | d18 |
  13. +------+---------+--------+

访问 NAS 上的共享数据:

  1. mysql> select * from local(
  2. "file_path" = "/mnt/doris/prefix_*.txt",
  3. "format" = "csv",
  4. "column_separator" =",",
  5. "shared_storage" = "true");
  6. +------+------+------+
  7. | c1 | c2 | c3 |
  8. +------+------+------+
  9. | 1 | 2 | 3 |
  10. | 1 | 2 | 3 |
  11. | 1 | 2 | 3 |
  12. | 1 | 2 | 3 |
  13. | 1 | 2 | 3 |
  14. +------+------+------+

可以配合desc function使用

  1. mysql> desc function local(
  2. "file_path" = "student.csv",
  3. "backend_id" = "10003",
  4. "format" = "csv");
  5. +-------+------+------+-------+---------+-------+
  6. | Field | Type | Null | Key | Default | Extra |
  7. +-------+------+------+-------+---------+-------+
  8. | c1 | TEXT | Yes | false | NULL | NONE |
  9. | c2 | TEXT | Yes | false | NULL | NONE |
  10. | c3 | TEXT | Yes | false | NULL | NONE |
  11. +-------+------+------+-------+---------+-------+

Keywords

  1. local, table-valued-function, tvf

Best Practice

  • 关于 local tvf 的更详细使用方法可以参照 S3 tvf, 唯一不同的是访问存储系统的方式不一样。

  • 通过 local tvf 访问 NAS 上的数据

    NAS 共享存储允许同时挂载到多个节点。每个节点都可以像访问本地文件一样访问共享存储中的文件。因此,可以将 NAS 视为本地文件系统,通过 local tvf 进行访问。

    当设置 "shared_storage" = "true" 时,Doris 会认为所指定的文件可以在任意 BE 节点访问。当使用通配符指定了一组文件时,Doris 会将访问文件的请求分发到多个 BE 节点上,这样可以利用多个节点的进行分布式文件扫描,提升查询性能。