Get query stats

This page describes how to get query stats using the cbt CLI . You can also get query stats using the Go client library for Cloud Bigtable.

The content provided here is intended for application developers. Before you read this page, you should understand the Bigtable storage model. You should also be familiar with Schema design best practices and understand performance.

The ability to get information about a Bigtable query can be useful when you are developing an application. It lets you get data on a query's performance and then adjust the query or change your schema design to fine-tune the performance of your query.

Although in general a query is any data request sent to a table, Bigtable returns query statistics only for read requests.

Before you begin

  1. If you haven't already installed the cbt CLI , follow the instructions on the cbt CLI overview including the steps to create a .cbtrc file.
  2. Review the Read rows section of the cbt CLI reference to familiarize yourself with the command-line syntax and options available for sending a cbt read request to your table. Note that the cbt CLI does not support filters.
  3. Ensure that you have bigtable.tables.readRows permission for the table or that you are a principal of the bigtable.reader role.

Run your query

  1. Create a query using the syntax for Read rows.

  2. Run the following command. The include-stats=full parameter tells Bigtable to return the query stats.

    cbt read TABLE_ID QUERY include-stats=full

    Replace the following:

    • TABLE_ID: the unique ID for the table that you are querying
    • QUERY: a cbt CLI -formatted query

    The terminal displays the data that was read and a list containing the following stats:

    • rows_seen_count: the number of rows that Bigtable processed for the request
    • rows_returned_count: the number of rows returned after applying filters
    • cells_seen_count: the number of cells processed for the request
    • cells_returned_count: the number of cells returned after applying filters
    • frontend_server_latency: request latency measured from the Bigtable front-end server pool, expressed in milliseconds

Interpret the results

  • Look at the ratio of cells seen to cells returned. If the quotient for cells_seen_count / cells_returned_count is 1 or close to 1, that's an indication that your query didn't cause Bigtable to process data that was ultimately filtered out.

  • Consider the number of rows returned. The higher that number is, the more work that Bigtable is doing. The optimal number here is dependent on your use case and latency requirements, but in general, a query that returns fewer rows will have lower latency.

Example

If you want to get query stats when you read all rows that match the regular expression orange:*.* in a table called my-table, you can run the following:

cbt read my-table regex='.*orange' columns='.*:.*' include-stats=full

The output is similar to the following:

  ----------------------------------------
  orange
    Details:Color                            @ 2022/09/26-14:48:01.286000
      "orange"
    Details:Size                             @ 2022/09/26-14:48:01.286000
      "medium"

  Request Stats
  ====================
  rows_seen_count: 10
  rows_returned_count : 1
  cells_seen_count: 2
  cells_returned_count: 2
  frontend_server_latency: 13ms

What's next