Thrift module: Client

Module	Services	Data types	Constants
Client	ClientService close_mutator close_scanner create_table drop_table exists_table flush_mutator get_cell get_cells get_cells_as_arrays get_row get_row_as_arrays get_schema get_table_id get_table_splits get_tables next_cells next_cells_as_arrays next_row next_row_as_arrays open_mutator open_scanner put_cell put_cell_as_array put_cells put_cells_as_arrays set_cell set_cell_as_array set_cells set_cells_as_arrays	Cell CellAsArray CellFlag CellInterval ClientException Key MutateSpec Mutator MutatorFlag RowInterval ScanSpec Scanner TableSplit Value

Enumeration: CellFlag

State flags for a table cell

Note for maintainers: the definition must be sync'ed with FLAG_* constants in src/cc/Hypertable/Lib/Key.h

DELETE_ROW: row is pending delete

DELETE_CF: column family is pending delete

DELETE_CELL: cell is pending delete

INSERT: cell is an insert/update (default state)

DELETE_ROW 0

DELETE_CF 1

DELETE_CELL 2

INSERT 255

Enumeration: MutatorFlag

Mutator creation flags

NO_LOG_SYNC: Do not sync the commit log IGNORE_UNKNOWN_CFS: Don't throw exception if mutator writes to unknown column family

NO_LOG_SYNC 1

IGNORE_UNKNOWN_CFS 2

Type declarations

Typedef: Scanner

Base type: i64

Opaque ID for a table scanner

A scanner is recommended for returning large amount of data, say a full table dump.

Typedef: Mutator

Base type: i64

Opaque ID for a table mutator

A mutator is recommended for injecting large amount of data (across many calls to mutator methods)

Typedef: Value

Base type: string

Value for table cell

Use binary instead of string to generate efficient type for Java.

Typedef: CellAsArray

Base type: list<string>

Alternative Cell interface for languages (e.g., Ruby) where user defined objects are much more expensive to create than builtin primitives. The order of members is the same as that in the Cell object definition.

The returned cells (as arrays) contain Cell as array: ["row_key", "column_family", "column_qualifier", "value", "timestamp"]

Note, revision and cell flag are not returned for the array interface.

Data structures

Struct: RowInterval

Field	Type	Required	Default value
start_row	`string`	no
start_inclusive	`bool`	no	1
end_row	`string`	no
end_inclusive	`bool`	no	1

Specifies a range of rows

start_row: The row to start scan with. Must not contain nulls (0x00)
start_inclusive: Whether the start row is included in the result (default: true)
end_row: The row to end scan with. Must not contain nulls
end_inclusive: Whether the end row is included in the result (default: true)

Struct: CellInterval

Field	Type	Required	Default value
start_row	`string`	no
start_column	`string`	no
start_inclusive	`bool`	no	1
end_row	`string`	no
end_column	`string`	no
end_inclusive	`bool`	no	1

Specifies a range of cells

start_row: The row to start scan with. Must not contain nulls (0x00)
start_column: The column (prefix of column_family:column_qualifier) of the start row for the scan
start_inclusive: Whether the start row is included in the result (default: true)
end_row: The row to end scan with. Must not contain nulls
end_column: The column (prefix of column_family:column_qualifier) of the end row for the scan
end_inclusive: Whether the end row is included in the result (default: true)

Struct: ScanSpec

Field	Type	Required	Default value
row_intervals	`list<RowInterval>`	no
cell_intervals	`list<CellInterval>`	no
return_deletes	`bool`	no	0
revs	`i32`	no	0
row_limit	`i32`	no	0
start_time	`i64`	no
end_time	`i64`	no
columns	`list<string>`	no
keys_only	`bool`	no	0

Specifies options for a scan

row_intervals: A list of ranges of rows to scan. Mutually exclusive with cell_interval
cell_intervals: A list of ranges of cells to scan. Mutually exclusive with row_intervals
return_deletes: Indicates whether cells pending delete are returned
revs: Specifies max number of revisions of cells to return
row_limit: Specifies max number of rows to return
start_time: Specifies start time in nanoseconds since epoch for cells to return
end_time: Specifies end time in nanoseconds since epoch for cells to return
columns: Specifies the names of the columns to return

Struct: Key

Field	Type	Required	Default value
row	`string`	yes
column_family	`string`	yes
column_qualifier	`string`	yes
timestamp	`i64`	no
revision	`i64`	no
flag	`i16`	yes	255

Defines a cell key

row: Specifies the row key. Note, it cannot contain null characters. If a row key is not specified in a return cell, it's assumed to be the same as the previous cell
column_family: Specifies the column family
column_qualifier: Specifies the column qualifier. A column family must be specified.
timestamp: Nanoseconds since epoch for the cell
revision: A 64-bit revision number for the cell
flag: A 16-bit integer indicating the state of the cell

Struct: MutateSpec

Field	Type	Required	Default value
appname	`string`	yes	""
flush_interval	`i32`	yes	1000
flags	`i32`	yes	2

Specifies options for a shared periodic mutator

appname: String key used to share/retrieve mutator, eg: "my_ht_app"
flush_interval: Time interval between flushes
flags: Mutator flags

Struct: Cell

Field	Type	Required	Default value
key	`Key`	yes
value	`Value`	no

Defines a table cell

key: Specifies the cell key
value: Value of a cell. Currently a sequence of uninterpreted bytes.

Struct: TableSplit

Field	Type	Required
start_row	`string`	no
end_row	`string`	no
location	`string`	no
ip_address	`string`	no

Defines a table split

start_row: Starting row of the split.
end_row: Ending row of the split.
location: Location (proxy name) of the split.
ip_address: The IP address of the split.

Exception: ClientException

Field	Type	Required	Default value
code	`i32`	yes
message	`string`	yes

Exception for thrift clients.

code: Internal use (defined in src/cc/Common/Error.h)
message: A message about the exception

Note: some languages (like php) don't have adequate namespace, so Exception would conflict with language builtins.

Services

Service: ClientService

Function: ClientService.create_table

void create_table(string name,
                  string schema)
    throws ClientException

Create a table

@param name - table name

@param schema - schema of the table (in xml)

Function: ClientService.open_scanner

Scanner open_scanner(string name,
                     ScanSpec scan_spec,
                     bool retry_table_not_found = 0)
    throws ClientException

Open a table scanner

@param name - table name

@param scan_spec - scan specification

@param retry_table_not_found - whether to retry upon errors caused by drop/create tables with the same name

Function: ClientService.close_scanner

void close_scanner(Scanner scanner)
    throws ClientException

Close a table scanner

@param scanner - scanner id to close

Function: ClientService.next_cells

list<Cell> next_cells(Scanner scanner)
    throws ClientException

Iterate over cells of a scanner

@param scanner - scanner id

Function: ClientService.next_cells_as_arrays

list<CellAsArray> next_cells_as_arrays(Scanner scanner)
    throws ClientException

Function: ClientService.next_row

list<Cell> next_row(Scanner scanner)
    throws ClientException

Iterate over rows of a scanner

@param scanner - scanner id

Function: ClientService.next_row_as_arrays

list<CellAsArray> next_row_as_arrays(Scanner scanner)
    throws ClientException

Alternative interface using array as cell

Function: ClientService.get_row

list<Cell> get_row(string name,
                   string row)
    throws ClientException

Get a row (convenience method for random access a row)

@param name - table name

@param row - row key

@return a list of cells (with row_keys unset)

Function: ClientService.get_row_as_arrays

list<CellAsArray> get_row_as_arrays(string name,
                                    string row)
    throws ClientException

Alternative interface using array as cell

Function: ClientService.get_cell

Value get_cell(string name,
               string row,
               string column)
    throws ClientException

Get a cell (convenience method for random access a cell)

@param name - table name

@param row - row key

@param column - column name

@return value (byte sequence)

Function: ClientService.get_cells

list<Cell> get_cells(string name,
                     ScanSpec scan_spec)
    throws ClientException

Get cells (convenience method for access small amount of cells)

@param name - table name

@param scan_spec - scan specification

@return a list of cells (a cell with no row key set is assumed to have the same row key as the previous cell)

Function: ClientService.get_cells_as_arrays

list<CellAsArray> get_cells_as_arrays(string name,
                                      ScanSpec scan_spec)
    throws ClientException

Alternative interface using array as cell

Function: ClientService.put_cells

void put_cells(string tablename,
               MutateSpec mutate_spec,
               list<Cell> cells)
    throws ClientException

Open a shared periodic mutator which causes cells to be written asyncronously. Users beware: calling this method merely writes cells to a local buffer and does not guarantee that the cells have been persisted. If you want guaranteed durability, use the open_mutator+set_cells* interface instead.

@param tablename - table name

@param mutate_spec - mutator specification

@param cells - set of cells to be written

Function: ClientService.put_cells_as_arrays

void put_cells_as_arrays(string tablename,
                         MutateSpec mutate_spec,
                         list<CellAsArray> cells)
    throws ClientException

Alternative to put_cell interface using array as cell

Function: ClientService.put_cell

void put_cell(string tablename,
              MutateSpec mutate_spec,
              Cell cell)
    throws ClientException

@param tablename - table name

@param mutate_spec - mutator specification

@param cell - cell to be written

Function: ClientService.put_cell_as_array

void put_cell_as_array(string tablename,
                       MutateSpec mutate_spec,
                       CellAsArray cell)
    throws ClientException

Alternative to put_cell interface using array as cell

Function: ClientService.open_mutator

Mutator open_mutator(string name,
                     i32 flags = 0,
                     i32 flush_interval = 0)
    throws ClientException

Open a table mutator

@param name - table name

@param flags - mutator flags

@param flush_interval - auto-flush interval in milliseconds; 0 disables it.

@return mutator id

Function: ClientService.close_mutator

void close_mutator(Mutator mutator,
                   bool flush = 1)
    throws ClientException

Close a table mutator

@param mutator - mutator id to close

Function: ClientService.set_cell

void set_cell(Mutator mutator,
              Cell cell)
    throws ClientException

Set a cell in the table

@param mutator - mutator id

@param cell - the cell to set

Function: ClientService.set_cell_as_array

void set_cell_as_array(Mutator mutator,
                       CellAsArray cell)
    throws ClientException

Alternative interface using array as cell

Function: ClientService.set_cells

void set_cells(Mutator mutator,
               list<Cell> cells)
    throws ClientException

Put a list of cells into a table

@param mutator - mutator id

@param cells - a list of cells (a cell with no row key set is assumed to have the same row key as the previous cell)

Function: ClientService.set_cells_as_arrays

void set_cells_as_arrays(Mutator mutator,
                         list<CellAsArray> cells)
    throws ClientException

Alternative interface using array as cell

Function: ClientService.flush_mutator

void flush_mutator(Mutator mutator)
    throws ClientException

Flush mutator buffers

Function: ClientService.exists_table

bool exists_table(string name)
    throws ClientException

Check if the table exists

@param name - table name

@return true if table exists, false ow

Function: ClientService.get_table_id

i32 get_table_id(string name)
    throws ClientException

Get the id of a table

@param name - table name

@return table id

Function: ClientService.get_schema

string get_schema(string name)
    throws ClientException

Get the schema of a table (that can be used with creat_table)

@param name - table name

@return schema string (in xml)

Function: ClientService.get_tables

list<string> get_tables()
    throws ClientException

Get a list of table names in the cluster

@return a list of table names

Function: ClientService.get_table_splits

list<TableSplit> get_table_splits(string name)
    throws ClientException

Get a list of table splits

@param name - table name

@return a list of table names

Function: ClientService.drop_table

void drop_table(string name,
                bool if_exists = 1)
    throws ClientException

Drop a table

@param name - table name

@param if_exists - if true, don't barf if the table doesn't exist

Thrift module: Client

Enumerations

Enumeration: CellFlag

Enumeration: MutatorFlag

Type declarations

Typedef: Scanner

Typedef: Mutator

Typedef: Value

Typedef: CellAsArray

Data structures

Struct: RowInterval

Struct: CellInterval

Struct: ScanSpec

Struct: Key

Struct: MutateSpec

Struct: Cell

Struct: TableSplit

Exception: ClientException

Services

Service: ClientService

Function: ClientService.create_table

Function: ClientService.open_scanner

Function: ClientService.close_scanner

Function: ClientService.next_cells

Function: ClientService.next_cells_as_arrays

Function: ClientService.next_row

Function: ClientService.next_row_as_arrays

Function: ClientService.get_row

Function: ClientService.get_row_as_arrays

Function: ClientService.get_cell

Function: ClientService.get_cells

Function: ClientService.get_cells_as_arrays

Function: ClientService.put_cells

Function: ClientService.put_cells_as_arrays

Function: ClientService.put_cell

Function: ClientService.put_cell_as_array

Function: ClientService.open_mutator

Function: ClientService.close_mutator

Function: ClientService.set_cell

Function: ClientService.set_cell_as_array

Function: ClientService.set_cells

Function: ClientService.set_cells_as_arrays

Function: ClientService.flush_mutator

Function: ClientService.exists_table

Function: ClientService.get_table_id

Function: ClientService.get_schema

Function: ClientService.get_tables

Function: ClientService.get_table_splits

Function: ClientService.drop_table