Thrift module: Client
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_ROW | 0 |
DELETE_CF | 1 |
DELETE_CELL | 2 |
DELETE_CELL_VERSION | 3 |
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: 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
| Key | Field | Type | Description | Requiredness | Default value |
| 1 | start_row | string | | optional | |
| 2 | start_inclusive | bool | | optional | 1 |
| 3 | end_row | string | | optional | |
| 4 | end_inclusive | bool | | optional | 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
| Key | Field | Type | Description | Requiredness | Default value |
| 1 | start_row | string | | optional | |
| 2 | start_column | string | | optional | |
| 3 | start_inclusive | bool | | optional | 1 |
| 4 | end_row | string | | optional | |
| 5 | end_column | string | | optional | |
| 6 | end_inclusive | bool | | optional | 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
| Key | Field | Type | Description | Requiredness | Default value |
| 1 | row_intervals | list<RowInterval> | | optional | |
| 2 | cell_intervals | list<CellInterval> | | optional | |
| 3 | return_deletes | bool | | optional | 0 |
| 4 | revs | i32 | | optional | 0 |
| 5 | row_limit | i32 | | optional | 0 |
| 6 | start_time | i64 | | optional | |
| 7 | end_time | i64 | | optional | |
| 8 | columns | list<string> | | optional | |
| 9 | keys_only | bool | | optional | 0 |
| 10 | cell_limit | i32 | | optional | 0 |
| 11 | row_regexp | string | | optional | |
| 12 | value_regexp | string | | optional | |
| 13 | scan_and_filter_rows | bool | | optional | 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
- 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
| Key | Field | Type | Description | Requiredness | Default value |
| 1 | row | string | | default | |
| 2 | column_family | string | | default | |
| 3 | column_qualifier | string | | default | |
| 4 | timestamp | i64 | | optional | |
| 5 | revision | i64 | | optional | |
| 6 | flag | KeyFlag | | default | UNKNOWN |
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
| Key | Field | Type | Description | Requiredness | Default value |
| 1 | appname | string | | required | "" |
| 2 | flush_interval | i32 | | required | 1000 |
| 3 | flags | i32 | | required | 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
| Key | Field | Type | Description | Requiredness | Default value |
| 1 | key | Key | | default | |
| 2 | value | Value | | optional | |
Defines a table cell
- key
- Specifies the cell key
- value
- Value of a cell. Currently a sequence of uninterpreted bytes.
Struct: Result
| Key | Field | Type | Description | Requiredness | Default value |
| 1 | is_empty | bool | | required | |
| 2 | id | i64 | | required | |
| 3 | is_scan | bool | | required | |
| 4 | is_error | bool | | required | |
| 5 | error | i32 | | optional | |
| 6 | error_msg | string | | optional | |
| 7 | cells | list<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
| Key | Field | Type | Description | Requiredness | Default value |
| 1 | is_empty | bool | | required | |
| 2 | id | i64 | | required | |
| 3 | is_scan | bool | | required | |
| 4 | is_error | bool | | required | |
| 5 | error | i32 | | optional | |
| 6 | error_msg | string | | optional | |
| 7 | cells | list<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
| Key | Field | Type | Description | Requiredness | Default value |
| 1 | is_empty | bool | | required | |
| 2 | id | i64 | | required | |
| 3 | is_scan | bool | | required | |
| 4 | is_error | bool | | required | |
| 5 | error | i32 | | optional | |
| 6 | error_msg | string | | optional | |
| 7 | cells | CellsSerialized | | optional | |
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
| Key | Field | Type | Description | Requiredness | Default value |
| 1 | name | string | | required | |
| 2 | is_namespace | bool | | required | |
Defines an individual namespace listing
- name
- Name of the listing.
- is_namespace
- true if this entry is a namespace.
Struct: TableSplit
| Key | Field | Type | Description | Requiredness | Default value |
| 1 | start_row | string | | optional | |
| 2 | end_row | string | | optional | |
| 3 | location | string | | optional | |
| 4 | ip_address | string | | optional | |
| 5 | hostname | string | | optional | |
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
| Key | Field | Type | Description | Requiredness | Default value |
| 1 | name | string | | optional | |
| 2 | ag | string | | optional | |
| 3 | max_versions | i32 | | optional | |
| 4 | ttl | string | | optional | |
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
| Key | Field | Type | Description | Requiredness | Default value |
| 1 | name | string | | optional | |
| 2 | in_memory | bool | | optional | |
| 3 | replication | i16 | | optional | |
| 4 | blocksize | i32 | | optional | |
| 5 | compressor | string | | optional | |
| 6 | bloom_filter | string | | optional | |
| 7 | columns | list<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
| Key | Field | Type | Description | Requiredness | Default value |
| 1 | access_groups | map<string, AccessGroup> | | optional | |
| 2 | column_families | map<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
| Key | Field | Type | Description | Requiredness | Default value |
| 1 | code | i32 | | default | |
| 2 | message | string | | default | |
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_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_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.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.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_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