Последнее обновление 16 окт. 2026 г.

HDFS

Описание

Табличная функция HDFS (TVF) читает файлы в HDFS в виде реляционной таблицы. Она поддерживает форматы csv, csv_with_names, csv_with_names_and_types, json, parquet, orc и avro.

Синтаксис

HDFS(
    "uri" = "<uri>",
    "fs.defaultFS" = "<fs_defaultFS>",
    "hadoop.username" = "<hadoop_username>",
    "format" = "<format>"
    [, "<optional_property_key>" = "<optional_property_value>" [, ...] ]
)

Параметры

Обязательные параметры

Параметр	Описание
`uri`	URI файла в HDFS для чтения. Если путь не существует или файл пуст, TVF возвращает пустой результат.
`fs.defaultFS`	URI файловой системы HDFS по умолчанию.
`hadoop.username`	Имя пользователя HDFS. Укажите непустую строку.
`format`	Формат файла: `csv`, `csv_with_names`, `csv_with_names_and_types`, `json`, `parquet`, `orc` или `avro`.

Необязательные параметры

Используйте следующие ключи для <optional_property_key> и соответствующие им значения для <optional_property_value>:

Параметр	Описание	Примечания
`hadoop.security.authentication`	Тип аутентификации HDFS.
`hadoop.kerberos.principal`	Принципал Kerberos.
`hadoop.kerberos.keytab`	Файл keytab Kerberos.
`dfs.client.read.shortcircuit`	Включает чтение HDFS в режиме short-circuit.
`dfs.domain.socket.path`	Путь к доменному сокету.
`dfs.nameservices`	Nameservice, используемый в режиме HA.
`dfs.ha.namenodes.<nameservice>`	Идентификаторы NameNode для указанного nameservice в режиме HA.
`dfs.namenode.rpc-address.<nameservice>.<namenode>`	RPC-адрес указанного NameNode.
`dfs.client.failover.proxy.provider.<nameservice>`	Класс провайдера прокси для переключения при отказе в nameservice.
`column_separator`	Разделитель столбцов; по умолчанию `\t`.
`line_delimiter`	Разделитель строк; по умолчанию `\n`.
`compress_type`	Сжатие: `UNKNOWN`, `PLAIN`, `GZ`, `LZO`, `BZ2`, `LZ4FRAME`, `DEFLATE` или `SNAPPYBLOCK`. По умолчанию `UNKNOWN`: тип сжатия определяется по суффиксу URI.
`read_json_by_line`	Чтение JSON построчно; по умолчанию `true`.	Загрузка JSON
`strip_outer_array`	Удаление внешнего массива JSON; по умолчанию `false`.	Загрузка JSON
`json_root`	Корневой путь JSON; по умолчанию пустой.	Загрузка JSON
`json_paths`	Пути к полям JSON; по умолчанию пустые.	Загрузка JSON
`num_as_string`	Чтение чисел JSON как строк; по умолчанию `false`.	Загрузка JSON
`fuzzy_parse`	Включает нечёткий разбор JSON; по умолчанию `false`.	Загрузка JSON
`trim_double_quotes`	Логический параметр для CSV; по умолчанию `false`. Если включён, удаляет обрамляющие двойные кавычки из каждого поля.
`skip_lines`	Целочисленный параметр для CSV; по умолчанию `0`. Пропускает начальные строки; игнорируется для `csv_with_names` и `csv_with_names_and_types`.
`path_partition_keys`	Имена столбцов партиционирования, закодированные в пути и перечисленные через запятую. Для `/path/to/city=beijing/date=2023-07-09` используйте `city,date`, чтобы извлечь эти значения.
`resource`	Существующий HDFS Resource, используемый для доступа к HDFS. См. CREATE RESOURCE.	Начиная с 2.1.4
`enable_mapping_varbinary`	В версии dev принимается только для совместимости и игнорируется: внешние двоичные данные всегда сопоставляются с `VARBINARY`. В Doris 4.1.5 этот параметр TVF остаётся настраиваемым со значением по умолчанию `false`.	Начиная с 4.0.3
`enable_mapping_timestamp_tz`	Начиная с 4.1.5 принимается только для совместимости; значение игнорируется. Parquet Timestamp с `isAdjustedToUTC=true` и ORC `TIMESTAMP_INSTANT` всегда сопоставляются с `TIMESTAMPTZ`, даже если этот параметр имеет значение `false`.	Начиная с 4.0.3
`hive.parquet.time-zone`	Необязательная строка, по умолчанию пустая. Задаёт часовой пояс, используемый при записи Parquet INT96: часовой пояс IANA или смещение UTC от `-12:00` до `+14:00`; короткие псевдонимы, такие как `CST` и `PRC`, не допускаются. См. Parquet.	Начиная с 4.1.5

Требования к правам доступа

При использовании параметра resource пользователю, выполняющему запрос, требуется привилегия USAGE на соответствующий Resource. Doris также должен иметь сетевой доступ к HDFS и действительные учётные данные HDFS или Kerberos для доступа к файлам.

Возвращаемое значение

Возвращает таблицу, имена и типы столбцов которой определяются по файлам. Поля со значением NULL возвращаются как SQL NULL. Несуществующий путь или пустой файл дают пустой результат. Неверные параметры, недоступное хранилище или некорректные файлы могут привести к ошибке анализа или выполнения.

Примеры

В следующих примерах предполагается, что файл student.csv в HDFS содержит:

1,alice,18
2,bob,20
3,jack,24
4,jackson,19
5,liming,18

Чтение файла CSV

SELECT * FROM HDFS(
    "uri" = "hdfs://127.0.0.1:8424/user/doris/csv_format_test/student.csv",
    "fs.defaultFS" = "hdfs://127.0.0.1:8424",
    "hadoop.username" = "doris",
    "format" = "csv",
    "column_separator" = ","
);

+------+---------+------+
| c1   | c2      | c3   |
+------+---------+------+
| 1    | alice   | 18   |
| 2    | bob     | 20   |
| 3    | jack    | 24   |
| 4    | jackson | 19   |
| 5    | liming  | 18   |
+------+---------+------+

Чтение файла CSV из HDFS в режиме HA

Настройте nameservice и адреса обоих NameNode для своего кластера HA. URI и fs.defaultFS используют логический nameservice:

SELECT * FROM HDFS(
    "uri" = "hdfs://my_hdfs/user/doris/csv_format_test/student.csv",
    "fs.defaultFS" = "hdfs://my_hdfs",
    "hadoop.username" = "doris",
    "format" = "csv",
    "column_separator" = ",",
    "dfs.nameservices" = "my_hdfs",
    "dfs.ha.namenodes.my_hdfs" = "nn1,nn2",
    "dfs.namenode.rpc-address.my_hdfs.nn1" = "namenode01:8020",
    "dfs.namenode.rpc-address.my_hdfs.nn2" = "namenode02:8020",
    "dfs.client.failover.proxy.provider.my_hdfs" = "org.apache.hadoop.hdfs.server.namenode.ha.ConfiguredFailoverProxyProvider"
);

+------+---------+------+
| c1   | c2      | c3   |
+------+---------+------+
| 1    | alice   | 18   |
| 2    | bob     | 20   |
| 3    | jack    | 24   |
| 4    | jackson | 19   |
| 5    | liming  | 18   |
+------+---------+------+

Просмотр автоматически определённой схемы

DESC FUNCTION HDFS(
    "uri" = "hdfs://127.0.0.1:8424/user/doris/csv_format_test/student.csv",
    "fs.defaultFS" = "hdfs://127.0.0.1:8424",
    "hadoop.username" = "doris",
    "format" = "csv",
    "column_separator" = ","
);

+-------+------+------+-------+---------+-------+
| Field | Type | Null | Key   | Default | Extra |
+-------+------+------+-------+---------+-------+
| c1    | TEXT | Yes  | false | NULL    | NONE  |
| c2    | TEXT | Yes  | false | NULL    | NONE  |
| c3    | TEXT | Yes  | false | NULL    | NONE  |
+-------+------+------+-------+---------+-------+

Примечания по использованию

Другие общие параметры файлов описаны в разделе S3 TVF. Настройки аутентификации и HA, специфичные для HDFS, описаны в разделе Хранилище HDFS.

Описание​

Синтаксис​

Параметры​

Обязательные параметры​

Необязательные параметры​

Требования к правам доступа​

Возвращаемое значение​

Примеры​

Чтение файла CSV​

Чтение файла CSV из HDFS в режиме HA​

Просмотр автоматически определённой схемы​

Примечания по использованию​