注意事項

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

• 本文以OSS域名新建OSSClient為例。如果您希望通過自定義域名、STS等方式新建OSSClient，請參見初始化。

• 要查詢文件，您必須具有oss:GetObject權(quán)限。具體操作，請參見為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)境變量中獲取訪問憑證。運行本代碼示例之前，請確保已設(shè)置環(huán)境變量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# 填寫B(tài)ucket所在地域?qū)?yīng)的Endpoint。以華東1（杭州）為例，Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com。
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"

# 填寫Endpoint對應(yīng)的Region信息，例如cn-hangzhou。注意，v4簽名下，必須填寫該參數(shù)
region = "cn-hangzhou"

# yourBucketName填寫存儲空間名稱。
bucket = oss2.Bucket(auth, endpoint, "yourBucketName", region=region)

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)容是對Python Select API中的select_object、select_object_to_file、create_select_object_meta等元素的詳細介紹。

• select_object

  • select_object 示例：

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

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

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

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

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

    • headers用于指定請求中附帶的header信息，其行為和get-object一致。比如，對于CSV文件，在某些情況下可以用bytes來指定SQL查詢在文件中的范圍。

  • select_params支持的參數(shù)

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

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

    說明

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

• select_object_to_file

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

  以上示例用于對指定Key的文件運行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):

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

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

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

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

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

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

相關(guān)文檔

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

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