Thrift module: Client

ModuleServicesData typesConstants
ClientClientService
AccessGroup
Cell
CellAsArray
CellInterval
CellsSerialized
ClientException
ColumnFamily
Future
Key
KeyFlag
MutateSpec
Mutator
MutatorAsync
MutatorFlag
Namespace
NamespaceListing
Result
ResultAsArrays
ResultSerialized
RowInterval
ScanSpec
Scanner
ScannerAsync
Schema
TableSplit
Value

Enumerations

Enumeration: KeyFlag

State flags for a key

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: key is pending delete

DELETE_CELL_VERSION: delete specific timestamped version of key

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

DELETE_ROW0
DELETE_CF1
DELETE_CELL2
DELETE_CELL_VERSION3
INSERT255

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_SYNC1
IGNORE_UNKNOWN_CFS2

Type declarations

Typedef: Future

Base type: i64

Opaque ID for a Future object


Typedef: Namespace

Base type: i64

Opaque ID for a Namespace


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: ScannerAsync

Base type: i64

Opaque ID for a asynchronous 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: MutatorAsync

Base type: i64

Opaque ID for a asynchronous 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.

Typedef: CellsSerialized

Base type: string

Binary buffer holding serialized sequence of cells

Data structures

Struct: RowInterval

KeyFieldTypeDescriptionRequirednessDefault value
1start_rowstringoptional
2start_inclusivebooloptional1
3end_rowstringoptional
4end_inclusivebooloptional1

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

KeyFieldTypeDescriptionRequirednessDefault value
1start_rowstringoptional
2start_columnstringoptional
3start_inclusivebooloptional1
4end_rowstringoptional
5end_columnstringoptional
6end_inclusivebooloptional1

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

KeyFieldTypeDescriptionRequirednessDefault value
1row_intervalslist<RowInterval>optional
2cell_intervalslist<CellInterval>optional
3return_deletesbooloptional0
4revsi32optional0
5row_limiti32optional0
6start_timei64optional
7end_timei64optional
8columnslist<string>optional
9keys_onlybooloptional0
10cell_limiti32optional0
11row_regexpstringoptional
12value_regexpstringoptional
13scan_and_filter_rowsbooloptional0

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

cell_limit
Specifies max number of cells to return per column family per row

row_regexp
Specifies a regexp used to filter by rowkey

value_regexp
Specifies a regexp used to filter by cell value

scan_and_filter_rows
Indicates whether table scan filters the rows specified instead of individual look up

Struct: Key

KeyFieldTypeDescriptionRequirednessDefault value
1rowstringdefault
2column_familystringdefault
3column_qualifierstringdefault
4timestampi64optional
5revisioni64optional
6flagKeyFlagdefaultUNKNOWN

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

KeyFieldTypeDescriptionRequirednessDefault value
1appnamestringrequired""
2flush_intervali32required1000
3flagsi32required2

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

KeyFieldTypeDescriptionRequirednessDefault value
1keyKeydefault
2valueValueoptional

Defines a table cell

key
Specifies the cell key

value
Value of a cell. Currently a sequence of uninterpreted bytes.

Struct: Result

KeyFieldTypeDescriptionRequirednessDefault value
1is_emptyboolrequired
2idi64required
3is_scanboolrequired
4is_errorboolrequired
5errori32optional
6error_msgstringoptional
7cellslist<Cell>optional

Specifies a result object for asynchronous requests. TODO: add support for update results

is_empty
Indicates whether this object contains a result or not

id
Scanner/mutator id for which these results pertain to
is_scan
Indicates whether these are scan results or update results
is_error
Indicates whether the async request was successful or not
error
Error code

error_msg
Error message

cells
Cells returned by asynchronous scanner

Struct: ResultAsArrays

KeyFieldTypeDescriptionRequirednessDefault value
1is_emptyboolrequired
2idi64required
3is_scanboolrequired
4is_errorboolrequired
5errori32optional
6error_msgstringoptional
7cellslist<CellAsArray>optional

Specifies a result object for asynchronous requests. TODO: add support for update results

is_empty
Indicates whether this object contains a result or not

id
Scanner/mutator id for which these results pertain to
is_scan
Indicates whether these are scan results or update results
is_error
Indicates whether the async request was successful or not
error
Error code

error_msg
Error message

cells
Cells returned by asynchronous scanner

Struct: ResultSerialized

KeyFieldTypeDescriptionRequirednessDefault value
1is_emptyboolrequired
2idi64required
3is_scanboolrequired
4is_errorboolrequired
5errori32optional
6error_msgstringoptional
7cellsCellsSerializedoptional

Specifies a serialized result object for asynchronous requests. TODO: add support for update results

is_empty
Indicates whether this object contains a result or not

id
Scanner/mutator id for which these results pertain to
is_scan
Indicates whether these are scan results or update results
is_error
Indicates whether the async request was successful or not
error
Error code

error_msg
Error message

cells
Cells returned by asynchronous scanner

Struct: NamespaceListing

KeyFieldTypeDescriptionRequirednessDefault value
1namestringrequired
2is_namespaceboolrequired

Defines an individual namespace listing

name
Name of the listing.

is_namespace
true if this entry is a namespace.

Struct: TableSplit

KeyFieldTypeDescriptionRequirednessDefault value
1start_rowstringoptional
2end_rowstringoptional
3locationstringoptional
4ip_addressstringoptional
5hostnamestringoptional

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.

hostname
The hostname of the split.

Struct: ColumnFamily

KeyFieldTypeDescriptionRequirednessDefault value
1namestringoptional
2agstringoptional
3max_versionsi32optional
4ttlstringoptional

Describes a ColumnFamily
name
Name of the column family

ag
Name of the access group for this CF

max_versions
Max versions of the same cell to be stored

ttl
Time to live for cells in the CF (ie delete cells older than this time)

Struct: AccessGroup

KeyFieldTypeDescriptionRequirednessDefault value
1namestringoptional
2in_memorybooloptional
3replicationi16optional
4blocksizei32optional
5compressorstringoptional
6bloom_filterstringoptional
7columnslist<ColumnFamily>optional

Describes an AccessGroup
name
Name of the access group

in_memory
Is this access group in memory

replication
Replication factor for this AG

blocksize
Specifies blocksize for this AG

compressor
Specifies compressor for this AG

bloom_filter
Specifies bloom filter type

columns
Specifies list of column families in this AG

Struct: Schema

KeyFieldTypeDescriptionRequirednessDefault value
1access_groupsmap<string, AccessGroup>optional
2column_familiesmap<string, ColumnFamily>optional

Describes a schema
name
Name of the access group

in_memory
Is this access group in memory

replication
Replication factor for this AG

blocksize
Specifies blocksize for this AG

compressor
Specifies compressor for this AG

bloom_filter
Specifies bloom filter type

columns
Specifies list of column families in this AG

Exception: ClientException

KeyFieldTypeDescriptionRequirednessDefault value
1codei32default
2messagestringdefault

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

The client service mimics the C++ client API, with table, scanner and mutator interface flattened.

Function: ClientService.create_namespace

void create_namespace(string ns)
    throws ClientException
Create a namespace

@param ns - namespace name

Function: ClientService.create_table

void create_table(Namespace ns,
                  string table_name,
                  string schema)
    throws ClientException
Create a table

@param ns - namespace id @param table_name - table name @param schema - schema of the table (in xml)

Function: ClientService.alter_table

void alter_table(Namespace ns,
                 string table_name,
                 string schema)
    throws ClientException
Alter a table

@param ns - namespace id @param table_name - table name @param schema - schema of the table (in xml)

Function: ClientService.open_namespace

Namespace open_namespace(string ns)
    throws ClientException
Open a namespace

@param ns - namespace @return value is guaranteed to be non-zero and unique

Function: ClientService.close_namespace

void close_namespace(Namespace ns)
    throws ClientException
Close a namespace

@param ns - namespace

Function: ClientService.open_future

Future open_future(i32 queue_size = 0)
    throws ClientException
Open a future object @param queue_size - num of results the future object can enqueue without blocking threads

Function: ClientService.cancel_future

void cancel_future(Future ff)
    throws ClientException
Cancel tasks outstanding in a future object @param ff - Future object

Function: ClientService.get_future_result

Result get_future_result(Future ff)
    throws ClientException
Fetch asynchronous results @param ff - Future object which has the asynchronous results @return - result from async scanner/mutator

Function: ClientService.get_future_result_as_arrays

ResultAsArrays get_future_result_as_arrays(Future ff)
    throws ClientException
Fetch asynchronous results @param ff - Future object which has the asynchronous results @return - result from async scanner/mutator

Function: ClientService.get_future_result_serialized

ResultSerialized get_future_result_serialized(Future ff)
    throws ClientException
Fetch asynchronous results @param ff - Future object which has the asynchronous results @return - result from async scanner/mutator

Function: ClientService.future_is_empty

bool future_is_empty(Future ff)
    throws ClientException
Check if future object's queue is empty

Function: ClientService.future_is_full

bool future_is_full(Future ff)
    throws ClientException
Check if future object's queue is full

Function: ClientService.future_is_cancelled

bool future_is_cancelled(Future ff)
    throws ClientException
Check if future object has been cancelled

Function: ClientService.future_has_outstanding

bool future_has_outstanding(Future ff)
    throws ClientException
Check if future object has outstanding operations

Function: ClientService.close_future

void close_future(Future ff)
    throws ClientException
Close a future object @param ff - the future object to be closed

Function: ClientService.open_scanner

Scanner open_scanner(Namespace ns,
                     string table_name,
                     ScanSpec scan_spec)
    throws ClientException
Open a table scanner @param ns - namespace id @param table_name - table name @param scan_spec - scan specification

Function: ClientService.open_scanner_async

ScannerAsync open_scanner_async(Namespace ns,
                                string table_name,
                                Future future,
                                ScanSpec scan_spec)
    throws ClientException
Open an asynchronous table scanner @param ns - namespace id @param table_name - table name @param future - callback object @param scan_spec - scan specification

Function: ClientService.close_scanner

void close_scanner(Scanner scanner)
    throws ClientException
Close a table scanner

@param scanner - scanner id to close

Function: ClientService.close_scanner_async

void close_scanner_async(ScannerAsync 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_cells_serialized

CellsSerialized next_cells_serialized(Scanner scanner)
Alternative interface returning buffer of serialized cells

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

CellsSerialized next_row_serialized(Scanner scanner)
    throws ClientException
Alternate interface returning a buffer of serialized cells for iterating by row for a given scanner

@param scanner - scanner id

Function: ClientService.get_row

list<Cell> get_row(Namespace ns,
                   string table_name,
                   string row)
    throws ClientException
Get a row (convenience method for random access a row)

@param ns - namespace id

@param table_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(Namespace ns,
                                    string name,
                                    string row)
    throws ClientException
Alternative interface using array as cell

Function: ClientService.get_row_serialized

CellsSerialized get_row_serialized(Namespace ns,
                                   string table_name,
                                   string row)
    throws ClientException
Alternative interface returning buffer of serialized cells

Function: ClientService.get_cell

Value get_cell(Namespace ns,
               string table_name,
               string row,
               string column)
    throws ClientException
Get a cell (convenience method for random access a cell)

@param ns - namespace id

@param table_name - table name

@param row - row key

@param column - column name

@return value (byte sequence)

Function: ClientService.get_cells

list<Cell> get_cells(Namespace ns,
                     string table_name,
                     ScanSpec scan_spec)
    throws ClientException
Get cells (convenience method for access small amount of cells)

@param ns - namespace id @param table_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(Namespace ns,
                                      string name,
                                      ScanSpec scan_spec)
    throws ClientException
Alternative interface using array as cell

Function: ClientService.get_cells_serialized

CellsSerialized get_cells_serialized(Namespace ns,
                                     string name,
                                     ScanSpec scan_spec)
    throws ClientException
Alternative interface returning buffer of serialized cells

Function: ClientService.refresh_shared_mutator

void refresh_shared_mutator(Namespace ns,
                            string table_name,
                            MutateSpec mutate_spec)
    throws ClientException
Create a shared mutator with specified MutateSpec. Delete and recreate it if the mutator exists.

@param ns - namespace id @param table_name - table name

@param mutate_spec - mutator specification


Function: ClientService.offer_cells

void offer_cells(Namespace ns,
                 string table_name,
                 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 ns - namespace id

@param table_name - table name

@param mutate_spec - mutator specification

@param cells - set of cells to be written

Function: ClientService.offer_cells_as_arrays

void offer_cells_as_arrays(Namespace ns,
                           string table_name,
                           MutateSpec mutate_spec,
                           list<CellAsArray> cells)
    throws ClientException
Alternative to offer_cell interface using array as cell

Function: ClientService.offer_cell

void offer_cell(Namespace ns,
                string table_name,
                MutateSpec mutate_spec,
                Cell cell)
    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 ns - namespace id

@param table_name - table name

@param mutate_spec - mutator specification

@param cell - cell to be written

Function: ClientService.offer_cell_as_array

void offer_cell_as_array(Namespace ns,
                         string table_name,
                         MutateSpec mutate_spec,
                         CellAsArray cell)
    throws ClientException
Alternative to offer_cell interface using array as cell

Function: ClientService.open_mutator

Mutator open_mutator(Namespace ns,
                     string table_name,
                     i32 flags = 0,
                     i32 flush_interval = 0)
    throws ClientException
Open a table mutator

@param ns - namespace id

@param table_name - table name

@param flags - mutator flags

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

@return mutator id

Function: ClientService.open_mutator_async

MutatorAsync open_mutator_async(Namespace ns,
                                string table_name,
                                Future future,
                                i32 flags = 0)
    throws ClientException
Open an asynchronous table mutator

@param ns - namespace id @param table_name - table name @param future - callback object @param flags - mutator flags

@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.close_mutator_async

void close_mutator_async(MutatorAsync mutator)
    throws ClientException
Close an asynchronous 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.set_cells_serialized

void set_cells_serialized(Mutator mutator,
                          CellsSerialized cells,
                          bool flush = 0)
    throws ClientException
Alternative interface using buffer of serialized cells

Function: ClientService.flush_mutator

void flush_mutator(Mutator mutator)
    throws ClientException
Flush mutator buffers

Function: ClientService.set_cell_async

void set_cell_async(MutatorAsync mutator,
                    Cell cell)
    throws ClientException
Set a cell in the table using an asynchonous mutator

@param mutator - mutator id

@param cell - the cell to set

Function: ClientService.set_cell_as_array_async

void set_cell_as_array_async(MutatorAsync mutator,
                             CellAsArray cell)
    throws ClientException
Alternative interface using array as cell using an asynchonous mutator

Function: ClientService.set_cells_async

void set_cells_async(MutatorAsync mutator,
                     list<Cell> cells)
    throws ClientException
Put a list of cells into a table using asynchonous mutator

@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_async

void set_cells_as_arrays_async(MutatorAsync mutator,
                               list<CellAsArray> cells)
    throws ClientException
Alternative interface using array as cell

Function: ClientService.set_cells_serialized_async

void set_cells_serialized_async(MutatorAsync mutator,
                                CellsSerialized cells,
                                bool flush = 0)
    throws ClientException
Alternative interface using buffer of serialized cells

Function: ClientService.flush_mutator_async

void flush_mutator_async(MutatorAsync mutator)
    throws ClientException
Flush mutator buffers

Function: ClientService.exists_namespace

bool exists_namespace(string ns)
    throws ClientException
Check if the namespace exists

@param ns - namespace name

@return true if ns exists, false ow

Function: ClientService.exists_table

bool exists_table(Namespace ns,
                  string name)
    throws ClientException
Check if the table exists

@param ns - namespace id

@param name - table name

@return true if table exists, false ow

Function: ClientService.get_table_id

string get_table_id(Namespace ns,
                    string table_name)
    throws ClientException
Get the id of a table

@param ns - namespace id

@param table_name - table name

@return table id string

Function: ClientService.get_schema_str

string get_schema_str(Namespace ns,
                      string table_name)
    throws ClientException
Get the schema of a table as a string (that can be used with create_table)

@param ns - namespace id

@param table_name - table name

@return schema string (in xml)

Function: ClientService.get_schema_str_with_ids

string get_schema_str_with_ids(Namespace ns,
                               string table_name)
    throws ClientException
Get the schema of a table as a string along with column family ids

@param ns - namespace id

@param table_name - table name

@return schema string (in xml)

Function: ClientService.get_schema

Schema get_schema(Namespace ns,
                  string table_name)
    throws ClientException
Get the schema of a table as a string (that can be used with create_table) @param ns - namespace id

@param table_name - table name

@return schema object describing a table

Function: ClientService.get_tables

list<string> get_tables(Namespace ns)
    throws ClientException
Get a list of table names in the namespace

@param ns - namespace id

@return a list of table names

Function: ClientService.get_listing

list<NamespaceListing> get_listing(Namespace ns)
    throws ClientException
Get a list of namespaces and table names table names in the namespace

@param ns - namespace

@return a list of table names

Function: ClientService.get_table_splits

list<TableSplit> get_table_splits(Namespace ns,
                                  string table_name)
    throws ClientException
Get a list of table splits

@param ns - namespace id

@param table_name - table name

@return a list of table names

Function: ClientService.drop_namespace

void drop_namespace(string ns,
                    bool if_exists = 1)
    throws ClientException
Drop a namespace

@param ns - namespace name

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

Function: ClientService.rename_table

void rename_table(Namespace ns,
                  string name,
                  string new_name)
    throws ClientException
Rename a table

@param ns - namespace id

@param name - current table name

@param new_name - new table name

Function: ClientService.drop_table

void drop_table(Namespace ns,
                string name,
                bool if_exists = 1)
    throws ClientException
Drop a table

@param ns - namespace id

@param name - table name

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