delika Python Client

Preview: This feature in preview state and might change or have limited support.

Requirements

Python 3.7+

Installation

# delika client only
pip install --extra-index-url=https://docs.delika.io/python/ delika
# delika client with Pandas and other dependent packages
pip install --extra-index-url=https://docs.delika.io/python/ delika[DataFrame]

If you have already installed delika or other dependencies (e.g. Pandas), you may want to upgrade them with --upgrade and --upgrade-strategy options.

pip install --upgrade --upgrade-strategy=eager --extra-index-url=https://docs.delika.io/python/ delika[DataFrame]

Low-Level API

Low-level API is an API client generated by OpenAPI generator. We do not recommend for users to use low-level API. Use high-level API below instead.

High-Level API

High-level API is a wrapper for the API client generated by OpenAPI generator.

References

Modules

  • delika: high-level API
  • delika.api_v1: low-level API
  • delika.pandas: work with Pandas data frame

Functions

  • delika.new_token(host, open_browser): Get JWT.
    • host: API host (default: https://api.delika.io/v1).
    • open_browser: Boolean value that indicates your program opens your browser at the point.
  • delika.read_token(key, path): Read JWT from local file.
    • key: Key.
    • path: Local file path (default: $HOME/.delika/token.json).
  • delika.new_client(token, host): Create a new instance of ApiClient.
    • token: JWT.
    • host: API host (default: https://api.delika.io/v1).
  • delika.load_client(key, path, host): Create a new instance of ApiClient.
    • key: Key.
    • path: Local file path (default: $HOME/.delika/token.json).
    • host: API host (default: https://api.delika.io/v1).
  • delika.pandas.read_delika_data(account_name, dataset_name, data_name, client): Read data into a data frame.
    • account_name: Account name.
    • dataset_name: Dataset name.
    • data_name: Data name.
    • client: ApiClient instance.
  • async delika.pandas.read_delika_sql(sql, client, query_timeout_sec): Run SQL and read the results into a data frame.
    • sql: SQL.
    • client: ApiClient instance.
    • query_timeout_sec: Timeout in second (default: 30)
  • delika.pandas.read_delika_query_results(query_id, client): Read the query results into a data frame.
    • query_id: Query ID.
    • client: ApiClient instance.
  • deprecated delika.pandas.to_delika(data, account_name, dataset_name, data_name, client): Upload data frame. This function is deprecated. Use to_delika_file instead.
    • data: Data frame.
    • account_name: Account name.
    • dataset_name: Dataset name.
    • data_name: Data name.
    • client: ApiClient instance.
  • delika.pandas.to_delika_file(data, account_name, dataset_name, data_name, client): Upload data frame into data file dataset.
    • data: Data frame.
    • account_name: Account name.
    • dataset_name: Dataset name.
    • data_name: Data name.
    • client: ApiClient instance.
  • delika.pandas.to_delika_collection(data, partition_column_name, account_name, dataset_name, data_name, client): Upload data frame into data collection dataset.
    • data: Data frame.
    • partition_column_name: Partition column name in the data frame. The value type of specified column must be string.
    • account_name: Account name.
    • dataset_name: Dataset name.
    • data_name: Data name (e.g. if foo.csv is given, uploaded file will be like 2020__foo.csv according to partition values).
    • client: ApiClient instance.

Types

  • delika.Jwt: Data class to hold JWT
    • token_type: Bearer.
    • access_token: Access token.
    • access_token_expires_on: Expiration time of access token.
    • refresh_token: Refresh token.
    • refresh_token_exipres_on: Expiration time of refresh token.
    • refresh(client): Refresh the current JWT.
      • client: OpenAPI client. It is convenient to use delika.ApiClient.refresh_jwt() instead of calling this method directly.
    • save(key, path): Save the current token in the specified path.
      • key: Token name.
      • path: Token file path (default: ~/.delika/token.json for Linux or macOS, %APPDATA%\delika\token.json for Windows)
  • delika.ApiClient: A wrapper class for ApiClient generated by OpenAPI generator
    • token: JWT which is hold by the client.
    • host: The API host.
    • refresh_token(): Refresh the client's JWT.
    • get_user_datasets(): Get your datasets.
    • get_account_datasets(account_name): Get the list of account's datasets.
      • account_name: Account name.
    • get_dataset_data(account_name, dataset_name): Get the list of dataset's data.
      • account_name: Account name.
      • dataset_name: Dataset name.
    • upload_data(account_name, dataset_name, data_name, schema, source, force_generate_table_definition): Download data.
      • account_name: Account name.
      • dataset_name: Dataset name.
      • data_name: Data name.
      • schema: Data schema.
      • source: Local file path to upload.
      • force_generate_table_definition: Indicates whether TableDefinition in data schema is generated automatically and replaces if TableDefinition is defined in the data schema.
    • download_data(account_name, dataset_name, data_name, destination): Download data.
      • account_name: Account name.
      • dataset_name: Dataset name.
      • data_name: Data name.
      • destination: Local file path or buffer to save.
    • start_query(sql): Post the SQL.
      • sql: SQL.
    • get_query_status(query_id): Get the query status.
      • query_id: Query ID.
    • download_query_results(query_id, destination): Download the query results.
      • query_id: Query ID.
      • destination: Local file path or buffer to save.

Data Types

delika Python (Pandas)
boolean pandas.BooleanDtype
number numpy.float64
factor pandas.CategoricalDtype
datetime pandas.DatetimeTZDtype
text pandas.StringDtype

Examples

Basic Use

import delika

# get JWT (launch a browser)
token = delika.new_token()
# save JWT to the default path with the default key ('Default').
token.save()
# create a new API client.
client = delika.new_client(token)

# you can create a new API client from saved JWT.
# client = delika.load_client()

# work with the API client.
my_datasets = client.get_user_datasets()
print(my_datasets)

# when your access_token is expired, you can refresh your JWT.
client.refresh_token()
# you need to save explicitly.
client.token.save()

Pandas

import delika.pandas

# read data as a data frame.
df1 = delika.pandas.read_delika_data(account_name, dataset_name, data_name, client)

# read SQL results as a data frame.
import asyncio
df2 = asyncio.run(delika.pandas.read_delika_sql(sql, client))

# upload from your data frame into data file
import pandas
df3 = pandas.DataFrame(...)
# the following two expressions are same
delika.pandas.to_delika_file(df3, account_name, dataset_name, data_name, client)
df3.delika.to_delika_file(account_name, dataset_name, data_name, client)

# upload from your data frame into data collection
df4 = pandas.DataFrame({'year':['2021',...], ...})
delika.pandas.to_delika_collection(df4, 'year', account_name, dataset_name, data_name, client)
df4.delika.to_delika_collection('year', account_name, dataset_name, data_name, client)

Version History

  • 0.0a4
    • Support uploading files into data collection dataset
    • Deprecate to_delika function
  • 0.0a3
    • Add read_delika_query_results function
  • 0.0a2
    • Rename functions
    • Add upload functions
  • 0.0a1
    • Initial release