最近更新时间: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 表达式,代表需要发起的检索操作。例如 | String | 是 |
ExpressionType | SelectRequest | 表达式类型,目前只支持 SQL 表达式,仅支持 SQL 参数 | String | 是 |
InputSerialization | SelectRequest | 描述待检索对象的格式 | Container | 是 |
OutputSerialization | SelectRequest | 描述检索结果的输出格式 | Container | 是 |
RequestProgress | SelectRequest | 是否需要返回查询进度 QueryProgress 信息,如果选中 KS3 Select 将周期性返回查询进度 | Container | 否 |
名称 | 父节点 | 描述 | 类型 | 是否必选 |
CompressionType | InputSerialization | 描述待检索对象的压缩格式。仅支持 NONE(未压缩),不支持 GZIP、BZIP2 压缩格式。默认值为 NONE | String | 否 |
CSV/JSON | InputSerialization | 描述在相应的对象格式下所需的文件参数。例如 CSV 格式需要指定分隔符 | Container | 是 |
名称 | 父节点 | 描述 | 类型 | 是否必选 |
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 | 否 |
名称 | 父节点 | 描述 | 类型 | 是否必选 |
Type | JSON | JSON 文件的类型:DOCUMENT 表示 JSON 文件仅包含一个独立的 JSON 对象,且该对象可以被切割成多行;LINES 表示 JSON 对象中的每一行包含一个独立的 JSON 对象。合法值为 DOCUMENT、LINES | Enum | 是 |
名称 | 父节点 | 描述 | 类型 | 是否必选 |
CSV/JSON | OutputSerialization | 指定检索结果的输出格式,可选项为 CSV 或 JSON | Container | 是 |
名称 | 父节点 | 描述 | 类型 | 是否必选 |
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 | 否 |
名称 | 父节点 | 描述 | 类型 | 是否必选 |
RecordDelimiter | JSON | 将输出结果中的记录分隔为不同行的字符,默认通过 \n 分隔。可指定任意 8 进制字符,最多支持 2 个字节。默认值为 \n | String | 否 |
名称 | 父节点 | 描述 | 类型 | 是否必选 |
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 信息 |
报头格式: 包括 :message-type、:event-type、:content-type 三种类型的报头。
正文格式: 可能包含单条记录、部分记录或多条记录,取决于检索结果的多少。
报头格式: 包括 :message-type、:event-type 两种类型的报头。
正文格式: 不包含正文内容。
报头格式: 包括 :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>报头格式: 包括 :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>报头格式: 包括 :message-type、:event-type 两种类型的报头。
正文格式: 不包含正文内容。
报头格式: 包括 :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 |
纯净模式
