コンテンツにスキップ

14. Pythonライブラリ#

14.1 はじめに#

本書は、SpeeDBee Hive(以降Hiveと記載)のPythonライブラリ仕様を定義したものです。

14.2 概要#

本ライブラリは、Hiveのデータベースサービス(以降DBサービスと記載)で定義したデータに対して、登録および検索を行うためのPythonライブラリです。
本ライブラリを利用するためには、HiveのDBサービスを起動させる必要があります。HiveのDBサービス起動方法は、「SpeeDBee Hive(ユーザガイド)」ドキュメントを参照ください。

14.3 動作環境#

本ライブラリを利用するためには、以下の要件を満たす必要があります。

Pythonバージョン3.5以上
  • 本ライブラリの構成
sbhivecl-63.10098.0-py3-none-any.whlライブラリ

上記の63.10098.0の部分はHiveのバージョンにより異なりますので適宜読み替えてください。

注意

SpeeDBeeHiveをインストールした以外のマシン(PC/ゲートウェイ)で使用するには、 別途SpeeDBeeのライブラリが必要となります。別途お問い合わせ下さい。

14.3.1 ライブラリのインストール#

下記ディレクトリに配置されています。

/usr/local/share/speedbeehive/sbhivecl/
C:/Program Files/SALTYSTER/SpeeDBeeHive/python3/Lib/site-packages/sbhivecl/

本ライブラリはpipでインストールします。 Windowsではインストールは不要です。

  • インストール

    $ sudo pip3 install sbhivecl-63.10098.0-py3-none-any.whl
    

  • アンインストール

    $ sudo pip3 uninstall sbhivecl
    

Windowsで使用する場合はscript内で以下のように指定します。

import sys
sys.path.append('C:\Program Files\SALTYSTER\SpeeDBeeHive\python3\Lib\site-packages')
import sbhivecl
import sbhivecl.errorcode

14.4 ライブラリ使用#

14.4.1 sbhiveclモジュール#

14.4.1.1 sbhivecl.init() … ライブラリの初期化#

書式

sbhivecl.init([env=None])

引数

No. 引数 説明
1 env 環境パラメータ(デフォルト None)

説明

本ライブラリの初期化を行います。ライブラリの利用前に呼び出します。ライブラリを利用 するプログラムの最初に1度呼び出します。このライブラリはスレッドセーフではありません。 環境パラメータは現在未使用(None を設定)です。

14.4.1.2 sbhivecl.term() … ライブラリの終了#

書式

sbhivecl.term()

引数

なし

説明

本ライブラリの終了処理を行います。ライブラリを利用するプログラムの最後に1度呼び出し ます。このライブラリはスレッドセーフではありません。

14.4.1.3 sbhivecl.connect() … Hive に接続#

書式

sbhivecl.connect(host, port, user, password[, read_timeout=None, write_timeout=None])

引数

No. 引数 説明
1 host Hiveのアドレスを指定
2 port HiveのDBサービス設定画面で設定したポートを指定
3 user HiveのDBサービス設定画面で設定したユーザ名を指定
4 password HiveのDBサービス設定画面で設定したパスワードを指定
5 read_timeout HiveのDBサービスからのデータ受信タイムアウト値を指定
単位は秒、デフォルト値は30秒
6 write_timeout HiveのDBサービスへのデータ送信タイムアウト値を指定
単位は秒、デフォルト値は30秒

戻り値

Connection クラスのインスタンスを返します。

説明

HiveのDBサービスへ接続します。DBサービスで設定したパラメータを、各変数に指定してください。

14.4.2 Connectionクラス#

14.4.2.1 Connection.insert() … データ値の登録#

書式

Connection.insert(name, data[, data_cnt=1])

引数

No. 引数 説明
1 name データ名
2 data データ値(or データ値の配列)
3 data_cnt データ件数(デフォルト値1)

戻り値

登録された件数を返します。

説明

データ値を登録します。

  • データ型について
    「登録するデータ値のデータ型」は、「DB サービスで定義したデータのデータ型」 に対応するPython のデータ型を使用してください。

    DBサービスで定義したデータのデータ型 Pythonデータ型
    INT_8, INT_16, INT_32, INT64,
    UINT_8, UINT_16, UINT_32, UINT_64
    int
    FLOAT, DOUBLE float
    STRING string
    • DB サービス設定画面で設定したデータの配列数が 1 より大きい場合は、 データ値は配列数分の要素を持つリストにしてください。

    • サンプルレートが 1 以上の場合、データを複数件まとめて登録することが可能です。 その場合、引数の data_cnt にまとめて登録するデータ件数を指定します。

14.4.2.2 Connection.get_col_lval() … データの最新値を取得#

書式

Connection.get_col_lval(name[, data_size=0])

引数

No. 引数 説明
1 data_size デフォルト値0。
STRING型を取得する場合には、取得する文字列データのデータバイトサイズを指定。

戻り値

データの最新値をタプルで返します。タプルには以下の情報が入ります。

インデックス番号 データ
0 最新値のタイムスタンプ(マイクロ秒まで)(datatime型)
1 UTC 1970-01-01 00:00:00からの通算ナノ秒
2 取得した最新値

説明

指定されたデータの最新データを取得します。

14.4.2.3 Connection.open_analyze_cur() … 分析検索カーソルの作成#

書式

Connection.open_analyze_cur(names, st, et, iv[, representative_value=RepresentativeValue.TOP, last_value=True, storage=Storage.MEM | Storage.FILE])

引数

No. 引数 説明
1 names データ名の配列
2 st 分析期間の開始タイムスタンプ(datatime型)
3 et 分析期間の終了タイムスタンプ(datatime型)
4 iv 分析幅(マイクロ秒)
5 representative_value 分析オプション
代表値が区間の先頭か末尾かを指定(デフォルト:先頭)
6 last_value 分析オプション
区間内にデータがない場合の処理の指定(デフォルト:前回値を引き継ぐ)
7 storage 分析オプション
検索対象ストレージの指定(デフォルト:メモリとファイルの両方を検索)

戻り値

Cursorクラスのインスタンスを返します。

説明

分析検索用のカーソルを作成します。

  • 分析オプション
    representative_value と storage のオプションについては、列挙型で定義されていますので、 以下をインポートする必要があります。

    from sbhivecl.cursor import RepresentativeValue, Storage
    

    • representative_value
      分析する代表値が、区間内の先頭か末尾かを指定します。
      デフォルトは先頭、末尾を指定する場合は、RepresentativeValue.LAST を指定してください。

    • last_value
      区間内にデータがない場合に、前回値を引き継ぐか、NULL とするか指定します。
      デフォルトは前回値を引き継ぐ、NULL とする場合は、False を指定してください。

    • storage
      検索する対象ストレージを指定します。
      メモリ DB を参照したい場合は、Storage.MEM、ファイル DB を参照したい場合は、 Storage.FILE を指定してください。デフォルトはメモリとファイルの両方を検索します。

14.4.2.4 Connection.open_serialize_cur() … シリアライズ検索カーソルの作成#

書式

Connection.open_serialize_cur(names, st, et[, storage=Storage.MEM | Storage.FILE])

引数

No. 引数 説明
1 names データ名の配列
2 st 分析期間の開始タイムスタンプ(datatime型)
3 et 分析期間の終了タイムスタンプ(datatime型)
4 storage 検索対象ストレージの指定(デフォルト:メモリとファイルの両方を検索)

戻り値

Cursorクラスのインスタンスを返します。

説明

シリアライズ検索用カーソルを作成します。

14.4.2.5 Connection.open_analyze_curex() … 分析用拡張検索カーソルの作成#

書式

Connection.open_analyze_curex(names, st, et, iv, copt[, representative_value=RepresentativeValue.TOP, last_value=True, storage=Storage.MEM | Storage.FILE])

引数

No. 引数 説明
1 names データ名の配列
2 st 分析期間の開始タイムスタンプ(datatime型)
3 et 分析期間の終了タイムスタンプ(datatime型)
4 iv 分析幅(マイクロ秒)
5 copt 拡張カーソルオプション
6 representative_value 分析オプション
代表値が区間の先頭か末尾かを指定(デフォルト:先頭)
7 last_value 分析オプション
区間内にデータがない場合の処理の指定(デフォルト:前回値を引き継ぐ)
8 storage 分析オプション
検索対象ストレージの指定(デフォルト:メモリとファイルの両方を検索)

戻り値

Cursorクラスのインスタンスを返します。

説明

分析用拡張検索カーソルを作成します。
統計データを取得することが可能です。

  • 拡張カーソルオプション
    取得する統計データのパラメータを指定します。統計データを取得するカラム単位で指定してください。
    取得するカラム数分の ExtraCursorOption クラスのインスタンスを生成し、配列データを引数 copt に設定してください。

  • ExtraCursorOptionクラス

    No. 引数 説明
    1 name データ名
    2 stat_gopt 取得する統計データの統計グループ
    3 stat_opts 統計オプション(現在未使用)(デフォルトNone)
    • 統計グループ 統計グループを以下に記載します

      統計グループ 説明
      StatGroup.BASIC 基本統計量

14.4.2.6 Connection.close() … Hive接続の切断#

書式

Connection.close()

引数

  • なし

戻り値

  • なし

説明

HiveのDBサービスとの接続を閉じます。

14.4.3 Cursorクラス#

検索カーソルは Cursor クラスで定義されています。
Cursor クラスのインスタンスが持つプロパティについて以下に示します。

プロパティ名 説明
tcnt すべての指定カラムにおいて条件に一致したデータ件数
分析検索では、値が0である場合、該当データが見つからないことを示す。
(すべてのレコードは NUL レコードになる)
シリアライズ検索ではレコード件数
acnt 分析検索結果のレコード件数
  • データ取得
    Cursorクラスは、イテレータとして使うことができるため、for文等で取得してください。 イテレータが返す要素はRowクラスのインスタンスになります。
    使用例を以下に示します。
    for row in conn.open_analyze_curex(names, st, et, iv, copt):
      print("row.ts={} ({})".format(row.ts, row.ts_nsec))
      if row.is_null:
        continue
    
      for col in row:
        print("name={} ts={} ({}) val={}".format(col.name, col.ts, col.ts_nsec, col.val))
        if col.stat is not None:
          print("dcnt={} acnt={}".format(col.stat.dcnt, col.stat.acnt))
          for bs in col.stat.basic:
            print("cnt={} sum={} sumsq={}".format(bs.cnt, bs.sum, bs.sumsq))
    


14.4.4 Rowクラス#

1レコードの情報はRowクラスで定義されています。
Rowクラスのインスタンスが持つプロパティとメソッドについて以下に示します。

プロパティ名 説明
ts カレントレコードのタイムスタンプ(datatime型)
ts_nsec カレントレコードのタイムスタンプ
UTC 1970-01-01 00:00:00からの通算ナノ秒
cols 指定したカラム数分の分析データ(キーがデータ名の辞書型)
  • 分析データ
    Rowクラスは、イテレータとして使うことができるためfor文等で取得してください。
    イテレータが返す要素はColumnクラスのインスタンスになります。

14.4.4.1 Row.is_null … NULL レコードの判定#

取得されたレコードが NULL レコードか判定することができます。

14.4.5 Columnクラス#

分析データに関する情報は Column クラスで定義されています。
Column クラスのインスタンスが持つプロパティについて以下に示します。

プロパティ名 説明
name データ名
dtype データ型
ts データタイムスタンプ(datatime型)
ts_nsec データタイムスタンプ
UTC 1970-01-01 00:00:00からの通算ナノ秒
ind データ取得インディケータ
val データ値(or データ値の配列)
stat 統計データに関する情報
  • データタイムスタンプ
    データタイムスタンプは、分析したタイムスタンプではなく、 該当データのタイムスタンプがセットされます。

  • データ取得インディケータ
    データ取得インディケータは、列挙型として定義されています。
    使用する場合には、以下をインポートして下さい。

    from sbhivecl.cursor import ColumnIndicator
    
    以下に各インディケータについて説明します。

    インディケータ 説明
    ColumnIndicator. NOT_FOUND 該当カラムのデータが見つからない。(検索条件に一致するデータが存在しない)これは対象カラムのレコード全体で、同じステータスが返される。
    ColumnIndicator. NUL カレントの分析のタイムスタンプ区間内において対象データが存在しない。
    ColumnIndicator. GET カレントの分析のタイムスタンプ区間内において対象データが存在し、データをcolumnインスタンスにセットした。
    ColumnIndicator. VAL_CONT 分析オプション last_value が「前回値を引き継ぐ」に設定されている場合に、カレントの分析のタイムスタンプ区間内において対象データが存在せず、その前の値を繰り返しセットしたことを示す。

14.4.6 Statクラス#

統計データに関する情報は Stat クラスで定義されています。
Stat クラスのインスタンスが持つプロパティについて以下に示します。

プロパティ名 説明
dcnt データ数
acnt 配列個数。カラムが配列型で定義されていた場合はその数。
各統計データの結果はこの個数分の配列に格納される。
stime データ範囲(分析区間)の開始タイムスタンプ(datatime型)
stime_nsec データ範囲(分析区間)の開始タイムスタンプ
UTC 1970-01-01 00:00:00からの通算ナノ秒
etime データ範囲(分析区間)の終了タイムスタンプ(datatime型)
etime_nsec データ範囲(分析区間)の終了タイムスタンプ
UTC 1970-01-01 00:00:00からの通算ナノ秒
basic 統計データ

14.4.7 Basicクラス#

統計データは Basic クラスで定義されています。
Basic クラスのインスタンスが持つプロパティについて以下に示します。

プロパティ名 説明
cnt データ件数
sum 総和
sumsq 2乗和
sumsqd 偏差平方和
min 最小値
max 最大値
rng 範囲
mean 算術平均値
var 分散
stdev 標準偏差
uvar 不偏分散
ustdev 標本不偏標準偏差
stder 標準誤差
cv 変動係数

14.5 例外#

本ライブラリでエラーが発生するとSbhiveError例外が送出されます。

  • SbhiveError例外のプロパティ

    プロパティ名 説明
    errmsg エラーの内容
    errno errorcodeモジュールで定義されているエラーコード詳細は「エラー種別」を参照してください。
    dberrno DBサービス内で定義されているエラーコード詳細は「DBサービスエラーコード」を参照してください。

14.5.1 エラー種別#

errorcode モジュールには以下のように定義されています。

種別 コード 説明
DATA_ERROR 1 登録するデータ値に関する例外
DB_ERROR 99 データベースに関する例外

14.5.2 DBサービスエラーコード#

DB_ERRORの例外が発生した際に出力される、DBサービス内で定義されたエラーコードは以下になります。

番号 説明
1013 接続エラー
92503 認証エラー
92504 セッションタイムアウト
92507 最大接続数を超えた
92508 受信タイムアウト
92509 送信タイムアウト
182202 データ名が一致しない
192102 接続パラメータのUSERが指定されていない
192103 接続パラメータのPASSWORDが指定されていない
192107 接続パラメータのUSERまたは、PASSWORDが間違っている
192501 DBサービスに接続していない