对象存储 OSS：SelectObject

注意事项

• 此操作要求您对该Object有读权限。
• 正确执行SQL语句时，返回206。如果SQL语句不正确，或者和文件不匹配，则返回400错误。

• 调用SelectObject接口查询数据时，按扫描的原文件实际大小计费。更多信息，请参见数据处理费用。

请求语法

请求元素

返回Body

• 当请求响应中HTTP Status是4xx，表明该请求没有通过相应的SQL语法检查或者目标文件有问题，返回错误信息的Body与Get API返回的错误信息一致。
• 当请求响应中HTTP Status是5xx，表明服务器内部错误，返回的错误信息的格式和Get API返回的错误信息一致。
• 当请求成功返回206时：
  • 若header x-oss-select-output-raw值为true，则表明返回结果是对象数据（而不是Frame包装的），客户端可以完全按照Get API的方式获取数据。
  • 若x-oss-select-output-raw的值为false，请求结果以Frame形式返回。
• Frame的格式为Version|Frame-Type | Payload Length | Header Checksum | Payload | Payload Checksum<1 byte><--3 bytes--><---4 bytes----><-------4 bytes--><variable><----4bytes---------->。
  说明 Checksum均为CRC32。Frame里所有的整数均以大端编码（big endian），且Version目前为1。

Frame Type

样例请求

SQL语句正则表达式

select_list: column name
            | column index (例如_1, _2. 仅Csv文件有column index)
            | json path (例如s.contacts.firstname 仅应用在JSON文件)
            | function(column index | column name)
            | function(json_path) (仅应用在JSON文件)
            | select_list AS alias

table: OSSOBJECT

      | OSSOBJECT json_path（仅应用于JSON文件）

对于CSV文件，table必须为OSSOBJECT。对于JSON文件（包括DOCUMENT或者LINES），table可以在OSSOBJECT后指定json_path。

json_path: ['string '] （string若没有空格或者*，则引号可以去掉；等价于.'string '）

          | [n] （应用在数组元素中，表示第n个元素，从0开始）

          | [*] （应用在数组或者对象中，表示任意子元素）

          | .'string ' （string若没有空格或者*，则引号可以去掉）

          | json_path jsonpath （json_path可以连接，例如 [n].property1.attributes[*]）

Where_opt:
| WHERE expr
expr:
| literal value
| column name
| column index
| json path (仅应用于JSON文件)
| expr op expr
| expr OR expr
| expr AND expr
| expr IS NULL
| expr IS NOT NULL
| (column name | column index | json path) IN (value1, value2,….)
| (column name | column index | json path) NOT in (value1, value2,…)
| (column name | column index | json path) between value1 and value2
| NOT (expr)
| expr op expr
| (expr)
| cast (column index |column name | json path | literal as INT|DOUBLE|)

• op：包括>、< 、>=、<=、!=、 =、，、LIKE、+、-、*、/、%以及字符串连接||。
• cast：对于同一个column，只能cast成一种类型。
• 聚合和Limit的混用：Select avg(cast(_1 as int)) from ossobject limit 100，其含义是指在前100行中计算第一列的AVG值。与MySQL不同的是在SelectObject中聚合永远只返回一行数据，因而对聚合来说无需限制其输出规模。SelectObject中limit将先于聚合函数执行。

SQL语句限制

数据的容错处理

CreateSelectObjectMeta

CreateSelectObjectMeta API用于获取目标文件总的行数，总的列数（对于CSV文件），以及Split个数（每一个Object分成多个数据块，每个数据块对应一个Split，每个Split由连续的行组成）。如果该信息不存在，则会扫描整个文件，分析并记录下CSV文件的上述信息。重复调用该API则会保存上述信息而不必重新扫描整个文件。

• 请求语法
  • 请求语法（CSV）

    POST  /samplecsv?x-oss-process=csv/meta
    <CsvMetaRequest>
        <InputSerialization>
            <CompressionType>None</CompressionType>
            <CSV>
                <RecordDelimiter>base64 encode的字符</RecordDelimiter>
                <FieldDelimiter>base64 encode的字符</FieldDelimiter>
                <QuoteCharacter>base64 encode的字符</QuoteCharacter>
            </CSV>
        </InputSerialization>
        <OverwriteIfExists>false|true</OverwriteIfExists>
    </CsvMetaRequest>

  • 请求语法（JSON）

    POST  /samplecsv?x-oss-process=json/meta
    <JsonMetaRequest>
        <InputSerialization>
            <CompressionType>None</CompressionType>
            <JSON>
                <Type>LINES</Type>
            </JSON>
        </InputSerialization>
        <OverwriteIfExists>false|true</OverwriteIfExists>
    </JsonMetaRequest>

• 请求元素

  名称	类型	描述
  CsvMetaRequest	容器	保存创建Select csv Meta请求的容器。 子节点：InputSerialization 父节点：None
  JsonMetaRequest	容器	保存创建 Select json meta请求的容器。 子节点：InputSerialization 父节点：None
  InputSerialization	容器	输入序列化参数（可选） 子节点：CompressionType、 CSV、JSON 父节点：CsvMetaRequest、JsonMetaRequest
  OverwriteIfExists	bool	重新计算SelectMeta，覆盖已有数据。（可选，默认是false，即如果Select Meta已存在则直接返回） 子节点：None 父节点：CsvMetaRequest、JsonMetaRequest
  CompressionType	枚举	指定文件压缩类型（可选）。目前不支持任何压缩，故只能为None。 子节点： None 父节点：InputSerialization
  RecordDelimiter	字符串	指定CSV换行符，以Base64编码。默认值为’\n’（可选）。未编码前的值最多为两个字符，以字符的ANSI值表示，例如在Java里用\n表示换行。 子节点：None 父节点：CSV
  FieldDelimiter	字符串	指定CSV列分隔符，以Base64编码。默认值为，（可选） 未编码前的值必须为一个字符，以字符的ANSI值表示，例如Java里用，表示逗号。 子节点：None 父节点：CSV （输入，输出）
  QuoteCharacter	字符串	指定CSV的引号字符，以Base64编码。默认值为\”（可选）。在CSV中引号内的换行符，列分隔符将被视作普通字符。未编码前的值必须为一个字符，以字符的ANSI值表示，例如Java里用\”表示引号。 子节点：None 父节点：CSV （输入）
  CSV	容器	指定CSV输入格式。 子节点：RecordDelimiter，FieldDelimiter，QuoteCharacter 父节点：InputSerialization
  JSON	容器	指定JSON输入格式。 子节点：Type 父节点：InputSerialization
  Type	枚举	指定JSON类型。 合法值 ：LINES

• 返回Body

  和SelectObject 类似，CreateSelectObjectMeta API也以Frame的形式返回。

  名称	Frame-Type值	Payload格式	描述
  Meta End Frame（Csv）	8388614	offset | total scanned bytes | status| splits count | rows count | columns count | error message <-8 bytes><------8 bytes------><--4bytes><--4 bytes--><--8 bytes><--4 bytes---><variable size>	用来汇报CreateSelectObjectMeta API最终的状态。 offset：8位整数，扫描结束时的文件偏移。 total scanned bytes：8位整数，最终扫描过的数据大小。 status：4位整数，最终的status。 splits_count：4位整数，总split个数。 rows_count：8位整数，总行数。 cols_count：4位整数，总列数。 error_message：详细的错误信息。若无错误，则error_message为空。
  Meta End Frame（Json）	8388615	offset | total scanned bytes | status| splits count | rows count | error message <-8 bytes><------8 bytes------><--4bytes><--4 bytes--><--8 bytes><variable size>	用来汇报CreateSelectObjectMeta API最终的状态。 offset：8位整数，扫描结束时的文件偏移。 total scanned bytes：8位整数，最终扫描过的数据大小。 status：4位整数，最终的status。 splits_count：4位整数，总split个数。 rows_count：8位整数，总行数。 error_message：详细的错误信息。若无错误，则error_message为空。

• 样例请求
  • 样例请求（CSV）

    POST /oss-select/bigcsv_normal.csv?x-oss-process=csv%2Fmeta HTTP/1.1
    Date: Fri, 25 May 2018 23:06:41 GMT
    Content-Type:
    Authorization: OSS AccessKeySignature
    User-Agent: aliyun-sdk-dotnet/2.8.0.0(windows 16.7/16.7.0.0/x86;4.0.30319.42000)
    Content-Length: 309
    Expect: 100-continue
    Connection: keep-alive
    Host: Host
    <?xml version="1.0"?>
    <CsvMetaRequest>
        <InputSerialization>
            <CSV>
                <RecordDelimiter>Cg==</RecordDelimiter>
                <FieldDelimiter>LA==</FieldDelimiter>
                <QuoteCharacter>Ig==</QuoteCharacter>
            </CSV>
        </InputSerialization>
        <OverwriteIfExisting>false</OverwriteIfExisting>
    </CsvMetaRequest>

  • 样例请求（JSON）

    POST /oss-select/sample.json?x-oss-process=json%2Fmeta HTTP/1.1
    Date: Fri, 25 May 2018 23:06:41 GMT
    Content-Type:
    Authorization: OSS AccessKeySignature
    User-Agent: aliyun-sdk-dotnet/2.8.0.0(windows 16.7/16.7.0.0/x86;4.0.30319.42000)
    Content-Length: 309
    Expect: 100-continue
    Connection: keep-alive
    Host: Host
    <?xml version="1.0"?>
    <JsonMetaRequest>
        <InputSerialization>
            <JSON>
                <Type>LINES</Type>
            </JSON>
        </InputSerialization>
        <OverwriteIfExisting>false</OverwriteIfExisting>
    </JsonMetaRequest>

支持的时间格式

自动识别是指无需指定日期格式就能把符合以下格式之一的字符串转成timestamp类型。例如cast­('20121201' as timestamp)会被解析成2012年12月1日。

以下格式为自动识别的格式：

由于以下格式会引起歧义，因此需要指定格式。如cast('20121201' as timestamp format 'YYYYDDMM')会将20121201解析成2012年1月12日。

ErrorCode

在下表的ErrorCode中，有些ErrorCode（例如InvalidCSVLine）可能以http status code的形式返回，也可能在End Frame中的status code返回，以何种形式返回ErrorCode取决于发生错误的CSV行在文件的具体位置。