SelectObject

请求语法分为 CSV 和 JSON 两种格式。

• 请求语法（CSV）

  POST /object?x-oss-process=csv/select HTTP/1.1 
  HOST: BucketName.oss-cn-hangzhou.aliyuncs.com 
  Date: time GMT
  Content-Length: ContentLength
  Content-MD5: MD5Value 
  Authorization: Signature
  <?xml  version="1.0"  encoding="UTF-8"?>
  <SelectRequest>    
      <Expression>base64 encode的SQL语句，例如c2VsZWN0IGNvdW50KCopIGZyb20gb3Nzb2JqZWN0IHdoZXJlIF80ID4gNDU=</Expression>
      <InputSerialization>
          <CompressionType>None|GZIP</CompressionType>
          <CSV>            
              <FileHeaderInfo>
                  NONE|IGNORE|USE
              </FileHeaderInfo>
              <RecordDelimiter>base64 encode的字符</RecordDelimiter>
              <FieldDelimiter>base64 encode的字符</FieldDelimiter>
              <QuoteCharacter>base64 encode的字符</QuoteCharacter>
              <CommentCharacter>base64 encode的字符</CommentCharacter>
              <Range>line-range=start-end|split-range=start-end</Range>
              <AllowQuotedRecordDelimiter>true|false</AllowQuotedRecordDelimiter>
          </CSV>   
          </InputSerialization>
          <OutputSerialization>
               <CSV>
               <RecordDelimiter>base64 encode的字符</RecordDelimiter>
               <FieldDelimiter>base64 encode的字符</FieldDelimiter>
  
              </CSV>
              <KeepAllColumns>false|true</KeepAllColumns>
              <OutputRawData>false|true</OutputRawData>
              <EnablePayloadCrc>true</EnablePayloadCrc>
              <OutputHeader>false</OutputHeader>
         </OutputSerialization>
       <Options>
          <SkipPartialDataRecord>false</SkipPartialDataRecord>
          <MaxSkippedRecordsAllowed>
          max allowed number of records skipped
          </MaxSkippedRecordsAllowed>
      </Options>
  </SelectRequest>

• 请求语法（JSON）

  POST /object?x-oss-process=json/select HTTP/1.1 
  HOST: BucketName.oss-cn-hangzhou.aliyuncs.com 
  Date: time GMT
  Content-Length: ContentLength
  Content-MD5: MD5Value 
  Authorization: Signature
  <?xml  version="1.0"  encoding="UTF-8"?>
  <SelectRequest>    
      <Expression>
          base64 encode的SQL语句，例如c2VsZWN0IGNvdW50KCopIGZyb20gb3Nzb2JqZWN0IHdoZXJlIF80ID4gNDU=
      </Expression>
      <InputSerialization>
          <CompressionType>None|GZIP</CompressionType>
          <JSON>
              <Type>DOCUMENT|LINES</Type>
              <Range>
              line-range=start-end|split-range=start-end
              </Range>
              <ParseJsonNumberAsString> true|false
              </ParseJsonNumberAsString>
          </JSON>
      </InputSerialization>
      <OutputSerialization>
          <JSON>
              <RecordDelimiter>
                  Base64 of record delimiter
              </RecordDelimiter>
          </JSON>
          <OutputRawData>false|true</OutputRawData>
                   <EnablePayloadCrc>true</EnablePayloadCrc>
      </OutputSerialization>
      <Options>
          <SkipPartialDataRecord>
              false|true
          </SkipPartialDataRecord>
          <MaxSkippedRecordsAllowed>
              max allowed number of records skipped
             </MaxSkippedRecordsAllowed>
          </Options>
  </SelectRequest>

SelectObject分为Data Frame、Continuous Frame以及End Frame三种不同的Frame Type，详细信息请参见下表。

样例请求分为 CSV 和 JSON 两种格式。

• 样例请求（CSV）

  POST /oss-select/bigcsv_normal.csv?x-oss-process=csv%2Fselect HTTP/1.1
  Date: Fri, 25 May 2018 22:11:39 GMT
  Content-Type:
  Authorization: OSS qn6q**************:77Dv****************
  User-Agent: aliyun-sdk-dotnet/2.8.0.0(windows 16.7/16.7.0.0/x86;4.0.30319.42000)
  Content-Length: 748
  Expect: 100-continue
  Connection: keep-alive
  Host: host name
  <?xml version="1.0"?>
  <SelectRequest>
      <Expression>c2VsZWN0IGNvdW50KCopIGZyb20gb3Nzb2JqZWN0IHdoZXJlIF80ID4gNDU=
      </Expression>
      <InputSerialization>
          <Compression>None</Compression>
          <CSV>
              <FileHeaderInfo>Ignore</FileHeaderInfo>
              <RecordDelimiter>Cg==</RecordDelimiter>
              <FieldDelimiter>LA==</FieldDelimiter>
              <QuoteCharacter>Ig==</QuoteCharacter>
              <CommentCharacter>Iw==</CommentCharacter/>
          </CSV>
      </InputSerialization>
      <OutputSerialization>
          <CSV>
              <RecordDelimiter>Cg==</RecordDelimiter>
              <FieldDelimiter>LA==</FieldDelimiter>
              <QuoteCharacter>Ig==</QuoteCharacter>            
          </CSV>
          <KeepAllColumns>false</KeepAllColumns>
              <OutputRawData>false</OutputRawData>
      </OutputSerialization>
  </SelectRequest>

• 样例请求（JSON）

  POST /oss-select/sample_json.json?x-oss-process=json%2Fselect HTTP/1.1
  Host: host name
  Accept-Encoding: identity
  User-Agent: aliyun-sdk-python/2.6.0(Darwin/16.7.0/x86_64;3.5.4)
  Accept: */*
  Connection: keep-alive
  date: Mon, 10 Dec 2018 18:28:11 GMT
  authorization: OSS qn6q**************:77Dv****************
  Content-Length: 317
  <SelectRequest>
      <Expression>c2VsZWN0ICogZnJvbSBvc3NvYmplY3Qub2JqZWN0c1sqXSB3aGVyZSBwYXJ0eSA9ICdEZW1vY3JhdCc=
      </Expression>
      <InputSerialization>
      <JSON>
          <Type>DOCUMENT</Type>
      </JSON>
      </InputSerialization>
      <OutputSerialization>
      <JSON>
          <RecordDelimiter>LA==</RecordDelimiter>
      </JSON>
      </OutputSerialization>
      <Options />
  </SelectRequest>

SQL语句正则表达式为SELECT select-list from table where_opt limit_opt。

SQL语句限制如下：

• 目前仅仅支持UTF-8编码的文本文件以及GZIP压缩过的UTF-8文本。GZIP文件不支持deflate格式。

• 仅支持单文件查询，不支持join、order by、group by、having。

• Where语句里不能包含聚合条件（e.g. where max(cast(age as int)) > 100这个是不允许的）。

• 支持的最大的列数是1000，SQL中最大列名长度不能超过1024字节。

• 在LIKE语句中，支持最多5个%通配符。*和%是等价的，表示0或多个任意字符。LIKE支持Escape关键字，用于将Pattern中的%*?特殊字符Escape成普通字符串。

• 在IN语句中，最多支持1024个常量项。

• Select后的Projection可以是列名，CSV列索引（_1, _2等），或者是聚合函数，或者是CAST函数；不支持其他表达式。 例如select _1 + _2 from ossobject是不允许的。

• 支持的CSV单行及单列的最大字符数均为256 KB。

• 支持的 from 后json path指定的JSON最大节点为512 KB，最大深度为10层，其数组内元素的个数最多为5000。select以及where后的字段必须是来自from后json path对应的节点。

• JSON文件的SQL中，select 或者where条件的表达式中不能有[*]数组通配符，数组通配符只能出现在from后的json path中。（例如select s.contacts[*] from ossobject s是不允许的，但是select * from ossobject.contacts[*]是可以的）。

• SQL最大长度为16 KB，where后面表达式个数最多20个，表达式深度最多10层，聚合操作最多100个。

以下列举了CSV的某些行缺失了某些列、JSON缺失某些Key、CSV的某些列类型不匹配SQL，以及JSON中某些Key类型不匹配SQL等常见的数据容错处理方法。

• CSV的某些行缺失了某些列

  当SkipPartialDataRecord没有被指定或者其值为False时，OSS会把缺失的列都当做null来计算SQL中的表达式。

  当SkipPartialDataRecord指定为True时，则OSS会忽略该行数据。此时，如果MaxSkippedRecordsAllowed未指定或者指定的值小于忽略的行数，则OSS会通过http status code或者End Frame的形式返回400错误。

  当SQL为select _1, _3 from ossobject，而CSV的某一行指定为 “张小,阿里巴巴”。

  • 当SkipPartialDataRecord指定为False时，返回内容为”张小,\n”

  • 当SkipPartialDataRecord指定为True时，该行被跳过。

• JSON缺失某些Key

  和CSV一样，JSON的某些对象可能未包括SQL中指定的Key。

  • 当SkipPartialDataRecord没有被指定或者其值为False时，此时OSS会把缺失的Key当做Null来计算SQL中的表达式。

  • 如果SkipPartialDataRecord为true时，OSS则会忽略该JSON节点的数据 。此时，如果MaxSkippedRecordsAllowed未指定或者指定的值小于忽略的行数，则OSS会通过http status code或者End Frame返回400错误。

  例如SQL为 select s.firstName, s.lastName , s.age from ossobject.contacts[*] s，某个JSON节点为{“firstName”:”小”，”lastName”:”张”}。

  • 当SkipPartialDataRecord为False或未指定时，该节点的返回值为{“firstName”:”小”, “lastName”:”张”}。

  • 当SkipPartialDataRecord为True时则跳过该行。

  说明

  对于JSON返回数据中Key的处理，SelectJson的输出只能为JSON LINES。输出结果中的Key值按以下规则确定。

  • 当SQL为select * from ossobject…时，如果*返回的内容是一个JSON对象（{…}），则原样返回；如果*不是一个JSON对象（例如是字符串或者数组），则会使用一个DummyKey _1来表示。

    当数据为{“Age”:5}select * from ossobject.Age s where s = 5，此时*对应的内容5不是一个JSON对象，故返回的内容为{“_1”:5}。假设SQL为select * from ossobject s where s.Age = 5 ，此时*对应的内容是{“Age”:5}，故原样返回。

  • 当SQL没有使用select *而是指定了列时，则返回的内容格式为{“{列1}”:值, “{列2}”：值…..}。 其中{列n}的生成方法如下：

    • 当select中指定了该列的Alias时用Alias。

    • 如果该列是一个JSON对象的Key时，用该Key作为输出的Key值。

    • 如果该列是JSON数组的某个元素时或者是聚合函数，用该列在输出中的序号（从1开始）加上前缀_作为输出值的key。

    当数据为{”contacts”:{“Age”:35, “Children”:[“child1”, “child2”,”child3”]}}：

    • 当SQL为select s.contacts.Age, s.contacts.Children[0] from ossobject s ，由于Age是输入JSON对象的Key，但Children[0]是数组Children的第一个元素，在输出中是第二列，故为”_2”:“child1”，则输出为 {“Age”:35, “_2”:”child1”}。

    • 当SQL为select max(cast(s.Age as int)) from ossobject.contacts s，由于该列是聚合函数，故而用该列在输出中的序号加上前缀_1表示Key，则输出为{“_1”:35}。

    • 如果指定了Aliasselect s.contacts.Age, s.contacts.Children[0] as firstChild from ossobject，则输出为{“Age”:35, “firstChild”:”child1”}。

  • JSON文件和SQL中Key的匹配是大小写敏感的，例如select s.Age 和select s.age是不同的。

• CSV的某些列类型不匹配SQL

  当CSV中某些行的数据类型和SQL中指定的数据类型不匹配时，该行数据会被忽略。和上面情况类似，其行为受到MaxSkippedRecordsAllowed的影响。当忽略行数超过上限时，OSS将处理中转并返回400。

  当SQL为select _1, _3 from ossobject where _3 > 5，某CSV行为张小，阿里巴巴，待入职时，由于第三列不是整数类型，则该行被跳过。

• JSON中某些Key类型不匹配SQL

  当SQL为select s.name from ossobject s where s.aliren_age > 5，JSON节点是{"Name":"张小", "aliren_age":待入职}，则该节点被跳过。

SelectObject通过以下两种形式返回ErrorCode。

• 一种是和其他OSS请求一样，在HTTP响应Headers里返回http status code，并在body里返回Error信息。此类错误通常是存在明显的输入错误（例如输入的SQL不正确），或者明显的数据错误。

• 另一种ErrorCode是在响应Body的End Frame中里返回。这种情况通常是SelectObject处理数据的过程中，检测到数据不正确或者和SQL不匹配（例如在某一行里原本是整数列现在是一个字符串，且SQL里指定了该列是整数），此时往往部分数据已处理完毕并已发送到客户端，且http status code仍然是206。