Python查询文件

注意事项

• 本文以华东1（杭州）外网Endpoint为例。如果您希望通过与OSS同地域的其他阿里云产品访问OSS，请使用内网Endpoint。关于OSS支持的Region与Endpoint的对应关系，请参见OSS地域和访问域名。

• 本文以OSS域名新建OSSClient为例。如果您希望通过自定义域名、STS等方式新建OSSClient，请参见初始化。

• 要查询文件，您必须具有oss:GetObject权限。具体操作，请参见为RAM用户授权自定义的权限策略。

• 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')

# 从环境变量中获取访问凭证。运行本代码示例之前，请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# 填写Bucket所在地域对应的Endpoint。以华东1（杭州）为例，Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"

# 填写Endpoint对应的Region信息，例如cn-hangzhou。注意，v4签名下，必须填写该参数
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的参数。
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

以下内容是对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，并返回查询结果。

    • sql是原始的SQL字符串，无需做base64编码。

    • Progress_callback是可选的用来汇报进度的回调函数。

    • select_params用于指定select执行的各种参数以及行为。

    • headers用于指定请求中附带的header信息，其行为和get-object一致。比如，对于CSV文件，在某些情况下可以用bytes来指定SQL查询在文件中的范围。

  • select_params支持的参数

    参数名称	描述
    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输出结果中的行分隔符。默认为\n。
    FieldDelimiter	CSV的列分隔符，仅支持一个字符，默认为逗号（,）。
    OutputFieldDelimiter	Select输出结果中的列分隔符，默认为逗号（,）。
    QuoteCharacter	CSV列的引号字符，只支持一个字符，默认为双引号。引号内的行列分隔符被当做普通字符处理。
    SplitRange	使用Split做分片查询。格式为(start, end)，此处为闭区间，表示查询范围从Split start#到end#。
    LineRange	使用行做分片查询。格式为(start, end)，此处为闭区间，表示查询范围从行号start#到end#。
    CompressionType	压缩类型，可以为GZIP。默认为None。
    KeepAllColumns	该参数设置为true时表示原CSV文件中未在select列中出现的列将以空值输出（但保留列的位置）。默认为False。 如果CSV文件中的列为 firstname, lastname, age，SQL为select firstname, age from ossobject。 如果KeepAllColumns为true，则输出为firstname,,age（中间多一个逗号）。 如果KeepAllColumns为false，则输出为firstname,age。 说明 引入该选项的原因是让原本处理GetObject返回数据的代码可以在不用修改的情况下平移切换到SelectObject。
    OutputRawData	该参数为True时表示输出为Select数据，没有Frame的包装，表明很长时间不返回数据时会引起超时。 该参数为False时表示输出为Frame包装的数据。默认是False。
    EnablePayloadCrc	为每个Frame计算CRC校验值，默认为False。
    OutputHeader	仅用于CSV文件，表示输出结果中第一行是Header信息。
    SkipPartialDataRecord	该参数为True时，如果CSV中某一列值不存在或者JSON中某一个Key不存在，则直接跳过整个记录。该参数为False时，则把该列当做null来处理。 假如某一行的列为firstname,lastname,age。SQL为select _1, _4 from ossobject。 如果为True，则直接跳过此行。 如果为False，则返回firstname,\n。
    MaxSkippedRecordsAllowed	允许跳过的行的最大值。默认为0，表示一旦有一行跳过就返回错误。
    ParseJsonNumberAsString	当该参数为True时：表示JSON文件中的数字都解析为字符串。 当参数为False时：按照整数或者浮点数进行解析，False为默认值。 当JSON文件中含有高精度的浮点数时，直接解析为浮点数会丢失精度。如果想保留原始的精度，则可以设置该参数为True，并且在SQL语句中将该列Cast为decimal类型即可。

  • select_object返回值：返回SelectObjectResult对象，该对象支持read()函数以获得所有select结果。同时也支持__iter__方法。

    说明

    如果Select结果偏大，调用read()函数会阻塞直到select结果完全返回，同时占用过多的内存。建议使用__iter__方法（foreach chunk in result），然后对每个chunk进行处理。__iter__方法不仅可以降低内存使用，且OSS服务器端每处理一个请求chunk客户端都能及时处理，不必等到全部结果返回后才处理。

• select_object_to_file

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

  以上示例用于对指定Key的文件运行SQL，将查询结果写入指定的文件。

  涉及的参数描述与select_object相同。

• create_select_object_meta

  • create_select_object_meta的语法结构

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

    以上示例用于对指定Key的文件进行创建或者获取select meta。select meta是指该文件的总行数、总列数（CSV文件）、总的Split数。

    如果该文件已经创建过meta，则调用该函数不会重新创建，除非在参数中指定OverwriteIfExists为true。

    创建select meta需要扫描整个文件。

  • select_meta_params中支持的参数

    参数名称	描述
    Json_Type	当Json_Type没有指定时，默认为CSV文件。 若指定，必须为LINES，表示文件是JSON LINES。 说明 JSON DOCUMENT不支持该操作。
    RecordDelimiter	CSV文件换行符。
    FieldDelimiter	CSV文件列分隔符。
    QuoteCharacter	CSV文件列引号符。引号符内的行列分隔符按普通字符处理。
    CompressionType	压缩类型。目前不支持任何压缩类型，故只能为None。
    OverwriteIfExists	覆盖原有的Select Meta。正常情况无需使用该选项。

  • create_select_object_meta返回值：GetSelectObjectMetaResult对象，包括rows、splits两个属性。对于CSV文件，其内部的select_resp对象还包括columns值，表示CSV文件的列数。

相关文档

• 关于查询文件的完整示例代码，请参见GitHub示例。

• 关于查询文件的API接口说明，请参见SelectObject。