Gerenciar a retenção de dados usando políticas de TTL

Nesta página, descrevemos como usar o console do Google Cloud Platform e a Google Cloud CLI para configurar políticas de time to live (TTL). Antes de ler esta página, é preciso entender o modelo de dados do Cloud Firestore.

Visão geral de time to live (TTL)

Use as políticas de time to live (TTL) para remover automaticamente dados desatualizados dos bancos de dados. Uma política de TTL designa um determinado campo como o prazo de validade de documentos em um determinado grupo de coleções. Com o TTL, é possível diminuir os custos de armazenamento limpando dados obsoletos. Normalmente, os dados são excluídos em até 24 horas após a data de validade.

Preços

As operações de exclusão de TTL são contabilizadas nos seus custos de exclusão de documentos. Para conferir os preços de operações de exclusão, consulte Preços do Cloud Firestore.

Limites e restrições

  • Somente um campo por grupo de coleções pode ser marcado como um campo de TTL.
  • No total, são permitidas 200 configurações no nível do campo. Uma configuração pode conter várias configurações para o mesmo campo. Por exemplo, uma isenção de indexação de campo único e uma política de TTL no mesmo campo contam como uma configuração de campo para o limite.
  • Para clientes do Firestore no modo Datastore, o TTL não pode ser usado com um modo de simultaneidade Otimista com grupos de entidades. Considere alterar o modo de simultaneidade seguindo esta.

Exclusão por TTL

Observe os principais comportamentos de exclusão orientada por TTL:

  • A exclusão por TTL não é um processo instantâneo. Os documentos expirados continuam aparecendo nas consultas e nas solicitações de pesquisa até que o processo de TTL exclua eles. O TTL não prioriza a velocidade de exclusão, para reduzir o custo total de propriedade para exclusões. Normalmente, os dados são excluídos em até 24 horas após a data de validade.

  • A exclusão de um documento pelo TTL não afeta as subcoleções do documento.

  • A aplicação de uma política de TTL a um grupo de coleções atual resulta na exclusão em massa de todos os dados que expiraram de acordo com a nova política de TTL. Essa exclusão em massa também não é instantânea e depende da quantidade de dados desse grupo de coleções.

  • Se um documento tiver um prazo de validade passado e você adicionar uma nova política de ttl à coleção, ele será excluído em até 24 horas após a conclusão da configuração da política de ttl e ficará ativo.

  • O TTL não exclui necessariamente os documentos na mesma ordem que os carimbos de data/hora de expiração.

  • As exclusões não são feitas de maneira transacional. Documentos com o mesmo prazo de validade não são necessariamente excluídos ao mesmo tempo. Se você precisar desse comportamento, faça as exclusões usando uma biblioteca de cliente.

  • O Cloud Firestore sempre vai usar o campo TTL mais recente para determinar a validade. Por exemplo, se um documento expirado, mas ainda não excluído, tiver o campo TTL atualizado para uma data posterior, o documento não vai expirar, e a nova data vai ser usada.

  • O TTL foi projetado para minimizar o impacto em outras atividades do banco de dados. As exclusões geradas pelo TTL são tratadas com uma prioridade mais baixa. Outras estratégias também estão em vigor para suavizar os picos de tráfego de exclusões orientadas por TTL.

  • A exclusão por TTL chama todos os listeners de snapshots ativos e aciona gatilhos do Cloud Firestore do Cloud Functions.

Campos e índices de TTL

Um campo de TTL pode ser indexado ou não indexado. No entanto, como um campo de TTL é um carimbo de data/hora, a indexação dele pode afetar o desempenho em taxas de tráfego mais altas. Indexar um campo de carimbo de data/hora pode criar pontos de acesso, o que é contra as práticas recomendadas. Os pontos de acesso são as taxas altas de leitura, gravação e exclusão para um intervalo de documentos estreito.

Por padrão, o Cloud Firestore cria um índice de campo único para todos os campos. É possível criar uma isenção de índice de campo único para desativar índices em um campo de TTL.

Permissões

O principal que configura uma política de TTL exige a permissão a seguir no projeto:

  • A visualização de políticas de TTL exige as permissões datastore.indexes.list e datastore.indexes.get.
  • A modificação de políticas de TTL exige a permissão datastore.indexes.update.
  • A verificação do status das operações TTL requer datastore.operations.list e datastore.operations.get.

Para conferir os papéis que atribuem essas permissões, consulte Papéis do Identity and Access Management do Cloud Firestore.

Antes de começar

Antes de usar a CLI gcloud para gerenciar políticas de TTL, use o comando gcloud components update para atualizar os componentes para a versão mais recente disponível:

gcloud components update

Criar uma política de TTL

Ao criar uma política de TTL, você designa um campo de documento como o tempo de expiração para documentos em um grupo de coleções.

O TTL usa um campo especificado para identificar documentos que podem ser excluídos. Esse campo de TTL deve ser do tipo Date and time. É possível selecionar um campo que já existe ou designar um campo que você planeja adicionar mais tarde.

Considere as informações a seguir antes de definir o valor do campo de TTL:

  • O valor do campo de TTL pode ser um horário no futuro, no presente ou no passado. Se o valor for um horário no passado, o documento estará imediatamente qualificado para exclusão. Por exemplo, é possível criar uma política de TTL com o campo expireAt que você adiciona aos documentos existentes.

  • Usar qualquer outro tipo de dados ou não definir o valor do campo desativa o TTL do documento individual.

Siga as etapas abaixo para criar uma política de TTL:

Console do Google Cloud

  1. No Console do Google Cloud Platform, acesse a página Bancos de dados.

    Acessar "Bancos de dados"

  2. Selecione o banco de dados necessário na lista de bancos de dados.

  3. No menu de navegação, clique em Time to live.

  4. Clique em Criar política.

  5. Insira um nome para o grupo de coleções e um campo de carimbo de data/hora.

  6. Clique em Criar.

O console retorna à página Time to live. Se a operação for iniciada com êxito, a página vai adicionar uma entrada à tabela de políticas de TTL. Em caso de falha, a página exibe uma mensagem de erro.

gcloud

Use o comando firestore fields ttls update para configurar uma política de TTL. Adicione a sinalização --async para evitar que a CLI gcloud aguarde a conclusão da operação.

 gcloud firestore fields ttls update
  ttl_field --collection-group=collection_group_name
  --enable-ttl 

Mesmo em um banco de dados vazio, pode levar dez minutos ou mais para ativar uma política de TTL. Após iniciar uma operação, o fechamento do terminal não cancela a operação.

Conferir políticas de TTL

Siga as etapas abaixo para acessar as políticas de TTL e os status delas.

Console do Google Cloud

  1. No Console do Google Cloud Platform, acesse a página Bancos de dados.

    Acessar "Bancos de dados"

  2. Selecione o banco de dados necessário na lista de bancos de dados.

  3. No menu de navegação, clique em Time to live.

O console lista as políticas de TTL do banco de dados e inclui o status de cada uma delas.

gcloud

Use o comando firestore fields ttls list para configurar uma política de TTL. O comando a seguir lista todas as políticas de TTL.

   gcloud firestore fields ttls list
   

Para listar políticas de TTL em um grupo de coleções específico, use o seguinte:

   gcloud firestore fields ttls list  --collection-group=collection_group_name
   

Conferir detalhes da operação

É possível usar a CLI gcloud para conferir mais detalhes sobre uma política de TTL que está no estado CREATING.

Use o comando operations list para ver todas as operações em execução e recentemente concluídas:

gcloud firestore operations list

A resposta inclui uma estimativa do progresso da operação.

Desativar uma política de TTL

Siga as etapas abaixo para desativar uma política de TTL.

Console do Google Cloud

  1. No Console do Google Cloud Platform, acesse a página Bancos de dados.

    Acessar "Bancos de dados"

  2. Selecione o banco de dados necessário na lista de bancos de dados.

  3. No menu de navegação, clique em Time to live.

  4. Na tabela de políticas de TTL, encontre a linha da política de TTL. Nessa linha, clique no botão Excluir (lixeira).

  5. Para confirmar, clique em Excluir.

O console retorna à página Time to live. Em caso de sucesso, o Cloud Firestore remove a política de TTL da tabela.

gcloud

1. Use o comando firestore fields ttls update para configurar uma política de TTL. Adicione a sinalização --async para evitar que a CLI gcloud aguarde a conclusão da operação.

   gcloud firestore fields ttls update ttl_field --collection-group=collection_group_name --disable-ttl
   

Monitorar exclusões por TTL

É possível usar o Cloud Monitoring para conferir métricas sobre exclusões orientadas por TTL. O Cloud Firestore fornece as seguintes métricas para TTL:

firestore.googleapis.com/document/ttl_deletion_count Contagem de exclusões por time to live

Contagem total de documentos excluídos pelas políticas de time to live (TTL).

firestore.googleapis.com/document/ttl_expiration_to_deletion_delays Atraso entre a expiração de time to live e a exclusão

Tempo decorrido entre a expiração de um documento de acordo com uma política de time to live (TTL) e o momento em que ele foi excluído.

Para configurar um painel com métricas do Cloud Firestore, consulte gerenciar painel personalizado e adicionar widgets de painel.