跳至主要内容
版本：v3

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()

Query​

Query 是 client.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 是非同步的，在取得資料或是任何結果相關資訊例如 columns、row_count 等，必須先確保 SQL 執行完成。

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

  • get_all()

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

  • get_first(limit: number)

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

  • get_last(limit: number)

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

  • get(limit: number, offset: number)

    依照給予的 limit 以及 offset 回傳部分資料。當 data_format 為 list 或是 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'>