trunk/hbase-server/src/main/protobuf/Client.proto

/**
 * 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.
 */

// This file contains protocol buffers that are used for Client service.

option java_package = "org.apache.hadoop.hbase.protobuf.generated";
option java_outer_classname = "ClientProtos";
option java_generic_services = true;
option java_generate_equals_and_hash = true;
option optimize_for = SPEED;

import "hbase.proto";
import "Comparator.proto";

/**
 * Container for a list of column qualifier names of a family.
 */
message Column {
  required bytes family = 1;
  repeated bytes qualifier = 2;
}

/**
 * The protocol buffer version of Get
 */
message Get {
  required bytes row = 1;
  repeated Column column = 2;
  repeated NameBytesPair attribute = 3;
  optional uint64 lockId = 4;
  optional Filter filter = 5;
  optional TimeRange timeRange = 6;
  optional uint32 maxVersions = 7 [default = 1];
  optional bool cacheBlocks = 8 [default = true];
  optional uint32 storeLimit = 9;
  optional uint32 storeOffset = 10;
}

/**
 * For performance reason, we don't use KeyValue
 * here. We use the actual KeyValue bytes.
 */
message Result {
  repeated bytes keyValueBytes = 1;
}

/**
 * The get request. Perform a single Get operation.
 * Unless existenceOnly is specified, return all the requested data
 * for the row that matches exactly, or the one that immediately
 * precedes it if closestRowBefore is specified.
 *
 * If existenceOnly is set, only the existence will be returned.
 */
message GetRequest {
  required RegionSpecifier region = 1;
  required Get get = 2;

  // If the row to get doesn't exist, return the
  // closest row before.
  optional bool closestRowBefore = 3;

  // The result isn't asked for, just check for
  // the existence. If specified, closestRowBefore
  // will be ignored
  optional bool existenceOnly = 4;
}

message GetResponse {
  optional Result result = 1;

  // used for Get to check existence only
  optional bool exists = 2;
}

/**
 * Condition to check if the value of a given cell (row,
 * family, qualifier) matches a value via a given comparator.
 *
 * Condition is used in check and mutate operations.
 */
message Condition {
  required bytes row = 1;
  required bytes family = 2;
  required bytes qualifier = 3;
  required CompareType compareType = 4;
  required Comparator comparator = 5;
}

/**
 * A specific mutate inside a mutate request.
 * It can be an append, increment, put or delete based
 * on the mutate type.
 */
message Mutate {
  required bytes row = 1;
  required MutateType mutateType = 2;
  repeated ColumnValue columnValue = 3;
  repeated NameBytesPair attribute = 4;
  optional uint64 timestamp = 5;
  optional uint64 lockId = 6;
  optional bool writeToWAL = 7 [default = true];

  // For some mutate, result may be returned, in which case,
  // time range can be specified for potential performance gain
  optional TimeRange timeRange = 10;

  enum MutateType {
    APPEND = 0;
    INCREMENT = 1;
    PUT = 2;
    DELETE = 3;
  }

  enum DeleteType {
    DELETE_ONE_VERSION = 0;
    DELETE_MULTIPLE_VERSIONS = 1;
    DELETE_FAMILY = 2;
  }

  message ColumnValue {
    required bytes family = 1;
    repeated QualifierValue qualifierValue = 2;

    message QualifierValue {
      optional bytes qualifier = 1;
      optional bytes value = 2;
      optional uint64 timestamp = 3;
      optional DeleteType deleteType = 4;
    }
  }
}

/**
 * The mutate request. Perform a single Mutate operation.
 *
 * Optionally, you can specify a condition. The mutate
 * will take place only if the condition is met.  Otherwise,
 * the mutate will be ignored.  In the response result,
 * parameter processed is used to indicate if the mutate
 * actually happened.
 */
message MutateRequest {
  required RegionSpecifier region = 1;
  required Mutate mutate = 2;
  optional Condition condition = 3;
}

message MutateResponse {
  optional Result result = 1;

  // used for mutate to indicate processed only
  optional bool processed = 2;
}

/**
 * Instead of get from a table, you can scan it with optional filters.
 * You can specify the row key range, time range, the columns/families
 * to scan and so on.
 *
 * This scan is used the first time in a scan request. The response of
 * the initial scan will return a scanner id, which should be used to
 * fetch result batches later on before it is closed.
 */
message Scan {
  repeated Column column = 1;
  repeated NameBytesPair attribute = 2;
  optional bytes startRow = 3;
  optional bytes stopRow = 4;
  optional Filter filter = 5;
  optional TimeRange timeRange = 6;
  optional uint32 maxVersions = 7 [default = 1];
  optional bool cacheBlocks = 8 [default = true];
  optional uint32 batchSize = 9;
  optional uint64 maxResultSize = 10;
  optional uint32 storeLimit = 11;
  optional uint32 storeOffset = 12;
}

/**
 * A scan request. Initially, it should specify a scan. Later on, you
 * can use the scanner id returned to fetch result batches with a different
 * scan request.
 *
 * The scanner will remain open if there are more results, and it's not
 * asked to be closed explicitly.
 *
 * You can fetch the results and ask the scanner to be closed to save
 * a trip if you are not interested in remaining results.
 */
message ScanRequest {
  optional RegionSpecifier region = 1;
  optional Scan scan = 2;
  optional uint64 scannerId = 3;
  optional uint32 numberOfRows = 4;
  optional bool closeScanner = 5;
}

/**
 * The scan response. If there are no more results, moreResults will
 * be false.  If it is not specified, it means there are more.
 */
message ScanResponse {
  repeated Result result = 1;
  optional uint64 scannerId = 2;
  optional bool moreResults = 3;
  optional uint32 ttl = 4;
}

message LockRowRequest {
  required RegionSpecifier region = 1;
  repeated bytes row = 2;
}

message LockRowResponse {
  required uint64 lockId = 1;
  optional uint32 ttl = 2;
}

message UnlockRowRequest {
  required RegionSpecifier region = 1;
  required uint64 lockId = 2;
}

message UnlockRowResponse {
}

/**
 * Atomically bulk load multiple HFiles (say from different column families)
 * into an open region.
 */
message BulkLoadHFileRequest {
  required RegionSpecifier region = 1;
  repeated FamilyPath familyPath = 2;
  optional bool assignSeqNum = 3;

  message FamilyPath {
    required bytes family = 1;
    required string path = 2;
  }
}

message BulkLoadHFileResponse {
  required bool loaded = 1;
}

/**
 * An individual coprocessor call. You must specify the protocol,
 * the method, and the row to which the call will be executed.
 *
 * You can specify the configuration settings in the property list.
 *
 * The parameter list has the parameters used for the method.
 * A parameter is a pair of parameter name and the binary parameter
 * value. The name is the parameter class name.  The value is the
 * binary format of the parameter, for example, protocol buffer
 * encoded value.
 */
message Exec {
  required bytes row = 1;
  required string protocolName = 2;
  required string methodName = 3;
  repeated NameStringPair property = 4;
  repeated NameBytesPair parameter = 5;
}

  /**
   * Executes a single {@link org.apache.hadoop.hbase.ipc.CoprocessorProtocol}
   * method using the registered protocol handlers.
   * {@link CoprocessorProtocol} implementations must be registered via the
   * {@link org.apache.hadoop.hbase.regionserver.HRegion#registerProtocol(
   * Class, org.apache.hadoop.hbase.ipc.CoprocessorProtocol)}
   * method before they are available.
 */
message ExecCoprocessorRequest {
  required RegionSpecifier region = 1;
  required Exec call = 2;
}

message ExecCoprocessorResponse {
  required NameBytesPair value = 1;
}

/**
 * An action that is part of MultiRequest.
 * This is a union type - exactly one of the fields will be set.
 */
message MultiAction {
  optional Mutate mutate = 1;
  optional Get get = 2;
  optional Exec exec = 3;
}

/**
 * An individual action result. The result will in the
 * same order as the action in the request. If an action
 * returns a value, it is set in value field. If it doesn't
 * return anything, the result will be empty. If an action
 * fails to execute due to any exception, the exception
 * is returned as a stringified parameter.
 */
message ActionResult {
  optional NameBytesPair value = 1;
  optional NameBytesPair exception = 2;
}

/**
 * You can execute a list of actions on a given region in order.
 *
 * If it is a list of mutate actions, atomic can be set
 * to make sure they can be processed atomically, just like
 * RowMutations.
 */
message MultiRequest {
  required RegionSpecifier region = 1;
  repeated MultiAction action = 2;
  optional bool atomic = 3;
}

message MultiResponse {
  repeated ActionResult result = 1;
}


service ClientService {
  rpc get(GetRequest)
    returns(GetResponse);

  rpc mutate(MutateRequest)
    returns(MutateResponse);

  rpc scan(ScanRequest)
    returns(ScanResponse);

  rpc lockRow(LockRowRequest)
    returns(LockRowResponse);

  rpc unlockRow(UnlockRowRequest)
    returns(UnlockRowResponse);

  rpc bulkLoadHFile(BulkLoadHFileRequest)
    returns(BulkLoadHFileResponse);

  rpc execCoprocessor(ExecCoprocessorRequest)
    returns(ExecCoprocessorResponse);

  rpc multi(MultiRequest)
    returns(MultiResponse);
}