Gerenciar a retenção de dados com índices de TTL

Nesta página, descrevemos como usar a API MongoDB, o console do Google Cloud e a Google Cloud CLI para configurar índices de time to live (TTL).

Visão geral de time to live (TTL)

Use os índices de TTL para automatizar remover dados desatualizados dos seus bancos de dados. Um índice 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. Em geral, 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 preços de operações de exclusão, consulte os preços da edição Enterprise do Cloud Firestore.

Limites e restrições

  • É possível criar apenas um índice de TTL por grupo de coleções.
  • É possível ter no máximo 500 índices 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. 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. Em geral, os dados são excluídos em até 24 horas após a data de validade.

  • A criação de um índice de TTL em uma coleção resulta em uma exclusão em massa de todos os dados expirados de acordo com o novo índice de TTL. Observação: 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 um novo índice 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 será usada.

  • O Cloud Firestore expira um documento somente quando o campo de TTL está definido como um valor Date and time/BSON Date ou um valor Array que contém um valor Date and time/BSON Date. Se o campo não for preenchido ou for definido como um valor como null, 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.

Campos de TTL e índices sem TTL

Um campo de TTL pode ser indexado ou não indexado. No entanto, como um campo de TTL é um carimbo de data/hora, incluir o campo em um índice sem TTL pode afetar o desempenho em taxas de tráfego mais altas. Incluir um campo de carimbo de data/hora em um índice que não seja de TTL 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.

Permissões

O principal que cria ou exclui um índice de TTL exige a seguinte permissão no projeto:

  • A visualização de índices de TTL exige as permissões datastore.indexes.list e datastore.indexes.get.
  • A criação ou exclusão de índices 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 gcloud CLI para gerenciar índices de TTL, use gcloud components update para atualizar os componentes para a versão mais recente disponível:

gcloud components update

Criar um índice de TTL

Ao criar um índice 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. O campo TTL precisa ser definido como um valor Timestamp/BSON Date ou um valor Array que contenha um valor Timestamp/BSON Date. É 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 um índice 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.

Para criar um índice TTL, siga estas etapas.

API MongoDB

Inclua a opção de índice expireAfterSeconds ao chamar o método createIndex():

db.COLLECTION_NAME.createIndex({"TTL_FIELD": 1, "expireAfterSeconds": EXPIRATION_OFFSET_SECONDS})

Exemplo:

db.restaurants.createIndex({"ts": 1, "expireAfterSeconds": 3600})

expireAfterSeconds identifica o TTL como um índice de TTL e é o deslocamento entre o valor de carimbo de data/hora do campo TTL e o prazo de validade. Se expireAfterSeconds estiver definido como 0, o tempo de expiração será fornecido diretamente pelo valor de carimbo de data/hora do campo TTL.

Observe as seguintes limitações:

  • Os índices de TTL precisam incluir exatamente um campo.
  • Os índices de TTL não podem ser usados em consultas.
  • É possível criar apenas um índice de TTL por grupo de coleções.
  • Os registros de auditoria para criação de índice de TTL com a API MongoDB usam o nome do método google.firestore.admin.v1.FirestoreAdmin.UpdateField.

Console do Google Cloud

  1. No Console do Google Cloud, 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 índices de TTL. Em caso de falha, a página exibe uma mensagem de erro.

gcloud

  1. Instale e inicialize a gcloud CLI CLI.

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

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

Duração da criação do índice de TTL

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

Conferir índices de TTL

Para ver os índices de TTL, siga estas etapas:

API MongoDB

Use o método listIndexes() para conferir os índices de TTL. Exemplo:

db.restaurants.listIndexes()

A saída vai incluir índices de TTL e não TTL. Os índices de TTL vão incluir a opção expireAfterSeconds.

Console do Google Cloud

  1. No Console do Google Cloud, 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 os índices de TTL do banco de dados e inclui o status de cada um deles.

gcloud

  1. Instale e inicialize a gcloud CLI CLI.

  2. Use o comando firestore fields ttls list para configurar um índice de TTL. O comando a seguir lista todos os índices de TTL.

    gcloud firestore fields ttls list

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

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

Conferir detalhes da operação

É possível usar a gcloud CLI para conferir mais detalhes sobre um índice 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.

Remover um índice de TTL

Para descartar um índice de TTL, siga estas etapas:

API MongoDB

Use o método dropIndex() para descartar um índice de TTL. Exemplo:

Descartar um índice de TTL usando o nome dele

db.restaurants.dropIndex("ts_1")

Descartar um índice de TTL usando a definição de índice

db.restaurants.dropIndex({"ts": 1})

Os registros de auditoria para exclusão de um índice TTL com a API MongoDB usam o nome do método google.firestore.admin.v1.FirestoreAdmin.UpdateField.

Console do Google Cloud

  1. No Console do Google Cloud, 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 índices de TTL, encontre a linha do índice 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 o índice de TTL da tabela.

gcloud

  1. Instale e inicialize a gcloud CLI CLI.

  2. Use o comando firestore fields ttls update para configurar um índice de TTL. Adicione a sinalização --async para evitar que a ferramenta gcloud CLI fique aguardando a conclusão da operação.

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

Monitorar exclusões por TTL

Use o Cloud Monitoring para conferir métricas sobre exclusões orientadas por TTL. O Cloud Firestore fornece as seguintes métricas para TTL:

Tipo de métrica Nome da métrica Descrição da métrica
firestore.googleapis.com/document/ttl_deletion_count Contagem de exclusões por TTL

Contagem total de documentos excluídos pelos índices de TTL.
firestore.googleapis.com/document/ttl_expiration_to_deletion_delays Atraso entre a expiração de TTL e a exclusão

Tempo decorrido entre a expiração de um documento em um índice de TTL e quando ele foi realmente excluído.

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