Table stats

Bigtable providestable stats — metadata about a table —that give you summary information about the table, such as the number ofrows or average number of cells per column.

This document describes table stats and explains how to get them using theGoogle Cloud CLI. Before you read this page, you should understand theBigtable storage model and be familiar withschema design best practices andgarbage collection.

Table stats provide observability into a Bigtable table. They canbe useful when you are troubleshooting issues with performance or storage orwhen you want to determine the source of storage costs. They can also help youdetermine whether you are storing more data than you need.

Expected precision

When you retrieve table stats for a table, the data that you get is approximate– the table stats reflect the state of your table in one of your instance'sclusters as of the most recent compaction.

A full set of table stats is not available until after initialcompaction, which typically occurs about a week after the table iscreated. Table stats are accurate as of the most recent compaction, which mightbe as much as a week ago.

Table stats fields

A request for a table's table stats returns the following fields. Details andexamples are in the next section.

Table stats also include the following fields for each column family in thetable.

Table stats field details

Row count

The row count is the number of rows in the table. Each row is identified by itsrow key.

Average number of columns per row

To arrive at the average number of columns per row for a table,Bigtable counts the number of columns in the entire table anddivides that value by the number of rows in the table.

Depending on your schema design and garbage collection policies, your tablemight have multiple cells in a column, or it might have only one. The number ofcells that you can store is bound by the data size limits outlined on theQuotas and limits page underData size within tables.

If you find that this number is higher than you expect, examine your garbagecollection rules to see if you are retaining more cells than you need. You mightalso ask whether your schema and write patterns should be adjusted.

Logical data in bytes (table)

This value represents the approximate number of bytes that would be needed toread your entire table. This table stat gives you an idea of how many bytes arestored in the table. Knowing the logical data in bytes can help you understandthe impact of compression on the table. For example, if the table size reportedin Cloud Monitoring is the same as or larger than logical data in bytes for thetable, then you might be storing your data in a format that isn't easilycompressed.

Column family stats field details

Table stats for a table include the following fields for each column family inthe table.

Average number of columns per row

This number is calculated by taking the number of columns in the column familyand dividing that number by the number of rows in the table.

As an example, consider the following table. The table has three rows withcolumns in column familiesfamily-A andfamily-B.

Column familyfamily-A has a total of five columns in the table. Divided bythree rows, that means that the average number of cells per column forfamily-A is1.67 (rounded here to two decimal places).

Column familyfamily-B has a total of three columns in the table. Divided bythree rows, the average number of columns per row forfamily-A is1.

Average number of cells per column

To determine a column family's average number of cells per column,Bigtable takes the count of all cells in the column family in allrows of the table and divides it by the number of rows in the table.

As an example, consider the following rows in column familyfamily-D.

The count of cells in the column family is 3 + 1 + 10 + 7 + 6 = 27. That valuedivided by 3 (the number of rows) means that column familyfamily-D has anaverage of cells per column of9.

Logical data in bytes (column family)

The logical data in bytes reflects the space that the column family occupies.This value is approximately the number of bytes that you need to read allthe data in the column family at the time the table stats were returned.

Example using the gcloud CLI

To get table stats for a table calledsample-table, use thebigtable instances table describe command:

gcloud bigtable instances tables describeTABLE_ID \    --instance=INSTANCE_ID --view stats

Replace the following:

• TABLE_ID: the permanent identifier for the table
• INSTANCE_ID: the permanent identifier for the instance

The output is similar to the following:

  columnFamilies:    my-family:     stats:       averageCellsPerColumn: 12.34       averageColumnsPerRow: 56.78       logicalDataBytes: 314159  name: projects/my-project/instances/INSTANCE_ID/tables/TABLE_ID  stats:    averageCellsPerColumn: 12.34    averageColumnsPerRow: 56.78    logicalDataBytes: 314159    rowCount: 271828

What's next

• Monitor your Bigtable resources.
• Use Key Visualizer to analyze your usage patterns.