Object Storage Service：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: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
  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: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
  Content-Length: 317
  <SelectRequest>
      <Expression>c2VsZWN0ICogZnJvbSBvc3NvYmplY3Qub2JqZWN0c1sqXSB3aGVyZSBwYXJ0eSA9ICdEZW1vY3JhdCc=
      </Expression>
      <InputSerialization>
      <JSON>
          <Type>DOCUMENT</Type>
      </JSON>
      </InputSerialization>
      <OutputSerialization>
      <JSON>
          <RecordDelimiter>LA==</RecordDelimiter>
      </JSON>
      </OutputSerialization>
      <Options />
  </SelectRequest>

SQL語句Regex為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。