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

Nesta página, descrevemos como usar o console do Google Cloud 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 modo Datastore.

Visão geral de time to live (TTL)

Use políticas de TTL para remover automaticamente dados desatualizados dos bancos de dados. Uma política de TTL designa uma determinada propriedade como o prazo de validade para entidades em um determinado tipo. 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 entidades. Para conferir os preços de operações de exclusão, consulte Preços do Firestore no modo Datastore.

Limites e restrições

Somente uma propriedade por tipo pode ser marcada como uma propriedade de TTL.
São permitidas 200 políticas de TTL.

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. As entidades expiradas continuam aparecendo nas consultas e nas solicitações de pesquisa até que o processo de TTL exclua elas. 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 uma entidade por TTL não remove as entidades descendentes dessa entidade.
A aplicação de uma política de TTL a um tipo existente 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 para esse tipo.
Se uma entidade tiver um prazo de validade no passado e você adicionar uma nova política de ttl ao tipo, a entidade será excluída em até 24 horas após a conclusão da configuração e a ativação da política.
O TTL não exclui necessariamente as entidades na mesma ordem que os carimbos de data/hora de expiração.
As exclusões não são feitas de maneira transacional. Entidades com o mesmo prazo de validade não são necessariamente excluídas ao mesmo tempo. Se você precisar desse comportamento, faça as exclusões usando uma biblioteca de cliente.
O modo Datastore sempre vai usar o campo TTL mais recente para determinar a validade. Por exemplo, se uma entidade expirada, mas ainda não excluída, tiver o campo TTL atualizado para uma data posterior, a entidade não vai expirar, e a nova data será usada.
O modo Datastore só expira um documento quando o campo de TTL está definido como um tipo Timestamp. Se o campo não for preenchido ou for definido como null, por exemplo, a expiração vai acontecer em cada documento de forma individual.
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.

Propriedades e índices de TTL

Uma propriedade TTL pode ser indexada ou não indexada. No entanto, como uma propriedade de TTL é um carimbo de data/hora, a indexação da propriedade pode afetar o desempenho em taxas de tráfego mais altas. Indexar uma propriedade de carimbo de data/hora não segue as práticas recomendadas e pode criar pontos de acesso. Os pontos de acesso são taxas altas de leitura, gravação e exclusão para um intervalo de chaves estreito.

Por padrão, o Datastore cria um índice integrado para todas as propriedades. É possível excluir uma propriedade dos índices para desativar índices em uma propriedade 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 Datastore.

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 uma propriedade de entidade como o tempo de expiração para entidades em um tipo. A política de TTL se aplica ao tipo especificado em todos os namespaces.

O TTL usa uma propriedade especificada para identificar entidades que podem ser excluídas. Essa propriedade de TTL precisa ser do tipo Date and time. É possível selecionar uma propriedade que já existe ou designar uma propriedade que você planeja adicionar mais tarde.

Considere o seguinte antes de definir o valor da propriedade de TTL:

O valor da propriedade de TTL pode ser um horário no futuro, no presente ou no passado. Se o valor for um horário no passado, a entidade estará imediatamente qualificada para exclusão. Por exemplo, é possível criar uma política de TTL com a propriedade expireAt que você adiciona às entidades atuais.
Usar qualquer outro tipo de dados ou não definir o valor da propriedade TTL desativa o TTL da entidade individual.

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

Console do Google Cloud

No Console do Google Cloud, acesse a página Bancos de Dados.

Acessar "Bancos de dados"
Selecione o banco de dados necessário na lista de bancos de dados.
No menu de navegação, clique em Time to live.
Clique em Criar política.
Insira um nome de tipo e um nome de propriedade de carimbo de data/hora.
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

No Console do Google Cloud, ative o Cloud Shell.

Ativar o Cloud Shell

Na parte inferior do Console do Google Cloud, uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a CLI do Google Cloud já instalada e com valores já definidos para o projeto atual. A inicialização da sessão pode levar alguns segundos.
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

No Console do Google Cloud, acesse a página Bancos de Dados.

Acessar "Bancos de dados"
Selecione o banco de dados necessário na lista de bancos de dados.
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

No Console do Google Cloud, ative o Cloud Shell.

Ativar o Cloud Shell

Na parte inferior do Console do Google Cloud, uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a CLI do Google Cloud já instalada e com valores já definidos para o projeto atual. A inicialização da sessão pode levar alguns segundos.
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 tipo 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

No Console do Google Cloud, acesse a página Bancos de Dados.

Acessar "Bancos de dados"
Selecione o banco de dados necessário na lista de bancos de dados.
No menu de navegação, clique em Time to live.
Na tabela de políticas de TTL, encontre a linha da política de TTL. Nessa linha, clique no botão Excluir (lixeira).
Para confirmar, clique em Excluir.

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

gcloud

No Console do Google Cloud, ative o Cloud Shell.

Ativar o Cloud Shell

Na parte inferior do Console do Google Cloud, uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a CLI do Google Cloud já instalada e com valores já definidos para o projeto atual. A inicialização da sessão pode levar alguns segundos.
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 Datastore fornece as seguintes métricas para TTL:

datastore.googleapis.com/entity/ttl_deletion_count	Contagem de exclusão por TTL	Contagem total de entidades excluídas pelas políticas de TTL.
datastore.googleapis.com/entity/ttl_expiration_to_deletion_delays	Atraso entre expiração de TTL e exclusão	Tempo decorrido entre a expiração de uma entidade de acordo com uma política de TTL e o momento em que ela foi realmente excluída.

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