Purgar valores de recursos para entidades
Beta
Esse recurso está em Beta. Para usá-lo, um administrador do workspace deve ativar a Funcionalidade avançada de visualizações de recursos na página Pré-visualizações . Consulte Gerenciar prévias do Databricks.
Use uma purga de entidades de recurso para remover os valores de recurso compute de uma ou mais Recurso Views para entidades selecionadas. Por default, uma purga define os valores de recurso selecionados como NULL nas linhas correspondentes das tabelas de materialização offline e online aplicáveis no Unity Catalog e no Lakebase. Para excluir linhas correspondentes, defina delete_rows=True. Faça a execução da purga no Workspace onde as materializações que você deseja purgar foram criadas. Isso não exclui as definições de recurso view, materializações ou dados de origem. As materializações criadas em outros Workspace não são afetadas.
Por exemplo, você pode limpar os valores de recurso materializados de um cliente depois de receber uma solicitação de exclusão de dados. Para também remover as linhas que contêm as chaves de entidade do cliente, defina delete_rows=True.
Before you submit a purge, you must remove the selected entities from the recurso source data and prevent the source from receiving new data for those entities. A purge does not change the source or stop scheduled and continuous materialization. If matching source data remains or arrives later, a materialization recreates the values.
Requisitos
- Os recursos devem ser Feature Views registrados. Cada recurso view deve ter pelo menos uma materialização criada no Workspace onde você envia a purga. Para purgar materializações criadas em diferentes Workspace, envie uma solicitação separada em cada Workspace.
RequestSource,FeatureViewSourcee outros recursos não materializáveis não são compatíveis. - Especifique de 1 a 500 recursos exclusivos por seus nomes de três partes do Unity Catalog.
- Nenhum recurso pode ter um backfill em andamento ou uma exclusão em sua fase de exclusão lógica quando você enviar a solicitação. Consulte Backfill Recurso Views.
- A tabela entities deve ser uma tabela Delta do Unity Catalog com pelo menos uma coluna. Consulte Prepare the entities table.
- Use o cliente de recurso engenharia do Databricks versão 0.18.0 e acima.
- Para exclusão de linhas com
delete_rows=True, use a versão 0.18.3 e acima do cliente de Engenharia de recursos da Databricks. - Para
delete_rows=True, inclua cada recurso que compartilha cada tabela materializada afetada. Uma solicitação pode abranger várias tabelas, e o requisito se aplica independentemente a cada tabela. A validação rejeita a cobertura incompleta comINVALID_PARAMETER_VALUEe lista as tabelas afetadas e as colunas que a solicitação não cobre.
Permissões
Para produção, o Databricks recomenda executar limpezas como o mesmo Service Principal que cria e materializa as recursos views. Normalmente, esse principal já tem os privilégios necessários. Se os privilégios tiverem mudado, verifique os seguintes requisitos antes de enviar uma limpeza.
Para enviar e concluir uma purga, você deve ter os seguintes privilégios:
MANAGEem cada recurso View na solicitação.SELECTna tabela de entidades.SELECTandMODIFYon each offline, partial-aggregate, and online table that the purge updates.- Acesso à instância ou projeto do Lakebase usado pelo armazenamento online, incluindo permissão para ler e atualizar suas tabelas online e para excluir linhas quando
delete_rows=True. Consulte Conceder permissões de projeto. - Para uma transmissão de registro de esquema sem um esquema embutido, a permissão para ler seus metadados de tabela de ingestão, como
SELECTouREAD_METADATAquando disponíveis. A leitura de validação de purga lê o esquema para resolver os tipos de key de entidade, e não as linhas da tabela de ingestão. USE CATALOGeUSE SCHEMAno catálogo pai e no esquema de cada recurso listado acima.
Para obter descrições completas dos privilégios do Unity Catalog, consulte Referência de privilégios do Unity Catalog. Para obter permissões de recurso View, consulte Materialize Feature Views.
Preparar a tabela de entidades
Crie uma tabela Delta que identifique as entidades a serem purgadas. Cada coluna deve corresponder a uma key de entidade de cada recurso View na solicitação. Os nomes de coluna e os tipos de dados devem corresponder às chaves de entidade da recurso View. Não inclua colunas não-key.
The table can contain a subset of the entity keys that is a leading prefix of the Recurso View's entities list. O expurgo corresponde a todas as entidades com os valores de key fornecidos, independentemente das keys restantes. Valores de key nulos são suportados.
As colunas da tabela de entidades devem conter todas as keys de entidade ou um prefixo inicial que corresponda à ordem da lista de entidades do recurso View. A ordem das colunas na tabela de entidades não importa.
For existing online tables, the primary-key order can differ from the recurso View's entities list order. In that case, validation uses the online table's primary-key prefix instead and reports the required order if a partial-key request does not match.
As Recursos views solicitadas podem ter conjuntos de keys de entidade diferentes, desde que as colunas da tabela de entidades sejam um subconjunto do conjunto de keys de entidade de cada Recurso view.
O job de limpeza resolve uma versão da tabela Delta e usa esse snapshot para cada destino. Não modifique a tabela de entidades após enviar a solicitação. Para expurgar entidades adicionadas após o job resolver a versão, envie outra solicitação.
Escolher valores NULL ou exclusão de linha
Por default, uma exclusão define os valores de recurso selecionados para NULL e mantém as linhas, incluindo as suas key de entidade e outras colunas. Use este modo para remover valores de recurso enquanto retém as linhas.
Defina delete_rows=True para remover linhas correspondentes, incluindo suas entity keys. Use a exclusão de linha para uma solicitação de exclusão de dados que requer a remoção das keys, bem como os valores de recurso. Inclua cada recurso que compartilha cada tabela materializada afetada, conforme descrito em Requisitos.
Como a limpeza funciona
Uma exclusão tem duas fases:
- Exclusão lógica (estados
PENDING_PURGEeRUNNING_PURGE): A exclusão apaga linhas correspondentes ou define valores de recurso paraNULL, depois sincroniza as alterações online. Depois desta fase, a exclusão libera o seu bloqueio nos recursos, por isso outra exclusão pode começar durante a limpeza. - Limpeza (estados
PENDING_CLEANUPeRUNNING_CLEANUP): Para tabelas offline, a limpeza aguarda pelo menos sete dias e, em seguida, remove arquivos de dados obsoletos e logs de transações. A operação permanece incompleta até que a limpeza seja concluída.
Se a retenção de arquivo ou log de uma tabela offline for maior que sete dias, a limpeza a reduzirá para sete dias para toda a tabela, o que também limita a viagem do tempo nessa tabela a sete dias. Não aumente nenhuma das configurações de retenção acima de sete dias durante a operação, ou a limpeza falhará.
As propriedades de retenção são delta.deletedFileRetentionDuration para arquivos de dados e delta.logRetentionDuration para logs de transação. A limpeza não restaura seus valores originais após o cleanup.
Para o Lakebase, o Databricks recomenda uma janela de point-in-time restore (PITR) de sete dias ou menos. Consulte Configurar sua janela de restauração. Os purges não aguardam a limpeza automática da história do Lakebase nem verificam a exclusão física dessa história.
Enviar uma purga
Chamar FeatureEngineeringClient.purge_feature_entities. O argumento delete_rows assume como padrão default False, portanto o exemplo a seguir define os valores dos recursos como NULL e mantém as linhas. O método retorna uma operação de longa execução sem esperar que a limpeza termine.
from databricks.feature_engineering import FeatureEngineeringClient
fe = FeatureEngineeringClient()
operation = fe.purge_feature_entities(
features=[
"main.feature_store.customer_purchase_count_30d",
"main.feature_store.customer_purchase_total_30d",
],
entities_table="main.feature_store.entities_to_purge",
)
print(f"Purge operation: {operation.name()}")
Para excluir linhas correspondentes:
operation = fe.purge_feature_entities(
features=[
"main.feature_store.customer_purchase_count_30d",
"main.feature_store.customer_purchase_total_30d",
],
entities_table="main.feature_store.entities_to_purge",
delete_rows=True,
)
Monitorar estados de operação
Use operation.done() para refresh a operação e verificar se ela terminou. Inspecione seu estado com operation.metadata() ou faça polling de fe.get_operation(name=operation.name()) e leia metadata["state"].
Para limpezas offline com cleanup, os estados descrevem estas fases:
PENDING_PURGE: A exclusão lógica está esperando para começar.RUNNING_PURGE: A purga elimina as linhas correspondentes ou define os valores dos recursos comoNULLe sincroniza as alterações online.PENDING_CLEANUP: A limpeza está aguardando a expiração do período de retenção offline.RUNNING_CLEANUP: A purga está limpando arquivos de dados offline e logs de transações obsoletos.
Limpezas somente online e execuções sem tarefas de limpeza podem informar PENDING ou RUNNING em seu lugar. A operação termina com SUCCEEDED, FAILED ou CANCELLED.
Verificar resultados por recurso
Os resultados por recurso estão disponíveis após a conclusão da operação. Na sessão de envio, use operation.wait() após operation.done() retornar True. Para recuperar resultados em uma sessão posterior, chame fe.get_operation(name=...) com o nome da operação impresso quando você enviou a limpeza:
from databricks.feature_engineering import FeatureEngineeringClient
from databricks.sdk.service.ml import PurgeFeatureEntitiesResponse
fe = FeatureEngineeringClient()
status = fe.get_operation(name="operations/<operation_id>")
if not status.done:
print(f"Purge is still in progress: {status.metadata['state']}")
elif status.error:
print(f"Purge operation error: {status.error}")
else:
response = PurgeFeatureEntitiesResponse.from_dict(status.response)
print(f"Purge state: {response.state}")
for result in response.results or []:
print(
result.feature,
result.offline_state,
result.online_state,
result.error,
)
A resposta concluída contém um resultado por recurso view:
offline_staterelata o resultado para materializações offline.online_staterelata o resultado combinado para materializações online.- Um resultado é
SUCCEEDED,FAILEDouNOT_APPLICABLE. - Um resultado é
NOT_APPLICABLEquando o recurso View não tem um destino de materialização para esse tipo de armazenamento. For example, an online-only recurso View has an offline outcome ofNOT_APPLICABLE, and a recurso View without an online materialization has an online outcome ofNOT_APPLICABLE. errorcontém o erro específico da recurso View quando um destino aplicável falha.
Verifique cada resultado por recurso. Uma operação pode terminar com resultados diferentes para diferentes recurso views ou tipos de armazenamento.
Verifique também response.state e response.error para ver se há falha no nível da operação.
Recuperar de falha parcial
Se uma limpeza falhar parcialmente, inspecione os erros por recurso e corrija qualquer problema de acesso ou configuração. Em seguida, envie uma nova solicitação de limpeza com um novo request_id para as View de Recurso com resultados com falha. Para exclusão de linha, inclua todos os recursos em compartilhamento de cada tabela materializada afetada, mesmo se alguns desses recursos tiverem sido bem-sucedidos na solicitação anterior. Mantenha os dados de origem limpos antes de tentar novamente. Se as falhas persistirem, entre em contato com o suporte do Databricks.
Tentar uma solicitação com segurança
Defina request_id como um valor UUID4 e retenha-o até que a solicitação seja aceita. Se uma falha de rede ou do cliente tornar o resultado do envio ambíguo, repita a mesma solicitação com a mesma ID. O Databricks retorna a operação existente em vez de iniciar um segundo expurgo.
O conjunto de recursos e a tabela de entidades devem corresponder à solicitação original. A reutilização de um ID com diferentes parâmetros de solicitação é rejeitada. O cliente gera um ID quando você omite um, mas é necessário um ID explícito para tornar as novas tentativas em nível de aplicativo idempotentes. Isso também é útil quando uma camada de orquestração externa pode tentar a operação novamente.
Atribuir custos de limpeza de compute
As execuções de limpeza usam compute serverless. Com a versão 0.18.1 do cliente do Databricks Recurso Engenharia e acima, use tags ou budget_policy_id para atribuir o custo de compute:
operation = fe.purge_feature_entities(
features=["main.feature_store.customer_purchase_count_30d"],
entities_table="main.feature_store.entities_to_purge",
tags={"team": "recommendations", "workflow": "privacy-deletion"},
budget_policy_id="00000000-0000-0000-0000-000000000000",
)
As tags se aplicam ao compute de limpeza, não aos recursos de Unity Catalog feature. Uma solicitação aceita no máximo 25 tags.