Skip to content
Browse files

Adding Lars's new interface definition from AVRO-1744.

  • Loading branch information...
1 parent 6d44552 commit 2881e97e568a48b6d473fe36197e3348d217a701 @hammer committed May 18, 2010
Showing with 562 additions and 0 deletions.
  1. +562 −0 Hbase.thrift.1744
View
562 Hbase.thrift.1744
@@ -0,0 +1,562 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+// ----------------------------------------------------------------
+// Hbase.thrift
+//
+// This is a Thrift interface definition file for the Hbase service.
+// Target language libraries for C++, Java, Ruby, PHP, (and more) are
+// generated by running this file through the Thrift compiler with the
+// appropriate flags. The Thrift compiler binary and runtime
+// libraries for various languages are available
+// from the Apache Incubator (http://incubator.apache.org/thrift/)
+//
+// See the package.html file for information on the version of Thrift
+// used to generate the *.java files checked into the Hbase project.
+// ----------------------------------------------------------------
+
+namespace java org.apache.hadoop.hbase.thrift.generated
+namespace cpp apache.hadoop.hbase.thrift
+namespace rb Apache.Hadoop.Hbase.Thrift
+namespace py hbase
+namespace perl Hbase
+
+// TODO: other language namespaces tbd...
+
+//
+// Types
+//
+
+// NOTE: all variables with the Text type are assumed to be correctly
+// formatted UTF-8 strings. This is a programming language and locale
+// dependent property that the client application is repsonsible for
+// maintaining. If strings with an invalid encoding are sent, an
+// IOError will be thrown.
+
+typedef binary Text
+typedef binary Bytes
+typedef i32 ScannerID
+
+/**
+ * A TRegionInfo contains information about an HTable region.
+ */
+struct TRegionInfo {
+ 1: Bytes startKey,
+ 2: Bytes endKey,
+ 3: i64 id,
+ 4: Bytes name,
+ 5: byte version
+}
+
+//
+// Exceptions
+//
+
+/**
+ * An IOError exception signals that an error occurred communicating
+ * to the HBase master or a HBase region server. Also used to return
+ * more general HBase error conditions.
+ */
+exception IOError {
+ 1: string message
+}
+
+/**
+ * An IllegalArgument exception indicates an illegal or invalid
+ * argument was passed into a procedure.
+ */
+exception IllegalArgument {
+ 1: string message
+}
+
+/**
+ * A AlreadyExists signals that a table with the specified
+ * name already exists
+ */
+exception AlreadyExists {
+ 1: string message
+}
+
+//
+// Client stuff
+//
+
+/**
+ * Addresses a single cell or multiple cells
+ * in a HBase table by column family and optionally
+ * column qualifier and timestamp.
+ */
+struct TColumn {
+ 1: required Bytes family,
+ 2: optional Bytes qualifier,
+ 3: optional i64 timestamp
+}
+
+struct TPut {
+ 1: required Bytes row,
+ 2: required map<TColumn, Bytes> values
+
+ // Default timestamp if TColumns don't provide one
+ 3: optional i64 timestamp,
+}
+
+/**
+ * Timestamps are only used if there are no columns added to the TDelete struct
+ */
+struct TDelete {
+ 1: required Bytes row,
+ //2: optional map<TColumn, DeleteType> columns
+ 2: optional list<TColumn> columns
+ 3: optional i64 timestamp
+}
+
+/*
+enum Filter {
+ COLUMNCOUNTGETFILTER = 0,
+ COMPAREFILTER = 1,
+ FILTERLIST = 2,
+ FIRSTKEYONLYFILTER = 3,
+ INCLUSIVESTOPROWFILTER = 4,
+ PAGEFILTER = 5,
+ PREFIXFILTER = 6,
+ QUALIFIERFILTER = 7,
+ ROWFILTER = 8,
+ SKIPFILTER = 9,
+ VALUEFILTER = 10,
+ WHILEMATCHFILTER = 11,
+}
+*/
+
+/**
+ * TColumn timestamps are ignored for gets.
+ */
+struct TGet {
+ 1: Bytes row,
+ 2: optional list<TColumn> columns,
+
+ // Set timestamp to get a specific timetamp (this overrides using a range),
+ 3: optional i64 timestamp,
+
+ // Set timerangeStart and timerangeEnd to get a range of timestamps.
+ 4: optional i64 timerangeStart,
+ 5: optional i64 timerangeEnd,
+
+ 6: optional i32 maxVersions,
+}
+
+struct TScan {
+ 1: required Bytes startRow,
+ 2: optional Bytes stopRow,
+ 3: optional list<TColumn> columns,
+
+}
+
+/**
+ * TODO: Rely on row/values being empty or add an extra field "bool empty"?
+ */
+struct TResult {
+ 1: optional Bytes row,
+ 2: optional map<TColumn, Bytes> values
+}
+
+//
+// Admin stuff
+//
+
+enum CompressionAlgorithm {
+ NONE = 0
+ LZO = 1,
+ GZ = 2,
+}
+
+/**
+ * A ColumnFamilyDescriptor contains information about a column family such as the
+ * number of versions, compression settings, etc.
+ *
+ * It is used as input when creating a table or adding a column. Once set, the
+ * parameters that specify a column cannot be changed without deleting the
+ * column and recreating it. If there is data stored in the column, it will be
+ * deleted when the column is deleted.
+ *
+ * A value of -1 for timeToLive means forever.
+ */
+struct ColumnFamilyDescriptor {
+ 1: required Bytes name,
+ 2: required CompressionAlgorithm compression, //TODO: I don't know of a way to set an initial value for an enum
+ 3: required i32 maxVersions = 3,
+ 4: required i32 blocksize = 65536,
+ 5: required bool inMemory = 0,
+ 6: required i32 timeToLive = -1,
+ 7: required bool blockCacheEnabled = 0,
+ 8: required bool bloomfilterEnabled = 0,
+}
+
+/**
+ * TableDescriptor contains the name of a table, and its
+ * column families.
+ */
+struct TableDescriptor {
+ 1: required Bytes name,
+ 2: optional bool rootRegion,
+ 3: optional bool metaRegion,
+ 4: optional bool metaTable,
+ 5: optional bool readOnly,
+ 6: required bool deferredLogFlush,
+ 7: required i64 maxFileSize,
+ 8: required i32 memStoreFlushSize,
+ 9: required set<ColumnFamilyDescriptor> families,
+}
+
+struct ClusterStatus {
+ 1: optional list<string> serverNames,
+ 2: optional list<string> deadServerNames,
+ 3: optional i32 serverCount,
+ 4: optional i32 deadServerCount,
+ 5: optional double averageLoad,
+ 6: optional i32 regionsCount,
+ 7: optional i32 requestsCount,
+ 8: optional string hbaseVersion,
+}
+
+
+//
+// Service
+//
+
+// Camel case doesn't work correctly here, hence the lower case "b"
+service Hbase {
+
+ //
+ // HBase Client
+ //
+
+ /**
+ * Test for the existence of columns in the table, as specified in the TGet.
+ *
+ * This will return true if the TGet matches one or more keys, false if not.
+ *
+ * This is a server-side call so it prevents any data from being transfered to
+ * the client.
+ *
+ * @param get the Get
+ * @return true if the specified TGet matches one or more keys, false if not
+ * @throws IOError
+ */
+ bool exists(1:Bytes table, 2:TGet get) throws (1:IOError io)
+
+ /**
+ * Method for getting data from a row.
+ *
+ * If the row cannot be found an empty Result is returned.
+ * This can be checked by TODO
+ *
+ * @param get the TGet to fetch
+ * @return the result
+ * @throws IOError
+ */
+ TResult get(1:Bytes table, 2:TGet get) throws (1:IOError io)
+
+ /**
+ * Method for getting multiple rows.
+ *
+ * This is currently not a very fast operation as the gets
+ * are done sequentially. Work to address this is done
+ * in https://issues.apache.org/jira/browse/HBASE-1845
+ *
+ * If a row cannot be found
+ * TODO: Return an empty result or just return nothing
+ */
+ list<TResult> getMultiple(1:Bytes table, 2:list<TGet> gets) throws (1:IOError io)
+
+ /**
+ * Return the row that matches <i>row</i> and <i>family</i> exactly, or the
+ * one that immediately precedes it.
+ *
+ * @param row row key
+ * @param family Column family to look for row in
+ * @return the result
+ * @throws IOError
+ */
+ TResult getRowOrBefore(1:Bytes table, 2:Bytes row, 3:Bytes family) throws (1:IOError io)
+
+ /**
+ * Commit a TPut to the table.
+ *
+ * If autoFlush is false, the update is buffered.
+ *
+ * @param put
+ * @throws IOError
+ */
+ void put(1:Bytes table, 2:TPut put) throws (1:IOError io)
+
+ /**
+ * Commit a List of Puts to the table.
+ *
+ * If autoFlush is false, the update is buffered.
+
+ * @param puts
+ * @throws IOException
+ */
+ void putMultiple(1:Bytes table, 2:list<TPut> puts) throws (1:IOError io)
+
+ /**
+ * Deletes as specified by the TDelete.
+ *
+ * Note: "delete" is a reserved keyword and cannot be used in Thrift
+
+ * @param delete
+ * @throws IOError
+ */
+ void deleteSingle(1:Bytes table, 2:TDelete deleteSingle) throws (1:IOError io)
+
+ /**
+ * Bulk commit a List of TDeletes to the table.
+
+ * @param deletes List of deletes. List is modified by this method.
+ * On exception holds deletes that were NOT applied.
+ * @throws IOError
+ */
+ void deleteMultiple(1:Bytes table, 2:list<TDelete> deletes) throws (1:IOError io)
+
+ /**
+ * Get a Scanner for the provided TScan object.
+ *
+ * @param table name of table
+ * @return scanner id to be used with other scanner procedures
+ */
+ i64 openScanner(1:Bytes table, 2:TScan scan) throws (1:IOError io)
+
+ /**
+ * Get a Scanner for the specified column family.
+ *
+ * @param family column family to scan
+ * @param table name of table
+ * @return scanner id to be used with other scanner procedures
+ */
+ i64 openColumnFamilyScanner(1:Bytes table, 2:Bytes family) throws (1:IOError io)
+
+ /**
+ * Get a Scanner for the specified column qualifier and column family.
+ *
+ * @param table name of table
+ * @param family column family to scan
+ * @param qualifier column qualifier to scan
+ * @return scanner id to be used with other scanner procedures
+ */
+ i64 openColumnScanner(1:Bytes table, 2:Bytes family, 3:Bytes qualifier) throws (1:IOError io)
+
+ /**
+ * Grab the next row's worth of values. The scanner will return a TResult.
+ *
+ * If this TResult is empty the scanner is exhausted and no further
+ * results are available.
+ *
+ * @return TResult object
+ * @throws IOError
+ */
+ TResult getScannerRow(1:i64 scannerId) throws (1:IOError io)
+
+ /**
+ * Grabs multiple rows from the scanner.
+ *
+ * @param nbRows number of rows to return
+ * @return Between zero and <param>numRows</param> TResults
+ * @throws IOError
+ */
+ list<TResult> getScannerRows(1:i64 scannerId, 2:i32 numRows) throws (1:IOError io)
+
+ /**
+ * Closes the scanner. Shoud be called if you need to close
+ * the Scanner before all results are read.
+ *
+ * Exhausted scanners are closed automatically.
+ */
+ void closeScanner(1:i64 scannerId) throws (1:IOError io)
+
+ //
+ // HBase Admin
+ //
+
+ /**
+ * @return true if the master is running
+ */
+ bool isMasterRunning()
+
+ /**
+ * Check to see if a table exists.
+ *
+ * @param table Table name to check
+ * @return true if the table exists
+ * @throws IOError
+ */
+ bool tableExists(1:Bytes table) throws (1:IOError io)
+
+ /**
+ * List all the userspace tables.
+ * In other words, scan the META table.
+ *
+ * @return returns an array of HTableDescriptors
+ * @throws IOError
+ */
+ list<TableDescriptor> listTables() throws (1:IOError io)
+
+ /**
+ * Method for getting a TableDescriptor for a table.
+ *
+ * @param table table name to get the descriptor for
+ * @return the TableDescriptor
+ * @throws IOError
+ */
+ TableDescriptor getTableDescriptor(1:Bytes table) throws (1:IOError io)
+
+ /**
+ * Create a table with the specified table descriptor.
+ *
+ * @param descriptor description of the table
+ *
+ * @throws IllegalArgument if an input parameter is invalid
+ * @throws AlreadyExists if the table name already exists
+ * @throws IOError
+ */
+ void createTable(1:TableDescriptor descriptor) throws (1:IOError io, 2:IllegalArgument ia, 3:AlreadyExists exists)
+
+ /**
+ * Deletes a table.
+ *
+ * @param table name of table to delete
+ * @throws IOError
+ */
+ void deleteTable(1:Bytes table) throws (1:IOError io)
+
+ /**
+ * Brings a table on-line (enables it).
+ *
+ * @param table name of the table
+ * @throws IOError
+ */
+ void enableTable(1:Bytes table) throws (1:IOError io)
+
+ /**
+ * Disables a table (takes it off-line).
+ * If it is being served, the master
+ * will tell the servers to stop serving it.
+ *
+ * @param table name of table to disable
+ * @throws IOError
+ */
+ void disableTable(1:Bytes table) throws (1:IOError io)
+
+ /**
+ * @param table name of table to check
+ * @return true if table is on-line
+ * @throws IOError
+ */
+ bool isTableEnabled(1:Bytes table) throws (1:IOError io)
+
+ /**
+ * @param table name of the table to check
+ * @return true if table is off-line
+ * @throws IOError
+ */
+ bool isTableDisabled(1:Bytes table) throws (1:IOError io)
+
+ /**
+ * Add a column family to an existing table.
+ *
+ * @param table name of the table to add column family to
+ * @param descriptor column family descriptor of column family to be added
+ * @throws IOError
+ */
+ void addColumnFamily(1:Bytes table, 2:ColumnFamilyDescriptor descriptor) throws (1:IOError io)
+
+ /**
+ * Delete a column family from a table.
+ *
+ * @param table name of table to delete the column family from
+ * @param columnFamilyName name of column family to be deleted
+ * @throws IOError
+ */
+ void deleteColumnFamily(1:Bytes table, 2:Bytes columnFamilyName) throws (1:IOError io)
+
+ /**
+ * Modify an existing column family on a table.
+ *
+ * @param table name of table
+ * @param columnFamilyName name of column family to be modified
+ * @param descriptor new column family descriptor to use
+ * @throws IOError
+ */
+ void modifyColumnFamily(1:Bytes table, 2:Bytes columnFamilyName, 3:ColumnFamilyDescriptor descriptor) throws (1:IOError io)
+
+ /**
+ * Flush a table or an individual region.
+ *
+ * @param name name of a table or region to flush
+ * @throws IOError
+ */
+ void flush(1:Bytes name) throws (1:IOError io)
+
+ /**
+ * Compact a table or an individual region.
+ *
+ * @param name name of a table or region to compact
+ * @throws IOError
+ */
+ void compact(1:Bytes name) throws (1:IOError io)
+
+ /**
+ * Major compact a table or an individual region.
+ *
+ * @param name name of a table or region to compact
+ * @throws IOError
+ */
+ void majorCompact(1:Bytes name) throws (1:IOError io)
+
+ /**
+ * Split a table or an individual region.
+ *
+ * @param name name of a table or region to compact
+ * @throws IOError
+ */
+ void split(1:Bytes name) throws (1:IOError io)
+
+ /**
+ * Modify an existing table
+ *
+ * @param name name of the table to modify
+ * @param descriptor modified description of the table
+ * @throws IOError
+ */
+ void modifyTable(1:Bytes name, 2:TableDescriptor descriptor) throws (1:IOError io)
+
+ /**
+ * Shuts down the HBase instance
+ *
+ * @throws IOError
+ */
+ void shutdown() throws (1:IOError io)
+
+ /**
+ * Get information about the cluster.
+ *
+ * @return cluster status
+ * @throws IOError
+ */
+ ClusterStatus getClusterStatus() throws (1:IOError io)
+
+}

0 comments on commit 2881e97

Please sign in to comment.
Something went wrong with that request. Please try again.