polars中数据读取与保存

为了降低资源使用并提高性能，在数据读取时我们读取为LazyFrame数据

在数据写入方面，LazyFrame数据仅csv和parquet文件有专用的数据写入方法，且都采用流式处理模式，该模式在polars官方被标注为不稳定的，所以实际数据写入时我们使用DataFrame数据的相关方法，对于LazyFrame数据再最后需要使用LazyFrame.collect()方法来获取最终结算后的DataFrame数据

CSV文本

数据读取：polars.scan_csv()

source                  str，文件或目录路径
                        为目录会自动扫描目录中所有文件并合并读取
                        所有文件字段必须完全一致，不一致会抛出ComputeError异常

关键字参数

读取设置
comment_prefix = None       用于指示注释行开始的字符串。在解析过程中跳过注释行
skip_rows = 0               导入时跳过前面skip_rows行
n_rows = None               读取n_rows行后停止读取，在多线程解析时，不能保证该值的准确性
encoding = 'utf8'           当设置为utf8-lossy时，无效的utf8值被替换为 � 字符
low_memory = False          是否使用低内存模式，以牺牲性能为代价减少内存压力
rechunk = False             解析完所有文件时，重新分配到连续内存
skip_rows_after_header = 0  解析 Headers 时跳过此行数
eol_char: str = '\n'        单字节行尾字符。在windows中使用默认的"\n"，额外的 "\r" 将在处理时自动删除
glob = True                 要读取的文件或目录路径是否通过glob规则匹配
raise_if_empty = True       是否抛出数据源为空的异常，为False返回没有列的空数据，否则引发NoDataError

解析设置
has_header = True           第一行是否为标头。为False列名将以column_x格式自动生成，x从1开始
separator  = ','            在文件中用作分隔符的单字节字符
quote_char = '"'            单字节字符用于CSV引用，默认值= "，设为None表示禁用改功能
schema = None,              dict{col:dtype}，指定每列数据类型而不自动推断，指定列的数量必须要和数据宽度相同
schema_overrides = None     dict{col:dtype}，指定部分字段数据类型，未指定字段会进行数据类型推断
null_values = None          str | [str] | dict{col:str}，指定要解析为空值的数据
missing_utf8_is_empty_string = False    异常utf8值是否解析为空字符串，默认为null
ignore_errors = False       是否忽略数据类型解析错误
infer_schema = True         是否进行数据类型推断，为False会全部解析为pl.String(如果未在schema或schema_overrides中指定)
infer_schema_length = 100   自动推断数据类型时分析的行数，为0则全部解析为pl.String，为None则会解析全部数据，这会导致速度大幅度减慢
try_parse_dates = False     是否尝试解析字符串为日期
new_columns = None          [str]，手动指定列名称，如果指定列表短与数据宽度，其余列将使用原始名称
truncate_ragged_lines = False   截断长于架构的行，默认会抛出ComputeError异常
decimal_comma= False        解析浮点数时使用逗号作为小数点

其他设置
cache = True                读取数据后进行缓存
with_column_names = None    func，将所有列名修改为将原列名经过此函数处理的返回值
                            函数接受仅有一个元素的tuple，为一个list，包含所有解析的字段名
                            返回一个list，表示新的列名称
row_index_name = None       在第一列插入指定名称的列作为行索引列，为None表示不创建行索引列
row_index_offset = 0,       在设置行索引时从指定偏移量开始创建索引，仅在设置了row_index_name时使用

数据写入：DataFrame.write_csv()

file            str，要写入的文件名，如果为None则将结果将作为字符串返回

关键字参数
include_bom = False,    是否在 CSV 输出中包含 UTF-8 BOM
include_header = True   是否在 CSV 输出中包含标题
separator = ','         使用此符号分隔 CSV 字段
line_terminator = '\n'  用于结束每行的字符串
quote_cha = '"'         用作引号字符的字节
batch_size = 1024       每个线程将处理的行数
float_scientific = None bool，对于小数是否始终使用科学形式，None表示自动
float_precision = None  int，写入小数时保留的小数位数
null_value = ""         写入null值时的字符串
quote_style = 'necessary' 写入时引号字符的添加策略
        necessary   仅在必要时添加
        always      全部添加
        never       永远不添加，这可能会导致无效的CSV数据
        non_numeric 仅在所有非数字字段添加
datetime_format = None  日期和时间的格式字符串
date_format = None      日期的格式字符串
time_format = None      时间的格式字符串
        年      %Y(4位年)、%C(年的前2位)、%y(年的后2位)
        月      %m(前导0)
        日      %d(前导0)、%e(前导空格)
        星期几  %w(周日为0)、%u(周日为7)
        %F     同%Y-%m-%d
        时      %H(前导0)、%k(前导空格)
        分      %M(前导0)
        秒      %S(前导0)
        %T      同%H:%M:%S

数据库

由于数据库返回是一次性将数据全部返回，所以无法使用LazyFrame，我们可以先将数据从数据库中读取为DataFrame，然后使用DataFrame.lazy()将数据转换为LazyFrame

数据读取：polars.read_database()

query       数据库查询语句
connection  数据库的游标对象

关键字参数
iter_batches = False    返回一个迭代器，每次迭代返回一小批数据而不是一次性全部返回
batch_size = None       int，返回迭代器时每次迭代返回数据的大小
                        当iter_batches为False时仍然可以设置次参数
                        在读取数据时在后台使用此大小分批获取全部数据
schema_overrides=None   dict{col:dtype}，手动指定各列的数据类型
infer_schema_length=100 int，自动推断数据类型时分析的行数，为0则全部解析为pl.String，为None则会分析全部
                        仅当数据作为行序列读取并且未为给定列设置 schema_overrides 参数时

数据写入：DataFrame.write_database()

该函数返回受影响的行数，如果驱动程序不支持返回 -1

table_name              要写入的表名，表不存在会自动创建
connection              数据库的游标对象

关键字参数
if_table_exists = 'fail' 表已存在时的写入策略，可选值append、replace(清除现有数据)、fail

EXCEL文件

EXCEL同样无法读取为LazyFrame，也需要读取后通过DataFrame.lazy()将数据转换为LazyFrame

数据读取：polars.read_excel()

source                  str，文件或目录路径

关键字参数
sheet_id= 1             int | [int]，要读取的工作表id(从1开始)
                        如果传入list，读取多个工作表并返回dict{sheetname：frame}
                        设为 0 会读取所有工作表
sheet_name= None        str | [str]，要读取的工作表名称
                        功能和sheet_id相同，不能与sheet_id同时指定
has_header = True       第一行是否为标题
columns = None          要读取的列名称或列索引组成的list
schema_overrides = None dict{col:dtype}，手动指定各列的数据类型
infer_schema_length = 100  int，自动推断数据类型时分析的行数，为0则全部解析为pl.String，为None则会分析全部
drop_empty_rows = True  读取时是否忽略空行
raise_if_empty = True   是否抛出数据源为空的异常，为False返回没有列的空数据，否则引发NoDataError

数据写入：DataFrame.write_excel()

workbook = 'dataframe.xlsx' str，要写入的文件名
worksheet = None            要写入的工作表名称，默认第一个工作表

关键字参数
position                    开始写入数据的单元格，可以为str或(int,int)
                            str为"A3"、"C5"等格式
                            (int,int)表示行和列的索引

column_formats = None       设置指定列的格式，dict{colname:str}或dict{selector:str}
dtype_formats = None        设置特定数据类型的格式，dict{dtype:str}

column_widths = None        设置列宽，dict{colname:int}，如果为一个int，则同时设置所有列
row_heights = None          设置行高，dict{row_x,int}，如果为一个int，则同时设置所有行
float_precision = 3         小数列的默认显示小数位，纯粹是一个格式设置，实际值不四舍五入
include_header = True       是否写入标题行
autofilter = True           是否开启数据筛选(必须开启写入标题行)
autofit = False             是否根绝每列数据的长度自动设置列宽
hidden_columns = None       要隐藏的列名或列名列表
hide_gridlines = False      是否隐藏网格线
sheet_zoom = None           int，设置工作表的默认缩放级别
freeze_panes = None         窗口冻结，str、tuple(row_x,col_x)

parquet文件

数据读取：polars.scan_parquet()

source                      str，文件或目录路径

关键字参数
n_rows = None               读取n_rows行后停止读取，在多线程解析时，不能保证该值的准确性
row_index_name = None       在第一列插入指定名称的列作为行索引列，为None表示不创建行索引列
row_index_offset = 0,       在设置行索引时从指定偏移量开始创建索引，仅在设置了row_index_name时使用
use_statistics = True       使用parquet中的统计信息来确定是否可以从读取中跳过页面
glob = True                 要读取的文件或目录路径是否通过glob规则匹配
schema = None,              指定列的数据类型。数据类型必须与文件中的数据类型匹配
rechunk = False             通过glob模式读取多个文件后将最终数据重新分块为连续的内存块
low_memory = False          是否使用低内存模式，以牺牲性能为代价减少内存压力
cache = True                读取数据后进行缓存

allow_missing_columns=False 读取多个parquet文件时，第一个文件中的某些列在后续文件中不存在时是否继续解析
                            默认是引发错误，设置为True则返回完整NULL列

数据写入：DataFrame.write_parquet()

file                        str，要写入的文件名

关键字参数
compression = 'zstd'        数据压缩方式
                            lz4(最快速)、uncompressed(不压缩)、snappy(对于较久的数据保证兼容性)、
                            gzip、lzo、brotli、zstd(性能好)
compression_leve = None     int，数据压缩级别，越高文件越小
                            gzip(0-10)、brotli(0-11)、zstd(1-12)
row_group_size = 512^2      行组的大小(以行为单位)
data_page_size = 1024^2     数据页大小(字节)