調用該介面對目標檔案執行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 說明
|
CompressionType | 枚舉 | 指定檔案壓縮類型:None|GZIP 子節點:None 父節點:InputSerialization |
FileHeaderInfo | 枚舉 | 指定CSV檔案頭資訊(可選) 取值:
子節點:None 父節點:CSV (輸入) |
RecordDelimiter | 字串 | 指定分行符號,以Base64編碼。預設值為 子節點:None 父節點:CSV (輸入、輸出),JSON(輸出) |
FieldDelimiter | 字串 | 指定CSV資料行分隔符號,以Base64編碼。預設值為 子節點:None 父節點:CSV (輸入,輸出) |
QuoteCharacter | 字串 | 指定CSV的引號字元,以Base64編碼。預設值為 子節點:None 父節點:CSV (輸入) |
CommentCharacter | 字串 | 指定CSV的注釋符,以Base64編碼。預設值為空白(即沒有注釋符)。 |
Range | 字串 | 指定查詢檔案的範圍(可選)。支援兩種格式: 說明 使用Range參數查詢的檔案需要有select meta。select meta詳情請參考CreateSelectObjectMeta。
其中start和end均為inclusive。其格式和range get中的range參數一致。 僅在文檔是CSV或者JSON Type為LINES時使用。 子節點:None 父節點:CSV (輸入)、JSON(輸入) |
KeepAllColumns | bool | 指定返回結果中包含CSV所有列的位置(可選,預設值為false)。但僅僅在select 語句裡出現的列會有值,不出現的列則為空白,返回結果中每一行的資料按照CSV列的順序從低到高排列。例如以下語句:
如果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------> | 用來返回最終的狀態,掃描的位元組數以及可能的出錯資訊。
|
範例請求
範例請求分為 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}。如果指定了Alias
select 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屬性中。例如 | 400 | 無 |
JsonNodeExceedsMaxDepth | JSON檔案的SQL根節點深度超過最大值。 | 400或者206 | 400或者無 |