查询与转换

TiDB Cloud Lake 支持直接查询已暂存的文件，而无需先将数据加载到表中。你可以查询任意 stage 类型（user、internal、external）中的文件，也可以直接查询对象存储和 HTTPS URL 中的文件。它非常适合在加载前后进行数据检查、验证和转换。

语法

仅查询

SELECT {
    [<alias>.]<column> [, [<alias>.]<column> ...] -- Query columns by name
  | [<alias>.]$<col_position> [, [<alias>.]$<col_position> ...] -- Query columns by position
  | [<alias>.]$1[:<column>] [, [<alias>.]$1[:<column>]  ...] -- Query rows as Variants
}
FROM {@<stage_name>[/<path>] | '<uri>'}  -- stage table function
  [( -- stage table function parameters
    [<connection_parameters>],
    [ PATTERN => '<regex_pattern>'],
    [ FILE_FORMAT => 'CSV | TSV | NDJSON | PARQUET | ORC | Avro | <custom_format_name>'],
    [ FILES => ( '<file_name>' [ , '<file_name>' ... ])],
    [ CASE_SENSITIVE => true | false ]
  )]
  [<alias>]

带转换的复制

COPY INTO [<database_name>.]<table_name> [ ( <col_name> [ , <col_name> ... ] ) ]
     FROM (
        SELECT {
            [<alias>.]<column> [, [<alias>.]<column> ...] -- Query columns by name
            | [<alias>.]$<col_position> [, [<alias>.]$<col_position> ...] -- Query columns by position
            | [<alias>.]$1[:<column>] [, [<alias>.]$1[:<column>]  ...] -- Query rows as Variants
            } ]
        FROM {@<stage_name>[/<path>] | '<uri>'}
    )
[ FILES = ( '<file_name>' [ , '<file_name>' ] [ , ... ] ) ]
[ PATTERN = '<regex_pattern>' ]
[ FILE_FORMAT = (
         FORMAT_NAME = '<your-custom-format>'
         | TYPE = { CSV | TSV | NDJSON | PARQUET | ORC | AVRO } [ formatTypeOptions ]
       ) ]
[ copyOptions ]

FROM 子句

FROM 子句使用与 Table Function 类似的语法。与普通表一样，在与其他表进行 join 时也可以使用表 alias。

table function 参数：

查询文件数据

select 列表支持三种语法；一次只能使用其中一种，不能混用。

将行作为 Variants 查询

• 支持的文件格式：NDJSON、AVRO、Parquet、ORC

语法：

SELECT [<alias>.]$1[:<column>] [, [<alias>.]$1[:<column>]  ...] <FROM Clause>

• 示例：SELECT $1:id, $1:name FROM ...
• 表结构：($1: Variant)。即只有一列，类型为 Variant Object，每个 Variant 表示完整的一行
• 说明：
  • 像 $1:column 这样的路径表达式的类型也是 Variant，在表达式中使用或加载到目标表列时可以自动转换为原生类型。有时你可能希望在执行特定类型操作前手动进行类型转换（例如 CAST($1:id AS INT)），以使语义更加明确。

按名称查询列

• 支持的文件格式：NDJSON、AVRO、Parquet、ORC

SELECT [<alias>.]<column> [, [<alias>.]<column>  ...] <FROM Clause>

• 示例：SELECT id, name FROM ...
• 表结构：从 Parquet 或 ORC 文件 schema 映射得到的列
• 说明：
  • 所有文件都必须具有相同的 Parquet/ORC schema；否则会返回错误

按位置查询列

• 支持的文件格式：CSV、TSV

SELECT [<alias>.]$<col_position>[, [<alias>.]$<col_position>,  ...] <FROM Clause>

• 示例：SELECT $1, $2 FROM ...
• 表结构：类型为 VARCHAR NULL 的列
• 说明
  • <col_position> 从 1 开始

查询元信息

你还可以在查询中包含文件元信息，这对于跟踪数据血缘和调试非常有用：

SELECT METADATA$FILENAME, METADATA$FILE_ROW_NUMBER, $1, <FROM Clause>
(
    FILE_FORMAT => 'ndjson_query_format',
    PATTERN => '.*[.]ndjson'
);

以下是支持的文件格式可用的文件级元信息字段：

使用场景：

• 数据血缘：跟踪每条记录来自哪个源文件
• 调试：通过文件和行号定位有问题的记录
• 增量处理：仅处理特定文件或文件中的特定范围

按文件格式分类的教程

• 在 Stage 中查询 Parquet 文件
• 在 Stage 中查询 ORC 文件
• 在 Stage 中查询 NDJSON 文件
• 在 Stage 中查询 Avro 文件
• 在 Stage 中查询 CSV 文件
• 在 Stage 中查询 TSV 文件

Schema Evolution

• Schema Evolution：在加载表结构持续演进的 Parquet 文件时，自动向表中添加新列。