17. Pythonライブラリ#

17.1 はじめに#

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

17.2 概要#

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

17.3 動作環境#

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

• 本ライブラリの構成

17.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

17.4 ライブラリ使用#

17.4.1 sbhiveclモジュール#

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

書式

sbhivecl.init([env=None])

引数

説明

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

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

書式

sbhivecl.term()

引数

なし

説明

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

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

書式

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

引数

戻り値

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

説明

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

17.4.2 Connectionクラス#

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

書式

Connection.insert(name, data[, 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 にまとめて登録するデータ件数を指定します。

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

書式

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

引数

戻り値

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

説明

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

17.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])

引数

戻り値

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 を指定してください。デフォルトはメモリとファイルの両方を検索します。
    

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

書式

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

引数

戻り値

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

説明

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

17.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])

引数

戻り値

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

説明

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

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

• ExtraCursorOptionクラス

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

  • 統計グループ 統計グループを以下に記載します

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

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

書式

Connection.close()

引数

• なし

戻り値

• なし

説明

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

17.4.3 Cursorクラス#

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

• データ取得
  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))
  

  
  
  

17.4.4 Rowクラス#

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

• 分析データ
  Rowクラスは、イテレータとして使うことができるためfor文等で取得してください。
  イテレータが返す要素はColumnクラスのインスタンスになります。
  

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

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

17.4.5 Columnクラス#

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

• データタイムスタンプ
  データタイムスタンプは、分析したタイムスタンプではなく、 該当データのタイムスタンプがセットされます。
  

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

  from sbhivecl.cursor import ColumnIndicator
  

  以下に各インディケータについて説明します。

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

17.4.6 Statクラス#

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

17.4.7 Basicクラス#

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

17.5 例外#

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

• SbhiveError例外のプロパティ

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

17.5.1 エラー種別#

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

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

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