Exclusões

Neste documento, descrevemos como excluir dados armazenados nas tabelas do Bigtable, discutimos quando usar cada abordagem e fornecemos exemplos. Antes de ler esta página, familiarize-se com a visão geral do Bigtable e conheça os conceitos envolvidos no design do esquema.

Para consistência, as descrições nesta página referem-se aos métodos da API usados para cada tipo de solicitação. No entanto, recomendamos que você sempre use uma das bibliotecas de cliente do Bigtable para acessar as APIs do Bigtable, em vez de usar REST ou RPC.

Os exemplos nesta página usam dados de amostra semelhantes aos dados que podem ser armazenados no Bigtable.

Para saber quantas vezes você pode usar as operações descritas nesta página por dia, consulte Cotas e limites.

Como o Bigtable exclui dados

Quando você envia uma solicitação de exclusão, as células são marcadas para exclusão e não podem ser lidas. Os dados são removidos até uma semana depois, durante a compactação, um processo em segundo plano que otimiza continuamente a tabela. Os metadados de exclusão podem fazer com que os dados ocupem um pouco mais de espaço (vários kb por linha) por alguns dias após o envio de uma solicitação de exclusão, até que ocorra a próxima compactação.

É possível enviar uma solicitação de exclusão mesmo que o cluster tenha excedido o limite de armazenamento e que as leituras e gravações estejam bloqueadas.

Excluir um intervalo de linhas

Se você quiser excluir uma grande quantidade de dados armazenados em linhas contíguas, use dropRowRange. Essa operação exclui todas as linhas de um intervalo de linhas identificadas por uma linha inicial e final ou um prefixo de chave de linha.

Os valores de chave de linha fornecidos ao excluir um intervalo de linhas são tratados como dados de serviço. Para informações sobre como os dados de serviço são tratados, consulte o Aviso de privacidade doGoogle Cloud .

Depois que uma exclusão é concluída e você recebe uma resposta, é possível gravar dados com segurança no mesmo intervalo de linhas.

A operação dropRowRange tem as seguintes restrições:

  • Não é possível descartar um intervalo de linhas de uma visualização autorizada.
  • Não é possível chamar o método dropRowRange de forma assíncrona. Se você enviar uma solicitação dropRowRange para uma tabela enquanto outra estiver em andamento, o Bigtable vai retornar um erro UNAVAILABLE com a mensagem A DropRowRange operation is already ongoing. Para resolver o erro, envie a solicitação novamente.
  • Em instâncias que usam replicação, o Bigtable pode levar muito tempo para concluir a operação devido ao aumento da latência de replicação e do uso da CPU. Para excluir dados de uma instância que usa replicação, use a API Data para ler e excluir seus dados.

Os exemplos de código a seguir mostram como descartar um intervalo de linhas que começam com o prefixo de chave de linha phone#5c10102:

Java

Para saber como instalar e usar a biblioteca de cliente do Bigtable, consulte Bibliotecas de cliente do Bigtable.

Para autenticar no Bigtable, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente. 

import com.google.cloud.bigtable.admin.v2.BigtableTableAdminClient;
import java.io.IOException;

public class DropRowRangeExample {
  public void dropRowRange(String projectId, String instanceId, String tableId) throws IOException {
    try (BigtableTableAdminClient tableAdminClient =
        BigtableTableAdminClient.create(projectId, instanceId)) {
      tableAdminClient.dropRowRange(tableId, "phone#4c410523");
    }
  }
}

Python

Para saber como instalar e usar a biblioteca de cliente do Bigtable, consulte Bibliotecas de cliente do Bigtable.

Para autenticar no Bigtable, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente. 

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

Para saber como instalar e usar a biblioteca de cliente do Bigtable, consulte Bibliotecas de cliente do Bigtable.

Para autenticar no Bigtable, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente. 

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

Excluir dados usando métodos da API Data

Se você precisa excluir pequenas quantidades de dados não contíguos, excluir os dados usando um método que chama a API Cloud Bigtable (API Data) geralmente é a melhor escolha. Use esses métodos se estiver excluindo MB, e não GB, de dados em uma solicitação. Usar a API Data é a única maneira de excluir dados de uma coluna (não do grupo de colunas).

Os métodos da API de dados chamam MutateRows com um dos três tipos de mutação:

  • DeleteFromColumn
  • DeleteFromFamily
  • DeleteFromRow

Uma solicitação de exclusão que usa a API Data é atômica: ou a solicitação é bem-sucedida e todos os dados são excluídos ou a solicitação falha e nenhum dado é removido.

Na maioria dos casos, evite usar métodos CheckAndMutate para excluir dados. No caso raro de você precisar de consistência forte, convém usar essa abordagem, mas saiba que ela consome muitos recursos, e o desempenho pode ser afetado.

Para usar MutateRows para excluir dados, envie uma solicitação readRows com um filtro para determinar o que quer excluir e, em seguida, envie a solicitação de exclusão. Para ver uma lista dos filtros disponíveis, consulte Filtros.

As amostras nesta seção pressupõem que você já tenha determinado quais dados excluir.

Excluir de uma coluna

Os exemplos de código a seguir demonstram como excluir todas as células de uma coluna em uma linha:

Java

Para saber como instalar e usar a biblioteca de cliente do Bigtable, consulte Bibliotecas de cliente do Bigtable.

Para autenticar no Bigtable, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente. 

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

Para saber como instalar e usar a biblioteca de cliente do Bigtable, consulte Bibliotecas de cliente do Bigtable.

Para autenticar no Bigtable, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente. 

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

Para saber como instalar e usar a biblioteca de cliente do Bigtable, consulte Bibliotecas de cliente do Bigtable.

Para autenticar no Bigtable, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente. 

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

Para saber como instalar e usar a biblioteca de cliente do Bigtable, consulte Bibliotecas de cliente do Bigtable.

Para autenticar no Bigtable, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente. 

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

Excluir de um grupo de colunas

Os exemplos de código a seguir demonstram como excluir células de um grupo de colunas em uma linha:

Java

Para saber como instalar e usar a biblioteca de cliente do Bigtable, consulte Bibliotecas de cliente do Bigtable.

Para autenticar no Bigtable, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente. 

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

Para saber como instalar e usar a biblioteca de cliente do Bigtable, consulte Bibliotecas de cliente do Bigtable.

Para autenticar no Bigtable, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente. 

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")
    row.delete_cells(column_family_id="cell_plan", columns=row.ALL_COLUMNS)
    row.commit()

Python asyncio

Para saber como instalar e usar a biblioteca de cliente do Bigtable, consulte Bibliotecas de cliente do Bigtable.

Para autenticar no Bigtable, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente. 

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

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

    await table.mutate_row("phone#4c410523#20190501", DeleteAllFromFamily("cell_plan"))

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

Node.js

Para saber como instalar e usar a biblioteca de cliente do Bigtable, consulte Bibliotecas de cliente do Bigtable.

Para autenticar no Bigtable, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente. 

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

Excluir de uma linha

Os snippets de código a seguir demonstram como excluir todas as células de uma linha:

Java

Para saber como instalar e usar a biblioteca de cliente do Bigtable, consulte Bibliotecas de cliente do Bigtable.

Para autenticar no Bigtable, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente. 

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 DeleteFromRowExample {
  public void deleteFromRow(String projectId, String instanceId, String tableId)
      throws IOException {
    try (BigtableDataClient dataClient = BigtableDataClient.create(projectId, instanceId)) {
      Mutation mutation = Mutation.create().deleteRow();
      dataClient.mutateRow(
          RowMutation.create(TableId.of(tableId), "phone#4c410523#20190501", mutation));
    }
  }
}

Python

Para saber como instalar e usar a biblioteca de cliente do Bigtable, consulte Bibliotecas de cliente do Bigtable.

Para autenticar no Bigtable, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente. 

def delete_from_row(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()
    row.commit()

Python asyncio

Para saber como instalar e usar a biblioteca de cliente do Bigtable, consulte Bibliotecas de cliente do Bigtable.

Para autenticar no Bigtable, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente. 

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

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

    await table.mutate_row("phone#4c410523#20190501", DeleteAllFromRow())

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

Node.js

Para saber como instalar e usar a biblioteca de cliente do Bigtable, consulte Bibliotecas de cliente do Bigtable.

Para autenticar no Bigtable, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente. 

const row = table.row('phone#4c410523#20190501');
await row.delete();
await printRows();

Excluir por streaming e em lotes

O streaming e o agrupamento em lote das solicitações de exclusão geralmente são a melhor maneira de excluir grandes quantidades de dados. Essa estratégia pode ser útil quando você tem requisitos de retenção de dados mais refinados do que o permitido pelas políticas de coleta de lixo.

Se o aplicativo for escrito em Java, você poderá ativar o controle de fluxo de gravação em lote ao enviar exclusões em lote para o Bigtable. Para mais informações, consulte Controle de fluxo de gravação em lote e Ativar o controle de fluxo de gravação em lote.

Os exemplos de código a seguir iniciam um stream de dados (leitura de linhas), os agrupam em lote e, em seguida, passam pelo lote e excluem todas as células da coluna data_plan_01gb1 no grupo de colunas cell_plan:

Go

Para saber como instalar e usar a biblioteca de cliente do Bigtable, consulte Bibliotecas de cliente do Bigtable.

Para autenticar no Bigtable, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente. 

// Copyright 2025 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package deletes


import (
	"context"
	"fmt"
	"io"

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

// streamingAndBatching starts a stream of data (reading rows), batches them, and then goes through the batch and deletes all the cells in column
func streamingAndBatching(w io.Writer, projectID, instanceID string, tableName string) error {
	// projectID := "my-project-id"
	// instanceID := "my-instance-id"
	// tableName := "mobile-time-series"

	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)

	// Slices to hold the row keys and the corresponding mutations.
	var rowKeys []string
	var mutations []*bigtable.Mutation

	// Read all rows from the table.
	err = tbl.ReadRows(ctx, bigtable.InfiniteRange(""), func(row bigtable.Row) bool {
		// For each row, create a mutation to delete the specified cell.
		mut := bigtable.NewMutation()
		mut.DeleteCellsInColumn("cell_plan", "data_plan_01gb")

		// Append the row key and mutation to the slices.
		rowKeys = append(rowKeys, row.Key())
		mutations = append(mutations, mut)

		// Continue processing rows.
		return true
	})
	if err != nil {
		return fmt.Errorf("tbl.ReadRows: %w", err)
	}

	if len(mutations) == 0 {
		return nil
	}
	// If there are mutations to apply, apply them in a single bulk request.
	// ApplyBulk returns a slice of errors, one for each mutation.
	var errs []error
	if errs, err = tbl.ApplyBulk(ctx, rowKeys, mutations); err != nil {
		return fmt.Errorf("tbl.ApplyBulk: %w", err)
	}
	if errs != nil {
		// Log any individual errors that occurred during the bulk operation.
		var errorCount int
		for _, individualErr := range errs {
			if individualErr != nil {
				fmt.Fprintf(w, "Error applying mutation: %v\n", individualErr)
				errorCount++
			}
		}
		if errorCount > 0 {
			return fmt.Errorf("encountered %d error(s) out of %d mutations", errorCount, len(errs))
		}
	}

	fmt.Fprintf(w, "Successfully deleted cells from all rows")
	return nil
}

Java

Para saber como instalar e usar a biblioteca de cliente do Bigtable, consulte Bibliotecas de cliente do Bigtable.

Para autenticar no Bigtable, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente. 

import com.google.api.gax.batching.Batcher;
import com.google.api.gax.rpc.ServerStream;
import com.google.cloud.bigtable.data.v2.BigtableDataClient;
import com.google.cloud.bigtable.data.v2.models.Query;
import com.google.cloud.bigtable.data.v2.models.Row;
import com.google.cloud.bigtable.data.v2.models.RowMutationEntry;
import com.google.cloud.bigtable.data.v2.models.TableId;
import java.io.IOException;

public class BatchDeleteExample {
  public void batchDelete(String projectId, String instanceId, String tableId)
      throws InterruptedException, IOException {
    try (BigtableDataClient dataClient = BigtableDataClient.create(projectId, instanceId)) {
      try (Batcher<RowMutationEntry, Void> batcher =
          dataClient.newBulkMutationBatcher(TableId.of(tableId))) {
        ServerStream<Row> rows = dataClient.readRows(Query.create(TableId.of(tableId)));
        for (Row row : rows) {
          batcher.add(
              RowMutationEntry.create(row.getKey()).deleteCells("cell_plan", "data_plan_05gb"));
        }
        // Blocks until mutations are applied on all submitted row entries.
        batcher.flush();
      }
    }
  }
}

Python

Para saber como instalar e usar a biblioteca de cliente do Bigtable, consulte Bibliotecas de cliente do Bigtable.

Para autenticar no Bigtable, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente. 

def streaming_and_batching(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)
    batcher = table.mutations_batcher(flush_count=2)
    rows = table.read_rows()
    for row in rows:
        row = table.row(row.row_key)
        row.delete_cell(column_family_id="cell_plan", column="data_plan_01gb")

    batcher.mutate_rows(rows)

Python asyncio

Para saber como instalar e usar a biblioteca de cliente do Bigtable, consulte Bibliotecas de cliente do Bigtable.

Para autenticar no Bigtable, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente. 

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

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

    async with table.mutations_batcher() as batcher:
        async for row in await table.read_rows_stream(ReadRowsQuery(limit=10)):
            await batcher.append(
                RowMutationEntry(
                    row.row_key,
                    DeleteRangeFromColumn(
                        family="cell_plan", qualifier=b"data_plan_01gb"
                    ),
                )
            )

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

Node.js

Para saber como instalar e usar a biblioteca de cliente do Bigtable, consulte Bibliotecas de cliente do Bigtable.

Para autenticar no Bigtable, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente. 

const rows = (await table.getRows({limit: 2}))[0];
const entries = rows.map(row => {
  return {
    key: row.id,
    method: 'delete',
    data: {
      column: 'cell_plan:data_plan_05gb',
    },
  };
});
await table.mutate(entries);
await printRows();

Excluir dados em uma visualização autorizada

É possível excluir dados da tabela enviando uma solicitação de exclusão para uma visualização autorizada. Use uma das seguintes opções:

  • CLI da gcloud
  • Cliente Bigtable para Java

Ao excluir dados de uma visualização autorizada, você fornece o ID dela e o ID da tabela.

Os dados que podem ser excluídos de uma visualização autorizada são limitados pela definição dela. Só é possível excluir dados incluídos na visualização autorizada. Se você tentar excluir dados que estão fora da definição da visualização autorizada ou sujeitos às seguintes regras, um erro de PERMISSION_DENIED será retornado:

  • Não é possível excluir um intervalo de linhas de uma visualização autorizada usando DropRowRange na API Admin.
  • Não é possível excluir de uma linha.
  • A exclusão de uma coluna é compatível desde que seja para linhas na visualização autorizada.
  • A exclusão de um grupo de colunas só é permitida se ele estiver configurado para permitir todos os prefixos de qualificador de coluna (qualifier_prefixes="") na visualização autorizada.

Por exemplo, se você tentar excluir de uma linha especificada e essa linha contiver colunas na tabela subjacente que não estão na sua visualização autorizada, a solicitação vai falhar.

A seguir