Thrift API와 필터 언어

이 문서는 HBase의 Thrift API에서 제공하는 필터 언어를 설명해요. Thrift 필터 언어는 HBase 0.92에서 도입됐어요. Thrift 또는 HBase 셸로 HBase에 접근할 때 서버 측 필터링을 수행할 수 있게 해 줘요. 필터를 문자열로 지정하면 서버에서 파싱해 필터를 구성해요.

출처: 문서

본문

보안 운영을 위한 클라이언트 측 구성 - Thrift 게이트웨이와 Thrift 게이트웨이가 클라이언트를 대신해 인증하도록 구성의 절차를 따라 서버와 클라이언트 측에서 Thrift를 보안 인증용으로 구성할 수 있어요.

이 장의 나머지에서는 Thrift API가 제공하는 필터 언어를 다뤄요.

필터 언어

Thrift 필터 언어는 HBase 0.92에서 도입됐어요. Thrift 또는 HBase 셸로 HBase에 접근할 때 서버 측 필터링을 수행할 수 있게 해 줘요. 셸 통합에 대한 자세한 내용은 셸의 scan help 명령을 사용해 알 수 있어요.

필터를 문자열로 지정하는데, 이 문자열이 서버에서 파싱되어 필터를 구성해요.

일반 필터 문자열 문법

간단한 필터 표현식은 문자열로 표현돼요.

"FilterName (argument, argument,... , argument)"

다음 문법 지침을 명심하세요.

괄호 안에 쉼표로 구분된 인자 목록 뒤에 필터 이름을 지정하세요.
인자가 문자열을 나타내면 작은따옴표(')로 묶어야 해요.
불리언, 정수 또는 비교 연산자(예: <, >, !=)를 나타내는 인자는 따옴표로 묶으면 안 돼요.
필터 이름은 단일 단어여야 해요. 공백, 작은따옴표, 괄호를 제외한 모든 ASCII 문자가 허용돼요.
필터의 인자는 어떤 ASCII 문자도 포함할 수 있어요. 인자에 작은따옴표가 있으면 앞에 작은따옴표를 하나 더 붙여 이스케이프해야 해요.

복합 필터와 연산자

이항 연산자

AND

AND 연산자를 사용하면 key-value가 두 필터를 모두 충족해야 해요.

OR

OR 연산자를 사용하면 key-value가 필터 중 하나 이상을 충족해야 해요.

단항 연산자

SKIP

특정 행에 대해 key-value 중 하나라도 필터 조건을 충족하지 못하면 전체 행을 건너뜁니다.

WHILE

특정 행에 대해 필터 조건을 충족하지 못하는 key-value에 도달할 때까지 key-value가 방출됩니다.

복합 연산자

다음 예시처럼 여러 연산자를 결합해 필터의 계층 구조를 만들 수 있어요.

(Filter1 AND Filter2) OR (Filter3 AND Filter4)

평가 순서

괄호가 가장 높은 우선순위를 가져요.
다음은 단항 연산자 SKIP와 WHILE로, 같은 우선순위를 가져요.
그다음은 이항 연산자예요. AND가 가장 높은 우선순위이고, 그다음 OR이에요.

우선순위 예시

Filter1 AND Filter2 OR Filter
is evaluated as
(Filter1 AND Filter2) OR Filter3

Filter1 AND SKIP Filter2 OR Filter3
is evaluated as
(Filter1 AND (SKIP Filter2)) OR Filter3

괄호를 사용해 평가 순서를 명시적으로 제어할 수 있어요.

비교 연산자

다음 비교 연산자가 제공돼요.

LESS (<)
LESS_OR_EQUAL (<=)
EQUAL (=)
NOT_EQUAL (!=)
GREATER_OR_EQUAL (>=)
GREATER (>)
NO_OP (no operation)

클라이언트는 기호(<, <=, =, !=, >, >=)를 사용해 비교 연산자를 표현해야 해요.

비교기(Comparator)

비교기는 다음 중 하나일 수 있어요.

BinaryComparator - Bytes.compareTo(byte[], byte[])를 사용해 지정된 바이트 배열에 대해 사전식(lexicographic)으로 비교해요.
BinaryPrefixComparator - 지정된 바이트 배열에 대해 사전식으로 비교해요. 이 바이트 배열의 길이까지만 비교해요.
RegexStringComparator - 주어진 정규식으로 지정된 바이트 배열과 비교해요. 이 비교기에는 EQUAL과 NOT_EQUAL 비교만 유효해요.
SubStringComparator - 주어진 하위 문자열이 지정된 바이트 배열에 나타나는지 테스트해요. 비교는 대소문자를 구분하지 않아요. 이 비교기에는 EQUAL과 NOT_EQUAL 비교만 유효해요.

비교기의 일반 문법은 ComparatorType:ComparatorValue예요.

다양한 비교기의 ComparatorType은 다음과 같아요.

BinaryComparator - binary
BinaryPrefixComparator - binaryprefix
RegexStringComparator - regexstring
SubStringComparator - substring

ComparatorValue는 어떤 값이든 될 수 있어요.

예시 ComparatorValues

binary:abc는 사전식으로 "abc"보다 큰 모든 것을 매치해요.
binaryprefix:abc는 처음 3자가 사전식으로 "abc"와 같은 모든 것을 매치해요.
regexstring:ab*yz는 "ab"로 시작하고 "yz"로 끝나지 않는 모든 것을 매치해요.
substring:abc123은 "abc123" 하위 문자열로 시작하는 모든 것을 매치해요.

필터 언어를 사용하는 예시 PHP 클라이언트 프로그램

<?
  $_SERVER['PHP_ROOT'] = realpath(dirname(__FILE__).'/..');
  require_once $_SERVER['PHP_ROOT'].'/flib/__flib.php';
  flib_init(FLIB_CONTEXT_SCRIPT);
  require_module('storage/hbase');
  $hbase = new HBase('<server_name_running_thrift_server>', <port on which thrift server is running>);
  $hbase->open();
  $client = $hbase->getClient();
  $result = $client->scannerOpenWithFilterString('table_name', "(PrefixFilter ('row2') AND (QualifierFilter (>=, 'binary:xyz'))) AND (TimestampsFilter ( 123, 456))");
  $to_print = $client->scannerGetList($result,1);
  while ($to_print) {
    print_r($to_print);
    $to_print = $client->scannerGetList($result,1);
  }
  $client->scannerClose($result);
?>

예시 필터 문자열

"PrefixFilter ('Row') AND PageFilter (1) AND FirstKeyOnlyFilter ()"는 다음 조건을 모두 충족하는 모든 key-value 쌍을 반환해요.
1. key-value를 포함하는 행이 접두사 Row를 가져야 함
2. key-value가 테이블의 첫 행에 위치해야 함
3. key-value 쌍이 행의 첫 번째 key-value여야 함
"(RowFilter (=, 'binary:Row 1') AND TimeStampsFilter (74689, 89734)) OR ColumnRangeFilter ('abc', true, 'xyz', false))"는 다음 두 조건을 모두 충족하는 모든 key-value 쌍을 반환해요.
- key-value가 row key Row 1을 가진 행에 있음
- key-value가 타임스탬프 74689 또는 89734를 가져야 함
- 또는 다음 조건을 충족해야 함:
  - key-value 쌍이 사전식으로 >= abc이고 < xyz인 열에 있어야 함
"SKIP ValueFilter (0)"은 행의 값 중 하나라도 0이 아니면 전체 행을 건너뜁니다.

개별 필터 문법

KeyOnlyFilter

이 필터는 인자를 받지 않아요. 각 key-value의 키 구성 요소만 반환해요.

FirstKeyOnlyFilter

이 필터는 인자를 받지 않아요. 각 행에서 첫 번째 key-value만 반환해요.

PrefixFilter

이 필터는 하나의 인자, 즉 row key의 접두사를 받아요. 지정된 행 접두사로 시작하는 행에 있는 key-value만 반환해요.

ColumnPrefixFilter

이 필터는 하나의 인자, 즉 열 접두사를 받아요. 지정된 열 접두사로 시작하는 열에 있는 key-value만 반환해요. 열 접두사는 "qualifier" 형태여야 해요.

MultipleColumnPrefixFilter

이 필터는 열 접두사 목록을 받아요. 지정된 열 접두사 중 하나로 시작하는 열에 있는 key-value를 반환해요. 각 열 접두사는 "qualifier" 형태여야 해요.

ColumnCountGetFilter

이 필터는 하나의 인자, 즉 제한을 받아요. 테이블의 첫 limit 개수 열을 반환해요.

PageFilter

이 필터는 하나의 인자, 즉 페이지 크기를 받아요. 테이블에서 page size 개수의 행을 반환해요.

ColumnPaginationFilter

이 필터는 두 인자, 즉 limit과 offset을 받아요. offset 개수 열 다음의 limit 개수 열을 반환해요. 모든 행에 대해 이 작업을 수행해요.

InclusiveStopFilter

이 필터는 하나의 인자, 즉 스캔을 중지할 row key를 받아요. 지정된 행까지 포함한 행들에 있는 모든 key-value를 반환해요.

TimeStampsFilter

이 필터는 타임스탬프 목록을 받아요. 지정된 타임스탬프 중 하나와 일치하는 key-value를 반환해요.

RowFilter

이 필터는 비교 연산자와 비교기를 받아요. 각 row key를 비교 연산자를 사용해 비교기와 비교하고, 비교가 true를 반환하면 그 행의 모든 key-value를 반환해요.

Family Filter

이 필터는 비교 연산자와 비교기를 받아요. 각 column family 이름을 비교 연산자를 사용해 비교기와 비교하고, 비교가 true를 반환하면 그 column family의 모든 Cells를 반환해요.

QualifierFilter

이 필터는 비교 연산자와 비교기를 받아요. 각 qualifier 이름을 비교 연산자를 사용해 비교기와 비교하고, 비교가 true를 반환하면 그 열의 모든 key-value를 반환해요.

ValueFilter

이 필터는 비교 연산자와 비교기를 받아요. 각 값을 비교 연산자를 사용해 비교기와 비교하고, 비교가 true를 반환하면 그 key-value를 반환해요.

DependentColumnFilter

이 필터는 두 인자, 즉 family와 qualifier를 받아요. 각 행에서 이 열을 찾으려 하고 같은 타임스탬프를 가진 그 행의 모든 key-value를 반환해요. 행이 지정된 열을 포함하지 않으면 그 행의 key-value는 하나도 반환되지 않아요.

SingleColumnValueFilter

이 필터는 column family, qualifier, 비교 연산자, 비교기를 받아요. 지정된 열을 찾지 못하면 그 행의 모든 열이 방출돼요. 열을 찾았고 비교기와의 비교가 true를 반환하면 행의 모든 열이 방출돼요. 조건이 실패하면 행은 방출되지 않아요.

SingleColumnValueExcludeFilter

이 필터는 SingleColumnValueFilter와 같은 인자를 받고 같은 동작을 해요. 다만 열을 찾았고 조건이 통과하면, 테스트된 열 값을 제외한 행의 모든 열이 방출돼요.

ColumnRangeFilter

이 필터는 minColumn과 maxColumn 사이의 열을 가진 키만 선택하는 데 사용돼요. minColumn과 maxColumn을 포함할지 여부를 나타내는 두 불리언 변수도 받아요.

Thrift API와 필터 언어