腾讯云对象存储SELECT Object Content

概述

COS Select 接口可以使用结构化查询语句（Structured Query Language，SQL）从指定对象（CSV、JSON 或者 Parquet 格式）中检索内容。在检索过程中，您需要指定对象内容的分隔符，并使用合适的 SQL 函数进行检索，COS Select 将返回相匹配的检索结果，您可以指定检索结果的保存格式。如您需要了解 COS Select 的更多介绍，请参见 COS Select 概述。有关 COS Select 的 SQL 表达式的介绍，您可以在开发者指南中参见 Select 命令 进一步了解。

权限限制

使用 COS Select，您必须具有cos:GetObject的授权。如果您是主账号，则默认拥有该权限。如果您是子账号，请联系您的主账号获取该操作的权限。有关权限设置，请参见 授权子账号访问 COS 文档。

对象数据格式

COS Select 支持检索以下格式的对象数据：CSV 格式：对象以 CSV 格式存储，并以固定的分隔符划分。JSON 格式：对象以 JSON 格式存储，可以是 JSON 文件或者 JSON 列表。Parquet 格式：对象以 Parquet 格式存储，可以包含嵌套结构。注意COS Select 的对象必须以 UTF-8 格式编码。COS Select 支持检索 GZIP 或者 BZIP2 压缩的 CSV、JSON 对象；支持检索经过 GZIP 或 Snappy 列压缩的 Parquet 对象。COS Select 支持检索 SSE-COS 加密的对象。

请求

请求示例

POST /<ObjectKey>?select&select-type=2 HTTP/1.1Host: <BucketName-APPID>.cos.<Region>.myqcloud.comDate: dateAuthorization: Auth String
Request body

说明Host: .cos..myqcloud.com，其中 为带 APPID 后缀的存储桶名字，例如 examplebucket-1250000000，可参阅 存储桶概览 > 基本信息 和 存储桶概述 > 存储桶命名规范 文档； 为 COS 的可用地域，可参阅 地域和访问域名 文档。Authorization: Auth String （详情请参见 请求签名 文档）。请求参数中 select 和 select-type=2 参数均为必填参数，其中 select 代表发起 select 请求，select-type=2 代表这一接口的版本信息。

请求头

此接口仅使用公共请求头部，详情请参见 公共请求头部 文档。

请求体

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

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

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

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

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

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

说明InputSerialization 元素描述了待检索的对象格式，为必填参数，该参数可以指定为 CSV 、JSON 或 Parquet 格式。OutputSerialization 元素描述了检索结果的保存格式，该参数可以仅可指定为 CSV 或者 JSON 格式。待检索的对象格式无需和检索结果的保存格式互相匹配，您可以检索一个 JSON 格式的对象，并将检索结果保存为 CSV 格式。下表展示了请求体中的各项元素组成：

InputSerialization container element

CSV container element (InputSerialization 子元素)

JSON container element (InputSerialization 子元素)

OutputSerialization container element

CSV container element (OutputSerialization 子元素)

JSON container element (OutputSerialization 子元素)

RequestProgress container element

响应

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

响应头

此接口仅返回公共响应头部，详情请参见 公共响应头部 文档。

响应体

由于响应体的大小无法预知，COS 将用户请求响应体以序列化形式展示，即将响应体切分成多个分块返回，如下展示了返回响应体的概览：

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

预响应（prelude）和响应结果（data）

COS 将检索结果切成多个分块，每个分块即一个 Message。每一个 Message 由预响应（prelude）和响应结果（data）组成。预响应包含两个部分：所在分块 Message 的总长度。所有头部的总长度。响应结果包含两个部分：响应报头（header）。响应正文（payload）。预响应和响应结果均以4字节的经过大端编码（big-endian）的 CRC 校验码结尾。COS Select 使用 CRC32计算 CRC 校验码，有关 CRC32的详细信息，请参见 RFC 文档。除了响应结果之外，COS Select 总共额外花费了16字节用于传输预响应和校验码信息。注意所有分块 Message 中的整数值均以网络字节序，即大端编码，传输。下图展示了分块 Message 以及检索结果中的响应报头 header 是如何构成的。每一个分块 Message 中可能包含多个 header 。

如上图所示，每一个分块 Message 均由预响应 prelude，预响应校验码 prelude CRC（由两个记录字节数的信息组成），报头信息 header ，响应正文 Payload 和正文校验码 Message CRC 构成。从上图可以看到，整个响应体的长度计算方式如下：

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

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

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

以下详细介绍响应体各部分组成：

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

COS Select 的响应类型主要可以分为以下几种：

下面将进一步介绍这些响应类型的详情。

Records message

报头格式
Records message 包括”:message-type”， “:event-type”， “:content-type”3种类型的报头。如下所示：

正文格式
Records message 正文可能包含单条记录，部分记录或者多条记录，取决于检索结果的多少。

Continuation Message

报头格式
Continuation Message 包括”:message-type”， “:event-type”2种类型的报头，如下所示：

正文格式
Continuation Message 中不包含正文内容。

Progress Message

报头格式
Progress Message 包括”:message-type”， “:event-type”， “:content-type”3种类型的报头，如下所示：

正文格式
Progress Message 的正文是一个包含了当前查询进度的 XML 文本，主要包含以下信息：BytesScanned：如果文件是压缩文件，该数值代表文件解压前的字节大小。如果文件不是压缩文件，该数值即文件的字节大小。BytesProcessed：如果文件是压缩文件，该数值代表文件解压后的字节大小。如果文件不是压缩文件，该数值即文件的字节大小。BytesReturned：COS Select 目前返回的检索结果字节大小。示例如下：

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

Stats Message

报头格式
Stats Message 包括”:message-type”， “:event-type”， “:content-type”3种类型的报头，如下所示：

正文格式
Stats message 的正文是一个包含了本次查询统计的 XML 文本，主要包含以下信息：BytesScanned：如果文件是压缩文件，该数值代表文件解压前的字节大小；如果文件不是压缩文件，该数值即文件的字节大小。BytesProcessed：如果文件是压缩文件，该数值代表文件解压后的字节大小；如果文件不是压缩文件，该数值即文件的字节大小。BytesReturned：COS Select 在本次查询中返回的检索结果字节大小。示例如下：

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

End Message

报头格式
End messages 包括”:message-type”，”:event-type”2种类型的报头，如下所示：

正文格式
End messages 中不包含正文内容。

Request Level Error Message

报头格式
Request Level Error Message 包括“:error-code”，“:error-message”，“:message-type”3种类型的报头，如下所示：

如果您需要了解 Request Level Error Message 中记录的错误码详情，可以查看 特殊错误码。正文格式
Request Level Error Message 信息中不包含正文内容。

特殊错误码

该请求常见的错误信息请参见 错误码 文档，特殊错误码信息如下所示：

示例

示例 1: 从 CSV 格式的对象中检索内容

以下示例展示了调用该接口从 CSV 格式的对象中检索全部内容，并将检索结果输出为 CSV 格式的过程。待检索的对象名为exampleobject.csv，该对象存储于北京地域（ap-beijing）的存储桶 examplebucket-1250000000 中。

POST /exampleobject.csv?select&select-type=2 HTTP/1.1Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.comDate: Tue, 12 Jan 2019 11:49:52 GMTAuthorization: authorization stringContent-Length: content length
<?xml version="1.0" encoding="UTF-8"?><SelectRequest>    <Expression>Select * from COSObject</Expression>    <ExpressionType>SQL</ExpressionType>    <InputSerialization>        <CompressionType>None</CompressionType>        <CSV>            <FileHeaderInfo>IGNORE</FileHeaderInfo>            <RecordDelimiter>\n</RecordDelimiter>            <FieldDelimiter>,</FieldDelimiter>            <QuoteCharacter>"            "</QuoteEscapeCharacter>            <Comments>#        </CSV>    </InputSerialization>    <OutputSerialization>        <CSV>            <QuoteFields>ASNEEDED</QuoteFields>            <RecordDelimiter>\n</RecordDelimiter>            <FieldDelimiter>,</FieldDelimiter>            <QuoteCharacter>"            "</QuoteEscapeCharacter>        </CSV>                                   </OutputSerialization></SelectRequest> 

如果您需要执行不同的检索指令，可以在 Expression 元素中修改 SQL 指令，有关指令的详细介绍，请参见 Select 命令，以下为部分常见检索场景的简介。假设您使用列索引筛选对象中的内容，您可以使用s._n筛选第n列的数据，n最小为1。如下指令将从对象中筛选第3列数值大于100的记录，并返回这些记录的第1和第2列：

SELECT s._1, s._2 FROM COSObject s WHERE s._3 > 100

如果您的 CSV 对象中具有列表头，且您打算使用列表头的名称筛选对象中的内容（将FileHeaderInfo设置为Use），您可以使用s.name进行索引，如下指令将从对象中筛选表头名为Id和FirstName的对象：

SELECT s.Id, s.FirstName FROM COSObject s

您也可以在 SQL 表达式中指定函数，如下指令将统计出第一列中小于1的记录数：

SELECT count(*) FROM COSObject s WHERE s._1 < 1

如下为响应的例子：

HTTP/1.1 200 OKx-cos-id-2: cos_id_demox-cos-request-id: cos_request_id_demoDate: Tue, 12 Jan 2019 11:50:29 GMT
A series of messages

示例2: 从 JSON 格式的对象中检索内容

以下示例展示了调用该接口从 JSON 格式的对象中检索全部内容，并将检索结果输出为 CSV 格式的过程。待检索的对象名为exampleobject.json，该对象存储于北京地域（ap-beijing）的存储桶 examplebucket-1250000000 中。

POST /exampleobject.json?select&select-type=2 HTTP/1.1Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.comDate: Tue, 12 Jan 2019 11:52:29 GMTAuthorization: authorization stringContent-Length: content length
<?xml version="1.0" encoding="UTF-8"?><SelectRequest>    <Expression>Select * from COSObject</Expression>    <ExpressionType>SQL</ExpressionType>    <InputSerialization>        <CompressionType>NONE</CompressionType>        <JSON>            <Type>DOCUMENT</Type>        </JSON>    </InputSerialization>    <OutputSerialization>        <CSV>            <QuoteFields>ASNEEDED</QuoteFields>            <RecordDelimiter>\n</RecordDelimiter>            <FieldDelimiter>,</FieldDelimiter>            <QuoteCharacter>"            "</QuoteEscapeCharacter>        </CSV>                                   </OutputSerialization></SelectRequest> 

同样的，您也可以对 JSON 对象执行不同的检索指令，可以在 Expression元素中修改 SQL 指令，有关指令的详细介绍，请参见 Select 命令，以下为部分常见检索场景的简介。您可以通过 JSON 属性名称检索相应的数据，如下指令将从对象中筛选city数值为 Seattle 的记录，并返回这些记录的country和city信息：

SELECT s.country, s.city from COSObject s where s.city = 'Seattle'

您也可以在 SQL 表达式中指定函数，如下指令将统计出 JSON 对象中的记录总数：

SELECT count(*) FROM COSObject s

注意事项

与 GET Object 接口不同， SELECT Object Content 不支持以下功能：返回对象的某一片段：您不能通过 Range 这类参数指定返回对象的某一部分。对于归档存储（ARCHIVE）和深度归档存储（DEEP_ARCHIVE）类型的对象，COS Select 无法直接进行检索，您需要取回数据后再进行操作。
对象存储官网1折活动，限时活动，即将结束，速速收藏
同尘科技为腾讯云授权服务中心。
购买腾讯云产品享受折上折，更有现金返利。同意关联立享优惠