Deletes

This document describes how to delete data stored in Bigtable tables, discusses when you should use each approach, and provides examples. Before you read this page, you should be familiar with the Bigtable overview and understand the concepts involved in schema design.

For consistency, descriptions on this page refer to the API methods that are used for each type of request. However, we strongly recommend that you always use one of the Bigtable client libraries to access the Bigtable APIs instead of using REST or RPC.

Examples on this page use sample data similar to the data that you might store in Bigtable.

To learn the number of times that you can use the operations described on this page per day, see Quotas and limits.

How Bigtable deletes data

When you send a delete request, cells are marked for deletion and cannot be read. The data is removed up to a week later during compaction, a background process that continuously optimizes the table. Deletion metadata can cause your data to take up slightly more space (several kb per row) for a few days after you send a delete request, until the next compaction occurs.

You can always send a delete request, even if your cluster has exceeded the storage limit and reads and writes are blocked.

Delete a range of rows

If you want to delete a large amount of data stored in contiguous rows, use dropRowRange. This operation deletes all rows for a range of rows identified by a starting and ending row or a row key prefix.

The row key values that you provide when you delete a range of rows are treated as service data. For information about how service data is handled, see the Google Cloud Privacy Notice.

After a successful deletion is complete and you receive a response, you can safely write data to the same row range.

The dropRowRange operation has the following restrictions:

You can't drop a range of rows from an authorized view.
You can't call the dropRowRange method asynchronously. If you send a dropRowRange request to a table while another request is in progress, Bigtable returns an UNAVAILABLE error with the message A DropRowRange operation is already ongoing. To resolve the error, send the request again.
With instances that use replication, be aware that Bigtable might take a long time to complete the operation due to increased replication latency and CPU usage. To delete data from an instance that uses replication, use the Data API to read and then delete your data.

The following code samples show how to drop a range of rows that start with the row key prefix phone#5c10102:

Go

To learn how to install and use the client library for Bigtable, see Bigtable client libraries.

To authenticate to Bigtable, set up Application Default Credentials. For more information, see Set up authentication for client libraries.


import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/bigtable"
)

func dropRowRange(w io.Writer, projectID, instanceID, tableName string) error {
	ctx := context.Background()
	adminClient, err := bigtable.NewAdminClient(ctx, projectID, instanceID)
	if err != nil {
		return fmt.Errorf("bigtable.NewAdminClient: %w", err)
	}
	defer adminClient.Close()

	// Use a specific row key prefix to drop.
	prefix := "phone#4c410523"
	if err := adminClient.DropRowRange(ctx, tableName, prefix); err != nil {
		return fmt.Errorf("adminClient.DropRowRange: %w", err)
	}

	fmt.Fprintf(w, "Successfully dropped row range with prefix: %s\n", prefix)
	return nil
}

Java

To learn how to install and use the client library for Bigtable, see Bigtable client libraries.

To authenticate to Bigtable, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

import com.google.bigtable.admin.v2.DropRowRangeRequest;
import com.google.cloud.bigtable.admin.v2.BigtableTableAdminClientV2;
import com.google.protobuf.ByteString;
import java.io.IOException;

public class DropRowRangeExample {
  public void dropRowRange(String projectId, String instanceId, String tableId) throws IOException {
    try (BigtableTableAdminClientV2 tableAdminClient = BigtableTableAdminClientV2.create()) {
      DropRowRangeRequest request =
          DropRowRangeRequest.newBuilder()
              .setName("projects/" + projectId + "/instances/" + instanceId + "/tables/" + tableId)
              .setRowKeyPrefix(ByteString.copyFromUtf8("phone#4c410523"))
              .build();
      tableAdminClient.dropRowRange(request);
    }
  }
}

Python

To learn how to install and use the client library for Bigtable, see Bigtable client libraries.

To authenticate to Bigtable, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

def drop_row_range(project_id, instance_id, table_id):
    from google.cloud.bigtable import Client

    client = Client(project=project_id, admin=True)
    instance = client.instance(instance_id)
    table = instance.table(table_id)
    row_key_prefix = "phone#4c410523"
    table.drop_by_prefix(row_key_prefix, timeout=200)

Node.js

To learn how to install and use the client library for Bigtable, see Bigtable client libraries.

To authenticate to Bigtable, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

await table.deleteRows('phone#5c10102');
await printRows();

Delete data using Data API methods

If you need to delete small amounts of non-contiguous data, deleting data using a method that calls the Cloud Bigtable API (Data API) is often the best choice. Use these methods if you are deleting MB, not GB, of data in a request. Using the Data API is the only way to delete data from a column (not column family).

Data API methods call MutateRows with one of three mutation types:

DeleteFromColumn
DeleteFromFamily
DeleteFromRow

A delete request using the Data API is atomic: either the request succeeds and all data is deleted, or the request fails and no data is removed.

In most cases, avoid using CheckAndMutate methods to delete data. In the rare event that you require strong consistency, you might want to use this approach, but be aware that it is resource-intensive and performance might be affected.

To use MutateRows to delete data, you send a readRows request with a filter to determine what you want to delete, and then you send the deletion request. For a list of the filters that are available, see Filters.

Samples in this section assume that you have already determined what data to delete.

Delete from a column

The following code samples demonstrate how to delete all the cells from a column in a row:

Go

To learn how to install and use the client library for Bigtable, see Bigtable client libraries.

To authenticate to Bigtable, set up Application Default Credentials. For more information, see Set up authentication for client libraries.


import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/bigtable"
)

func deleteFromColumn(w io.Writer, projectID, instanceID, tableName string) error {
	ctx := context.Background()
	client, err := bigtable.NewClient(ctx, projectID, instanceID)
	if err != nil {
		return fmt.Errorf("bigtable.NewClient: %w", err)
	}
	defer client.Close()
	tbl := client.Open(tableName)

	// Use a specific row key, column family, and column name that exists in your table.
	// This sample assumes a schema with a "cell_plan" column family.
	rowKey := "phone#4c410523#20190501"
	columnFamilyName := "cell_plan"
	columnName := "data_plan_01gb"
	mut := bigtable.NewMutation()
	mut.DeleteCellsInColumn(columnFamilyName, columnName)

	if err := tbl.Apply(ctx, rowKey, mut); err != nil {
		return fmt.Errorf("tbl.Apply: %w", err)
	}

	fmt.Fprintf(w, "Successfully deleted cells from column %s:%s for row: %s\n", columnFamilyName, columnName, rowKey)
	return nil
}

Java

To learn how to install and use the client library for Bigtable, see Bigtable client libraries.

To authenticate to Bigtable, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

import com.google.cloud.bigtable.data.v2.BigtableDataClient;
import com.google.cloud.bigtable.data.v2.models.Mutation;
import com.google.cloud.bigtable.data.v2.models.RowMutation;
import com.google.cloud.bigtable.data.v2.models.TableId;
import java.io.IOException;

public class DeleteFromColumnExample {
  public void deleteFromColumnCells(String projectId, String instanceId, String tableId)
      throws IOException {
    try (BigtableDataClient dataClient = BigtableDataClient.create(projectId, instanceId)) {
      Mutation mutation = Mutation.create().deleteCells("cell_plan", "data_plan_01gb");
      dataClient.mutateRow(
          RowMutation.create(TableId.of(tableId), "phone#4c410523#20190501", mutation));
    }
  }
}

Python

To learn how to install and use the client library for Bigtable, see Bigtable client libraries.

To authenticate to Bigtable, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

def delete_from_column(project_id, instance_id, table_id):
    from google.cloud.bigtable import Client

    client = Client(project=project_id, admin=True)
    instance = client.instance(instance_id)
    table = instance.table(table_id)
    row = table.row("phone#4c410523#20190501")
    row.delete_cell(column_family_id="cell_plan", column="data_plan_01gb")
    row.commit()

Python asyncio

To learn how to install and use the client library for Bigtable, see Bigtable client libraries.

To authenticate to Bigtable, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

async def delete_from_column(project_id, instance_id, table_id):
    from google.cloud.bigtable.data import BigtableDataClientAsync
    from google.cloud.bigtable.data import DeleteRangeFromColumn

    client = BigtableDataClientAsync(project=project_id)
    table = client.get_table(instance_id, table_id)

    await table.mutate_row(
        "phone#4c410523#20190501",
        DeleteRangeFromColumn(family="cell_plan", qualifier=b"data_plan_01gb"),
    )

    await table.close()
    await client.close()

Node.js

To learn how to install and use the client library for Bigtable, see Bigtable client libraries.

To authenticate to Bigtable, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

await table.mutate({
  key: 'phone#4c410523#20190501',
  method: 'delete',
  data: {
    column: 'cell_plan:data_plan_05gb',
  },
});
await printRows();

Delete from a column family

The following code samples demonstrate how to delete cells from a column family in a row:

Go

To learn how to install and use the client library for Bigtable, see Bigtable client libraries.

To authenticate to Bigtable, set up Application Default Credentials. For more information, see Set up authentication for client libraries.


import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/bigtable"
)

func deleteFromColumnFamily(w io.Writer, projectID, instanceID, tableName string) error {
	ctx := context.Background()
	client, err := bigtable.NewClient(ctx, projectID, instanceID)
	if err != nil {
		return fmt.Errorf("bigtable.NewClient: %w", err)
	}
	defer client.Close()
	tbl := client.Open(tableName)

	// Use a specific row key and column family that exists in your table.
	// This sample assumes a schema with a "stats_summary" column family.
	rowKey := "phone#5c10102#20190501"
	columnFamilyName := "stats_summary"
	mut := bigtable.NewMutation()
	mut.DeleteCellsInFamily(columnFamilyName)

	if err := tbl.Apply(ctx, rowKey, mut); err != nil {
		return fmt.Errorf("tbl.Apply: %w", err)
	}

	fmt.Fprintf(w, "Successfully deleted cells from family %s for row: %s\n", columnFamilyName, rowKey)
	return nil
}

Java

To learn how to install and use the client library for Bigtable, see Bigtable client libraries.

To authenticate to Bigtable, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

import com.google.cloud.bigtable.data.v2.BigtableDataClient;
import com.google.cloud.bigtable.data.v2.models.RowMutation;
import com.google.cloud.bigtable.data.v2.models.TableId;
import java.io.IOException;

public class DeleteFromColumnFamilyExample {
  public void deleteFromColumnFamily(String projectId, String instanceId, String tableId)
      throws IOException {
    try (BigtableDataClient dataClient = BigtableDataClient.create(projectId, instanceId)) {
      dataClient.mutateRow(
          RowMutation.create(TableId.of(tableId), "phone#5c10102#20190501")
              .deleteFamily("stats_summary"));
    }
  }
}

Python

To learn how to install and use the client library for Bigtable, see Bigtable client libraries.

To authenticate to Bigtable, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

def delete_from_column_family(project_id, instance_id, table_id):
    from google.cloud.bigtable import Client

    client = Client(project=project_id, admin=True)
    instance = client.instance(instance_id)
    table = instance.table(table_id)
    row = table.row("phone#4c410523#20190501"