Filtros de linha e máscaras de coluna

Esta página fornece orientação sobre o uso de filtros de linha e máscaras de coluna para filtrar dados confidenciais em suas tabelas.

O que são filtros de linha?

Os filtros de linha permitem controlar quais linhas um usuário pode acessar em uma tabela com base na lógica personalizada. No momento da consulta, um filtro de linha avalia uma condição e retorna somente as linhas que a atendem. Isso é comumente utilizado para implementar segurança em nível de linha — por exemplo, restringir usuários a registros de uma região, departamento ou account específicos.

Os filtros de linha são definidos como funções definidas pelo usuário (UDFs) do SQL e também podem incorporar lógica Python ou Scala quando envolvidos em uma UDF do SQL. Você pode aplicar filtros de linha por tabela ou centralmente por meio de políticas ABAC usando tags controladas.

O que são máscaras de coluna?

As máscaras de coluna controlam quais valores os usuários veem em colunas específicas, dependendo de quem são. No momento da consulta, a máscara substitui cada referência a uma coluna pelo resultado de uma função de mascaramento. Isso permite que dados confidenciais, como números de identidade social ou e-mails, sejam editados ou transformados com base na identidade ou função do usuário.

Cada coluna pode ter uma máscara. A máscara deve ser definida como uma UDF SQL que retorna um valor do mesmo tipo da coluna que está sendo mascarada. O SQL UDF pode opcionalmente chamar UDFs Python ou Scala para implementar lógica de mascaramento complexa. As máscaras de coluna também podem receber outras colunas como entradas, por exemplo, para variar o comportamento com base em vários atributos.

Assim como os filtros de linha, as máscaras de coluna podem ser aplicadas por tabela ou gerenciadas centralmente por meio de políticas ABAC. Eles operam no momento da consulta e se integram perfeitamente com o SQL padrão, Notebook e painéis.

Quando se deve utilizar a visualização dinâmica em vez de filtros e máscaras?

A visualização dinâmica, os filtros de linha e as máscaras de coluna permitem aplicar filtros ou transformações lógicas no momento da consulta, mas diferem na forma como são gerenciados, definidos e expostos aos usuários.

Recurso	Aplica-se a	gerenciar utilizando	Impacto da nomenclatura	Melhor usado para...
Visão dinâmica	Exibições	Lógica SQL	Cria um novo nome de objeto	compartilhamento de dados filtrados ou abrangendo várias tabelas
Filtros de linha	tabelas	ABAC ou tabelas de mapeamento	Nome da tabela inalterado	Controle de acesso em nível de linha vinculado a tags de usuário ou de dados
Máscaras de coluna	Tabelas/colunas	ABAC ou tabelas de mapeamento	Nome da tabela inalterado	Elaboração de dados confidenciais de colunas com base na identidade

• Utilize a visualização dinâmica quando necessitar de uma camada somente leitura em uma ou mais tabelas de origem, especialmente para compartilhamento de dados ou aplicação de lógica em várias entradas.
• Use filtros de linha e máscaras de coluna quando quiser aplicar lógica diretamente a uma tabela, sem alterar o nome da tabela ou introduzir novos objetos. Estes podem ser gerenciados utilizando políticas ABAC (recomendado) ou manualmente em tabelas.

Para uma comparação completa, consulte Métodos de controle de acesso comparados.

Como aplicar filtros e máscaras

Você pode implementar filtros de linha e máscaras de coluna de duas maneiras principais:

• Utilizando políticas ABAC (Pré-visualização Pública): Aplique filtros e máscaras de forma centralizada usando tags controladas e políticas reutilizáveis. Essa abordagem se aplica a catálogos e esquemas em geral e reduz a necessidade de configuração tabela por tabela. As políticas ABAC são mais seguras do que as políticas manuais em nível de tabela, pois podem ser definidas por administradores de nível superior e não podem ser substituídas pelos proprietários das tabelas, o que ajuda a impor controles de acesso centralizados. Além disso, em muitos casos, apresentam melhor desempenho, uma vez que a lógica de filtragem e mascaramento nas políticas ABAC é avaliada de forma mais eficiente do que nas UDFs específicas de cada tabela. A Databricks recomenda o uso do ABAC para a maioria dos casos de uso. Para aplicar filtros e máscaras usando ABAC, consulte Controle de acesso baseado em atributos (ABAC)Unity Catalog.

• Atribuição manual por tabela : aplique filtros e máscaras atribuindo funções diretamente a tabelas e colunas individuais. Esse método pode usar tabelas de mapeamento ou outra lógica personalizada. Permite um controle detalhado e específico para cada tabela, mas é mais difícil de escalar e manter. Para obter mais informações, consulte Aplicar manualmente filtros de linha e máscaras de coluna.

Recomendações de desempenho

Filtros de linha e máscaras de coluna controlam a visibilidade dos dados garantindo que os usuários não possam view o conteúdo dos valores das tabelas base antes das operações de filtragem e mascaramento. Eles apresentam bom desempenho em resposta a consultas em casos de uso comuns. Em aplicações menos comuns, onde o mecanismo de consulta deve escolher entre otimizar o desempenho da consulta e proteger contra vazamento de informações dos valores filtrados/mascarados, ele sempre tomará a decisão segura às custas de algum impacto no desempenho da consulta. Para minimizar esse impacto no desempenho, aplique as seguintes recomendações:

• Use funções de política simples: funções de política com menos expressões geralmente têm melhor desempenho do que expressões mais complexas. Evite usar tabelas de mapeamento e subconsultas de expressão em favor de funções CASE simples.
• Limite o número de máscaras de coluna e funções de mascaramento: várias máscaras de coluna exclusivas em tabelas grandes podem prejudicar o desempenho das consultas. Cada máscara distinta requer avaliação durante as consultas, aumentando a sobrecarga de processamento. Aplique máscaras apenas às colunas que contenham dados verdadeiramente sensíveis e reutilize as funções de mascaramento sempre que possível.
• Reduza o número de argumentos de função: o Databricks não pode otimizar referências de coluna para a tabela de origem resultantes de argumentos de função de política, mesmo que essas colunas não sejam usadas na consulta. Use funções de política com menos argumentos, pois as consultas dessas tabelas terão melhor desempenho.
• Evite adicionar filtros de linha com muitas conjunções AND: Como apenas um filtro de linha distinto pode ser resolvido em tempo de execução para um determinado usuário e tabela, uma abordagem comum é combinar várias funções de política desejadas com AND. No entanto, a cada conjunção adicional, aumentam as chances de que a(s) conjunção(ões) incluam componentes mencionados em outras partes desta tabela que possam afetar o desempenho (como tabelas de mapeamento). Use menos palavras conjuntas para melhorar o desempenho.
• Use expressões determinísticas que não podem gerar erros em políticas de tabela e consultas dessas tabelas: algumas expressões podem gerar erros se as entradas fornecidas não forem válidas, como a divisão ANSI. Nesses casos, o compilador SQL não deve empurrar operações com essas expressões (como filtros) muito para baixo no plano de consulta para evitar a possibilidade de erros como “divisão por zero”, que revelam informações sobre valores antes de filtrar e/ou mascarar operações. Use expressões determinísticas que nunca geram erros, como try_divide.
• Prefira UDFs SQL a UDFs Python : UDFs Python geralmente têm menos desempenho que SQL e oferecem menos oportunidades de otimização. Se você precisar usar Python, marque explicitamente UDFs como DETERMINISTIC quando elas não envolverem lógica ou dependências não determinísticas.
• Execute consultas de teste em sua tabela para avaliar o desempenho: construa consultas realistas que representem a carga de trabalho que você espera para sua tabela com filtros de linha ou máscaras de coluna e meça o desempenho. Faça pequenas modificações nas funções de política e observe seus efeitos até atingir um bom equilíbrio entre desempenho e expressividade da lógica de filtragem e mascaramento.

Para mais práticas recomendadas e exemplos de UDFs, consulte UDFs para práticas recomendadas de políticas ABAC.

comportamento de incompatibilidade de tipo de dados

Ao criar um filtro de linha ou uma máscara de coluna, o tipo de dados de cada coluna da tabela passada para a função deve corresponder ao tipo de parâmetro correspondente na UDF (função definida pelo usuário). Se houver uma incompatibilidade de tipos, como uma coluna STRING passada para um parâmetro INT , o Databricks converte implicitamente o valor da coluna para o tipo do parâmetro, o que pode causar comportamento inesperado quando a coluna contém valores que não podem ser convertidos.

Com o modo ANSI desativado (spark.sql.ansi.enabled = false), os valores não convertíveis são convertidos silenciosamente para NULL, nenhum erro é gerado e a UDF recebe NULL em vez do valor real da coluna. Isso pode produzir resultados incorretos, como um filtro de linha que retorna todas as linhas em vez de filtrá-las, ou uma máscara de coluna que mascara os valores errados. A Databricks recomenda ativar o modo ANSI (spark.sql.ansi.enabled = true), que gera um erro quando uma conversão falha, tornando o problema imediatamente visível, em vez de retornar silenciosamente NULL.

Exemplo: Filtro de linha com incompatibilidade de tipo

Considere uma tabela com uma coluna STRING e um filtro de linha cujo parâmetro foi acidentalmente declarado como INT em vez de STRING:

SQL

SET spark.sql.ansi.enabled = false;

CREATE TABLE employees (
  id INT,
  salary INT,
  department STRING
);

INSERT INTO employees VALUES
  (91, 200000, null),
  (1, 200000, 'exec'),
  (2, 50000, 'engineering'),
  (3, 150000, 'exec');

-- Bug: parameter type is INT, but the column is STRING
CREATE FUNCTION salary_filter(dept INT) RETURNS BOOLEAN
RETURN dept IS NULL;

ALTER TABLE employees SET ROW FILTER salary_filter ON (department);

Quando consultados, os valores department 'exec' e 'engineering' não podem ser convertidos para INT, então eles são convertidos silenciosamente para NULL. Como o filtro retorna true quando a entrada é NULL, todas as linhas são retornadas em vez de apenas as linhas onde department é na verdade NULL:

SQL

SELECT * FROM employees;

| ID | Salário | Departamento | | -- | ------ | ----------- | | 91 | 200000 | nulo | | 1 | 200000 | exec | | 2 | 50000 | engenharia | | 3 | 150000 | exec |

A definição correta da UDF usa STRING como tipo de parâmetro para corresponder à coluna:

SQL

CREATE FUNCTION salary_filter(dept STRING) RETURNS BOOLEAN
RETURN dept IS NULL;

Com essa correção, a consulta retorna apenas a linha onde department é NULL.

Limitações

• As versões Databricks Runtime abaixo de 12.2 LTS não oferecem suporte a filtros de linha ou máscaras de coluna. Esses tempos de execução falham com segurança, o que significa que se você tentar acessar tabelas a partir desses tempos de execução, nenhum dado será retornado.
• Você não pode aplicar máscaras de segurança ou de coluna no nível da linha a uma exibição.
• Não é possível usar o catálogo REST do Iceberg ou as APIs REST do Unity para acessar tabelas com filtros de linha ou máscaras de coluna.
• As APIs do Delta Lake não são suportadas.
• Os provedores Delta Sharing não podem compartilhar tabelas com segurança em nível de linha ou máscaras de coluna. No entanto, os destinatários Delta Sharing podem aplicar filtros de linha e máscaras de coluna somente a tabelas compartilhadas e tabelas externas, não a tabelas de transmissão ou visualizações materializadas.
• Não há suporte para o acesso baseado em caminho a arquivos em tabelas com políticas.
• MERGE instruções não oferecem suporte a tabelas com políticas de filtro de linha ou máscara de coluna que contenham aninhamento, agregações, janelas, limites ou funções não determinísticas.
• As versões Databricks Runtime abaixo de 17.2 não oferecem suporte DELETE, UPDATE e MERGE em tabelas particionadas com políticas de filtro de linha ou máscara de coluna definidas na coluna de partição.
• Não há suporte para políticas de filtro de linha nem máscara de coluna com dependências circulares em relação às políticas originais.
• Os filtros de linha e as máscaras de coluna não podem fazer referência a tabelas que também tenham filtros de linha ou máscaras de coluna ativos. Em configurações ABAC, você pode contornar isso excluindo o proprietário da função de política da política da tabela referenciada.
• Viagem do tempo não funciona com segurança em nível de linha ou máscaras de coluna. Em configurações ABAC, usuários explicitamente excluídos de uma política ainda podem executar consultas de viagem do tempo nos dados subjacentes.
• Clones profundos e superficiais não são suportados em tabelas que possuem segurança em nível de linha ou máscaras de coluna. Em configurações ABAC, usuários explicitamente excluídos de uma política ainda podem executar operações de clonagem nos dados subjacentes.
• Não é possível criar um índice de pesquisa vetorial a partir de uma tabela que tenha filtros de linha ou máscaras de coluna aplicados.

Limitação do modo de acesso dedicado

Não é possível acessar uma tabela com filtros de linha ou máscaras de coluna a partir de um recurso compute acesso dedicado no Databricks Runtime 15.3 ou anterior. Você pode usar o modo de acesso dedicado no Databricks Runtime 15.4 LTS ou superior se o seu workspace estiver habilitado para compute serverless . No entanto, apenas operações de leitura são suportadas no Databricks Runtime 15.4 até 16.2. As operações de escrita (incluindo INSERT, UPDATE e DELETE) requerem Databricks Runtime 16.3 ou superior e devem usar padrões suportados, como MERGE INTO.

Ao compute tabelas com filtros de linha ou máscaras de coluna a partir do modo de acesso dedicado, Databricks utiliza compute serverless para impor controles de acesso refinados (FGAC). Consequentemente, todas as limitações e considerações da FGAC se aplicam. Consulte Controle de acesso granular em computededicada.

O FGAC utiliza o Cloud Fetch para gravar conjuntos de resultados temporários no armazenamento interno workspace . Se você tiver o versionamento de buckets S3 ativado, isso pode levar a um crescimento exponencial do armazenamento. Consulte as considerações sobre versionamento de buckets S3 para obter recomendações de configuração.