SelectObject

更新时间：2023-06-26

接口描述

此接口用于向Bucket中指定object执行SQL语句，选取出指定内容返回。请求者必须对选取的object具有read权限。在SelectObject前需要确保对应的Bucket和Object已经存在，详细信息参考 SelectObject 开发者文档。

请求（Request）

请求语法

POST /<ObjectKey>?select&type=json/csv/parquet HTTP/1.1
Host: <BucketName>.bj.bcebos.com
Date: <Date>
Authorization: <Authorization_String>
Content-Type: application/json; charset=utf-8
Content-Length: <Content_Length>
{
    "selectRequest": {
        "expression": "Base64Encode(Select * from BosObject)",
        "expressionType": "SQL",
        "inputSerialization": {
            "compressionType": "GZIP/NONE",
            // JSON or CSV or Parquet
        },
        "outputSerialization": {
            // JSON or CSV or Parquet
        },
        "requestProgress": {
            "enabled": false/true
        }
    }
}

请求参数

名词类型描述是否必须

type string select的目标object类型，目前支持json/csv/parquet 是

名词	类型	描述	是否必须
type	string	select的目标object类型，目前支持json/csv/parquet	是

请求主体

JSON文件

名称	是否必须	类型	描述
selectRequest	是	-	json body根节点
+ expression	是	string	经过base64编码的sql语句
+ expressionType	是	string	查询语句语法类型，只支持"SQL"
+ inputSerialization	是	-	输入流节点，其子节点描述查询的object格式信息
++compressionType	否	string	指定查询的object是否压缩，可选值为"NONE"或"GZIP"
++ json	是	-	json节点，其子节点描述json文件相关信息
+++ type	是	string	json type，查询的json object格式，可选值为"DOCUMENT"或"LINES"
+ outputSerialization	是	-	输出流节点，其子节点描述查询结果返回格式信息
++ json	是		json节点，其子节点描述返回的json数据相关信息
+++ recordDelimiter	否	string	指定换行符，以Base64编码。默认值为\n（可选）
+ requestProgress	否	-	select进度信息节点，其子节点描述select操作的执行进度，3s定时返回给用户
++ enabled	否	boolean	描述是否需要定时返回进度信息，可选值为false/true；如果数据筛选耗时久可能导致504超时，设置其为true可以维持http连接

CSV文件

名称	是否必须	类型	描述
selectRequest	是	-	json body根节点
+ expression	是	string	经过base64编码的sql语句
+ expressionType	是	string	查询语句语法类型，只支持"SQL"
+ inputSerialization	是	-	输入流节点，其子节点描述查询的object格式信息
++ compressionType	否	string	指定查询的object是否压缩，可选值为"NONE"或"GZIP"
++ csv	是	-	csv节点，其子节点描述csv文件相关信息
+++ fileHeaderInfo	否	string	可选值NONE/IGNORE/USE，指定CSV文件首行头信息，默认值NONE代表无header信息，IGNORE代表有header信息但是忽略，NONE和IGNORE意味着只能用列序号取出某一列；USE表示使用header信息，只能用header名取出某一列
+++ recordDelimiter	否	string	指定csv文件换行符，以Base64编码，默认值为\n（可选），最多为2个字符，例如\r\n
+++ fieldDelimiter	否	string	指定csv文件列分隔符，以Base64编码，默认值为,（可选），最多为1个字符，例如;
+++ quoteCharacter	否	string	指定csv文件引号字符，以Base64编码，在CSV中引号内的换行符，列分隔符将被视作普通字符；默认值为双引号"（可选），最多为1个字符，例如单引号'
+++ commentCharacter	否	string	指定csv文件注释符，以Base64编码，一行以注释符开头则表示该行可以忽略；默认值为#（可选），最多为2个字符，例如//
+ outputSerialization	是	-	输出流节点，其子节点描述查询结果返回格式信息
++ outputHeader	否	boolean	在返回结果开头输出CSV头信息，默认false; 需要fileHeaderInfo字段取值USE，该值为true会在返回结果的每一个Records message第一行加上对应的csv header名称；可选值为false/true
++ csv	是	-	csv节点，其子节点描述返回的csv数据相关信息
+++ quoteFields	否	string	可选值ALWAYS/ASNEEDED，指定返回的csv数据每个字段是否使用""包围; ASNEEDED表示返回文件中原始数据，ALWAYS表示总是用""包围field; 默认是ASNEEDED
+++ recordDelimiter	否	string	指定返回的csv数据的换行符，以Base64编码。默认值为\n（可选），最多为2个字符，例如\r\n
+++ fieldDelimiter	否	string	指定返回的csv数据的列分隔符，以Base64编码。默认值为,（可选），最多为1个字符，例如;
+++ quoteCharacter	否	string	指定返回的csv数据的引号字符，以Base64编码，在CSV中引号内的换行符，列分隔符将被视作普通字符；默认值为双引号"（可选），最多为1个字符，例如单引号'
+ requestProgress	否	-	select进度信息节点，其子节点描述select操作的执行进度，3s定时返回给用户
++ enabled	否	boolean	描述是否需要定时返回进度信息，可选值为false/true；如果数据筛选耗时久可能导致504超时，设置其为true可以维持http连接

Parquet文件

名称	是否必须	类型	描述
selectRequest	是	-	json body根节点
+ expression	是	string	经过base64编码的sql语句
+ expressionType	是	string	查询语句语法类型，只支持"SQL"
+ inputSerialization	是	-	输入流节点，其子节点描述查询的object格式信息
++ compressionType	否	string	指定查询的object是否压缩，可选值为"NONE"
++ parquet	是	-	parquet节点，其子节点描述parquet文件相关信息，为空
+ outputSerialization	是	-	输出流节点，其子节点描述查询结果返回格式信息
++ json	是		json节点，其子节点描述返回的json数据相关信息
+++ recordDelimiter	否	string	指定换行符，以Base64编码。默认值为\n（可选）
+ requestProgress	否	-	select进度信息节点，其子节点描述select操作的执行进度，3s定时返回给用户
++ enabled	否	boolean	描述是否需要定时返回进度信息，可选值为false/true；如果数据筛选耗时久可能导致504超时，设置其为true可以维持http连接

请求头域

无特殊头域

响应（Response）

响应头域

名称类型描述

Transfer-Encoding String 值为chunked，表示返回内容以http1.1 chunked编码方式分块返回
响应参数

无

名称	类型	描述
Transfer-Encoding	String	值为chunked，表示返回内容以http1.1 chunked编码方式分块返回

响应主体

SelectObject接口响应以chunk形式返回，包括Records message，Continuation message，End message三种类型：

message	格式	描述
Records message	prelude(8 byte) + n * (header_key_len(1 byte) + header_key + header_val_len(2 byte) + header_val) + payload + crc32(4 byte)	包含Select请求返回的数据，可以是一行，也可以是多行记录
Continuation message	同上，固定格式，只是payload内容不一样	每3秒定时给client返回当前select进展(扫描字节数/返回字节数)以及维持http连接
End message	同上，固定格式，payload内容为空	标志着该次select请求的结束，headers字段包括error-code，error-message，message-type，bytes-scanned等信息

message具体格式详细说明：

prelude部分一共8个byte，前4byte表示message总长度，后4byte表示headers部分总长度，chunk总长度(prelude前4byte存储的值) - header总长度 - 8byte的prelude - 4byte的crc32 = payload部分数据总长度；crc32表示整个message的纠删码

headers包含以下自定义<key,value>：“message-type”: {"Records", "Cont", "End"} ; "error-code": 具体错误码 ; "error-message": "详细错误信息"

Payload表示返回的真实数据，可以是任意格式；其中Continuation message的Payload里边包括BytesScanned和BytesReturned两个字段表示的select进度信息

示例

CSV文件请求示例

POST /object?select&type=csv HTTP/1.1
Host: bucket.bj.bcebos.com
Date: Thu, 15 May 2017 00:17:23 GMT
Authorization: <Authorization_String>
Content-Type: application/json; charset=utf-8
Content-Length: 512
{
    "selectRequest": {
        "expression": "c2VsZWN0IGNvdW50KCopIGZyb20gbxkl2JqZWN0IHdoZXJlIF80ID4gNDU=",
        "expressionType": "SQL",
        "inputSerialization": {
            "compressionType": "NONE",
            "csv": {
                "fileHeaderInfo": "NONE",
                "recordDelimiter": "Cg==",
                "fieldDelimiter": "LA==",
                "quoteCharacter": "Ig==",
                "commentCharacter": "Iw=="
            }
        },
        "outputSerialization": {
            "outputHeader": FALSE,
            "csv": {
                "quoteFields": "ALWAYS",
                "recordDelimiter": "Cg==",
                "fieldDelimiter": "LA==",
                "quoteCharacter": "Ig=="
            }
        },
        "requestProgress": {
            "enabled": false
        }
    }
}

CSV文件响应示例

HTTP/1.1 200 OK
x-bce-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409
Date: Wed, 06 Apr 2016 06:34:40 GMT
ETag: "1b2cf535f27731c974343645a3985328"
Transfer-Encoding: chunked
Connection: close
Server: BceBos
----- Body ------
<Records message>
……
<Continuation Message>
……
<Records message>
<Continuation Message>
<End message>

JSON文件请求示例

POST /object?select&type=json HTTP/1.1
Host: bucket.bj.bcebos.com
Date: Thu, 15 May 2017 00:17:23 GMT
Authorization: <Authorization_String>
Content-Type: application/json; charset=utf-8
Content-Length: 512
{
    "selectRequest": {
        "expression": "c2VsZWN0IGNvdW50KCopIGZyb20gbxkl2JqZWN0IHdoZXJlIF80ID4gNDU=",
        "expressionType": "SQL",
        "inputSerialization": {
            "compressionType": "NONE",
            "json": {
                "type": "DOCUMENT"
            }
        },
        "outputSerialization": {
            "json": {
                "recordDelimiter": "Cg=="
            }
        },
        "requestProgress": {
            "enabled": false
        }
    }
}

JSON文件响应示例

HTTP/1.1 200 OK
x-bce-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409
Date: Wed, 06 Apr 2016 06:34:40 GMT
ETag: "1b2cf535f27731c974343645a3985328"
Transfer-Encoding: chunked
Connection: close
Server: BceBos
----- Body ------
<Records message>
……
<Continuation Message>
……
<Records message>
<Continuation Message>
<End message>

Parquet文件请求示例

POST /object?select&type=parquet HTTP/1.1
Host: bucket.bj.bcebos.com
Date: Thu, 15 May 2017 00:17:23 GMT
Authorization: <Authorization_String>
Content-Type: application/json; charset=utf-8
Content-Length: 512
{
    "selectRequest": {
        "expression": "c2VsZWN0IGNvdW50KCopIGZyb20gbxkl2JqZWN0IHdoZXJlIF80ID4gNDU=",
        "expressionType": "SQL",
        "inputSerialization": {
            "compressionType": "NONE",
            "parquet": {}
        },
        "outputSerialization": {
            "json": {
                "recordDelimiter": "Cg=="
            }
        },
        "requestProgress": {
            "enabled": false
        }
    }
}

Parquet文件响应示例

HTTP/1.1 200 OK
x-bce-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409
Date: Wed, 06 Apr 2016 06:34:40 GMT
ETag: "1b2cf535f27731c974343645a3985328"
Transfer-Encoding: chunked
Connection: close
Server: BceBos
----- Body ------
<Records message>
……
<Continuation Message>
……
<Records message>
<Continuation Message>
<End message>

权限控制

软链接

百度智能云

对象存储 BOS