SelectObject
所有文档

          对象存储 BOS

          SelectObject

          接口描述

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

          请求(Request)

          • 请求语法

            POST /<ObjectKey>?select&type=json/csv 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
                    },
                    "outputSerialization": {
                        // JSON or CSV
                    },
                    "requestProgress": {
                        "enabled": false/true
                    }
                }
            } 
          • 请求参数

            名词 类型 描述 是否必须
            type string select的目标object类型,目前支持json/csv
          • 请求主体

            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连接
          • 请求头域

            无特殊头域

          响应(Response)

          • 响应头域

            名称 类型 描述
            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具体格式详细说明:

            select-msg.png

            1. prelude部分一共8个byte,前4byte表示message总长度,后4byte表示headers部分总长度,chunk总长度(prelude前4byte存储的值) - header总长度 - 8byte的prelude - 4byte的crc32 = payload部分数据总长度;crc32表示整个message的纠删码
            2. headers包含以下自定义<key,value>:“message-type”: {"Records", "Cont", "End"} ; "error-code": 具体错误码 ; "error-message": "详细错误信息"
            3. 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>  
          上一篇
          权限控制
          下一篇
          软链接