Skip to main content
Version: v1

Python SDK

Installation

pip install canner-python-client

Constructor

client = canner.client.bootstrap(
endpoint='https://web.default.myname.apps.cannerdata.com/web',
workspace_id='444e8753-a4c0-4875-bdc0-834c79061d56',
token='Y2xpZW50XzA0OTgzODM4LWNhZjktNGNmZi1hNDA4LWFkZDY3ZDc5MjIxNjo2N2YyNGY5OWEzYjFiZTEyZTg2MDI2MmMzNGQzZDRiYQ=='
)
NameTypeDescription
endpointstringCanner Enterprise 的網址到 /web 的部分,例如: https://web.default.myname.apps.cannerdata.com/web.
tokenstringPersonal access token, 請參閱 取得 Personal Access Token
workspace_idstring每個工作區都會有一個獨一無二的 ID,會顯示在工作區的網址。例如 https://web.default.myname.apps.cannerdata.com/web/workspaces/444e8753-a4c0-4875-bdc0-834c79061d56

Saved SQL Operations

List Saved Query

  • list_saved_query(): Array<string>

    列出工作區內所有已儲存 SQL 語句的標題。

    queries = client.list_saved_query()
    print(queries)
    # ['select_users1', 'select_users2']

Use Saved Query

  • use_saved_query(title: string, data_format: data_format, cache_refresh: boolean, cache_ttl: number): Query

    執行完成之後,返回的物件為 Query,提供不同的方法對資料做操作。例如: 可以透過 query.get_all() 取得所有的資料。

    • title: 要執行的 SQL Query 標題
    • data_format: 決定 query 回傳的資料格式,目前提供 list, df, np 三種,預設為 list
    • cache_refresh: True 或是 False,預設為 False。是否更新現有的快取資料,如果想取得快取資料,此選項應設定為 False
    • cache_ttl: 秒數,最早可允許幾秒前的快取資料,預設為 86400(允許一天內的快取)。只在 cache_refresh=False時有效。
    queries = client.list_saved_query()
    # ['select_users1', 'select_users2']
    query = client.use_saved_query(queries[0], data_format='list')
    query.wait_for_finish()
    data = query.get_all()

Query Operations

Generate Query

  • gen_query(sql: string, data_format: data_format): Query

    執行完成之後,返回的物件為 Query,提供不同的方法對資料做操作。例如: 可以透過 query.get_all() 取得所有的資料。

    • sql: 要執行的 SQL 語句
    • data_format: 決定 query 回傳的資料格式,目前提供 list, df, np 三種,預設為 list
    query = client.gen_query('select * from canner.myworkspace.users', data_format='list')
    query.wait_for_finish()
    data = query.get_all()

File Operations

List File

  • list_file(): Array<string>

    列出工作區內所有檔案的絕對路徑。這些絕對路徑作為你之後取得檔案的參數。

    files = client.list_file()
    print(files)
    # ['/data.csv', '/folder/data.json']

Read CSV File

  • get_csv(absolute_path: string): List

    csv = client.get_csv('/data.csv')
    print(csv)
    # [['id', 'first_name', 'last_name', 'email', 'gender', 'ip_address'],
    # ['1', 'Vina', 'Dietz', 'vdietz0@amazon.com', 'Female', '58.198.39.195'],
    # ['2', 'Catharine', 'Dore', 'cdore1@zdnet.com', 'Female', '181.18.237.86'],
    # ['3', 'Lammond', 'Bricket', 'lbricket2@patch.com', 'Male', '227.86.240.205'],
    # ...
    # ]
  • get_pandas_csv(absolute_path: string): DataFrame

    如果你想使用 pandas,這個方法可以直接將你的 csv 轉成 pandasDataFrame

    pd_csv = client.get_pandas_csv('/data.csv')
    print(type(pd_csv))
    # <class 'pandas.core.frame.DataFrame'>
    pd_csv.head(1)
    # id first_name last_name email gender ip_address
    # 0 1 Vina Dietz vdietz0@amazon.com Female # 58.198.39.195

Read JSON File

  • get_json(absolute_path: string): JSON

    json = client.get_json('/data.json')
    print(json)
    # [
    # {'id': {'$oid': '5ccbb8ddfc13ae1baf00000a'}, 'first_name': 'Isabelle', 'last_name': 'Zarfati', 'email': 'izarfati0@typepad.com', 'gender': 'Female', 'ip_address': '30.231.98.125'},
    # {'id': {'$oid': '5ccbb8dffc13ae1baf0003f1'}, 'first_name': 'Hayley', 'last_name': 'Brian', 'email': 'hbrianrr@google.co.uk', 'gender': 'Female', 'ip_address': '16.64.29.80'}
    # ]

  • get_pandas_json(absolute_path: string): DataFrame

    如果你想使用 pandas,這個方法可以直接將你的 json 轉成 pandasDataFrame

    pd_json = client.get_pandas_json('/data.json', orient='records')
    print(type(pd_json))
    # <class 'pandas.core.frame.DataFrame'>
    pd_json.head()
    # email first_name gender id ip_address last_name
    # 0 izarfati0@typepad.com Isabelle Female {'$oid': '5ccbb8ddfc13ae1baf00000a'} 30.231.98.125 Zarfati
    # 1 hbrianrr@google.co.uk Hayley Female {'$oid': '5ccbb8dffc13ae1baf0003f1'} 16.64.29.80 Brian

Read Image

  • get_pil_image(absolute_path: string): PIL

    將圖片轉成 PIL(Python Image Library)的格式。

    pil_image = client.get_pil_image('/file.jpg')
    print(type(pil_image))
    # <class 'PIL.JpegImagePlugin.JpegImageFile'>
  • get_np_image(absolute_path: string): ndarray

    如果你要使用 scikit-image,可以使用這個方法將圖片轉成 numpy.ndarray。就能利用 scikit-image 的方法對圖片進行操作

    from skimage import io
    np_image = client.get_np_image('/file.jpg')
    print(type(np_image))
    # <class 'numpy.ndarray'>
    io.imshow(np_image)

Put CSV File

  • put_csv(absolute_path: string, data: list): Boolean

    data = [['col1', 'col2'], ['val1', 'val2']]
    result = client.put_csv('/data.csv', data)
    print(result)
    # True
  • put_csv(absolute_path: string, data: pd.DataFrame): Boolean

    import pandas as pd
    data = pd.DataFrame([{
    'col1': 'val1',
    'col2': 'val2'
    }])
    result = client.put_csv('data.csv', data)
    print(result)
    # True

Put JSON File

  • put_json(absolute_path: string, data: dict): Boolean

    data = {'key': 'value'}
    result = client.put_json('data.json', data)
    print(result)
    # True
  • put_json(absolute_path: string, data: pd.DataFrame): Boolean

    data = {'Product': {'0': 'value', '1': 'value2'}}
    result = client.put_json('data.json', data)
    print(result)
    # True

Query

Queryclient.gen_query 以及 client.use_saved_query 所回傳的物件。

example: use_saved_query

queries = client.list_saved_query()
# ['select_users1', 'select_users2']
query = client.use_saved_query(queries[0])
query.wait_for_finish()
data = query.get_all()

example: gen_query

query = client.gen_query('select * from canner.myworkspace.users')
query.wait_for_finish()
data = query.get_all()

Properties

  • columns

    columns 資訊

    query.columns
    # [{'name': 'status',
    # 'type': 'varchar',
    # 'typeSignature': {'rawType': 'varchar',
    # 'typeArguments': [],
    # 'literalArguments': [],
    # 'arguments': [{'kind': 'LONG_LITERAL', 'value': 2147483647}]}
    # }]
  • row_count

    資料總筆數

    query.row_count
    # 100

Get Data

  • wait_for_finish(timeout=5, period=3)

    執行 SQL 是非同步的,在取得資料或是任何結果相關資訊例如 columnsrow_count 等,必須先確保 SQL 執行完成。

    • timeout: 秒數,最長等待時間。
    • period: 秒數,每幾秒中檢查 Query 狀態是否完成。
  • get_all()

    回傳所有資料。當 data_formatlist 或是 df 的時候會包含欄位列。

  • get_first(limit: number)

    回傳前幾筆資料,預設為一筆。當 data_formatlist 或是 df 的時候會包含欄位列。

  • get_last(limit: number)

    回傳最後幾筆資料,預設為一筆。當 data_formatlist 或是 df 的時候會包含欄位列。

  • get(limit: number, offset: number)

    依照給予的 limit 以及 offset 回傳部分資料。當 data_formatlist 或是 df 的時候會包含欄位列。

Data Format

目前提供 3 種資料格式

  • list: Python list,為預設值
  • df: DataFrame
  • np: Numpy.ndarray

你可以在 client.gen_query 或是 client.use_saved_query 時指定

query = client.use_saved_query('query_name', data_format="list")
print(type(query.get_first()))
# <class 'list'>
query = client.use_saved_query('query_name', data_format="df")
print(type(query.get_first()))
# <class 'pandas.core.frame.DataFrame'>
query = client.use_saved_query('query_name', data_format="np")
print(type(query.get_first()))
# <class 'numpy.ndarray'>

也可以隨時改變 query.data_format 使用不同的 data_format。

query = client.use_saved_query('query_name')

query.data_format = 'list'
print(type(query.get_first()))
# <class 'list'>
query.data_format = 'df'
print(type(query.get_first()))
# <class 'pandas.core.frame.DataFrame'>
query.data_format = 'np'
print(type(query.get_first()))
# <class 'numpy.ndarray'>