使用 Snowpark XML RowTag Reader

在 session.read.option("rowTag", "<rowtag>").xml() 中指定 .option("rowTag", "<rowtag>") 会激活 Snowpark XML RowTag Reader。此模式不是将整个文档作为单个对象加载，而是根据指定的 rowTag 拆分文件，将每个匹配元素作为单独的行加载，并将每行拆分为多列，以生成 Snowpark DataFrame。它特别适用于处理 XML 文件中的特定元素，或以可扩展的 Snowpark 原生方式引入大型 XML 文件。

示例

以样本 XML 为例：

<library>
    <book id="1">
        <title>The Art of Snowflake</title>
        <author>Jane Doe</author>
        <price>29.99</price>
        <reviews>
            <review>
                <user>tech_guru_87</user>
                <rating>5</rating>
                <comment>Very insightful and practical.</comment>
            </review>
            <review>
                <user>datawizard</user>
                <rating>4</rating>
                <comment>Great read for data engineers.</comment>
            </review>
        </reviews>
        <editions>
            <edition year="2023" format="Hardcover"/>
            <edition year="2024" format="eBook"/>
        </editions>
    </book>

    <book id="2">
        <title>XML for Data Engineers</title>
        <author>John Smith</author>
        <price>35.50</price>
        <reviews>
            <review>
                <user>xml_master</user>
                <rating>5</rating>
                <comment>Perfect for mastering XML parsing.</comment>
            </review>
        </reviews>
        <editions>
            <edition year="2022" format="Paperback"/>
        </editions>
    </book>
</library>
Copy

Snowpark 脚本

df = session.read.option("rowTag", "book").xml("@mystage/books.xml")
Copy

这会将每个 <book> 元素从 XML 文件加载到自己的行中，其中子元素（例如，<title> 和 <author>）会自动提取为 VARIANT 类型的列。

输出

_id

author

editions

price

reviews

title

"2"

"John Smith"

{ "edition": { "_format": "Paperback", "_year": "2022" } }

"35.50"

{ "review": { "comment": "Perfect for mastering XML parsing.", "rating": "5", "user": "xml_master" } }

"XML for Data Engineers"

"1"

"Jane Doe"

{ "edition": [ { "_format": "Hardcover", "_year": "2023" }, { "_format": "eBook", "_year": "2024" } ] }

"29.99"

{ "review": [ { "comment": "Very insightful and practical.", "rating": "5", "user": "tech_guru_87" }, { "comment": "Great read for data engineers.", "rating": "4", "user": "datawizard" } ] }

"The Art of Snowflake"

  • 由 rowTag 标识的每个 XML 元素都变成一行。

  • 该标签中的每个子元素都成为一列，存储为 VARIANT。嵌套元素被捕获为嵌套 VARIANT 数据。

  • 由此产生的 DataFrame 经过展平和列化，其行为与任何其他 Snowpark DataFrame 无异。

开始使用

  1. 安装 Snowpark Python 包：

    pip install snowflake-snowpark-python
    Copy

  2. 将 XML 文件上传到 Snowflake 暂存区：

    PUT file:///path/to/books.xml @mystage;
    Copy

  3. 使用 Snowpark 读取 XML 文件：

    df = session.read.option("rowTag", "book").xml("@mystage/books.xml")
    Copy

  4. 使用 DataFrame 方法进行转换或保存：

    df.select(col("`title`"), col("`author`")).show()
df.write.save_as_table("books_table")
    Copy

支持的选项

  • :code:`rowTag`（必填）：要提取为行的 XML 元素的名称。

  • :code:`rowValidationXSDPath`（可选）：用于在加载过程中验证每个 rowTag 片段的 XSD 的暂存区路径。

  • mode`（可选）：默认行为加载时无需验证。当设置 :code:`rowValidationXSDPath 时：

    • PERMISSIVE – 对 _corrupt_record 中无效的行进行隔离处理；加载其余的行。

    • FAILFAST – 在第一个无效行处停止并引发错误。

有关 XML 选项的更多信息，请参阅 snowflake.snowpark.DataFrameReader.xml。

使用 XSD 验证 XML

您可以在加载期间根据 XSD 验证每个 rowTag 片段。设置 XSD 路径并选择验证模式：

df = (
session.read
    .option("rowTag", "book")
    .option("rowValidationXSDPath", "@mystage/schema.xsd")  # validates each row element
    .option("mode", "PERMISSIVE")                         # or "FAILFAST"
    .xml("@mystage/books.xml")
)
Copy

PERMISSIVE：选择使用 时默认使用的角色和仓库。无效的行会被隔离在专门的 _corrupt_record 列中；而有效的行则会正常加载。要保留结果，请使用 df.write.save_as_table("<table_name>") 将 DataFrame 写入表中。该表将包括所有已解析的列以及额外的 _corrupt_record 列：对于有效行，该列为 NULL；对于无效行，该列则包含完整的 XML 记录（其他列则显示 NULL）。

+-------------------+
| _corrupt_record   |
+-------------------+
| <book id="1"> ... |
| <book id="2"> ... |
+-------------------+

FAILFAST：选择使用 时默认使用的角色和仓库。读取操作会在第一个有问题的行处停止并返回错误。

限制

Snowpark XML RowTag Reader 具有以下限制：

  • 不推断架构，并且输出列都是 VARIANT 类型。

  • 仅支持存储在 Snowflake 暂存区中的文件。不支持本地文件。

  • 仅在 Snowpark Python 库中可用。

语言: 中文