Scan (Apache HBase 2.0.6 API)

java.lang.Object
- org.apache.hadoop.hbase.client.Operation
- - org.apache.hadoop.hbase.client.OperationWithAttributes
  - - org.apache.hadoop.hbase.client.Query
    - - org.apache.hadoop.hbase.client.Scan

All Implemented Interfaces:

Attributes

Direct Known Subclasses:

InternalScan
```
@InterfaceAudience.Public
public class Scan
extends Query
```
Used to perform Scan operations.
All operations are identical to Get with the exception of instantiation. Rather than specifying a single row, an optional startRow and stopRow may be defined. If rows are not specified, the Scanner will iterate over all rows.
To get all columns from all rows of a Table, create an instance with no constraints; use the Scan() constructor. To constrain the scan to specific column families, call addFamily for each family to retrieve on your Scan instance.
To get specific columns, call addColumn for each column to retrieve.
To only retrieve columns within a specific range of version timestamps, call setTimeRange.
To only retrieve columns with a specific timestamp, call setTimestamp .
To limit the number of versions of each column to be returned, call setMaxVersions.
To limit the maximum number of values returned for each call to next(), call setBatch.
To add a filter, call setFilter.
For small scan, it is deprecated in 2.0.0. Now we have a setLimit(int) method in Scan object which is used to tell RS how many rows we want. If the rows return reaches the limit, the RS will close the RegionScanner automatically. And we will also fetch data when openScanner in the new implementation, this means we can also finish a scan operation in one rpc call. And we have also introduced a setReadType(ReadType) method. You can use this method to tell RS to use pread explicitly.
Expert: To explicitly disable server-side block caching for this scan, execute setCacheBlocks(boolean).
Note: Usage alters Scan instances. Internally, attributes are updated as the Scan runs and if enabled, metrics accumulate in the Scan instance. Be aware this is the case when you go to clone a Scan instance or if you go to reuse a created Scan instance; safer is create a Scan instance per usage.

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class Scan.ReadType

Nested Classes
Modifier and Type	Class and Description
`static class`	`Scan.ReadType`

Field Summary

Fields
Modifier and Type	Field and Description
`private boolean`	`allowPartialResults` Partial `Result`s are `Result`s must be combined to form a complete `Result`.
`private Boolean`	`asyncPrefetch`
`private int`	`batch`
`private boolean`	`cacheBlocks`
`private int`	`caching` -1 means no caching specified and the value of `HConstants.HBASE_CLIENT_SCANNER_CACHING` (default to `HConstants.DEFAULT_HBASE_CLIENT_SCANNER_CACHING`) will be used
`static boolean`	`DEFAULT_HBASE_CLIENT_SCANNER_ASYNC_PREFETCH` Default value of `HBASE_CLIENT_SCANNER_ASYNC_PREFETCH`.
`private Map<byte[],NavigableSet<byte[]>>`	`familyMap`
`static String`	`HBASE_CLIENT_SCANNER_ASYNC_PREFETCH` Parameter name for client scanner sync/async prefetch toggle.
`private boolean`	`includeStartRow`
`private boolean`	`includeStopRow`
`private int`	`limit` The number of rows we want for this scan.
`private static org.slf4j.Logger`	`LOG`
`private long`	`maxResultSize`
`private int`	`maxVersions`
`private long`	`mvccReadPoint` The mvcc read point to use when open a scanner.
`private boolean`	`needCursorResult`
`private static String`	`RAW_ATTR`
`private Scan.ReadType`	`readType` Control whether to use pread at server side.
`private boolean`	`reversed`
`static String`	`SCAN_ATTRIBUTES_METRICS_DATA` Deprecated.
`static String`	`SCAN_ATTRIBUTES_METRICS_ENABLE` Deprecated. since 1.0.0. Use `setScanMetricsEnabled(boolean)`
`static String`	`SCAN_ATTRIBUTES_TABLE_NAME`
`private boolean`	`small` Set it true for small scan to get better performance Small scan should use pread and big scan can use seek + read seek + read is fast but can cause two problem (1) resource contention (2) cause too much network io [89-fb] Using pread for non-compaction read request https://issues.apache.org/jira/browse/HBASE-7266 On the other hand, if setting it true, we would do openScanner,next,closeScanner in one RPC call.
`private byte[]`	`startRow`
`private byte[]`	`stopRow`
`private int`	`storeLimit`
`private int`	`storeOffset`
`private TimeRange`	`tr`

Fields inherited from class org.apache.hadoop.hbase.client.Query
colFamTimeRangeMap, consistency, filter, loadColumnFamiliesOnDemand, targetReplicaId

Fields inherited from class org.apache.hadoop.hbase.client.OperationWithAttributes
ID_ATRIBUTE

Constructor Summary

Constructors
Constructor and Description
`Scan()` Create a Scan operation across all rows.
`Scan(byte[] startRow)` Deprecated. since 2.0.0 and will be removed in 3.0.0. Use `new Scan().withStartRow(startRow)` instead.
`Scan(byte[] startRow, byte[] stopRow)` Deprecated. since 2.0.0 and will be removed in 3.0.0. Use `new Scan().withStartRow(startRow).withStopRow(stopRow)` instead.
`Scan(byte[] startRow, Filter filter)` Deprecated. since 2.0.0 and will be removed in 3.0.0. Use `new Scan().withStartRow(startRow).setFilter(filter)` instead.
`Scan(Get get)` Builds a scan object with the same specs as get.
`Scan(Scan scan)` Creates a new instance of this class while copying all values.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`Scan`	`addColumn(byte[] family, byte[] qualifier)` Get the column from the specified family with the specified qualifier.
`Scan`	`addFamily(byte[] family)` Get all columns from the specified family.
`private byte[]`	`calculateTheClosestNextRowKeyForPrefix(byte[] rowKeyPrefix)` When scanning for a prefix the scan should stop immediately after the the last row that has the specified prefix.
`static Scan`	`createScanFromCursor(Cursor cursor)` Create a new Scan with a cursor.
`boolean`	`getAllowPartialResults()`
`int`	`getBatch()`
`boolean`	`getCacheBlocks()` Get whether blocks should be cached for this Scan.
`int`	`getCaching()`
`byte[][]`	`getFamilies()`
`Map<byte[],NavigableSet<byte[]>>`	`getFamilyMap()` Getting the familyMap
`Filter`	`getFilter()`
`Map<String,Object>`	`getFingerprint()` Compile the table and column family (i.e.
`int`	`getLimit()`
`long`	`getMaxResultSize()`
`int`	`getMaxResultsPerColumnFamily()`
`int`	`getMaxVersions()`
`(package private) long`	`getMvccReadPoint()` Get the mvcc read point used to open a scanner.
`Scan.ReadType`	`getReadType()`
`int`	`getRowOffsetPerColumnFamily()` Method for retrieving the scan's offset per row per column family (#kvs to be skipped)
`ScanMetrics`	`getScanMetrics()` Deprecated. Use `ResultScanner.getScanMetrics()` instead. And notice that, please do not use this method and `ResultScanner.getScanMetrics()` together, the metrics will be messed up.
`byte[]`	`getStartRow()`
`byte[]`	`getStopRow()`
`TimeRange`	`getTimeRange()`
`boolean`	`hasFamilies()`
`boolean`	`hasFilter()`
`boolean`	`includeStartRow()`
`boolean`	`includeStopRow()`
`Boolean`	`isAsyncPrefetch()`
`boolean`	`isGetScan()`
`boolean`	`isNeedCursorResult()`
`boolean`	`isRaw()`
`boolean`	`isReversed()` Get whether this scan is a reversed one.
`boolean`	`isScanMetricsEnabled()`
`boolean`	`isSmall()` Deprecated. since 2.0.0 and will be removed in 3.0.0. See the comment of `setSmall(boolean)`
`int`	`numFamilies()`
`Scan`	`readAllVersions()` Get all available versions.
`Scan`	`readVersions(int versions)` Get up to the specified number of versions of each column.
`(package private) Scan`	`resetMvccReadPoint()` Set the mvcc read point to -1 which means do not use it.
`Scan`	`setACL(Map<String,Permission> perms)`
`Scan`	`setACL(String user, Permission perms)`
`Scan`	`setAllowPartialResults(boolean allowPartialResults)` Setting whether the caller wants to see the partial results when server returns less-than-expected cells.
`Scan`	`setAsyncPrefetch(boolean asyncPrefetch)`
`Scan`	`setAttribute(String name, byte[] value)` Sets an attribute.
`Scan`	`setAuthorizations(Authorizations authorizations)` Sets the authorizations to be used by this Query
`Scan`	`setBatch(int batch)` Set the maximum number of cells to return for each call to next().
`Scan`	`setCacheBlocks(boolean cacheBlocks)` Set whether blocks should be cached for this Scan.
`Scan`	`setCaching(int caching)` Set the number of rows for caching that will be passed to scanners.
`Scan`	`setColumnFamilyTimeRange(byte[] cf, long minStamp, long maxStamp)` Get versions of columns only within the specified timestamp range, [minStamp, maxStamp) on a per CF bases.
`Scan`	`setConsistency(Consistency consistency)` Sets the consistency level for this operation
`Scan`	`setFamilyMap(Map<byte[],NavigableSet<byte[]>> familyMap)` Setting the familyMap
`Scan`	`setFilter(Filter filter)` Apply the specified server-side filter when performing the Query.
`Scan`	`setId(String id)` This method allows you to set an identifier on an operation.
`Scan`	`setIsolationLevel(IsolationLevel level)` Set the isolation level for this query.
`Scan`	`setLimit(int limit)` Set the limit of rows for this scan.
`Scan`	`setLoadColumnFamiliesOnDemand(boolean value)` Set the value indicating whether loading CFs on demand should be allowed (cluster default is false).
`Scan`	`setMaxResultSize(long maxResultSize)` Set the maximum result size.
`Scan`	`setMaxResultsPerColumnFamily(int limit)` Set the maximum number of values to return per row per Column Family
`Scan`	`setMaxVersions()` Deprecated. since 2.0.0 and will be removed in 3.0.0. It is easy to misunderstand with column family's max versions, so use `readAllVersions()` instead.
`Scan`	`setMaxVersions(int maxVersions)` Deprecated. since 2.0.0 and will be removed in 3.0.0. It is easy to misunderstand with column family's max versions, so use `readVersions(int)` instead.
`(package private) Scan`	`setMvccReadPoint(long mvccReadPoint)` Set the mvcc read point used to open a scanner.
`Scan`	`setNeedCursorResult(boolean needCursorResult)` When the server is slow or we scan a table with many deleted data or we use a sparse filter, the server will response heartbeat to prevent timeout.
`Scan`	`setOneRowLimit()` Call this when you only want to get one row.
`Scan`	`setPriority(int priority)`
`Scan`	`setRaw(boolean raw)` Enable/disable "raw" mode for this scan.
`Scan`	`setReadType(Scan.ReadType readType)` Set the read type for this scan.
`Scan`	`setReplicaId(int Id)` Specify region replica id where Query will fetch data from.
`Scan`	`setReversed(boolean reversed)` Set whether this scan is a reversed one
`Scan`	`setRowOffsetPerColumnFamily(int offset)` Set offset for the row per Column Family.
`Scan`	`setRowPrefixFilter(byte[] rowPrefix)` Set a filter (using stopRow and startRow) so the result set only contains rows where the rowKey starts with the specified prefix.
`Scan`	`setScanMetricsEnabled(boolean enabled)` Enable collection of `ScanMetrics`.
`Scan`	`setSmall(boolean small)` Deprecated. since 2.0.0 and will be removed in 3.0.0. Use `setLimit(int)` and `setReadType(ReadType)` instead. And for the one rpc optimization, now we will also fetch data when openScanner, and if the number of rows reaches the limit then we will close the scanner automatically which means we will fall back to one rpc.
`Scan`	`setStartRow(byte[] startRow)` Deprecated. since 2.0.0 and will be removed in 3.0.0. Use `withStartRow(byte[])` instead. This method may change the inclusive of the stop row to keep compatible with the old behavior.
`Scan`	`setStopRow(byte[] stopRow)` Deprecated. since 2.0.0 and will be removed in 3.0.0. Use `withStopRow(byte[])` instead. This method may change the inclusive of the stop row to keep compatible with the old behavior.
`Scan`	`setTimeRange(long minStamp, long maxStamp)` Get versions of columns only within the specified timestamp range, [minStamp, maxStamp).
`Scan`	`setTimestamp(long timestamp)` Get versions of columns with the specified timestamp.
`Scan`	`setTimeStamp(long timestamp)` Deprecated. As of release 2.0.0, this will be removed in HBase 3.0.0. Use `setTimestamp(long)` instead
`Map<String,Object>`	`toMap(int maxCols)` Compile the details beyond the scope of getFingerprint (row, columns, timestamps, etc.) into a Map along with the fingerprinted information.
`Scan`	`withStartRow(byte[] startRow)` Set the start row of the scan.
`Scan`	`withStartRow(byte[] startRow, boolean inclusive)` Set the start row of the scan.
`Scan`	`withStopRow(byte[] stopRow)` Set the stop row of the scan.
`Scan`	`withStopRow(byte[] stopRow, boolean inclusive)` Set the stop row of the scan.

Methods inherited from class org.apache.hadoop.hbase.client.Query
doLoadColumnFamiliesOnDemand, getACL, getAuthorizations, getColumnFamilyTimeRange, getConsistency, getIsolationLevel, getLoadColumnFamiliesOnDemandValue, getReplicaId

Methods inherited from class org.apache.hadoop.hbase.client.OperationWithAttributes
getAttribute, getAttributeSize, getAttributesMap, getId, getPriority

Methods inherited from class org.apache.hadoop.hbase.client.Operation
toJSON, toJSON, toMap, toString, toString

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - LOG
```
private static final org.slf4j.Logger LOG
```
  - RAW_ATTR
```
private static final String RAW_ATTR
```
    See Also:
    
    Constant Field Values
  - startRow
```
private byte[] startRow
```
  - includeStartRow
```
private boolean includeStartRow
```
  - stopRow
```
private byte[] stopRow
```
  - includeStopRow
```
private boolean includeStopRow
```
  - maxVersions
```
private int maxVersions
```
  - batch
```
private int batch
```
  - allowPartialResults
```
private boolean allowPartialResults
```
    Partial Results are Results must be combined to form a complete Result. The Results had to be returned in fragments (i.e. as partials) because the size of the cells in the row exceeded max result size on the server. Typically partial results will be combined client side into complete results before being delivered to the caller. However, if this flag is set, the caller is indicating that they do not mind seeing partial results (i.e. they understand that the results returned from the Scanner may only represent part of a particular row). In such a case, any attempt to combine the partials into a complete result on the client side will be skipped, and the caller will be able to see the exact results returned from the server.
  - storeLimit
```
private int storeLimit
```
  - storeOffset
```
private int storeOffset
```
  - SCAN_ATTRIBUTES_METRICS_ENABLE
```
@Deprecated
public static final String SCAN_ATTRIBUTES_METRICS_ENABLE
```
    Deprecated. since 1.0.0. Use setScanMetricsEnabled(boolean)
    
    See Also:
    
    Constant Field Values
  - SCAN_ATTRIBUTES_METRICS_DATA
```
@Deprecated
public static final String SCAN_ATTRIBUTES_METRICS_DATA
```
    Deprecated.
    
    Use getScanMetrics()
    
    See Also:
    
    Constant Field Values
  - SCAN_ATTRIBUTES_TABLE_NAME
```
public static final String SCAN_ATTRIBUTES_TABLE_NAME
```
    See Also:
    
    Constant Field Values
  - caching
```
private int caching
```
    -1 means no caching specified and the value of HConstants.HBASE_CLIENT_SCANNER_CACHING (default to HConstants.DEFAULT_HBASE_CLIENT_SCANNER_CACHING) will be used
  - maxResultSize
```
private long maxResultSize
```
  - cacheBlocks
```
private boolean cacheBlocks
```
  - reversed
```
private boolean reversed
```
  - tr
```
private TimeRange tr
```
  - familyMap
```
private Map<byte[],NavigableSet<byte[]>> familyMap
```
  - asyncPrefetch
```
private Boolean asyncPrefetch
```
  - HBASE_CLIENT_SCANNER_ASYNC_PREFETCH
```
public static final String HBASE_CLIENT_SCANNER_ASYNC_PREFETCH
```
    Parameter name for client scanner sync/async prefetch toggle. When using async scanner, prefetching data from the server is done at the background. The parameter currently won't have any effect in the case that the user has set Scan#setSmall or Scan#setReversed
    
    See Also:
    
    Constant Field Values
  - DEFAULT_HBASE_CLIENT_SCANNER_ASYNC_PREFETCH
```
public static final boolean DEFAULT_HBASE_CLIENT_SCANNER_ASYNC_PREFETCH
```
    Default value of HBASE_CLIENT_SCANNER_ASYNC_PREFETCH.
    
    See Also:
    
    Constant Field Values
  - small
```
private boolean small
```
    Set it true for small scan to get better performance Small scan should use pread and big scan can use seek + read seek + read is fast but can cause two problem (1) resource contention (2) cause too much network io [89-fb] Using pread for non-compaction read request https://issues.apache.org/jira/browse/HBASE-7266 On the other hand, if setting it true, we would do openScanner,next,closeScanner in one RPC call. It means the better performance for small scan. [HBASE-9488]. Generally, if the scan range is within one data block(64KB), it could be considered as a small scan.
  - mvccReadPoint
```
private long mvccReadPoint
```
    The mvcc read point to use when open a scanner. Remember to clear it after switching regions as the mvcc is only valid within region scope.
  - limit
```
private int limit
```
    The number of rows we want for this scan. We will terminate the scan if the number of return rows reaches this value.
  - readType
```
private Scan.ReadType readType
```
    Control whether to use pread at server side.
  - needCursorResult
```
private boolean needCursorResult
```
- Constructor Detail
  - Scan
```
public Scan()
```
    Create a Scan operation across all rows.
  - Scan
```
@Deprecated
public Scan(byte[] startRow,
                        Filter filter)
```
    Deprecated. since 2.0.0 and will be removed in 3.0.0. Use new Scan().withStartRow(startRow).setFilter(filter) instead.
    
    See Also:
    
    HBASE-17320
  - Scan
```
@Deprecated
public Scan(byte[] startRow)
```
    Deprecated. since 2.0.0 and will be removed in 3.0.0. Use new Scan().withStartRow(startRow) instead.
    
    Create a Scan operation starting at the specified row.
    If the specified row does not exist, the Scanner will start from the next closest row after the specified row.
    
    Parameters:
    
    startRow - row to start scanner at or after
    
    See Also:
    
    HBASE-17320
  - Scan
```
@Deprecated
public Scan(byte[] startRow,
                        byte[] stopRow)
```
    Deprecated. since 2.0.0 and will be removed in 3.0.0. Use new Scan().withStartRow(startRow).withStopRow(stopRow) instead.
    
    Create a Scan operation for the range of rows specified.
    
    Parameters:
    
    startRow - row to start scanner at or after (inclusive)
    
    stopRow - row to stop scanner before (exclusive)
    
    See Also:
    
    HBASE-17320
  - Scan
```
public Scan(Scan scan)
     throws IOException
```
    Creates a new instance of this class while copying all values.
    
    Parameters:
    
    scan - The scan instance to copy from.
    
    Throws:
    
    IOException - When copying the values fails.
  - Scan
```
public Scan(Get get)
```
    Builds a scan object with the same specs as get.
    
    Parameters:
    
    get - get to model scan after
- Method Detail
  - isGetScan
```
public boolean isGetScan()
```
  - addFamily
```
public Scan addFamily(byte[] family)
```
    Get all columns from the specified family.
    Overrides previous calls to addColumn for this family.
    
    Parameters:
    
    family - family name
    
    Returns:
    
    this
  - addColumn
```
public Scan addColumn(byte[] family,
                      byte[] qualifier)
```
    Get the column from the specified family with the specified qualifier.
    Overrides previous calls to addFamily for this family.
    
    Parameters:
    
    family - family name
    
    qualifier - column qualifier
    
    Returns:
    
    this
  - setTimeRange
```
public Scan setTimeRange(long minStamp,
                         long maxStamp)
                  throws IOException
```
    Get versions of columns only within the specified timestamp range, [minStamp, maxStamp). Note, default maximum versions to return is 1. If your time range spans more than one version and you want all versions returned, up the number of versions beyond the default.
    
    Parameters:
    
    minStamp - minimum timestamp value, inclusive
    
    maxStamp - maximum timestamp value, exclusive
    
    Returns:
    
    this
    
    Throws:
    
    IOException
    
    See Also:
    
    setMaxVersions(), setMaxVersions(int)
  - setTimeStamp
```
@Deprecated
public Scan setTimeStamp(long timestamp)
                              throws IOException
```
    Deprecated. As of release 2.0.0, this will be removed in HBase 3.0.0. Use setTimestamp(long) instead
    
    Get versions of columns with the specified timestamp. Note, default maximum versions to return is 1. If your time range spans more than one version and you want all versions returned, up the number of versions beyond the defaut.
    
    Parameters:
    
    timestamp - version timestamp
    
    Returns:
    
    this
    
    Throws:
    
    IOException
    
    See Also:
    
    setMaxVersions(), setMaxVersions(int)
  - setTimestamp
```
public Scan setTimestamp(long timestamp)
```
    Get versions of columns with the specified timestamp. Note, default maximum versions to return is 1. If your time range spans more than one version and you want all versions returned, up the number of versions beyond the defaut.
    
    Parameters:
    
    timestamp - version timestamp
    
    Returns:
    
    this
    
    See Also:
    
    setMaxVersions(), setMaxVersions(int)
  - setColumnFamilyTimeRange
```
public Scan setColumnFamilyTimeRange(byte[] cf,
                                     long minStamp,
                                     long maxStamp)
```
    Description copied from class: Query
    
    Get versions of columns only within the specified timestamp range, [minStamp, maxStamp) on a per CF bases. Note, default maximum versions to return is 1. If your time range spans more than one version and you want all versions returned, up the number of versions beyond the default. Column Family time ranges take precedence over the global time range.
    
    Overrides:
    
    setColumnFamilyTimeRange in class Query
    
    Parameters:
    
    cf - the column family for which you want to restrict
    
    minStamp - minimum timestamp value, inclusive
    
    maxStamp - maximum timestamp value, exclusive
    
    Returns:
    
    this
  - setStartRow
```
@Deprecated
public Scan setStartRow(byte[] startRow)
```
    Deprecated. since 2.0.0 and will be removed in 3.0.0. Use withStartRow(byte[]) instead. This method may change the inclusive of the stop row to keep compatible with the old behavior.
    
    Set the start row of the scan.
    If the specified row does not exist, the Scanner will start from the next closest row after the specified row.
    
    Parameters:
    
    startRow - row to start scanner at or after
    
    Returns:
    
    this
    
    Throws:
    
    IllegalArgumentException - if startRow does not meet criteria for a row key (when length exceeds HConstants.MAX_ROW_LENGTH)
    
    See Also:
    
    withStartRow(byte[]), HBASE-17320
  - withStartRow
```
public Scan withStartRow(byte[] startRow)
```
    Set the start row of the scan.
    If the specified row does not exist, the Scanner will start from the next closest row after the specified row.
    
    Parameters:
    
    startRow - row to start scanner at or after
    
    Returns:
    
    this
    
    Throws:
    
    IllegalArgumentException - if startRow does not meet criteria for a row key (when length exceeds HConstants.MAX_ROW_LENGTH)
  - withStartRow
```
public Scan withStartRow(byte[] startRow,
                         boolean inclusive)
```
    Set the start row of the scan.
    If the specified row does not exist, or the inclusive is false, the Scanner will start from the next closest row after the specified row.
    
    Parameters:
    
    startRow - row to start scanner at or after
    
    inclusive - whether we should include the start row when scan
    
    Returns:
    
    this
    
    Throws:
    
    IllegalArgumentException - if startRow does not meet criteria for a row key (when length exceeds HConstants.MAX_ROW_LENGTH)
  - setStopRow
```
@Deprecated
public Scan setStopRow(byte[] stopRow)
```
    Deprecated. since 2.0.0 and will be removed in 3.0.0. Use withStopRow(byte[]) instead. This method may change the inclusive of the stop row to keep compatible with the old behavior.
    
    Set the stop row of the scan.
    The scan will include rows that are lexicographically less than the provided stopRow.
    Note: When doing a filter for a rowKey Prefix use setRowPrefixFilter(byte[]). The 'trailing 0' will not yield the desired result.
    
    Parameters:
    
    stopRow - row to end at (exclusive)
    
    Returns:
    
    this
    
    Throws:
    
    IllegalArgumentException - if stopRow does not meet criteria for a row key (when length exceeds HConstants.MAX_ROW_LENGTH)
    
    See Also:
    
    withStopRow(byte[]), HBASE-17320
  - withStopRow
```
public Scan withStopRow(byte[] stopRow)
```
    Set the stop row of the scan.
    The scan will include rows that are lexicographically less than the provided stopRow.
    Note: When doing a filter for a rowKey Prefix use setRowPrefixFilter(byte[]). The 'trailing 0' will not yield the desired result.
    
    Parameters:
    
    stopRow - row to end at (exclusive)
    
    Returns:
    
    this
    
    Throws:
    
    IllegalArgumentException - if stopRow does not meet criteria for a row key (when length exceeds HConstants.MAX_ROW_LENGTH)
  - withStopRow
```
public Scan withStopRow(byte[] stopRow,
                        boolean inclusive)
```
    Set the stop row of the scan.
    The scan will include rows that are lexicographically less than (or equal to if inclusive is true) the provided stopRow.
    
    Parameters:
    
    stopRow - row to end at
    
    inclusive - whether we should include the stop row when scan
    
    Returns:
    
    this
    
    Throws:
    
    IllegalArgumentException - if stopRow does not meet criteria for a row key (when length exceeds HConstants.MAX_ROW_LENGTH)
  - setRowPrefixFilter
```
public Scan setRowPrefixFilter(byte[] rowPrefix)
```
    Set a filter (using stopRow and startRow) so the result set only contains rows where the rowKey starts with the specified prefix.
    
    This is a utility method that converts the desired rowPrefix into the appropriate values for the startRow and stopRow to achieve the desired result.
    
    This can safely be used in combination with setFilter.
    
    NOTE: Doing a setStartRow(byte[]) and/or setStopRow(byte[]) after this method will yield undefined results.
    
    Parameters:
    
    rowPrefix - the prefix all rows must start with. (Set null to remove the filter.)
    
    Returns:
    
    this
  - calculateTheClosestNextRowKeyForPrefix
```
private byte[] calculateTheClosestNextRowKeyForPrefix(byte[] rowKeyPrefix)
```
    When scanning for a prefix the scan should stop immediately after the the last row that has the specified prefix. This method calculates the closest next rowKey immediately following the given rowKeyPrefix.
    
    IMPORTANT: This converts a rowKeyPrefix into a rowKey.
    
    If the prefix is an 'ASCII' string put into a byte[] then this is easy because you can simply increment the last byte of the array. But if your application uses real binary rowids you may run into the scenario that your prefix is something like:
    { 0x12, 0x23, 0xFF, 0xFF }
    Then this stopRow needs to be fed into the actual scan
    { 0x12, 0x24 } (Notice that it is shorter now)
    This method calculates the correct stop row value for this usecase.
    
    Parameters:
    
    rowKeyPrefix - the rowKeyPrefix.
    
    Returns:
    
    the closest next rowKey immediately following the given rowKeyPrefix.
  - setMaxVersions
```
@Deprecated
public Scan setMaxVersions()
```
    Deprecated. since 2.0.0 and will be removed in 3.0.0. It is easy to misunderstand with column family's max versions, so use readAllVersions() instead.
    
    Get all available versions.
    
    Returns:
    
    this
    
    See Also:
    
    readAllVersions(), HBASE-17125
  - setMaxVersions
```
@Deprecated
public Scan setMaxVersions(int maxVersions)
```
    Deprecated. since 2.0.0 and will be removed in 3.0.0. It is easy to misunderstand with column family's max versions, so use readVersions(int) instead.
    
    Get up to the specified number of versions of each column.
    
    Parameters:
    
    maxVersions - maximum versions for each column
    
    Returns:
    
    this
    
    See Also:
    
    readVersions(int), HBASE-17125
  - readAllVersions
```
public Scan readAllVersions()
```
    Get all available versions.
    
    Returns:
    
    this
  - readVersions
```
public Scan readVersions(int versions)
```
    Get up to the specified number of versions of each column.
    
    Parameters:
    
    versions - specified number of versions for each column
    
    Returns:
    
    this
  - setBatch
```
public Scan setBatch(int batch)
```
    Set the maximum number of cells to return for each call to next(). Callers should be aware that this is not equivalent to calling setAllowPartialResults(boolean). If you don't allow partial results, the number of cells in each Result must equal to your batch setting unless it is the last Result for current row. So this method is helpful in paging queries. If you just want to prevent OOM at client, use setAllowPartialResults(true) is better.
    
    Parameters:
    
    batch - the maximum number of values
    
    See Also:
    
    Result.mayHaveMoreCellsInRow()
  - setMaxResultsPerColumnFamily
```
public Scan setMaxResultsPerColumnFamily(int limit)
```
    Set the maximum number of values to return per row per Column Family
    
    Parameters:
    
    limit - the maximum number of values returned / row / CF
  - setRowOffsetPerColumnFamily
```
public Scan setRowOffsetPerColumnFamily(int offset)
```
    Set offset for the row per Column Family.
    
    Parameters:
    
    offset - is the number of kvs that will be skipped.
  - setCaching
```
public Scan setCaching(int caching)
```
    Set the number of rows for caching that will be passed to scanners. If not set, the Configuration setting HConstants.HBASE_CLIENT_SCANNER_CACHING will apply. Higher caching values will enable faster scanners but will use more memory.
    
    Parameters:
    
    caching - the number of rows for caching
  - getMaxResultSize
```
public long getMaxResultSize()
```
    Returns:
    
    the maximum result size in bytes. See setMaxResultSize(long)
  - setMaxResultSize
```
public Scan setMaxResultSize(long maxResultSize)
```
    Set the maximum result size. The default is -1; this means that no specific maximum result size will be set for this scan, and the global configured value will be used instead. (Defaults to unlimited).
    
    Parameters:
    
    maxResultSize - The maximum result size in bytes.
  - setFilter
```
public Scan setFilter(Filter filter)
```
    Description copied from class: Query
    
    Apply the specified server-side filter when performing the Query. Only Filter.filterCell(org.apache.hadoop.hbase.Cell) is called AFTER all tests for ttl, column match, deletes and column family's max versions have been run.
    
    Overrides:
    
    setFilter in class Query
    
    Parameters:
    
    filter - filter to run on the server
    
    Returns:
    
    this for invocation chaining
  - setFamilyMap
```
public Scan setFamilyMap(Map<byte[],NavigableSet<byte[]>> familyMap)
```
    Setting the familyMap
    
    Parameters:
    
    familyMap - map of family to qualifier
    
    Returns:
    
    this
  - getFamilyMap
```
public Map<byte[],NavigableSet<byte[]>> getFamilyMap()
```
    Getting the familyMap
    
    Returns:
    
    familyMap
  - numFamilies
```
public int numFamilies()
```
    Returns:
    
    the number of families in familyMap
  - hasFamilies
```
public boolean hasFamilies()
```
    Returns:
    
    true if familyMap is non empty, false otherwise
  - getFamilies
```
public byte[][] getFamilies()
```
    Returns:
    
    the keys of the familyMap
  - getStartRow
```
public byte[] getStartRow()
```
    Returns:
    
    the startrow
  - includeStartRow
```
public boolean includeStartRow()
```
    Returns:
    
    if we should include start row when scan
  - getStopRow
```
public byte[] getStopRow()
```
    Returns:
    
    the stoprow
  - includeStopRow
```
public boolean includeStopRow()
```
    Returns:
    
    if we should include stop row when scan
  - getMaxVersions
```
public int getMaxVersions()
```
    Returns:
    
    the max number of versions to fetch
  - getBatch
```
public int getBatch()
```
    Returns:
    
    maximum number of values to return for a single call to next()
  - getMaxResultsPerColumnFamily
```
public int getMaxResultsPerColumnFamily()
```
    Returns:
    
    maximum number of values to return per row per CF
  - getRowOffsetPerColumnFamily
```
public int getRowOffsetPerColumnFamily()
```
    Method for retrieving the scan's offset per row per column family (#kvs to be skipped)
    
    Returns:
    
    row offset
  - getCaching
```
public int getCaching()
```
    Returns:
    
    caching the number of rows fetched when calling next on a scanner
  - getTimeRange
```
public TimeRange getTimeRange()
```
    Returns:
    
    TimeRange
  - getFilter
```
public Filter getFilter()
```
    Overrides:
    
    getFilter in class Query
    
    Returns:
    
    RowFilter
  - hasFilter
```
public boolean hasFilter()
```
    Returns:
    
    true is a filter has been specified, false if not
  - setCacheBlocks
```
public Scan setCacheBlocks(boolean cacheBlocks)
```
    Set whether blocks should be cached for this Scan.
    This is true by default. When true, default settings of the table and family are used (this will never override caching blocks if the block cache is disabled for that family or entirely).
    
    Parameters:
    
    cacheBlocks - if false, default settings are overridden and blocks will not be cached
  - getCacheBlocks
```
public boolean getCacheBlocks()
```
    Get whether blocks should be cached for this Scan.
    
    Returns:
    
    true if default caching should be used, false if blocks should not be cached
  - setReversed
```
public Scan setReversed(boolean reversed)
```
    Set whether this scan is a reversed one
    This is false by default which means forward(normal) scan.
    
    Parameters:
    
    reversed - if true, scan will be backward order
    
    Returns:
    
    this
  - isReversed
```
public boolean isReversed()
```
    Get whether this scan is a reversed one.
    
    Returns:
    
    true if backward scan, false if forward(default) scan
  - setAllowPartialResults
```
public Scan setAllowPartialResults(boolean allowPartialResults)
```
    Setting whether the caller wants to see the partial results when server returns less-than-expected cells. It is helpful while scanning a huge row to prevent OOM at client. By default this value is false and the complete results will be assembled client side before being delivered to the caller.
    
    Parameters:
    
    allowPartialResults -
    
    Returns:
    
    this
    
    See Also:
    
    Result.mayHaveMoreCellsInRow(), setBatch(int)
  - getAllowPartialResults
```
public boolean getAllowPartialResults()
```
    Returns:
    
    true when the constructor of this scan understands that the results they will see may only represent a partial portion of a row. The entire row would be retrieved by subsequent calls to ResultScanner.next()
  - setLoadColumnFamiliesOnDemand
```
public Scan setLoadColumnFamiliesOnDemand(boolean value)
```
    Description copied from class: Query
    
    Set the value indicating whether loading CFs on demand should be allowed (cluster default is false). On-demand CF loading doesn't load column families until necessary, e.g. if you filter on one column, the other column family data will be loaded only for the rows that are included in result, not all rows like in normal case. With column-specific filters, like SingleColumnValueFilter w/filterIfMissing == true, this can deliver huge perf gains when there's a cf with lots of data; however, it can also lead to some inconsistent results, as follows: - if someone does a concurrent update to both column families in question you may get a row that never existed, e.g. for { rowKey = 5, { cat_videos => 1 }, { video => "my cat" } } someone puts rowKey 5 with { cat_videos => 0 }, { video => "my dog" }, concurrent scan filtering on "cat_videos == 1" can get { rowKey = 5, { cat_videos => 1 }, { video => "my dog" } }. - if there's a concurrent split and you have more than 2 column families, some rows may be missing some column families.
    
    Overrides:
    
    setLoadColumnFamiliesOnDemand in class Query
  - getFingerprint
```
public Map<String,Object> getFingerprint()
```
    Compile the table and column family (i.e. schema) information into a String. Useful for parsing and aggregation by debugging, logging, and administration tools.
    
    Specified by:
    
    getFingerprint in class Operation
    
    Returns:
    
    Map
  - toMap
```
public Map<String,Object> toMap(int maxCols)
```
    Compile the details beyond the scope of getFingerprint (row, columns, timestamps, etc.) into a Map along with the fingerprinted information. Useful for debugging, logging, and administration tools.
    
    Specified by:
    
    toMap in class Operation
    
    Parameters:
    
    maxCols - a limit on the number of columns output prior to truncation
    
    Returns:
    
    Map
  - setRaw
```
public Scan setRaw(boolean raw)
```
    Enable/disable "raw" mode for this scan. If "raw" is enabled the scan will return all delete marker and deleted rows that have not been collected, yet. This is mostly useful for Scan on column families that have KEEP_DELETED_ROWS enabled. It is an error to specify any column when "raw" is set.
    
    Parameters:
    
    raw - True/False to enable/disable "raw" mode.
  - isRaw
```
public boolean isRaw()
```
    Returns:
    
    True if this Scan is in "raw" mode.
  - setSmall
```
@Deprecated
public Scan setSmall(boolean small)
```
    Deprecated. since 2.0.0 and will be removed in 3.0.0. Use setLimit(int) and setReadType(ReadType) instead. And for the one rpc optimization, now we will also fetch data when openScanner, and if the number of rows reaches the limit then we will close the scanner automatically which means we will fall back to one rpc.
    
    Set whether this scan is a small scan
    Small scan should use pread and big scan can use seek + read seek + read is fast but can cause two problem (1) resource contention (2) cause too much network io [89-fb] Using pread for non-compaction read request https://issues.apache.org/jira/browse/HBASE-7266 On the other hand, if setting it true, we would do openScanner,next,closeScanner in one RPC call. It means the better performance for small scan. [HBASE-9488]. Generally, if the scan range is within one data block(64KB), it could be considered as a small scan.
    
    Parameters:
    
    small -
    
    See Also:
    
    setLimit(int), setReadType(ReadType), HBASE-17045
  - isSmall
```
@Deprecated
public boolean isSmall()
```
    Deprecated. since 2.0.0 and will be removed in 3.0.0. See the comment of setSmall(boolean)
    
    Get whether this scan is a small scan
    
    Returns:
    
    true if small scan
    
    See Also:
    
    HBASE-17045
  - setAttribute
```
public Scan setAttribute(String name,
                         byte[] value)
```
    Description copied from interface: Attributes
    
    Sets an attribute. In case value = null attribute is removed from the attributes map. Attribute names starting with _ indicate system attributes.
    
    Specified by:
    
    setAttribute in interface Attributes
    
    Overrides:
    
    setAttribute in class OperationWithAttributes
    
    Parameters:
    
    name - attribute name
    
    value - attribute value
  - setId
```
public Scan setId(String id)
```
    Description copied from class: OperationWithAttributes
    
    This method allows you to set an identifier on an operation. The original motivation for this was to allow the identifier to be used in slow query logging, but this could obviously be useful in other places. One use of this could be to put a class.method identifier in here to see where the slow query is coming from.
    
    Overrides:
    
    setId in class OperationWithAttributes
    
    Parameters:
    
    id - id to set for the scan
  - setAuthorizations
```
public Scan setAuthorizations(Authorizations authorizations)
```
    Description copied from class: Query
    
    Sets the authorizations to be used by this Query
    
    Overrides:
    
    setAuthorizations in class Query
  - setACL
```
public Scan setACL(Map<String,Permission> perms)
```
    Overrides:
    
    setACL in class Query
    
    Parameters:
    
    perms - A map of permissions for a user or users
  - setACL
```
public Scan setACL(String user,
                   Permission perms)
```
    Overrides:
    
    setACL in class Query
    
    Parameters:
    
    user - User short name
    
    perms - Permissions for the user
  - setConsistency
```
public Scan setConsistency(Consistency consistency)
```
    Description copied from class: Query
    
    Sets the consistency level for this operation
    
    Overrides:
    
    setConsistency in class Query
    
    Parameters:
    
    consistency - the consistency level
  - setReplicaId
```
public Scan setReplicaId(int Id)
```
    Description copied from class: Query
    
    Specify region replica id where Query will fetch data from. Use this together with Query.setConsistency(Consistency) passing Consistency.TIMELINE to read data from a specific replicaId.
    Expert: This is an advanced API exposed. Only use it if you know what you are doing
    
    Overrides:
    
    setReplicaId in class Query
  - setIsolationLevel
```
public Scan setIsolationLevel(IsolationLevel level)
```
    Description copied from class: Query
    
    Set the isolation level for this query. If the isolation level is set to READ_UNCOMMITTED, then this query will return data from committed and uncommitted transactions. If the isolation level is set to READ_COMMITTED, then this query will return data from committed transactions only. If a isolation level is not explicitly set on a Query, then it is assumed to be READ_COMMITTED.
    
    Overrides:
    
    setIsolationLevel in class Query
    
    Parameters:
    
    level - IsolationLevel for this query
  - setPriority
```
public Scan setPriority(int priority)
```
    Overrides:
    
    setPriority in class OperationWithAttributes
  - setScanMetricsEnabled
```
public Scan setScanMetricsEnabled(boolean enabled)
```
    Enable collection of ScanMetrics. For advanced users.
    
    Parameters:
    
    enabled - Set to true to enable accumulating scan metrics
  - isScanMetricsEnabled
```
public boolean isScanMetricsEnabled()
```
    Returns:
    
    True if collection of scan metrics is enabled. For advanced users.
  - getScanMetrics
```
@Deprecated
public ScanMetrics getScanMetrics()
```
    Deprecated. Use ResultScanner.getScanMetrics() instead. And notice that, please do not use this method and ResultScanner.getScanMetrics() together, the metrics will be messed up.
    
    Returns:
    
    Metrics on this Scan, if metrics were enabled.
    
    See Also:
    
    setScanMetricsEnabled(boolean)
  - isAsyncPrefetch
```
public Boolean isAsyncPrefetch()
```
  - setAsyncPrefetch
```
public Scan setAsyncPrefetch(boolean asyncPrefetch)
```
  - getLimit
```
public int getLimit()
```
    Returns:
    
    the limit of rows for this scan
  - setLimit
```
public Scan setLimit(int limit)
```
    Set the limit of rows for this scan. We will terminate the scan if the number of returned rows reaches this value.
    This condition will be tested at last, after all other conditions such as stopRow, filter, etc.
    
    Parameters:
    
    limit - the limit of rows for this scan
    
    Returns:
    
    this
  - setOneRowLimit
```
public Scan setOneRowLimit()
```
    Call this when you only want to get one row. It will set limit to 1, and also set readType to Scan.ReadType.PREAD.
    
    Returns:
    
    this
  - getReadType
```
public Scan.ReadType getReadType()
```
    Returns:
    
    the read type for this scan
  - setReadType
```
public Scan setReadType(Scan.ReadType readType)
```
    Set the read type for this scan.
    Notice that we may choose to use pread even if you specific Scan.ReadType.STREAM here. For example, we will always use pread if this is a get scan.
    
    Returns:
    
    this
  - getMvccReadPoint
```
long getMvccReadPoint()
```
    Get the mvcc read point used to open a scanner.
  - setMvccReadPoint
```
Scan setMvccReadPoint(long mvccReadPoint)
```
    Set the mvcc read point used to open a scanner.
  - resetMvccReadPoint
```
Scan resetMvccReadPoint()
```
    Set the mvcc read point to -1 which means do not use it.
  - setNeedCursorResult
```
public Scan setNeedCursorResult(boolean needCursorResult)
```
    When the server is slow or we scan a table with many deleted data or we use a sparse filter, the server will response heartbeat to prevent timeout. However the scanner will return a Result only when client can do it. So if there are many heartbeats, the blocking time on ResultScanner#next() may be very long, which is not friendly to online services. Set this to true then you can get a special Result whose #isCursor() returns true and is not contains any real data. It only tells you where the server has scanned. You can call next to continue scanning or open a new scanner with this row key as start row whenever you want. Users can get a cursor when and only when there is a response from the server but we can not return a Result to users, for example, this response is a heartbeat or there are partial cells but users do not allow partial result. Now the cursor is in row level which means the special Result will only contains a row key. Result.isCursor() Result.getCursor() Cursor
  - isNeedCursorResult
```
public boolean isNeedCursorResult()
```
  - createScanFromCursor
```
public static Scan createScanFromCursor(Cursor cursor)
```
    Create a new Scan with a cursor. It only set the position information like start row key. The others (like cfs, stop row, limit) should still be filled in by the user. Result.isCursor() Result.getCursor() Cursor

Class Scan

Nested Class Summary

Field Summary

Fields inherited from class org.apache.hadoop.hbase.client.Query

Fields inherited from class org.apache.hadoop.hbase.client.OperationWithAttributes

Constructor Summary

Method Summary

Methods inherited from class org.apache.hadoop.hbase.client.Query

Methods inherited from class org.apache.hadoop.hbase.client.OperationWithAttributes

Methods inherited from class org.apache.hadoop.hbase.client.Operation

Methods inherited from class java.lang.Object

Field Detail

LOG

RAW_ATTR

startRow

includeStartRow

stopRow

includeStopRow

maxVersions

batch

allowPartialResults

storeLimit

storeOffset

SCAN_ATTRIBUTES_METRICS_ENABLE

SCAN_ATTRIBUTES_METRICS_DATA

SCAN_ATTRIBUTES_TABLE_NAME

caching

maxResultSize

cacheBlocks

reversed

tr

familyMap

asyncPrefetch

HBASE_CLIENT_SCANNER_ASYNC_PREFETCH

DEFAULT_HBASE_CLIENT_SCANNER_ASYNC_PREFETCH

small

mvccReadPoint

limit

readType

needCursorResult

Constructor Detail

Scan

Scan

Scan

Scan

Scan

Scan

Method Detail

isGetScan

addFamily

addColumn

setTimeRange

setTimeStamp

setTimestamp

setColumnFamilyTimeRange

setStartRow

withStartRow

withStartRow

setStopRow

withStopRow

withStopRow

setRowPrefixFilter

calculateTheClosestNextRowKeyForPrefix

setMaxVersions

setMaxVersions

readAllVersions

readVersions

setBatch

setMaxResultsPerColumnFamily

setRowOffsetPerColumnFamily

setCaching

getMaxResultSize

setMaxResultSize

setFilter

setFamilyMap

getFamilyMap

numFamilies

hasFamilies

getFamilies

getStartRow