開發 - Python Client

Installation

pip install cannerflow-python-client

Constructor

Normal Python Env

client = cannerflow.client.bootstrap(

endpoint='https://web.default.myname.apps.cannerflow.com',

workspace_id='444e8753-a4c0-4875-bdc0-834c79061d56',

token='Y2xpZW50XzA0OTgzODM4LWNhZjktNGNmZi1hNDA4LWFkZDY3ZDc5MjIxNjo2N2YyNGY5OWEzYjFiZTEyZTg2MDI2MmMzNGQzZDRiYQ=='

)

Name	Type	Description
endpoint	string	CannerFlow 的網址，例如: https://web.default.myname.apps.cannerflow.com.
token	string	Personal access token, 請參閱 取得 Personal Access Token
workspace_id	string	每個工作區都會有一個獨一無二的 ID，會顯示在工作區的網址。例如 https://web.default.myname.apps.cannerflow.com/workspaces/444e8753-a4c0-4875-bdc0-834c79061d56

In CannerFlow Jupyter Notebook

client

In CannerFlow Jupyter Notebook, we'll initialize the client for you, so you don't have to setup any credentials.

Learn more about Jupyter Notebook in CannerFlow

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