Filtros de linha e máscaras de coluna

Filtros de linha e máscaras de coluna são controles de acesso do Unity Catalog que restringem as linhas e os valores das colunas que um usuário pode ver no momento da consulta. Esta página descreve a forma em nível de tabela desses controles, que são configurados diretamente em tabelas individuais usando SQL e gerenciados pelo proprietário da tabela. Para filtragem de linhas consistente e mascaramento de colunas em várias tabelas, as políticas ABAC são a abordagem recomendada. Anexam-se no nível do catálogo ou esquema e aplicam-se automaticamente com base em tags governadas.

dica

A Databricks recomenda políticas ABAC quando você precisa de filtragem de linhas e mascaramento de colunas consistentes em várias tabelas. As políticas ABAC são anexadas no nível do catálogo ou do esquema e aplicadas automaticamente com base em tags regulamentadas, em vez de exigir configuração por tabela.

O que são filtros de linha?

Filtros de linha restringem quais linhas um usuário pode ver em uma tabela. O filtro é uma função SQL definida pelo usuário (UDF) que avalia cada linha no momento da consulta. As linhas para as quais a função retorna FALSE são excluídas dos resultados da query. Isso é comumente usado para segurança em nível de linha. Por exemplo, você pode restringir usuários a registros de uma região específica, departamento ou account.

Filtros de linha no nível da tabela são vinculados a uma única tabela usando ALTER TABLE ... SET ROW FILTER e gerenciados pelo proprietário da tabela. Para uma filtragem de linha consistente em várias tabelas, use Políticas ABAC em vez disso.

O que são máscaras de coluna?

As máscaras de coluna controlam os valores que um usuário vê para colunas específicas. A máscara é uma UDF SQL que recebe o valor da coluna como entrada e retorna o valor original ou uma versão mascarada. O tipo de retorno deve corresponder ou ser conversível para o tipo de dados da coluna. Cada coluna pode ter uma máscara. Máscaras de coluna podem usar outras colunas como entradas para variar o comportamento com base em múltiplos atributos.

Máscaras de coluna em nível de tabela são vinculadas a uma coluna usando ALTER TABLE ... ALTER COLUMN ... SET MASK e gerenciadas pelo proprietário da tabela. Aplicam-se somente àquela coluna naquela tabela. Para mascaramento de coluna consistente em várias tabelas, use políticas ABAC em vez disso.

Quando usar políticas ABAC ou views dinâmicas em vez disso

O Unity Catalog oferece dois mecanismos relacionados para controle de acesso em nível de linha e coluna:

• As políticas ABAC são aplicadas no nível do catálogo ou do esquema e se aplicam automaticamente a tabelas e colunas com base em tags governadas. Use o ABAC quando precisar de regras consistentes em várias tabelas, separação de funções entre autores de políticas e gestões de dados, ou cobertura automática de novas tabelas à medida que são marcadas. Para comparar lado a lado com filtros de linha e máscaras de coluna em nível de tabela, consulte Quando usar ABAC vs. filtros de linha em nível de tabela e máscaras de coluna.
• Visualizações dinâmicas envolvem uma ou mais tabelas base em uma visualização SQL que filtra linhas, mascara colunas ou remodela dados, normalmente controladas por funções de associação a grupos is_account_group_member() como. Use exibições dinâmicas quando quiser expor uma versão selecionada, transformada ou combinada dos seus dados a usuários que não têm acesso às tabelas subjacentes. Exemplos de casos de uso incluem o compartilhamento de um subconjunto redigido de uma tabela de fatos com um grupo de analistas, ou a combinação de colunas de várias tabelas em uma única camada segura.

Abordagem	Aplica-se a	gerenciar utilizando	Ideal para
Filtros de linha e máscaras de coluna em nível de tabela	Tabelas e colunas individuais	ALTER TABLE pelo proprietário da tabela ou por um usuário com MANAGE	Lógica específica da tabela
Políticas ABAC	Tabelas e colunas correspondentes a condições de tag	CREATE POLICY anexado a um catálogo, esquema ou tabela por seu proprietário ou um usuário com MANAGE	Regras centralizadas aplicadas automaticamente em muitas tabelas
Visão dinâmica	Uma view criada a partir de uma ou mais tabelas base	Lógica SQL na definição da view	Compartilhamento de uma versão curada ou transformada dos dados

Para uma comparação mais detalhada com visualizações dinâmicas e políticas ABAC, consulte Quando usar ABAC vs. filtros de linha no nível da tabela e máscaras de coluna.

Como aplicar filtros de linha e máscaras de coluna

Os filtros de linha e as máscaras de coluna podem ser aplicados de uma das seguintes maneiras:

• Uso de políticas ABAC (recomendado): Aplique filtros e máscaras de forma centralizada utilizando tags controladas e políticas reutilizáveis. ABAC escala em catálogos e esquemas e pode ser definido por administradores de nível superior, de modo que os proprietários de tabelas não possam substituí-los nem removê-los. A lógica das políticas também é avaliada mais eficientemente do que as UDFs específicas de tabela. Consulte Controle de acesso baseado em atributos no Unity Catalog.
• Atribuição Manual por Tabela : Aplique filtros e máscaras atribuindo UDFs diretamente a tabelas e colunas individuais. Isso permite um controle refinado e específico da tabela, mas é mais difícil de escala e manter. 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 visualizar os valores das tabelas-base antes da aplicação de filtragem ou mascaramento. Quando o mecanismo de consulta precisa escolher entre a otimização e a proteção contra o vazamento de informações de valores filtrados ou mascarados, ele sempre faz a escolha segura, o que pode afetar o desempenho da consulta. Para minimizar esse impacto:

• Utilize UDFs simples. Funções com menos expressões têm melhor desempenho. Prefira expressões CASE simples em vez de tabelas de mapeamento ou subconsultas de expressão.
• Limite o número de máscaras de coluna distintas em tabelas grandes. Cada máscara distinta é avaliada durante as consultas. Aplique máscaras apenas a colunas verdadeiramente sensíveis e reutilize as funções de mascaramento sempre que possível.
• Reduza o número de argumentos de UDF. O Databricks não consegue otimizar referências a colunas resultantes de argumentos de UDF, mesmo que essas colunas não sejam usadas na consulta. Utilize UDFs com menos argumentos sempre que possível.
• Evite filtros de linha com muitos AND conjuntos. Apenas um filtro de linha distinto pode ser resolvido em tempo de execução para um determinado usuário e tabela, portanto, um padrão comum é combinar a lógica com AND. Quanto mais conjunções você adicionar, maior a probabilidade de o filtro combinado incluir um dos padrões alertados acima. Use menos conjuntos quando possível.
• Use expressões determinísticas que não podem gerar erros. Expressões que podem gerar erros (como divisão ANSI) impedem o compilador SQL de empurrar operações para baixo no plano de consulta, porque erros como "divisão por zero" poderiam revelar informações sobre valores antes da filtragem ou mascaramento. Use expressões determinísticas que nunca gerem erros, como try_divide.
• Prefira SQL a UDFs Python. UDFs Python apresentam menos desempenho que o SQL e oferecem menos oportunidades de otimização. Se for preciso usar Python, marque a UDF como DETERMINISTIC quando aplicável.

Para obter orientação completa sobre o desempenho de UDFs (incluindo predicate pushdown e detalhes de otimização em nível de mecanismo), consulte Considerações de Desempenho para Políticas ABAC. A maior parte da orientação lá se aplica igualmente a filtros de linha aplicados manualmente e máscaras de coluna. Para exemplos de UDFs, consulte Padrões comuns para filtragem de linha e mascaramento de coluna.

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 | 200.000 | nulo | | 1 | 200.000 | exec | | 2 | 50.000 | engenharia | | 3 | 150.000 | 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 filtros de linha ou máscaras de coluna em nível de tabela. Tabelas com filtros de linha ou máscaras de coluna baseados em ABAC podem ser compartilhadas se o proprietário do compartilhamento estiver isento da política. Consulte as tabelasDelta Sharing com políticas ABAC ou visualize-as de forma que façam referência a elas.
• Destinatários do Delta Sharing podem aplicar filtros de linha e máscaras de coluna apenas a tabelas compartilhadas e tabelas externas, não a tabelas de transmissão ou views 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 do AI Search de uma tabela com filtros de linha ou máscaras de coluna aplicados.
• Não é possível aplicar máscaras de coluna a colunas que sejam referenciadas por colunas geradas. Consulte Colunas geradas e máscaras de coluna.

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.