Post on 10-May-2015
HBase: The Definitive Guide
CHAPTER 4
Client API: Advanced Features
この章の内容
• Filters ※すみません、ここまでしか書いてません。。
• Counters
• Coprocessors
• HTablePool
• Connection Handling
Filter
• Scan や Get に適用可能
– #setFilter(filter)
• 検索条件を指定して結果を絞る
• 絞り込みはサーバサイドで実行される
– Figure 4-1 (p138)
• クライアントで定義
• シリアライズしてサーバに送信
• サーバでデシリアライズされて実行
Filter
• 階層
– Filter(interface) <- FilterBase <- ●●Filter
• 絞り込み対象
– Row key
– カラムファミリー名
– カラム名(qualifier)
–値(value)
– Timestamp など
比較 operator (CompareFilter.CompareOp)
• LESS
• LESS_OR_EQUAL
• EQUAL
• NOT_EQUAL
• GREATER_OR_EQUAL
• GREATER
• NO_OP
Comparator(WritableByteArrayComparable)
• BinaryComparator– 完全一致 (byte[]のまま比較)
• BinaryPrefixComparator– 前方一致 (同上)
• NullComparator• BitComparator• RegexStringComparator
– 正規表現 (byte*+ → String → Pattern.matcherで比較)
• SubstringComparator– 中間一致 (byte*+ → String → #toLowerCase → #contains で比較)
※↑最後の3つのComparatorは、 EQUAL、 NOT_EQUAL のみ指定可能。
CompareFilterのサブクラス
• 階層
– Filter(interface) <- FilterBase <- CompareFilter <-●●Filter
• RowFilter
• FamilyFilter
• QualifierFilter
• ValueFilter
• DependentColumnFilter
RowFilter
• RowKeyが条件に合うカラムを返す。• Example 4-1 (p141)
– Filter1• RowKey <= "row-22“
– LESS_OR_EQUAL– BinaryComparator
• 結果– row-1– row-10– row-100– row-11– …(中略)– row-22
RowFilter• Example 4-1 (p141)
– Filter2• RowKey = ".*-.5" (正規表現)
– EQUAL– RegexStringComparator
• 結果– row-15– row-25– …(中略)– row-95
– Filter3• RowKey like '%-5%' (中間一致)
– EQUAL– SubstringComparator
• 結果– row-5– row-50– …(中略)– row-59
FamilyFilter
• カラムファミリー名が条件に合うカラムを返す。• Example 4-2 (p142)
– Filter1• family < "colfam3“
– LESS– BinaryComparator
• 結果– colfam1, colfam2 を返す。– colfam3 は返さない。
– Filter2• family = "colfam3“
– EQUAL– BinaryComparator
• Get#addFamily("colfam1") を指定• 結果=何も返さない
QualifierFilter/ValueFilter
• QualifierFilter– カラム名(qualifier名)が条件に合うカラムを返す。
• ValueFilter– カラムの値が条件に合うカラムを返す。
– (値=“a”) で条件指定する。• col1=“a”, col2=“a” …全てのカラムを判定する。
– 後述の SingleColumnValueFilterはカラム名を指定するところが違う• (col1=“a”)で条件指定する。
DependentColumnFilter
• 比較内容– valueでの比較– 指定したカラムと、timestampが一致するか
• Scan#setBathは指定できない。– #hasFilterRow() がtrueを返す– P167 Filters Summary 参照
• Example 4-5 (p145~)– (1)“colfam1:col-5“, true, operatorとcomparator無し
• "colfam1:col-5" と同じtimestamp のカラムを返す。• ただし、"colfam1:col-5"自身は除く。
– (2)“colfam1:col-5“, false, operatorとcomparator無し• "colfam1:col-5" と同じtimestamp のカラムを返す。• "colfam1:col-5"自身も含む。
DependentColumnFilter
• Example 4-5 (p145~)– (3)“colfam1:col-5“, true, EQUAL, BinaryPrefixComparator("val-5")
• value like “val-5%” (前方一致) に一致して、且つ、• "colfam1:col-5" と同じtimestamp のカラムを返す。• ただし、"colfam1:col-5"自身は除く。
– (4)“colfam1:col-5“, false , EQUAL, BinaryPrefixComparator("val-5")• value like “val-5%” (前方一致) に一致して、且つ、• "colfam1:col-5" と同じtimestampのカラムを返す。• “colfam1:col-5”自身も含む。
– (5)“colfam1:col-5“, true, EQUAL, RegexStringComparator(".*¥¥.5“)• value = “.*¥¥.5” (正規表現) に一致して、且つ、• “colfam1:col-5” と同じtimestampのカラムを返す。• ただし、"colfam1:col-5"自身は除く。
– (6)“colfam1:col-5“, false, EQUAL, RegexStringComparator(".*¥¥.5")• value = “.*¥¥.5” (正規表現) に一致して、且つ、• "colfam1:col-5" と同じtimestampのカラムを返す。• “colfam1:col-5”自身も含む。
専用フィルタ• SingleColumnValueFilter• SingleColumnValueExcludeFilter• PrefixFilter• PageFilter• KeyOnlyFilter• FirstKeyOnlyFilter• InclusiveStopFilter• TimestampsFilter• ColumnCountGetFilter• ColumnPaginationFilter• ColumnPrefixFilter• RandomRowFilter
SingleColumnValueFilterSingleColumnValueExcludeFilter
• CompareFilterは継承していないが、引数の指定の仕方は同じ。– 比較Operator(CompareFilter.CompareOp)– Comparator(WritableByteArrayComparable)
• 補助的なメソッド– #setFilterIfMissing(boolean)
• false(デフォルト)の場合、指定カラムが存在しない行(ROW)も返る。
– #setLatestVersionOnly(boolean)• true(デフォルト)の場合、最新バージョンのカラムのみが返る。
• ValueFilterとの違い– カラム名を指定可能。そのカラムの値が条件に合うカラムを返す。– 条件に合う場合、そのRowの全てのカラムを返す。
– SingleColumnValueExcludeFilter は 判定に使ったカラムは返されない。
SingleColumnValueFilter (p147~)SingleColumnValueExcludeFilter
• 例)
– row-1 colfam1:col-1 Value:val-1
– row-1 colfam1:col-2 Value:val-5
– row-2 colfam1:col-1 Value:val-5
– row-2 colfam1:col-2 Value:val-10
– row-3 colfam1:col-3 Value:val-100
• ValueFilter EQUAL SubstringComparator("val-5")– row-1 colfam1:col-2 Value:val-5
– row-2 colfam1:col-1 Value:val-5
• SingleColumnValueFilter “colfam1:col-1” EQUALSubstringComparator(“val-5”) ※setFilterIfMissing(true)– row-2 colfam1:col-1 Value:val-5
– row-2 colfam1:col-2 Value:val-10
• SingleColumnValueExcludeFilter “colfam1:col-1” EQUALSubstringComparator(“val-5”) ※setFilterIfMissing(true)– row-2 colfam1:col-2 Value:val-10
SingleColumnValueFilter (p147~)SingleColumnValueExcludeFilter
• 例)
– row-1 colfam1:col-1 Value:val-1
– row-1 colfam1:col-2 Value:val-5
– row-2 colfam1:col-1 Value:val-5
– row-2 colfam1:col-2 Value:val-10
– row-3 colfam1:col-3 Value:val-100
• SingleColumnValueFilter “colfam1:col-1” EQUALSubstringComparator(“val-5”) ※setFilterIfMissing(false)– row-2 colfam1:col-1 Value:val-5
– row-2 colfam1:col-2 Value:val-10
– row-3 colfam1:col-3 Value:val-100
• SingleColumnValueExcludeFilter “colfam1:col-1” EQUALSubstringComparator(“val-5”) ※setFilterIfMissing(false)– row-2 colfam1:col-2 Value:val-10
– row-3 colfam1:col-3 Value:val-100
PrefixFilter (p149)
• 行キーの先頭部分が一致する行(ROW)の全カラムを返す。
• new PrefixFilter(Bytes.toBytes("row-1"))
• new RowFilter(
CompareFilter.CompareOp.EQUAL,
new BinaryPrefixComparator(Bytes.toBytes("row-1")));
• 上の2つは同じ結果
PageFilter (p149~)• 行(ROW)数を指定。最大N行分の全カラムを返す。• フィルターはRegionごとに平行で動作するため、クライアントに返る行数はN行以上になるはず。。
• Example 4-8– クライアント側で、取得したlast rowを覚えておいてwhile ((result = scanner.next()) != null) {
System.out.println(localRows++ + ": " + result);totalRows++;lastRow = result.getRow();
}– 次のScanで startRowを更新 (POSTFIX = new byte[] {0})if (lastRow != null) {
byte[] startRow = Bytes.add(lastRow, POSTFIX);System.out.println("start row: "
+ Bytes.toStringBinary(startRow));scan.setStartRow(startRow);
}
KeyOnlyFilter (p151)
• Keyのみ返す。– Valueを取り除いた結果を返す。
– コンストラクタにtrueを渡すと、Valueのlengthを返す。
• FilterList(※後述)で他のFilterと組み合わせて使ってみた例)
– KeyOnlyFilter適用前• row-1 colfam1:col-1 Value:val-1
– new KeyOnlyFilter() を FilterListに追加• row-1 colfam1:col-1 Value:
– ※(val-1が除去されている)
– new KeyOnlyFilter(true) を FilterListに追加• row-1 colfam1:col-1 Value:5
– ※(val-1のlengh=5が返る)
FirstKeyOnlyFilter (p151)
• 各行(ROW)において、先頭のカラムを返す。(1行につき1個)
• ユースケース
– ROWカウンター
– column qualifier に epoch 値を指定したときに、ソートされているので、1回のScanで各行の一番古いtimestampのカラムだけ取得
InclusiveStopFilter (p151~)
• Scanで指定するstop row は exclusive に対して、そのstop rowも結果に含めたい場合に使用する。
TimestampsFilter (p152~)• 指定されたtimestampと一致するデータを返す。
• List で timestamp を複数指定可能
• このFilterでレンジ指定はできない。→Scan#setTimeRange
• Example 4-10 (p153)– Scan1
• timestamp=5,10,15 のカラムのみを取得
– Scan2• timestamp=5,10,15 且つ、
• Scan#setTimeRange(8, 12)– timestamp=10 のカラムのみを取得
ColumnCountGetFilter (p154)
• Scanではなく、Getで使用するためのFilter。
• 1行(Row)の取得最大カラム数を指定する。
ColumnPaginationFilter (p154~)
• PageFilterが行(ROW)数を指定したのに対し、このFilterは1行あたりのカラム数を指定する。
• limit, offset を指定。→ 先頭 offset 個を除いた最大 limit 個のカラムが返る。
ColumnPrefixFilter (p155)
• PrefixFilter(行キーの先頭部分が一致)に対して、このFilterはカラム名の先頭部分が一致するカラムを返す。
• new ColumnPrefixFilter(Bytes.toBytes("col-1"))• new QualifierFilter(CompareFilter.CompareOp.EQUAL,
new BinaryPrefixComparator(Bytes.toBytes("col-1")));• 上の2つは同じ結果
RandomRowFilter (p155)
• RandomRowFilter(float chance)
– コンストラクタの引数には、0.0 and 1.0 の範囲の値を指定する。
–引数にマイナス値を渡した場合は結果は全て除外される。
–引数に1.0より大きい値を渡した場合は結果は全ての行を含む。
Decorating Filters
• SkipFilter
• WhileMatchFilter
SkipFilter (p155~)• Rowの全カラムがWrap対象のFilterの条件に適合する場合のみ返す
• 例)– row-1 colfam1:col-1 Value:val-1– row-1 colfam1:col-2 Value:val-5– row-2 colfam1:col-1 Value:val-5– row-2 colfam1:col-2 Value:val-10– row-3 colfam1:col-3 Value:val-100– row-4 colfam1:col-1 Value:val-5– row-4 colfam1:col-2 Value:val-5
• ValueFilter EQUAL SubstringComparator("val-5")– row-1 colfam1:col-2 Value:val-5– row-2 colfam1:col-1 Value:val-5– row-4 colfam1:col-1 Value:val-5– row-4 colfam1:col-2 Value:val-5
• 上の ValueFilterを SkipFilterでWrap– row-4 colfam1:col-1 Value:val-5– row-4 colfam1:col-2 Value:val-5
WhileMatchFilter (p157~)
• Wrap対象のFilterの条件に適合しなくなったら、それ以降の全Scanをスキップする。
• Example 4-13 (p157~)–条件:RowFilter
• NOT_EQUAL
• BinaryComparator("row-05")
– Results of scan #2: (p158)• row-04 まで読み込んで、row-05が条件に適合しないので、そこでScan全体が終了。
FilterList (p159~)
• 複数のFilterを組み合わせる• FilterListクラスも Filter インタフェースを implement している。
• Table 4-3. FilterList.Operator enumeration (p159)– MUST_PASS_ALL
• 全てのフィルターを満たす場合に結果に含まれる。※AND条件
– MUST_PASS_ONE• どれか1個のフィルターを満たす場合に結果に含まれる。※OR条件
• 1個のFilterListにつき、Operatorは1種類– 入れ子にすることは可能
• FilterList(MUST_PASS_ALL, [FilterList(MUST_PASS_ONE, [FilterA, FilterB]),
FilterList(MUST_PASS_ONE, [FilterC, FilterD])] )
カスタムフィルター (p160~)
• Filter インタフェースを implement する。または、FilterBaseクラスを extend する。
• Table 4-4 Filter.ReturnCode enumeration (p161)– ReturnCode filterKeyValue(KeyValue v);の戻り値– INCLUDE
• 条件判定中の KeyValueが result に含まれる。
– SKIP• 条件判定中の KeyValueは result に含まれない。次の KeyValueへ。
– NEXT_COL• 条件判定中の KeyValueは result に含まれない。次のカラムへ。• TimestampsFilterで使用。同カラムで複数バージョンある場合。
– NEXT_ROW• 条件判定中の KeyValueは result に含まれない。次のROW へ。
– SEEK_NEXT_USING_HINT
カスタムフィルター メソッド (p162~)• Figure 4-2 (p163) の図も参照
• boolean filterRowKey(byte[] buffer, int offset, int length)– Rowを処理するかどうか判定
• ReturnCode filterKeyValue(KeyValue v)– 現在行の各KeyValueをフィルタリング。
• void filterRow(List<KeyValue> kvs)– 前のフィルタリングが終わって、results に含まれているKeyValueにアクセスする。
– DependentColumnFilterが使用。• Timestampが合わないKeyValueを results から除外している。
• boolean filterRow()– 最終的な調査。trueならば results をクリアーする。
• void reset()– 行毎の初期化処理
• boolean filterAllRemaining()– falseならば残りのscan続行。trueならばScanを打ち切る。