Version: v1

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

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 轉成 pandas 的 DataFrame。

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 轉成 pandas 的 DataFrame。

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

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

Installation​

Constructor​

Saved SQL Operations​

List Saved Query​

Use Saved Query​

Query Operations​

Generate Query​

File Operations​

List File​

Read CSV File​

Read JSON File​

Read Image​

Put CSV File​

Put JSON File​

Query​

Properties​

Get Data​

Data Format​