polars.scan_csv

polars.scan_csv(
    source: str | Path | IO[str] | IO[bytes] | bytes | list[str] | list[Path] | list[IO[str]] | list[IO[bytes]] | list[bytes],
    *,
    has_header: bool = True,
    separator: str = ',',
    comment_prefix: str | None = None,
    quote_char: str | None = '"',
    skip_rows: int = 0,
    skip_lines: int = 0,
    schema: SchemaDict | None = None,
    schema_overrides: SchemaDict | Sequence[PolarsDataType] | None = None,
    null_values: str | Sequence[str] | dict[str,
    str] | None = None,
    empty_string_is_null: bool = True,
    ignore_errors: bool = False,
    cache: bool | None = None,
    with_column_names: Callable[[list[str]],
    list[str]] | None = None,
    infer_schema: bool = True,
    infer_schema_length: int | None = 100,
    infer_schema_files: int = 18446744073709551615,
    n_rows: int | None = None,
    encoding: CsvEncoding = 'utf8',
    low_memory: bool = False,
    rechunk: bool | None = None,
    skip_rows_after_header: int = 0,
    row_index_name: str | None = None,
    row_index_offset: int = 0,
    try_parse_dates: bool = False,
    eol_char: str = '\n',
    new_columns: Sequence[str] | None = None,
    raise_if_empty: bool = True,
    truncate_ragged_lines: bool = False,
    decimal_comma: bool = False,
    glob: bool = True,
    storage_options: StorageOptionsDict | None = None,
    credential_provider: CredentialProviderFunction | Literal['auto'] | None = 'auto',
    retries: int | None = None,
    file_cache_ttl: int | None = None,
    include_file_paths: str | None = None,
    missing_columns: Literal['insert',
    'raise'] | None = None,
) → LazyFrame

Лениво считывает данные из файла CSV или нескольких файлов с помощью шаблонов glob.

Это позволяет оптимизатору запросов проталкивать предикаты и проекции на уровень сканирования, потенциально снижая потребление памяти.

Изменено в версии 0.20.31: Параметр dtypes был переименован в schema_overrides.

Изменено в версии 0.20.4: * Параметр row_count_name был переименован в row_index_name. * Параметр row_count_offset был переименован в row_index_offset.

Параметры:

source

Путь или пути к файлу либо каталогу. Если для сканирования облачных ресурсов требуется аутентификация, см. параметр storage_options.

has_header

Указывает, является ли первая строка набора данных заголовком. Если задано значение False, имена столбцов будут сгенерированы в следующем формате: column_x, где x — перечисление всех столбцов набора данных, начиная с 1.

separator

Однобайтовый символ-разделитель в файле.

comment_prefix

Строка, обозначающая начало строки комментария. Строки комментариев пропускаются при разборе. Часто используемые префиксы комментариев: # и //.

quote_char

Однобайтовый символ для заключения значений CSV в кавычки; по умолчанию — ". Задайте None, чтобы отключить специальную обработку кавычек и экранирование.

skip_rows

Начать чтение после skip_rows строк. Заголовок будет разобран со смещением на это число строк. При пропуске строк учитываются экранирование CSV и комментарии. Чтобы пропускать только по символу новой строки, используйте skip_lines.

skip_lines

Начать чтение после skip_lines строк. Заголовок будет разобран со смещением на это число строк. При пропуске строк экранирование CSV не учитывается. Чтобы пропускать корректные строки CSV, используйте skip_rows.

schema

Задаёт схему. В этом случае polars не выполняет вывод схемы. Этот аргумент задаёт полную схему, тогда как schema_overrides можно использовать для частичного переопределения схемы. Обратите внимание, что порядок столбцов в переданном schema должен совпадать с порядком столбцов в считываемом файле CSV.

schema_overrides

Переопределяет типы данных при выводе схемы. Значением должен быть словарь {colname:dtype,} или, если в new_columns передаётся список строк, список типов данных той же длины.

null_values

Значения, которые следует интерпретировать как null. Можно передать:

• str: все значения, равные этой строке, будут считаться null.
• List[str]: все значения, равные любой строке из этого списка, будут считаться null.
• Dict[str, str]: словарь, сопоставляющий имени столбца строковое значение null.

empty_string_is_null

По умолчанию отсутствующее строковое значение считается null. Если для empty_string_is_null задано значение False, отсутствующие строковые значения будут декодированы как пустые строки.

ignore_errors

Продолжать чтение строк, если некоторые из них приводят к ошибкам. Сначала попробуйте задать infer_schema=False, чтобы считывать все столбцы как pl.String и проверить, какие значения могут вызывать проблему.

cache

Кэшировать результат после чтения.

Устарело с версии 1.39.0: Кэширование файлов больше не поддерживается.

with_column_names

Применяет функцию к именам столбцов непосредственно перед их определением; функция получит список имён столбцов и должна вернуть список имён столбцов.

infer_schema

Если задано True, схема выводится на основе данных с использованием первых infer_schema_length строк. Если задано False, схема не выводится и будет pl.String, если она не указана в schema или schema_overrides.

infer_schema_length

Максимальное число строк, сканируемых для вывода схемы. Ограничение применяется отдельно к каждому файлу, включённому согласно infer_schema_files. Если задано None, все данные будут считаны в память (это медленно). Также можно задать infer_schema=False, чтобы считывать все столбцы как pl.String.

infer_schema_files

Количество файлов, используемых для вывода схемы.

Предупреждение

Эта возможность считается нестабильной. Она может быть изменена в любой момент без объявления таких изменений нарушающими обратную совместимость.

n_rows

Прекратить чтение файла CSV после считывания n_rows.

encoding{‘utf8’, ‘utf8-lossy’}

При lossy-преобразовании недопустимые значения utf8 заменяются символами �. По умолчанию используется «utf8».

low_memory

Снижает нагрузку на память за счёт производительности.

rechunk

Перераспределяет данные в непрерывную область памяти после разбора всех блоков и файлов.

Устарело с версии 1.43.2: Сначала соберите данные в DataFrame, а затем вызовите rechunk для возвращённого DataFrame.

skip_rows_after_header

Пропустить указанное количество строк после разбора заголовка.

row_index_name

Если задано значение, отличное от None, добавляет в DataFrame столбец с индексом строки и указанным именем.

row_index_offset

Смещение, с которого начинается столбец индекса строк (используется, только если задано его имя).

try_parse_dates

Пытается автоматически разобрать даты. Можно определить большинство форматов, похожих на ISO8601, а также некоторые другие. Если разбор не удастся, тип данных столбца останется pl.String.

eol_char

Однобайтовый символ конца строки (по умолчанию: \n). Для файлов с переводами строк Windows (\r\n) можно оставить значение по умолчанию \n. При обработке лишний символ \r будет удалён.

new_columns

Задаёт явный список строковых имён столбцов (например, при сканировании файла CSV без заголовка). Если переданный список короче ширины DataFrame, оставшиеся столбцы сохранят исходные имена.

raise_if_empty

Если источник не содержит данных, возникает исключение NoDataError. Если для этого параметра задано значение False, вместо этого возвращается пустой LazyFrame без столбцов.

truncate_ragged_lines

Обрезать строки, длина которых превышает ширину схемы.

decimal_comma

Разбирать числа с плавающей точкой, используя запятую вместо точки в качестве десятичного разделителя.

glob

Разворачивать путь согласно правилам glob.

storage_options

Параметры подключения к облачному провайдеру.

В настоящее время поддерживаются облачные провайдеры AWS, GCP и Azure. Список поддерживаемых ключей см. здесь:

• aws
• gcp
• azure
• Hugging Face (hf://): принимает API-ключ в параметре token: {'token': '...'} или через переменную окружения HF_TOKEN.

Если storage_options не задан, Polars попытается получить нужные сведения из переменных окружения.

credential_provider

Функция, вызываемая для получения учётных данных облачного хранилища. Функция должна возвращать словарь ключей учётных данных и необязательное время истечения срока их действия.

Предупреждение

Эта возможность считается нестабильной. Она может быть изменена в любой момент без объявления таких изменений нарушающими обратную совместимость.

retries

Количество повторных попыток при сбое доступа к облачному экземпляру.

Устарело с версии 1.37.1: Вместо этого передайте {“max_retries”: n} через storage_options.

file_cache_ttl

Время в секундах, в течение которого загруженные облачные файлы хранятся после последнего обращения к ним. Если значение не задано, используется переменная окружения POLARS_FILE_CACHE_TTL (по умолчанию — 1 час).

Устарело с версии 1.39.0: Кэширование файлов больше не поддерживается.

include_file_paths

Добавить путь к исходному файлу или файлам в виде столбца с указанным именем.

missing_columns

Настройка поведения при отсутствии в данных столбцов, указанных в схеме:

• "insert": добавить отсутствующие столбцы со значениями NULL.
• "raise": вызвать ошибку.

Предупреждение

Эта возможность считается нестабильной. Она может быть изменена в любой момент без объявления таких изменений нарушающими обратную совместимость.

Возвращает:

LazyFrame

См. также

read_csv

Считывает файл CSV в DataFrame.

Примеры

>>> import pathlib
>>>
>>> (
...     pl.scan_csv("my_long_file.csv")  # lazy, doesn't do a thing
...     .select(
...         ["a", "c"]
...     )  # select only 2 columns (other columns will not be read)
...     .filter(
...         pl.col("a") > 10
...     )  # the filter is pushed down the scan, so less data is read into memory
...     .head(100)  # constrain number of returned results to 100
... )  

Можно использовать with_column_names для изменения заголовка перед сканированием:

>>> df = pl.DataFrame(
...     {"BrEeZaH": [1, 2, 3, 4], "LaNgUaGe": ["is", "hard", "to", "read"]}
... )
>>> path: pathlib.Path = dirpath / "mydf.csv"
>>> df.write_csv(path)
>>> pl.scan_csv(
...     path, with_column_names=lambda cols: [col.lower() for col in cols]
... ).collect()
shape: (4, 2)
┌─────────┬──────────┐
│ breezah ┆ language │
│ ---     ┆ ---      │
│ i64     ┆ str      │
╞═════════╪══════════╡
│ 1       ┆ is       │
│ 2       ┆ hard     │
│ 3       ┆ to       │
│ 4       ┆ read     │
└─────────┴──────────┘

Также можно просто заменить имена столбцов (или задать их, если в файле нет заголовка), передав список новых имён столбцов в параметр new_columns:

>>> df.write_csv(path)
>>> pl.scan_csv(
...     path,
...     new_columns=["idx", "txt"],
...     schema_overrides=[pl.UInt16, pl.String],
... ).collect()
shape: (4, 2)
┌─────┬──────┐
│ idx ┆ txt  │
│ --- ┆ ---  │
│ u16 ┆ str  │
╞═════╪══════╡
│ 1   ┆ is   │
│ 2   ┆ hard │
│ 3   ┆ to   │
│ 4   ┆ read │
└─────┴──────┘