multiGet

读同一HashKey下的多行数据。

  1. /**
  2.  * Get multiple value under the same hash key.
  3.  * @param tableName table name
  4.  * @param hashKey used to decide which partition to put this k-v,
  5.  *                should not be null or empty.
  6.  * @param sortKeys all the k-v under hashKey will be sorted by sortKey,
  7.  *                if null or empty, means fetch all sortKeys under the hashKey.
  8.  * @param maxFetchCount max count of k-v pairs to be fetched.
  9.  *                      max_fetch_count <= 0 means no limit. default value is 100.
  10.  * @param maxFetchSize max size of k-v pairs to be fetched.
  11.  *                     max_fetch_size <= 0 means no limit. default value is 1000000.
  12.  * @param values output values; if sortKey is not found, then it will not appear in values.
  13.  *               the returned sortKey is just the same one in incoming sortKeys.
  14.  * @return true if all data is fetched; false if only partial data is fetched.
  15.  * @throws PException
  16.  */
  17. public boolean multiGet(String tableName, byte[] hashKey, List<byte[]> sortKeys, int maxFetchCount, int maxFetchSize, List<Pair<byte[], byte[]>> values) throws PException;
  18. public boolean multiGet(String tableName, byte[] hashKey, List<byte[]> sortKeys, List<Pair<byte[], byte[]>> values) throws PException;

注：

  • 提供了两个版本的接口，其中第一个接口可以指定maxFetchCount和maxFetchSize。
  • 参数：
    • 传入参数：需传入TableName、HashKey、SortKeys；选择性传入maxFetchCount、maxFetchSize。
    • 传出参数：数据通过values传出，values由用户在调用前new出来。
    • SortKeys如果非空，则只读取指定的数据；SortKeys如果为空，则表示读取该HashKey下的所有数据。
    • maxFetchCount和maxFetchSize用于限制读取的数据量，maxFetchCount表示最多读取的数据条数，maxFetchSize表示最多读取的数据字节数，两者任一达到限制就停止读取。
  • 返回值：如果用户指定了maxFetchCount或者maxFetchSize，单次查询可能只获取到部分结果。如果所有满足条件的数据都已经获取到，则返回true；否则返回false。
  • 异常：如果出现异常，譬如网络错误、超时错误、服务端错误等，会抛出 PException。multiGet还有另外一个版本的接口，可以支持SortKey的范围查询和条件过滤，只读取满足特定条件的数据。并且从1.8.0开始在MultiGetOptions中增加了reverse参数，支持逆向扫描数据。
  1. public enum FilterType {
  2.     FT_NO_FILTER(0),
  3.     FT_MATCH_ANYWHERE(1), // match filter string at any position
  4.     FT_MATCH_PREFIX(2),   // match filter string at prefix
  5.     FT_MATCH_POSTFIX(3);  // match filter string at postfix
  6. }
  7.  
  8. public class MultiGetOptions {
  9.     public boolean startInclusive = true; // if the startSortKey is included
  10.     public boolean stopInclusive = false; // if the stopSortKey is included
  11.     public FilterType sortKeyFilterType = FilterType.FT_NO_FILTER; // filter type for sort key
  12.     public byte[] sortKeyFilterPattern = null; // filter pattern for sort key
  13.     public boolean noValue = false; // only fetch hash_key and sort_key, but not fetch value
  14.     public boolean reverse = false; // if search in reverse direction
  15. }
  16.  
  17. /**
  18. * Get multiple key-values under the same hashKey with sortKey range limited.
  19. * @param tableName table name
  20. * @param hashKey used to decide which partition the key may exist
  21. *                should not be null or empty.
  22. * @param startSortKey the start sort key.
  23. *                     null means "".
  24. * @param stopSortKey the stop sort key.
  25. *                    null or "" means fetch to the last sort key.
  26. * @param options multi-get options.
  27. * @param maxFetchCount max count of kv pairs to be fetched
  28. *                      maxFetchCount <= 0 means no limit. default value is 100
  29. * @param maxFetchSize max size of kv pairs to be fetched.
  30. *                     maxFetchSize <= 0 means no limit. default value is 1000000.
  31. * @param values output values; if sortKey is not found, then it will not appear in values.
  32. *               the returned sortKey is just the same one in incoming sortKeys.
  33. * @return true if all data is fetched; false if only partial data is fetched.
  34. * @throws PException
  35. */
  36. public boolean multiGet(String tableName, byte[] hashKey,
  37.                     byte[] startSortKey, byte[] stopSortKey, MultiGetOptions options,
  38.                     int maxFetchCount, int maxFetchSize,
  39.                     List<Pair<byte[], byte[]>> values) throws PException;
  40. public boolean multiGet(String tableName, byte[] hashKey,
  41.                     byte[] startSortKey, byte[] stopSortKey, MultiGetOptions options,
  42.                     List<Pair<byte[], byte[]>> values) throws PException;

注：

  • 提供了两个版本的接口，其中第一个接口可以指定maxFetchCount和maxFetchSize。
  • 参数：
    • 传入参数：需传入TableName、HashKey、StartSortKey、StopSortKey、MultiGetOptions；选择性传入maxFetchCount、maxFetchSize。
    • 传出参数：数据通过values传出，values由用户在调用前new出来。
    • StopSortKeys如果为空，不论stopInclusive为何值，都会读到该HashKey的SortKey结束。
    • maxFetchCount和maxFetchSize用于限制读取的数据量，maxFetchCount表示最多读取的数据条数，maxFetchSize表示最多读取的数据字节数，两者任一达到限制就停止读取。
    • MultiGetOptions说明：
      • startInclusive：是否包含StartSortKey，默认为true。
      • stopInclusive：是否包含StopSortKey，默认为false。
      • sortKeyFilterType：SortKey的过滤类型，包括无过滤、任意位置匹配、前缀匹配和后缀匹配，默认无过滤。
      • sortKeyFilterPattern：SortKey的过滤模式串，空串相当于无过滤。
      • noValue：只返回HashKey和SortKey，不返回Value数据，默认为false。
      • reverse：是否逆向扫描数据库，从后往前查找数据。但是查找得到的结果在list中还是按照SortKey从小到大顺序存放。从Pegasus Server 1.8.0时开始支持。
    • 返回值：如果读取了所有满足条件的数据，返回true；如果只读取了部分满足条件的数据，返回false。
    • 异常：如果出现异常，譬如网络错误、超时错误、服务端错误等，会抛出 PException。
    • 示例：获取某个HashKey下的所有数据（注意如果数据条数太多容易超时）
      • multiGet(hashKey, null, null, new MultiGetOptions(), -1, -1, values);