全部產品
Search
文件中心

Object Storage Service:SelectObject

更新時間:Jun 19, 2024

調用該介面對目標檔案執行SQL語句,返回執行結果。

注意事項

  • 此操作要求您對該Object有讀許可權。

  • 正確執行SQL語句時,返回206。如果SQL語句不正確,或者和檔案不匹配,則返回400錯誤。

  • 調用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>

請求元素

名稱

類型

描述

SelectRequest

容器

儲存Select請求的容器

子節點:Expression,InputSerialization,OutputSerialization

父節點:None

Expression

字串

以Base 64 編碼的SQL語句

子節點:None

父節點:SelectRequest

InputSerialization

容器

輸入序列化參數(可選)

子節點:CompressionType、CSV、JSON

父節點:SelectRequest

OutputSerialization

容器

輸出序列化參數(可選)

子節點:CSV、JSON、OutputRawData

父節點:SelectRequest

CSV(InputSerialization)

容器

輸入CSV的格式參數(可選)

子節點:FileHeaderInfo、RecordDelimiter、FieldDelimiter、QuoteCharacter、CommentCharacter、 Range

父節點:InputSerialization

CSV(OutputSerialization)

容器

輸出CSV的格式參數(可選)

子節點: RecordDelimiter、 FieldDelimiter

父節點:OutputSerialization

JSON(InputSerialization)

容器

輸入JSON的格式參數(可選)

子節點:Type、Range、ParseJsonNumberAsString

JSON(OutputSerialization)

容器

輸出JSON的格式參數(可選)

子節點:RecordDelimiter

Type

枚舉

指定輸入JSON的類型:DOCUMENT 、 LINES

OutputRawData

bool,預設false

指定輸出資料為純資料(可選)

子節點:None

父節點:OutputSerialization

說明
  • 您在請求中指定OutputRawData值時,OSS服務端會按照請求中的要求返回資料。

  • 您在請求中不指定OutputRawData值時,OSS服務端會自動選擇一種格式返回。

  • 當您顯式地指定OutputRawData為True時,如果該SQL長時間內沒有返回資料,則HTTP請求可能因沒有資料返回而逾時。

CompressionType

枚舉

指定檔案壓縮類型:None|GZIP

子節點:None

父節點:InputSerialization

FileHeaderInfo

枚舉

指定CSV檔案頭資訊(可選)

取值:

  • Use:該CSV檔案有頭資訊,可以用CSV列名作為Select中的列名。

  • Ignore:該CSV檔案有頭資訊,但不可用CSV列名作為Select中的列名。

  • None:該檔案沒有頭資訊,為預設值。

子節點:None

父節點:CSV (輸入)

RecordDelimiter

字串

指定分行符號,以Base64編碼。預設值為\n(可選)。未編碼前的值最多為兩個字元,以字元的ANSI值表示,例如在Java中使用\n表示換行。

子節點:None

父節點:CSV (輸入、輸出),JSON(輸出)

FieldDelimiter

字串

指定CSV資料行分隔符號,以Base64編碼。預設值為,(可選)。未編碼前的值必須為一個字元,以字元的ANSI值表示,例如在Java中使用,表示逗號。

子節點:None

父節點:CSV (輸入,輸出)

QuoteCharacter

字串

指定CSV的引號字元,以Base64編碼。預設值為\”(可選)。在CSV中引號內的分行符號,資料行分隔符號將被視作一般字元。未編碼前的值必須為一個字元,以字元的ANSI值表示,例如在Java中使用\”表示引號。

子節點:None

父節點:CSV (輸入)

CommentCharacter

字串

指定CSV的注釋符,以Base64編碼。預設值為空白(即沒有注釋符)。

Range

字串

指定查詢檔案的範圍(可選)。支援兩種格式:

說明

使用Range參數查詢的檔案需要有select meta。select meta詳情請參考CreateSelectObjectMeta

  • 按行查詢:line-range=start-end。例如line-range=10-20表示掃描第10行到第20行。

  • 按Split查詢:split-range=start-end。例如split-range=10-20表示掃描第10到第20個split。

其中start和end均為inclusive。其格式和range get中的range參數一致。

僅在文檔是CSV或者JSON Type為LINES時使用。

子節點:None

父節點:CSV (輸入)、JSON(輸入)

KeepAllColumns

bool

指定返回結果中包含CSV所有列的位置(可選,預設值為false)。但僅僅在select 語句裡出現的列會有值,不出現的列則為空白,返回結果中每一行的資料按照CSV列的順序從低到高排列。例如以下語句:

select _5, _1 from ossobject.

如果KeepAllColumns = true,假設一共有6列資料,則返回以下資料:

Value of 1st column,,,,Value of 5th column,\n

子節點:None

父節點:OutputSerialization(Csv)

EnablePayloadCrc

bool

在每個Frame中會有一個32位的crc32校正值。用戶端可以計算相應payload的Crc32值進行資料完整性校正。

子節點:None

父節點:OutputSerialization

Options

容器

額外的選擇性參數。

子節點:SkipPartialDataRecord、MaxSkippedRecordsAllowed

父節點:SelectRequest

OutputHeader

bool

在返回結果開頭輸出CSV頭資訊。

預設false。

子節點:None

父節點:OutputSerialization

SkipPartialDataRecord

bool

忽略缺失資料的行。當該參數為false時, OSS會忽略缺失某些列(該列值當做null)而不報錯。當該參數為true時,該行資料因為不完整而被整體跳過。當跳過的行數超過指定的最大跳過行數時OSS會報錯並停止處理。

預設false。

子節點:None

父節點:Options

MaxSkippedRecordsAllowed

Int

指定最大能容忍的跳過的行數。當某一行資料因為不匹配SQL中期望的類型、或者某一列或者多列資料缺失且SkipPartialDataRecord為True時,該行資料會被跳過。如果跳過的行數超過該參數的值,OSS會停止處理並報錯。

說明

如果某一行是非法CSV行,例如在一列中間連續含有奇數個quote字元,則OSS會馬上停止處理並報錯,因為該錯誤很可能會影響對整個CSV檔案的解析。即該參數用來調整對非整齊資料的容忍度,但不應用於非法的CSV檔案。

預設 0。

子節點:None

父節點:Options

ParseJsonNumberAsString

bool

將JSON中的數字(整數和浮點數)解析成字串。目前JSON中的浮點數解析時會損失精度,如果要完整保留未經處理資料,則推薦用該選項。如果需要進行數值計算,則可以在SQL中cast成需要的格式,例如int、double、decimal。

預設值: false

子節點:None

父節點:JSON

AllowQuotedRecordDelimiter

bool

指定CSV內容是否含有在引號中的分行符號。

例如某一列值為"abc\ndef" (此處\n為換行), 則該值需設定為true。當該值為false時,select支援header range的語義,可以更高效的進行分區查詢。

預設值:true

子節點:None

父節點:InputSerialization

返回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

SelectObject分為Data Frame、Continuous Frame以及End Frame三種不同的Frame Type,詳細資料請參見下表。

名稱

Frame-Type值

Payload格式

描述

Data Frame

8388609

offset | data<-8 bytes><---variable->

包含Select請求返回的資料,並用offset來彙報進展。offset為當前掃描位置(從檔案頭開始的位移),值為8位整數。

Continuous Frame

8388612

offset<----8 bytes-->

用以彙報當前進展以及維持HTTP串連。如果該查詢在5s內未返回資料,則返回一個Continuous Frame。

End Frame

8388613

offset | total scanned bytes | http status code | error message<--8bytes-><--8bytes---------><----4 bytes--------><-variable------>

用來返回最終的狀態,掃描的位元組數以及可能的出錯資訊。

  • offset為掃描後最終的位置位移。

  • total scanned bytes為最終掃描過的資料大小。

  • http status code為最終的處理結果。

    說明

    返回status code的原因在於SelectObject為串流,因而在發送Response Header時僅處理了第一個Block。如果第一個Block資料和SQL匹配,則在Response Header中的Status為206。如果如下的資料非法,且已無法更改Header中的Status,則只能在End Frame裡包含最終的Status及其出錯資訊。此時用戶端應視其為最終狀態。

  • error message為錯誤資訊,包括所有跳過的行號及其總行數。

    說明

    error message格式為ErrorCodes.DetailMessage。其中ErrorCodes包含一個或者多個ErrorCode,多個ErrorCode之間用逗號隔開。ErrorCodes和DetailMessage之間用句號(.)隔開。

範例請求

範例請求分為 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語句Regex

SQL語句Regex為SELECT select-list from table where_opt limit_opt

重要

SELECT以及where為關鍵字,不得更改。

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
說明

支援的function為AVG、SUM、MAX、MIN、COUNT、 CAST(類型轉換函式)。其中,COUNT後面只能使用星號(*)。

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語句限制

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":待入職},則該節點被跳過。

CreateSelectObjectMeta

CreateSelectObjectMeta API用於擷取目標檔案總的行數,總的列數(對於CSV檔案),以及Split個數(每一個Object分成多個資料區塊,每個資料區塊對應一個Split,每個Split由連續的行組成)。如果該資訊不存在,則會掃描整個檔案,分析並記錄下CSV檔案的上述資訊。重複調用該API則會儲存上述資訊而不必重新掃描整個檔案。

說明
  • CreateSelectObjectMeta操作要求您對該Object有寫入權限。

  • 如果該API執行正確,返回200。如果目標檔案不是合法CSV或者JSON LINES檔案,或者指定的CSV分隔字元和目標CSV不匹配,則返回400。

  • 請求文法

    • 請求文法(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 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: 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 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: 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日。

以下格式為自動識別的格式:

格式

說明

YYYYMMDD

年月日

YYYY/MM/DD

年/月/日

DD/MM/YYYY/

日/月/年

YYYY-MM-DD

年-月-日

DD-MM-YY

日-月-年

DD.MM.YY

日.月.年

HH:MM:SS.mss

小時:分鐘:秒.毫秒

HH:MM:SS

小時:分鐘:秒

HH MM SS mss

小時 分鐘 秒 毫秒

HH.MM.SS.mss

小時.分鐘.秒.毫秒

HHMM

小時分鐘

HHMMSSmss

小時分鐘秒毫秒

YYYYMMDD HH:MM:SS.mss

年月日 小時:分鐘:秒.毫秒

YYYY/MM/DD HH:MM:SS.mss

年/月/日 小時:分鐘:秒.毫秒

DD/MM/YYYY HH:MM:SS.mss

日/月/年 小時:分鐘:秒.毫秒

YYYYMMDD HH:MM:SS

年月日 小時:分鐘:秒

YYYY/MM/DD HH:MM:SS

年/月/日 小時:分鐘:秒

DD/MM/YYYY HH:MM:SS

日/月/年 小時:分鐘:秒

YYYY-MM-DD HH:MM:SS.mss

年-月-日 小時:分鐘:秒.毫秒

DD-MM-YYYY HH:MM:SS.mss

日-月-年 小時:分鐘:秒.毫秒

YYYY-MM-DD HH:MM:SS

年-月-日 小時:分鐘:秒

YYYYMMDDTHH:MM:SS

年月日T小時:分鐘:秒

YYYYMMDDTHH:MM:SS.mss

年月日T小時:分鐘:秒.毫秒

DD-MM-YYYYTHH:MM:SS.mss

日-月-年T小時:分鐘:秒.毫秒

DD-MM-YYYYTHH:MM:SS

日-月-年T小時:分鐘:秒

YYYYMMDDTHHMM

年月日T小時分鐘

YYYYMMDDTHHMMSS

年月日T小時分鐘秒

YYYYMMDDTHHMMSSMSS

年月日T小時分鐘秒毫秒

ISO8601-0

年-月-日T小時:分鐘+小時:分鐘,或者年-月-日T小時:分鐘-小時:分鐘

這裡+表示時區在標準時間UTC前面,-表示在後面。注意這個格式可用ISO8601-0來表示

ISO8601-1

年-月-日T小時:分鐘:秒+小時:分鐘,或者年-月-日T小時:分鐘-小時:分鐘

這裡+表示時區在標準時間UTC前面,-表示在後面. 這個格式可用ISO8601-1來表示

CommonLog

例如28/Feb/2017:12:30:51 +0700

RFC822

例如Tue, 28 Feb 2017 12:30:51 GMT

?D/?M/YY

日/月/年,此處日月均可用1位或者2位表示

?D/?M/YY ?H:?M

日/月/年/小時:分鐘,此處日月分鐘小時均可用1位或者2位表示

?D/?M/YY ?H:?M:?S

日/月/年/小時:分鐘:秒,此處日月秒分鐘小時均可用1位或者2位表示

由於以下格式會引起歧義,因此需要指定格式。如cast('20121201' as timestamp format 'YYYYDDMM')會將20121201解析成2012年1月12日。

格式

說明

YYYYDDMM

年日月

YYYY/DD/MM

年/日/月

MM/DD/YYYY

月/日/年

YYYY-DD-MM

年-日-月

MM-DD-YYYY

月-日-年

MM.DD.YYYY

月.日.年

ErrorCode

SelectObject通過以下兩種形式返回ErrorCode。

  • 一種是和其他OSS請求一樣,在HTTP響應Headers裡返回http status code,並在body裡返回Error資訊。此類錯誤通常是存在明顯的輸入錯誤(例如輸入的SQL不正確),或者明顯的資料錯誤。

  • 另一種ErrorCode是在響應Body的End Frame中裡返回。這種情況通常是SelectObject處理資料的過程中,檢測到資料不正確或者和SQL不匹配(例如在某一行裡原本是整數列現在是一個字串,且SQL裡指定了該列是整數),此時往往部分資料已處理完畢並已發送到用戶端,且http status code仍然是206。

在下表的ErrorCode中,有些ErrorCode(例如InvalidCSVLine)可能以http status code的形式返回,也可能在End Frame中的status code返回,以何種形式返回ErrorCode取決於發生錯誤的CSV行在檔案的具體位置。

ErrorCode

描述

HTTP Status Code

Http Status Code in End Frame

InvalidSqlParameter

非法的SQL參數。

請求中SQL為空白或者SQL長度超過最大值或者SQL不是以base64編碼。

400

InvalidInputFieldDelimiter

非法的CSV資料行分隔符號(輸入)。

該參數不是以Base64編碼或者解碼後的長度大於1。

400

InvalidInputRecordDelimiter

非法的CSV行分隔字元(輸入)。該參數不是以Base64編碼或者解碼後長度大於2。

400

InvalidInputQuote

非法的CSV Quote字元(輸入)。該參數不是以Base64編碼或者解碼後長度超過1。

400

InvalidOutputFieldDelimiter

非法的CSV資料行分隔符號(輸出)。該參數不是以Base64編碼或者解碼後的長度大於1。

400

InvalidOutputRecordDelimiter

非法的CSV行分隔字元(輸出)。該參數不是以Base64編碼或者解碼後長度大於2。

400

UnsupportedCompressionFormat

非法的Compression參數。該參數值不是NONE或者GZIP(此處大小寫無關)。

400

InvalidCommentCharacter

非法的CSV注釋字元。該參數值不是以Base64編碼或者解碼後的值超過1。

400

InvalidRange

非法的Range參數。該參數不是以line-range=或者split-range=作為首碼,或者range值本身不符合HTTP range規範。

400

DecompressFailure

Compression參數是GZIP且解壓失敗。

400

InvalidMaxSkippedRecordsAllowed

MaxSkippedRecordsAllowed參數不是整數。

400

SelectCsvMetaUnavailable

指定了Range參數,但目標對象沒有CSV meta時,此時應該先調用Create Select object MetaAPI。

400

InvalidTextEncoding

對象不是以UTF-8編碼。

400

InvalidOSSSelectParameters

同時指定了EnablePayloadCrc為True以及OutputRawData為True時,兩個參數衝突,返回此錯誤。

400

InternalError

OSS系統出現錯誤。

500或者206

500或者無

SqlSyntaxError

Base64解碼後的SQL語法錯誤。

400

SqlExceedsMaxInCount

SQL中IN語句包含的值數目超過1024。

400

SqlExceedsMaxColumnNameLength

SQL中列名超過最大長度時1024。

400

SqlInvalidColumnIndex

SQL中列Index小於1或者大於1000。

400

SqlAggregationOnNonNumericType

SQL中彙總函式應用在非數值列中。

400

SqlInvalidAggregationOnTimestamp

SQL中SUM/AVG彙總應用在日期類型列。

400

SqlValueTypeOfInMustBeSame

SQL中IN語句包含不同類型的值。

400

SqlInvalidEscapeChar

SQL LIKE語句中Escape的字元為?或%或*。

400

SqlOnlyOneEscapeCharIsAllowed

SQL LIKE語句中Escape字元長度大於1。

400

SqlNoCharAfterEscapeChar

SQL LIKE語句中Escape字元後面沒有被Escape字元。

400

SqlInvalidLimitValue

SQL Limit語句後的數字小於1。

400

SqlExceedsMaxWildCardCount

SQL LIKE語句中萬用字元*或者%的個數超過最大值。

400

SqlExceedsMaxConditionCount

SQL Where語句中條件運算式個數超過最大值。

400

SqlExceedsMaxConditionDepth

SQL Where語句中條件樹的深度超過最大值。

400

SqlOneColumnCastToDifferentTypes

SQL語句中同一列被Cast成不同類型。

400

SqlOperationAppliedToDifferentTypes

SQL條件陳述式中一個操作符應用在兩個不同類型的對象。例如_col1 > 3如果其中col1是字串時就會報這個錯誤。

400

SqlInvalidColumnName

SQL語句中使用列名且該列名並不在CSV檔案Header中出現。

400

SqlNotSupportedTimestampFormat

SQL CAST語句中指定了時間戳記格式,且該格式不支援。

400

SqlNotMatchTimestampFormat

SQL CAST語句中指定了時間戳記格式,但該格式和提供的時間戳記字串不匹配。

400

SqlInvalidTimestampValue

SQL CAST語句中未指定時間戳記格式,且提供的時間戳記字串無法cast成時間戳記類型。

400

SqlInvalidLikeOperand

SQL LIKE語句中左邊不是列名或者列Index或者左邊的列不是字串類型,或者右邊字串。

400

SqlInvalidMixOfAggregationAndColumn

SQL Select語句中同時包含彙總操作以及非彙總操作的列名、列Index。

400

SqlExceedsMaxAggregationCount

SQL Select語句中包含的彙總操作超過最大值。

400

SqlInvalidMixOfStarAndColumn

SQL Select語句中同時包含*以及列名、列Index。

400

SqlInvalidKeepAllColumnsWithAggregation

SQL包含彙總操作,同時KeepAllColumns參數為True。

400

SqlInvalidKeepAllColumnsWithDuplicateColumn

SQL包含重複的列名、列索引,同時KeepAllColumns參數為True。

400

SqlInvalidSqlAfterAnalysis

SQL過分複雜導致分析後無法支援。

400

InvalidArithmeticOperand

SQL中算術操作應用在非數字類型的常量或者列。

400

SqlInvalidAndOperand

SQL中AND操作串連的兩個運算式不是bool類型。

400

SqlInvalidOrOperand

SQL中OR操作串連的兩個運算式不是bool類型。

400

SqlInvalidNotOperand

SQL中NOT操作應用在非bool類型的運算式。

400

SqlInvalidIsNullOperand

SQL中IS NULL應用在常量上。

400

SqlComparerOperandTypeMismatch

SQL中比較操作應用在兩個不同類型的對象。

400

SqlInvalidConcatOperand

SQL中字串串連操作(||)串連兩個常量。

400

SqlUnsupportedSql

SQL過分複雜從而產生的SQL計劃超過最大值。

400

HeaderInfoExceedsMaxSize

SQL指定了輸出Header資訊,且Header資訊超過最大允許的長度。

400

OutputExceedsMaxSize

SQL的輸出有放大導致輸出結果中單行超過最大長度。

400

InvalidCsvLine

CSV行是非法時(包括長度超過最大允許的長度),或者被跳過的行數超過MaxSkippedRecordsAllowed。

400或者206

400或者無

NegativeRowIndex

SQL中作為數組Index的值為負數。

400

ExceedsMaxNestedColumnDepth

SQL中的JSON屬性嵌套層數超過最大值。

400

NestedColumnNotSupportInCsv

嵌套的屬性(含有數組[]或者.)不支援在CSV的SQL中。

400

TableRootNodeOnlySupportInJson

只有JSON檔案支援在From ossobject後指定根節點路徑。

400

JsonNodeExceedsMaxSize

JSON檔案的SQL的根節點大小超過允許最大值。

400或者206

400或者無

InvalidJsonData

非法的JSON資料(格式不正確)。

400或者206

400或者無

ExceedsMaxJsonArraySize

JSON檔案的SQL的根節點中的某個數組的元素個數超過最大值。

400或者206

400或者無

WildCardNotAllowed

JSON檔案的SQL中wild card *不能出現select或者where的JSON屬性中。例如select s.a.b[*] from ossobject where a.c[*] > 0是不支援的。

400

JsonNodeExceedsMaxDepth

JSON檔案的SQL根節點深度超過最大值。

400或者206

400或者無