注意事項(xiàng)

• 本文以華東1（杭州）外網(wǎng)Endpoint為例。如果您希望通過與OSS同地域的其他阿里云產(chǎn)品訪問OSS，請(qǐng)使用內(nèi)網(wǎng)Endpoint。關(guān)于OSS支持的Region與Endpoint的對(duì)應(yīng)關(guān)系，請(qǐng)參見訪問域名和數(shù)據(jù)中心。

• 本文以O(shè)SS域名新建OSSClient為例。如果您希望通過自定義域名、STS等方式新建OSSClient，請(qǐng)參見初始化。

• 要查詢文件，您必須具有oss:GetObject權(quán)限。具體操作，請(qǐng)參見為RAM用戶授權(quán)自定義的權(quán)限策略。

• OSS僅支持查詢CSV文件和JSON文件，不支持查詢其他格式的文件。

Python SDK示例

以下代碼用于查詢CSV和JSON文件：

import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider

def select_call_back(consumed_bytes, total_bytes =  None):
        print('Consumed Bytes:' + str(consumed_bytes) + '\n')

# 從環(huán)境變量中獲取訪問憑證。運(yùn)行本代碼示例之前，請(qǐng)確保已設(shè)置環(huán)境變量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())
# yourEndpoint填寫B(tài)ucket所在地域?qū)?yīng)的Endpoint。以華東1（杭州）為例，Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com。
# 填寫B(tài)ucket名稱。
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'examplebucket')
key =  'python_select.csv'
content =  'Tom Hanks,USA,45\r\n'*1024
filename =  'python_select.csv'

# 上傳CSV文件。
bucket.put_object(key, content)
# Select API的參數(shù)。
csv_meta_params = {'RecordDelimiter': '\r\n'}
select_csv_params = {'CsvHeaderInfo': 'None',
                    'RecordDelimiter': '\r\n',
                    'LineRange': (500, 1000)}

csv_header = bucket.create_select_object_meta(key, csv_meta_params)
print(csv_header.rows)
print(csv_header.splits)
result = bucket.select_object(key, "select * from ossobject where _3 > 44", select_call_back, select_csv_params)
select_content = result.read()
print(select_content)

result = bucket.select_object_to_file(key, filename,
      "select * from ossobject where _3 > 44", select_call_back, select_csv_params)
bucket.delete_object(key)

###JSON DOCUMENT
key =  'python_select.json'
content =  "{\"contacts\":[{\"key1\":1,\"key2\":\"hello world1\"},{\"key1\":2,\"key2\":\"hello world2\"}]}"
filename =  'python_select.json'
# 上傳JSON DOCUMENT。
bucket.put_object(key, content)
select_json_params = {'Json_Type': 'DOCUMENT'}
result = bucket.select_object(key, "select s.key2 from ossobject.contacts[*] s where s.key1 = 1", None, select_json_params)
select_content = result.read()
print(select_content)

result = bucket.select_object_to_file(key, filename,
      "select s.key2 from ossobject.contacts[*] s where s.key1 = 1", None, select_json_params)
bucket.delete_object(key)

###JSON LINES
key =  'python_select_lines.json'
content =  "{\"key1\":1,\"key2\":\"hello world1\"}\n{\"key1\":2,\"key2\":\"hello world2\"}"
filename =  'python_select.json'
# 上傳JSON LINE。
bucket.put_object(key, content)
select_json_params = {'Json_Type': 'LINES'}
json_header = bucket.create_select_object_meta(key,select_json_params)
print(json_header.rows)
print(json_header.splits)

result = bucket.select_object(key, "select s.key2 from ossobject s where s.key1 = 1", None, select_json_params)
select_content =  result.read()
print(select_content)
result = bucket.select_object_to_file(key, filename,
           "select s.key2 from ossobject s where s.key1 = 1", None, select_json_params)
bucket.delete_object(key)

Python SelectObject

以下內(nèi)容是對(duì)Python Select API中的select_object、select_object_to_file、create_select_object_meta等元素的詳細(xì)介紹。

• select_object

  • select_object 示例：

    def select_object(self, key, sql,
                       progress_callback=None,
                       select_params=None
                       byte_range=None
                       headers=None
                       ):

    以上示例用于對(duì)指定Key的文件運(yùn)行SQL，并返回查詢結(jié)果。

    • sql是原始的SQL字符串，無需做base64編碼。

    • Progress_callback是可選的用來匯報(bào)進(jìn)度的回調(diào)函數(shù)。

    • select_params用于指定select執(zhí)行的各種參數(shù)以及行為。

    • headers用于指定請(qǐng)求中附帶的header信息，其行為和get-object一致。比如，對(duì)于CSV文件，在某些情況下可以用bytes來指定SQL查詢?cè)谖募械姆秶?/p>

  • select_params支持的參數(shù)

    參數(shù)名稱	描述
    Json_Type	當(dāng)Json_Type沒有指定時(shí)，默認(rèn)為CSV文件。 當(dāng)Json_Type指定為DOCUMENT時(shí)，該文件為JSON DOCUMENT文件。 當(dāng)Json_Type指定為L(zhǎng)INES時(shí)，該文件為JSON LINE文件。
    CsvHeaderInfo	CSV的header信息。 合法值為None、Ignore以及Use。 None：該文件沒有header信息。 Ignore：該文件有header信息但未在SQL中使用。 Use：該文件有Header信息且在sql語句中使用了Header中的列名。
    CommentCharacter	CSV中的注釋字符。僅支持一個(gè)字符，默認(rèn)為None表示沒有注釋字符。
    RecordDelimiter	CSV中的行分隔符，僅支持一個(gè)或兩個(gè)字符。默認(rèn)為\n。
    OutputRecordDelimiter	Select輸出結(jié)果中的行分隔符。默認(rèn)為\n。
    FieldDelimiter	CSV的列分隔符，僅支持一個(gè)字符，默認(rèn)為逗號(hào)（,）。
    OutputFieldDelimiter	Select輸出結(jié)果中的列分隔符，默認(rèn)為逗號(hào)（,）。
    QuoteCharacter	CSV列的引號(hào)字符，只支持一個(gè)字符，默認(rèn)為雙引號(hào)。引號(hào)內(nèi)的行列分隔符被當(dāng)做普通字符處理。
    SplitRange	使用Split做分片查詢。格式為(start, end)，此處為閉區(qū)間，表示查詢范圍從Split start#到end#。
    LineRange	使用行做分片查詢。格式為(start, end)，此處為閉區(qū)間，表示查詢范圍從行號(hào)start#到end#。
    CompressionType	壓縮類型，可以為GZIP。默認(rèn)為None。
    KeepAllColumns	該參數(shù)設(shè)置為true時(shí)表示原CSV文件中未在select列中出現(xiàn)的列將以空值輸出（但保留列的位置）。默認(rèn)為False。 如果CSV文件中的列為 firstname, lastname, age，SQL為select firstname, age from ossobject。 如果KeepAllColumns為true，則輸出為firstname,,age（中間多一個(gè)逗號(hào)）。 如果KeepAllColumns為false，則輸出為firstname,age。 說明 引入該選項(xiàng)的原因是讓原本處理GetObject返回?cái)?shù)據(jù)的代碼可以在不用修改的情況下平移切換到SelectObject。
    OutputRawData	該參數(shù)為True時(shí)表示輸出為Select數(shù)據(jù)，沒有Frame的包裝，表明很長(zhǎng)時(shí)間不返回?cái)?shù)據(jù)時(shí)會(huì)引起超時(shí)。 該參數(shù)為False時(shí)表示輸出為Frame包裝的數(shù)據(jù)。默認(rèn)是False。
    EnablePayloadCrc	為每個(gè)Frame計(jì)算CRC校驗(yàn)值，默認(rèn)為False。
    OutputHeader	僅用于CSV文件，表示輸出結(jié)果中第一行是Header信息。
    SkipPartialDataRecord	該參數(shù)為True時(shí)，如果CSV中某一列值不存在或者JSON中某一個(gè)Key不存在，則直接跳過整個(gè)記錄。該參數(shù)為False時(shí)，則把該列當(dāng)做null來處理。 假如某一行的列為firstname,lastname,age。SQL為select _1, _4 from ossobject。 如果為True，則直接跳過此行。 如果為False，則返回firstname,\n。
    MaxSkippedRecordsAllowed	允許跳過的行的最大值。默認(rèn)為0，表示一旦有一行跳過就返回錯(cuò)誤。
    ParseJsonNumberAsString	當(dāng)該參數(shù)為True時(shí)：表示JSON文件中的數(shù)字都解析為字符串。 當(dāng)參數(shù)為False時(shí)：按照整數(shù)或者浮點(diǎn)數(shù)進(jìn)行解析，F(xiàn)alse為默認(rèn)值。 當(dāng)JSON文件中含有高精度的浮點(diǎn)數(shù)時(shí)，直接解析為浮點(diǎn)數(shù)會(huì)丟失精度。如果想保留原始的精度，則可以設(shè)置該參數(shù)為True，并且在SQL語句中將該列Cast為decimal類型即可。

  • select_object返回值：返回SelectObjectResult對(duì)象，該對(duì)象支持read()函數(shù)以獲得所有select結(jié)果。同時(shí)也支持__iter__方法。

    說明

    如果Select結(jié)果偏大，調(diào)用read()函數(shù)會(huì)阻塞直到select結(jié)果完全返回，同時(shí)占用過多的內(nèi)存。建議使用__iter__方法（foreach chunk in result），然后對(duì)每個(gè)chunk進(jìn)行處理。__iter__方法不僅可以降低內(nèi)存使用，且OSS服務(wù)器端每處理一個(gè)請(qǐng)求chunk客戶端都能及時(shí)處理，不必等到全部結(jié)果返回后才處理。

• select_object_to_file

  def select_object_to_file(self, key, filename, sql,
                     progress_callback=None,
                     select_params=None
                     headers=None
                     ):

  以上示例用于對(duì)指定Key的文件運(yùn)行SQL，將查詢結(jié)果寫入指定的文件。

  涉及的參數(shù)描述與select_object相同。

• create_select_object_meta

  • create_select_object_meta的語法結(jié)構(gòu)

    def create_select_object_meta(self, key, select_meta_params=None, header=None):

    以上示例用于對(duì)指定Key的文件進(jìn)行創(chuàng)建或者獲取select meta。select meta是指該文件的總行數(shù)、總列數(shù)（CSV文件）、總的Split數(shù)。

    如果該文件已經(jīng)創(chuàng)建過meta，則調(diào)用該函數(shù)不會(huì)重新創(chuàng)建，除非在參數(shù)中指定OverwriteIfExists為true。

    創(chuàng)建select meta需要掃描整個(gè)文件。

  • select_meta_params中支持的參數(shù)

    參數(shù)名稱	描述
    Json_Type	當(dāng)Json_Type沒有指定時(shí)，默認(rèn)為CSV文件。 若指定，必須為L(zhǎng)INES，表示文件是JSON LINES。 說明 JSON DOCUMENT不支持該操作。
    RecordDelimiter	CSV文件換行符。
    FieldDelimiter	CSV文件列分隔符。
    QuoteCharacter	CSV文件列引號(hào)符。引號(hào)符內(nèi)的行列分隔符按普通字符處理。
    CompressionType	壓縮類型。目前不支持任何壓縮類型，故只能為None。
    OverwriteIfExists	覆蓋原有的Select Meta。正常情況無需使用該選項(xiàng)。

  • create_select_object_meta返回值：GetSelectObjectMetaResult對(duì)象，包括rows、splits兩個(gè)屬性。對(duì)于CSV文件，其內(nèi)部的select_resp對(duì)象還包括columns值，表示CSV文件的列數(shù)。

相關(guān)文檔

• 關(guān)于查詢文件的完整示例代碼，請(qǐng)參見GitHub示例。

• 關(guān)于查詢文件的API接口說明，請(qǐng)參見SelectObject。