全部文档
当前文档

暂无内容

如果没有找到您期望的内容,请尝试其他搜索词

文档中心

Select Object Content

最近更新时间:2026-11-18 17:42:29

描述

对指定 Bucket 内的对象执行 SQL 查询,服务端过滤后流式返回符合条件的结果数据,支持 CSV、JSON 格式对象的查询。使用 Select Object Content 必须拥有所查询对象的 KS3:GetObject 权限。

请求方式: POST

请求地址:

https://{BucketName}.{endpoint}/{ObjectName}?select&select-type=2

对于标准 / 低频 / 深度低频存储对象:可直接查询。

对于归档 / 冷归档存储对象:解冻后且在解冻有效期内可查询。

请求

请求语法

POST /{ObjectName}?select&select-type=2 HTTP/1.1
Host: {BucketName}.{endpoint}
Date: {date}
Authorization: {SignatureValue}
Content-Length: {length}
Content-MD5: {md5}
Content-Type: application/xml

<SelectRequest>
    ...
</SelectRequest>

请求公共头

名称

描述

Authorization

必要的请求验证信息

Content-Length

请求体的长度信息(不包含头部),以字节为单位

Content-Type

请求体中资源的类型,例如 text/plain

Content-MD5

请求对象的 MD5 摘要信息

Date

当前请求的时间和日期,格式如:Wed, 01 Mar 2006 12:00:00 GMT

Expect

当用户应用使用 100-continue,认证通过才会发送请求体。如果头部信息认证无效,则不会发送请求内容。有效值:100-continue

Host

路径样式的请求,其值为 ks3-cn-beijing.ksyuncs.com;虚拟样式的请求中,样式为 BucketName.ks3-cn-beijing.ksyuncs.com

请求体

以下请求展示了用户发起一个 KS3 Select 请求,检索 CSV 格式对象的所有内容,并将结果保存为 CSV 格式对象:

<?xml version="1.0" encoding="UTF-8"?>
<SelectRequest>
    <Expression>Select * from ks3Object</Expression>
    <ExpressionType>SQL</ExpressionType>
    <InputSerialization>
        <CompressionType>NONE</CompressionType>
        <CSV>
            <FileHeaderInfo>IGNORE</FileHeaderInfo>
            <RecordDelimiter>\n</RecordDelimiter>
            <FieldDelimiter>,</FieldDelimiter>
            <QuoteCharacter>"</QuoteCharacter>
            <QuoteEscapeCharacter>"</QuoteEscapeCharacter>
            <Comments>#</Comments>
        </CSV>
    </InputSerialization>
    <OutputSerialization>
        <CSV>
            <QuoteFields>ASNEEDED</QuoteFields>
            <RecordDelimiter>\n</RecordDelimiter>
            <FieldDelimiter>,</FieldDelimiter>
            <QuoteCharacter>"</QuoteCharacter>
            <QuoteEscapeCharacter>"</QuoteEscapeCharacter>
        </CSV>
    </OutputSerialization>
    <RequestProgress>
        <Enabled>FALSE</Enabled>
    </RequestProgress>
</SelectRequest>

以下请求展示了用户发起一个 KS3 Select 请求,检索 JSON 格式对象的所有内容,并将结果保存为 JSON 格式对象:

<?xml version="1.0" encoding="UTF-8"?>
<SelectRequest>
    <Expression>Select * from KS3Object</Expression>
    <ExpressionType>SQL</ExpressionType>
    <InputSerialization>
        <CompressionType>NONE</CompressionType>
        <JSON>
            <Type>DOCUMENT</Type>
        </JSON>
    </InputSerialization>
    <OutputSerialization>
        <JSON>
            <RecordDelimiter>\n</RecordDelimiter>
        </JSON>
    </OutputSerialization>
    <RequestProgress>
        <Enabled>FALSE</Enabled>
    </RequestProgress>
</SelectRequest>

InputSerialization 元素描述了待检索的对象格式,为必填参数,可以指定为 CSV、JSON 格式。

OutputSerialization 元素描述了检索结果的保存格式,仅可指定为 CSV 或 JSON 格式。

待检索的对象格式无需和检索结果的保存格式互相匹配,可以检索一个 JSON 格式的对象,并将检索结果保存为 CSV 格式。

请求体元素组成

名称

父节点

描述

类型

是否必选

Expression

SelectRequest

SQL 表达式,代表需要发起的检索操作。例如 SELECT s._1 FROM KS3Object s,可从 CSV 格式的对象中检索第一列内容。表达式需符合本期支持的 SQL 语法范围

String

是

ExpressionType

SelectRequest

表达式类型,目前只支持 SQL 表达式,仅支持 SQL 参数

String

是

InputSerialization

SelectRequest

描述待检索对象的格式

Container

是

OutputSerialization

SelectRequest

描述检索结果的输出格式

Container

是

RequestProgress

SelectRequest

是否需要返回查询进度 QueryProgress 信息,如果选中 KS3 Select 将周期性返回查询进度

Container

否

InputSerialization 子元素

名称

父节点

描述

类型

是否必选

CompressionType

InputSerialization

描述待检索对象的压缩格式。仅支持 NONE(未压缩),不支持 GZIP、BZIP2 压缩格式。默认值为 NONE

String

否

CSV/JSON

InputSerialization

描述在相应的对象格式下所需的文件参数。例如 CSV 格式需要指定分隔符

Container

是

CSV container(InputSerialization 子元素)

名称

父节点

描述

类型

是否必选

RecordDelimiter

CSV

将 CSV 对象中记录分隔为不同行的字符,默认通过 \n 分隔。可指定任意 8 进制字符,如逗号、分号、Tab 等。该参数最多支持 2 个字节,即可输入 \r\n 这类格式的分隔符。默认值为 \n

String

否

FieldDelimiter

CSV

指定分隔 CSV 对象中每一行的字符,默认通过 , 分隔。可指定任意 8 进制字符,该参数最多支持 1 个字节。默认值为 ,

String

否

QuoteCharacter

CSV

如果待检索的 CSV 对象中存在包含分隔符的字符串,可使用 QuoteCharacter 进行转义,避免该字符串被切割。如 CSV 对象中存在 "a, b" 这个字符串,双引号 " 可以避免其被分隔成 a 和 b 两个字符。默认值为 "

String

否

QuoteEscapeCharacter

CSV

如果待检索的字符串中已存在 ",需使用 " 进行转义以保证字符串可以正常转义。如字符串 """ a , b """ 将被解析为 " a , b "。默认值为 "

String

否

FileHeaderInfo

CSV

待检索对象中是否存在列表头。合法值为 NONE、USE、IGNORE:NONE 代表对象中没有列表头;USE 代表对象中存在表头并可使用表头检索;IGNORE 代表对象中存在表头但不使用表头检索(仍可通过列索引检索)。默认值为 NONE

Enum

否

Comments

CSV

指定某行记录为注释行,该字符会被添加到该行记录的首字符。如果某一行记录被指定为注释,KS3 Select 将不对此行做任何分析。默认值为 #

String

否

JSON container(InputSerialization 子元素)

名称

父节点

描述

类型

是否必选

Type

JSON

JSON 文件的类型:DOCUMENT 表示 JSON 文件仅包含一个独立的 JSON 对象,且该对象可以被切割成多行;LINES 表示 JSON 对象中的每一行包含一个独立的 JSON 对象。合法值为 DOCUMENT、LINES

Enum

是

OutputSerialization 子元素

名称

父节点

描述

类型

是否必选

CSV/JSON

OutputSerialization

指定检索结果的输出格式,可选项为 CSV 或 JSON

Container

是

CSV container(OutputSerialization 子元素)

名称

父节点

描述

类型

是否必选

QuoteFields

CSV

指定输出结果为文件时,是否需要使用 " 进行转义。合法值为 ALWAYS、ASNEEDED,默认值为 ASNEEDED。ALWAYS 代表对所有输出的检索文件应用 ",ASNEEDED 代表仅在需要时使用

String

是

RecordDelimiter

CSV

将输出结果中的记录分隔为不同行的字符,默认通过 \n 分隔。可指定任意 8 进制字符,最多支持 2 个字节。默认值为 \n

String

否

FieldDelimiter

CSV

将输出结果中的每一行进行分列的字符,默认通过 , 分隔。可指定任意 8 进制字符,最多支持 1 个字节。默认值为 ,

String

否

QuoteCharacter

CSV

如果输出结果中存在包含分隔符的字符串,可使用 QuoteCharacter 进行转义,保证该字符串不会在后续分析中被切割。默认值为 "

String

否

QuoteEscapeCharacter

CSV

如果即将输出的字符串中已存在 ",需使用 " 进行转义以保证字符串可以正常转义。默认值为 "

String

否

JSON container(OutputSerialization 子元素)

名称

父节点

描述

类型

是否必选

RecordDelimiter

JSON

将输出结果中的记录分隔为不同行的字符,默认通过 \n 分隔。可指定任意 8 进制字符,最多支持 2 个字节。默认值为 \n

String

否

RequestProgress 子元素

名称

父节点

描述

类型

是否必选

Enabled

RequestProgress

指定是否需要 KS3 Select 定期返回查询进度。默认值为 FALSE,可 3 秒返回一次

Boolean

否

响应

响应状态码

执行成功的检索操作将返回 200 OK 状态码。

响应头

此接口仅返回公共响应头部。

响应体

由于响应体的大小无法预知,KS3 将响应体以序列化形式展示,即将响应体切分成多个分块返回:

<Message 1>
<Message 2>
<Message 3>
......
<Message n>

检索结果切成多个分块,每个分块即一个 Message。每一个 Message 由预响应(prelude)和响应结果(data)组成:

  • 预响应包含两部分:所在分块 Message 的总长度、所有头部的总长度。

  • 响应结果包含两部分:响应报头(header)、响应正文(payload)。

预响应和响应结果均以 4 字节的经过大端编码(big-endian)的 CRC 校验码结尾。KS3 Select 使用 CRC32 计算 CRC 校验码。

所有分块 Message 中的整数值均以网络字节序,即大端编码传输。

响应体总长度计算方式:

响应体总长度 = 预响应长度 + 预响应校验码长度 + 响应正文长度 + 响应报头长度 + 响应正文校验码长度

由于校验码(prelude CRC 和 Message CRC)和预响应 prelude 总长度固定为 16 字节,因此响应体总长还可通过如下方式快速计算:

响应体总长度 = 响应正文长度 + 响应报头长度 + 16

响应体各部分组成:

组成

描述

预响应 prelude

分别记录了分块 Message 的总长度和所有报头的总长度,每个记录 4 字节,总长 8 字节:total byte-length 记录所在分块 Message 的总长度,使用大端编码,包含该记录本身容量共 4 字节;headers byte-length 记录所有报头的总长度,使用大端编码,不包含该记录所占空间共 4 字节

预响应校验码 prelude CRC

预响应的 CRC 校验码,使用大端编码,总共 4 字节。预响应校验码可以帮助程序快速识别预响应信息是否正确,减少缓冲时的阻塞

报头信息 header

分块 Message 记录的检索结果的元数据信息,诸如数据类型、正文格式。根据数据类型的差异,本部分的字节长度也有所差异。响应报头以 kv 键值对形式存储,使用 UTF-8 编码,可以以任意顺序展示,但每一项元数据仅记录一次

响应正文 Payload

记录检索结果,或者与请求相关的信息

正文校验码 Message CRC

使用大端编码的 CRC 校验码,总长 4 字节

单个 header 结构:

同一个分块 Message 中可能记录了多个 header,每一个响应报头 header 由以下几部分组成:

组成

描述

Header Name Byte-Length

记录 Header Name 的字节长度信息

Header Name

报头类型,合法值包括 :message-type、:event-type、:error-code 和 :error-message

Header Value Type

Header Value 的类型,对于 KS3 Select 而言这个值固定为 7,代表类型为 String

Value String Byte-Length

Header Value 的字节长度信息,固定 2 字节

Header Value String

响应报头的正文,即响应正文的元数据信息,Header Value 的字节长度与响应类型相关

响应报头类型说明:

报头

Key 值

合法 Value 值

MessageType Header

:message-type

error(报错信息)或 event(具体事件)

EventType Header

:event-type

Records(返回检索记录)、Cont(保持 TCP 连接)、Progress(定期返回检索结果)、Stats(本次查询统计信息)、End(本次查询结束)

ErrorCode Header

:error-code

特殊错误码中的错误码信息

ErrorMessage Header

:error-message

服务端返回的错误码信息,可用于定位错误

响应类型

KS3 Select 的响应类型主要分为以下几种:

响应类型

描述

Records message

检索信息,可以包含单条记录、部分记录或多条记录,取决于检索结果的多少。一个响应体中可能包含多个 Records message

Continuation message

连接信息,KS3 Select 周期性地发送这些信息以保持 TCP 连接,随机出现在响应体中。客户端最好能够自动识别这类信息并做过滤处理,以免弄脏检索结果

Progress message

进度信息,KS3 Select 周期性地返回这些信息以反馈当前查询进度

Stats message

统计信息,KS3 Select 在查询结束后返回本次查询的相关统计信息

End message

结束信息,代表本次查询已经结束,没有后续响应数据。只有在接收到该类型的信息时才能认为查询结束

RequestLevelError message

报错信息,KS3 Select 在查询出现错误时返回,包含请求的错误原因。如果返回了这一信息,则将不会再返回 End message 信息

Records message

  • 报头格式: 包括 :message-type、:event-type、:content-type 三种类型的报头。

  • 正文格式: 可能包含单条记录、部分记录或多条记录,取决于检索结果的多少。

Continuation Message

  • 报头格式: 包括 :message-type、:event-type 两种类型的报头。

  • 正文格式: 不包含正文内容。

Progress Message

  • 报头格式: 包括 :message-type、:event-type、:content-type 三种类型的报头。

  • 正文格式: 是一个包含了当前查询进度的 XML 文本,主要包含以下信息:

    • BytesScanned:如果文件是压缩文件,该数值代表文件解压前的字节大小;如果文件不是压缩文件,该数值即文件的字节大小。

    • BytesProcessed:如果文件是压缩文件,该数值代表文件解压后的字节大小;如果文件不是压缩文件,该数值即文件的字节大小。

    • BytesReturned:KS3 Select 目前返回的检索结果字节大小。

示例:

<?xml version="1.0" encoding="UTF-8"?>
<Progress>
    <BytesScanned>512</BytesScanned>
    <BytesProcessed>1024</BytesProcessed>
    <BytesReturned>1024</BytesReturned>
</Progress>

Stats Message

  • 报头格式: 包括 :message-type、:event-type、:content-type 三种类型的报头。

  • 正文格式: 是一个包含了本次查询统计的 XML 文本,主要包含以下信息:

    • BytesScanned:如果文件是压缩文件,该数值代表文件解压前的字节大小;如果文件不是压缩文件,该数值即文件的字节大小。

    • BytesProcessed:如果文件是压缩文件,该数值代表文件解压后的字节大小;如果文件不是压缩文件,该数值即文件的字节大小。

    • BytesReturned:KS3 Select 在本次查询中返回的检索结果字节大小。

示例:

<?xml version="1.0" encoding="UTF-8"?>
<Stats>
    <BytesScanned>512</BytesScanned>
    <BytesProcessed>1024</BytesProcessed>
    <BytesReturned>1024</BytesReturned>
</Stats>

End Message

  • 报头格式: 包括 :message-type、:event-type 两种类型的报头。

  • 正文格式: 不包含正文内容。

Request Level Error Message

  • 报头格式: 包括 :error-code、:error-message、:message-type 三种类型的报头。

  • 正文格式: 不包含正文内容。

示例

请求示例

以下示例对 CSV 格式对象执行查询,检索第一列大于 100 的记录:

POST /example.csv?select&select-type=2 HTTP/1.1
Host: ks3-example.ks3-cn-beijing.ksyuncs.com
Date: Wed, 01 Mar 2026 12:00:00 GMT
Authorization: authorization string
Content-Length: 350
Content-MD5: md5
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8"?>
<SelectRequest>
    <Expression>SELECT * FROM KS3Object s WHERE s._1 > 100</Expression>
    <ExpressionType>SQL</ExpressionType>
    <InputSerialization>
        <CompressionType>NONE</CompressionType>
        <CSV>
            <FileHeaderInfo>IGNORE</FileHeaderInfo>
            <RecordDelimiter>\n</RecordDelimiter>
            <FieldDelimiter>,</FieldDelimiter>
            <QuoteCharacter>"</QuoteCharacter>
            <QuoteEscapeCharacter>"</QuoteEscapeCharacter>
            <Comments>#</Comments>
        </CSV>
    </InputSerialization>
    <OutputSerialization>
        <CSV>
            <QuoteFields>ASNEEDED</QuoteFields>
            <RecordDelimiter>\n</RecordDelimiter>
            <FieldDelimiter>,</FieldDelimiter>
            <QuoteCharacter>"</QuoteCharacter>
            <QuoteEscapeCharacter>"</QuoteEscapeCharacter>
        </CSV>
    </OutputSerialization>
    <RequestProgress>
        <Enabled>FALSE</Enabled>
    </RequestProgress>
</SelectRequest>

响应示例

查询成功后返回 200 OK,响应体以流式分块 Message 形式返回:

HTTP/1.1 200 OK
x-kss-request-id: request id
Date: Wed, 01 Mar 2026 12:00:00 GMT
Content-Type: application/octet-stream
Server: KS3

<Message 1: Records message>
<Message 2: Records message>
<Message 3: Progress message>
......
<Message n: End message>

客户端需按分块 Message 协议逐块解析:读取预响应获取长度 → 读取报头判断类型 → 读取响应正文获取数据 → 校验 CRC → 继续读取下一个 Message,直到收到 End message(查询结束)或 RequestLevelError message(查询报错)。

错误码

错误码

错误信息

含义

HTTP 状态码

InvalidXML

The XML is invalid

XML 格式不合法

400 Bad Request

MissingRequiredParameter

The SelectRequest entity is missing a required parameter

检索请求缺少必填参数项

400 Bad Request

MissingExpectedExpression

The SQL expression is missing

缺少 SQL 表达式

400 Bad Request

MissingInputSerialization

The input serialization is missing

未指定输入 CSV 对象的数据序列化格式

400 Bad Request

InvalidCompressionFormat

The file is not in a supported compression format. Only GZIP and BZIP2 are supported

不合法的文件压缩格式,仅支持 GZIP 和 BZIP2 两种格式

400 Bad Request

MissingInputFormat

The input format is missing

缺少输入格式

400 Bad Request

InvalidFileHeaderInfo

The input FileHeaderInfo is invalid. Only NONE, USE, and IGNORE are supported

输入的文件表头信息不合法。仅支持 NONE、USE 和 IGNORE

400 Bad Request

InvalidRequestParameter

The input RecordDelimiter of CSV is invalid

输入的 CSV 文件换行符不合法

400 Bad Request

InvalidRequestParameter

The input FieldDelimiter of CSV is invalid

输入的 CSV 文件列分隔符不合法

400 Bad Request

InvalidRequestParameter

The input QuoteCharacter of CSV is invalid

输入的 CSV 文件引用符不合法

400 Bad Request

InvalidRequestParameter

The input AllowQuoteRecordDelimiter of csv is invalid. Only TRUE and FALSE are supported

在输入 CSV 文件中启用转义符的配置不合法,仅支持 TRUE 和 FALSE

400 Bad Request

InvalidJsonType

The JsonType is invalid. Only DOCUMENT and LINES are supported

不合法的 JSON 类型,仅支持 DOCUMENT 和 LINES

400 Bad Request

MissingOutputSerialization

The output serialization is missing.

未指定输出 CSV 对象的数据序列格式

400 Bad Request

MissingOutputFormat

The output format is missing

缺少输出格式

400 Bad Request

InvalidQuoteFields

The QuoteFields is invalid. Only ALWAYS and ASNEEDED are supported

不合法的转义规则,仅支持 ALWAYS 和 ASNEEDED

400 Bad Request

InvalidRequestParameter

The output RecordDelimiter of CSV is invalid

输出的 CSV 文件换行符不合法

400 Bad Request

InvalidRequestParameter

The output FieldDelimiter of CSV is invalid

输出的 CSV 文件列分隔符不合法

400 Bad Request

InvalidRequestParameter

The output QuoteCharacter of CSV is invalid

输出的 CSV 文件转义符不合法

400 Bad Request

InvalidRequestParameter

The output QuoteEscapeCharacter of CSV is invalid

输出的 CSV 的双引号转义符不合法

400 Bad Request

InvalidRequestParameter

The output RecordDelimiter of JSON is invalid

输出的 JSON 文件换行符不合法

400 Bad Request

SQLParsingError

Encountered an error parsing the SQL expression

解析 SQL 表达式出现问题

400 Bad Request

SQLParsingError

Other expressions are not allowed in the SELECT list when '*' is used without dot notation.

SELECT list 不允许在未使用点符的时候使用 '*'

400 Bad Request

SQLParsingError

The SQL expression contains an empty SELECT

SQL 表达式中包含了空的 SELECT 子句

400 Bad Request

SQLParsingError

GROUP is not supported in the SQL expression

SQL 表达式中不支持 GROUP 子句

400 Bad Request

SQLParsingError

UNION is not supported in the SQL expression

SQL 表达式中不支持 UNION 子句

400 Bad Request

SQLParsingError

FROM is missing in the SQL expression

SQL 表达式中缺少 FROM 子句

400 Bad Request

SQLParsingError

ORDER is not supported in the SQL expression

SQL 表达式中不支持 ORDER 子句

400 Bad Request

SQLParsingError

The column index is invalid in the SQL expression

SQL 表达式中指定的列索引不合法

400 Bad Request

SQLParsingError

The table alias is invalid in WHERE

WHERE 子句中的表别名不合法

400 Bad Request

Bzip2DecompressError

Encountered an error decompressing the bzip2 file

解压 BZIP2 格式的文件时出现问题

400 Bad Request

Bzip2DecompressError

BZIP2 is not applicable to the queried object

BZIP2 格式不适用于解压待查询对象

400 Bad Request

GzipDecompressError

Encountered an error decompressing the gzip file

解压 GZIP 格式的文件时出现问题

400 Bad Request

GzipDecompressError

GZIP is not applicable to the queried object

GZIP 格式不适用于解压待查询对象

400 Bad Request

Busy

The service is busy. Please retry later

后端服务阻塞,请稍后重试

400 Bad Request

Overload

The service is overload. Please retry later

后端服务过载,请稍后重试

400 Bad Request

AmbiguousFieldName

Field name matches to multiple fields in the file

指定的表头名称存在多个相同的值

400 Bad Request

ComparisonFailed

Attempt to compare failed

匹配失败,请重试

400 Bad Request

CastFailed

Attempt to convert from one data type to another using CAST failed in the SQL expression.

在 SQL 表达式中通过 CAST 函数转换数据类型时出现错误

400 Bad Request

OverMaxRecordSize

The length of a record in the input or result is greater than maxCharsPerRecord of 1 MB

输入或输出的文件中,单行记录大小超过 1MB 限制

400 Bad Request

LastRecordParseFail

Please check the last record in the input

请检查输入文件的最后一行记录

400 Bad Request

CSVParsingError

Encountered an error parsing the CSV file

解析 CSV 格式文件的时候出现问题

400 Bad Request

JSONParsingError

Encountered an error parsing the JSON file

解析 JSON 格式文件的时候出现问题

400 Bad Request

ErrorWritingRow

Encountered an error parsing the SELECT result. Please try again

无法格式化查询结果,请检查文件并重试

400 Bad Request

InvalidRequestParameter

The input Comment of CSV is invalid

不合法的 CSV 文件注释符

400 Bad Request

InvalidTextEncoding

UTF-8 encoding is required. Please check the file and try again.

检索文件和检索结果仅支持 UTF-8 编码

400 Bad Request

NoSuchKey

The specified key does not exist

指定的对象键不存在

404 Not Found

AccessDenied

Access Denied

签名或者权限不正确,拒绝访问

403 Forbidden

MethodNotAllowed

The specified method is not allowed against this resource

当前资源不支持该 HTTP 方法

405 Method Not Allowed

InternalError

We encountered an internal error. Please try again

服务端内部错误

500 Internal Server

文档导读
纯净模式常规模式

纯净模式

点击可全屏预览文档内容
文档反馈