[Hadoop Wiki] Update of "Hbase/ThriftApi" by JesseAnderson

[Apache Wiki <wi...@apache.org>]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Hadoop Wiki" for change notification.

The "Hbase/ThriftApi" page has been changed by JesseAnderson:
http://wiki.apache.org/hadoop/Hbase/ThriftApi?action=diff&rev1=21&rev2=22

Comment:
Major fixes of missing and incorrect Thrift API calls.

  
  
  == Data Type Spec ==
- This design documentation is now outdated. See Hbase.thrift for an up-to-date API.
+ See Hbase.thrift for an up-to-date API and a complete definition of all methods and data types.
  
- This section contains the definitions of Thrift data types needed for communication.
+ This section contains some definitions of Thrift data types needed for communication.
  
- ==== columnDescriptor ====
+ ==== ColumnDescriptor ====
  
- Used by getColumnDescriptors. How much information should we expose here?
+ Used by getColumnDescriptors.
  
  {{{
- struct columnDescriptor {
+ struct ColumnDescriptor {
-   1:string name,
+   1:Text name,
-   2:int32 maxVersions,
+   2:i32 maxVersions = 3,
-   3:bool compression
+   3:string compression = "NONE",
+   4:bool inMemory = 0,
+   5:string bloomFilterType = "NONE",
+   6:i32 bloomFilterVectorSize = 0,
+   7:i32 bloomFilterNbHashes = 0,
+   8:bool blockCacheEnabled = 0,
+   9:i32 timeToLive = -1
  }
  }}}
  
- ==== regionDescriptor ====
+ ==== TRegionInfo ====
  Used by getTableRegions. 
  
  {{{
- struct regionDescriptor {
+ struct TRegionInfo {
-   1:string startKey,
+   1:Text startKey,
-   2:string host
+   2:Text endKey,
+   3:i64 id,
+   4:Text name,
+   5:byte version,
+   6:Text serverName,
+   7:i32 port
  }
  }}}
  
- ==== mutation ====
+ ==== Mutation ====
  
  Used when performing batch update operations. isDelete is the switch you flip when you want to delete a cell. 
  
  {{{
- struct mutation {
+ struct Mutation {
-   1:bool isDelete="false",
+   1:bool isDelete = 0,
-   2:string columnName,
-   3:string value
+   2:Text column,
+   3:Text value,
+   4:bool writeToWAL = 1
  }
  }}}
  
+ ==== TRowResult ====
+ 
+ Used by getRow and other gets of rows.
+ 
+ {{{
+ struct TRowResult {
+   1:Text row,
+   2:map<Text, TCell> columns
+ }
+ }}}
+ 
+ 
  == Method Spec ==
  
- This section contains the definition of the methods we want to expose to clients. If you have a method to propose, add it to the appropriate subsection below along with a  comment explaining why we should want such a method.
+ This section contains some definitions of the methods exposed to clients. If you have a method to propose, add a JIRA along with a comment explaining why we should want such a method.
  
  === Meta-info methods ===
  
@@ -99, +123 @@

  Returns a list of table names.
  
  {{{
- list<string> getTableNames()
+ list<Text> getTableNames()
  }}}
  
  ==== Get Column Descriptors ====
- Return a list of column descriptors for a given table.
+ Return a list of column families for a given table.
  
  {{{
- list<columnDescriptor> getColumnDescriptors(string tableName)
+ map<Text,ColumnDescriptor> getColumnDescriptors(Text tableName)
  }}}
  
  ==== Get Table Regions ====
- Return a list of the region and host tuples that make up a table.
+ Return a list of the regions that make up a table.
  
  {{{
- list<regionDescriptor> getTableRegions(string tableName)
+ list<TRegionInfo> getTableRegions(Text tableName)
  }}}
  
  === Row methods ===
  
  ==== Get Row ====
- Retrieve a map<col name, value> for a given row, with all the usual options. (timestamp, selected columns)
+ Retrieve a list<TRowResult> for a given row, with all the usual options. (timestamp, selected columns).  There are lots of other methods to get rows with different parameters.
  
  {{{
+ list<TRowResult> getRow(Text tableName, Text row, map<Text, Text> attributes)
- map<string, string> getRow(string tableName, string row),
- map<string, string> getRow(string tableName, string row, i64 timestamp),
- map<string, string> getRow(string tableName, string row, list<string> columns),
- map<string, string> getRow(string tableName, string row, list<string> columns, i64 timestamp)
  }}}
  
  ==== Mutate Row (Put) ====
  Send a series of mutation commands (put, delete) to the table.
  
  {{{
+ void mutateRow(Text tableName, Text row, list<Mutation> mutations, map<Text, Text> attributes)
- void mutateRow(string tableName, string row, list<mutation> mutations),
- void mutateRow(string tableName, string row, list<mutation> mutations, i64 timestamp)
  }}}
  
  ==== Delete Row ====
  Delete an entire row.
  
  {{{
+ void deleteAllRow(Text tableName, Text row, map<Text, Text> attributes)
- void deleteRow(string tableName, string row),
- void deleteRow(string tableName, string row, i64 timestamp)
  }}}
  
  === Scanner methods ===
+ 
+ Scanner methods use a scanner id that is maintained on the Thrift server.  The ScannerId is defined as:
+ {{{
+ typedef i32    ScannerID
+ }}}
+ 
+ In Thrift, an i32 is a signed, 32-bit integer that identifies the scanner object on the Thrift server.
  
  ==== Open Scanner ====
  Create a scanner for a table with some options.
  
  {{{
+ ScannerID scannerOpen(Text tableName, Text startRow, list<Text> columns, map<Text, Text> attributes)
- i32 openScanner(string tableName, string startRow),
- i32 openScanner(string tableName, string startRow, string stopRow),
- i32 openScanner(string tableName, string startRow, string stopRow, list<string> columns)
  }}}
  
  ==== Get Scanner Results ====
  Retrieve one or more records from the scanner at once. 
  
  {{{
- map<string, string> getScannerResult(i32 scannerID)
+ list<TRowResult> scannerGetList(ScannerID id, i32 numberOfRows)
  }}}
  
  ==== Close Scanner ====
  Close a scanner.
  
  {{{
- void closeScanner(i32 scannerID)
+ void scannerClose(ScannerID id)
  }}}
  
- 
- == Comments on API design ==
- 
- Bryan, I think you may want to use the "binary" type instead of "string" to avoid any possible encoding issues. "binary" is a raw raw byte[] in Java. -- Chad
- 
- Bryan, I've been working on various Thrift servers and clients (mainly C++ and Ruby) at Powerset and will be taking a look at creating a Thrift server implementation of this API.  Is this something on which you are actively working?  If not, I'll take a look at the REST server code as a model for hooking up the Thrift API to Hbase.  Other than that, without knowing a bit more about the HBase API, the Thrift API looks good.  One thing that we'll need to add to it are Exception declarations.  -- DavidSimpson
- 
- Using the thrift API presumes that the system is already running the thrift servlet.  How does one get that started? -- JimRWilson <<DateTime(2008-04-01T15:56:33Z)>>
- 
- Jim, to start a thrift server, do ${HBASE_HOME}/bin/hbase thrift start or ${HBASE_HOME}/bin/start-daemon.sh start thrift if you want logs captured and a pid file written (FYI, this kind of question belongs over in the hbase mailing list -- no one reads the wiki; smile).
-