Python SDK
Installation
pip install canner-python-client
Constructor
- Normal Python Env (Standalone Mode)
- Normal Python Env (Cluster Mode)
client = canner.client.bootstrap(
endpoint='https://web.default.myname.apps.cannerdata.com/web',
workspace_id='444e8753-a4c0-4875-bdc0-834c79061d56',
token='Y2xpZW50XzA0OTgzODM4LWNhZjktNGNmZi1hNDA4LWFkZDY3ZDc5MjIxNjo2N2YyNGY5OWEzYjFiZTEyZTg2MDI2MmMzNGQzZDRiYQ=='
)
Name | Type | Description |
---|---|---|
endpoint | string | Canner Enterprise 的網址到 /web 的部分,例如: https://web.default.myname.apps.cannerdata.com/web . |
token | string | Personal access token, 請參閱 取得 Personal Access Token |
workspace_id | string | 每個工作區都會有一個獨一無二的 ID,會顯示在工作區的網址。例如 https://web.default.myname.apps.cannerdata.com/web/workspaces/ 444e8753-a4c0-4875-bdc0-834c79061d56 |
client = canner.client.bootstrap(
endpoint='https://web.default.myname.apps.cannerdata.com',
workspace_id='444e8753-a4c0-4875-bdc0-834c79061d56',
token='Y2xpZW50XzA0OTgzODM4LWNhZjktNGNmZi1hNDA4LWFkZDY3ZDc5MjIxNjo2N2YyNGY5OWEzYjFiZTEyZTg2MDI2MmMzNGQzZDRiYQ=='
)
Name | Type | Description |
---|---|---|
endpoint | string | Canner Enterprise 的網址,例如: https://web.default.myname.apps.cannerdata.com . |
token | string | Personal access token, 請參閱 取得 Personal Access Token |
workspace_id | string | 每個工作區都會有一個獨一無二的 ID,會顯示在工作區的網址。例如 https://web.default.myname.apps.cannerdata.com/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'>