Filters
When you read data from Bigtable, you can read specific rows or rangesof rows. However, you don't always need all of the data in all of the rows. Youmight only need rows that contain a specific value in their row key, or cellswithin a specific column family.
To limit the results of a read request, includefilters in the request. Afilter is applied to the data before the response is sent, reducing the amountof data that is returned. As result, using filters can mean lower network costsand faster throughput. This page provides an overview of howBigtable filters work and a list of available filters.
For details and code samples for each filter, seeFilter examples.
Note: The HBase client for Java uses HBase's filter APIs instead of the Bigtable Data API. To learn about HBase's filter APIs, see theHBase documentation.
How filters work
When your read request includes a filter, Bigtable retrieves a rowor a range of rows from your table. For each of theinput rows that itretrieves, Bigtable evaluates the row using your filter, thengenerates anoutput row based on the filter results.
Bigtable provides several types of filters, as described in thefollowing sections. Basic filters fall under two categories:limiting andmodifying. You can combine basic filters intocomposing filters.
In most cases, a filter is applied toall rows unless you specify row key,row range, or number of rows that the filter should be applied to. One exceptionis therow key regex filter, whichcan restrict the row range in certain cases if the regex is a fixed prefix. Ingeneral, to avoid the slowness of a full table scan, always specify the rows fora filter.
Limiting filters
Alimiting filter controls which rows or cells are included in the response,based on whether they match specific criteria. For example, you can say thatthe response should include only rows in which the row key matches a regularexpression, or that you want only cells from a specific column family.
Many limiting filters can exclude cells from an output row. If all of the cellsare excluded from an output row, the row is not included in the response.
See theSummary of filters for a complete list of limiting filters.
Modifying filters
Amodifying filter affects the data or metadata for individual cells.
Note: Modifying filters affect the data that is returned in the read request,not the data in the table.Bigtable provides the following modifying filters:
Thestrip value filter, which replaces each cell's valuewith an empty string. This filter is useful when you only need the number ofrows or the list of row keys that meet your criteria, rather than the data fromthose rows.
Theapply label filter, which applies a label to each cellto identify which filter produced each cell in the response. Your applicationcan use these labels to perform additional filtering on the client side.
Composing filters
Acomposing filter allows you to combine multiple basic filters into one,which makes it possible to apply more than one filter to a single read request.For example, to get CPU usage data for your servers, you could use one filter toinclude only rows where the row key starts withSERVER, followed by a secondfilter to include only cells within theCPU column family.
Bigtable provides the following composing filters:
- Achain, which applies a sequence of filters to each input rowand returns an output row. A chain filter is like using a logical AND.
- Aninterleave, which sends each input row through multiplefilters, then combines all of the filter results for the input row into a singleoutput row. An interleave filter is like using a logical OR.
- Acondition, which generates an output row by applying oneof two possible filters to the input row. The filter is chosen by applying apredicate filter to the input row, then checking to see whether the predicatefilter's output row contains any cells.
Filters and performance
Filters allow you to retrieve only the data you actually need. As a result,filters can improve performance by reducing the amount of data that is sent toyour application.
However, filters are not an all-purpose solution to every performance issue. Ingeneral, filters should be used to controlthroughput efficiency, not toreduce the latency between sending a request and receiving a response. Usedcorrectly, filters can be an effective part of a strategy toimprove readperformance.
Theconditions filter, in particular, can increase latency,because conditions are much slower than other filters. If your read request isextremely performance-sensitive, do not use conditions in the request.
Warning: Using a regex rowkey filter without also specifying a start, end,prefix, or number of rows results in a full table scan, which can be slow.Summary of filters
The following tables list the filters that Bigtable provides,including links to details and code samples for each filter.
| Limiting filters | |
|---|---|
| Block all | Don't emit any cells. Mostly useful for debugging. |
| Cells per column limit | Include only theN most recent versions of a column in a row. |
| Cells per row limit | Include only the firstN cells from a row. |
| Cells per row offset | Omit the firstN cells from a row. |
| Column family regex | Include only cells whose column family matches anRE2 regular expression. |
| Column qualifier regex | Include only cells whose column qualifier matches a regular expression. |
| Column range | Include only cells in a specific column family whose column qualifier is within a specific range. |
| Pass all | Emit all input cells. Mostly useful for debugging. |
| Row key regex | Include only cells whose row key matches a regular expression. |
| Row sample | Retrieve a random sample of rows. |
| Sink | Include cells in the final output row, and prevent them from being modified or removed by a subsequent filter. |
| Timestamp range | Include only cells whose timestamp falls within a specific range. |
| Value range | Include only cells whose value falls within a specific range. |
| Value regex | Include only cells whose value matches a regular expression. |
| Modifying filters | |
|---|---|
| Apply label | Add a label to all cells. |
| Strip value | Return an empty string for each cell value. |
| Composing filters | |
|---|---|
| Chain | Apply multiple filters in order. |
| Condition | Apply one of two possible filters to a row. |
| Interleave | Combine output rows from multiple filters into a single output row. |
What's next
Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2026-02-19 UTC.