Filtrar dados confidenciais da tabela usando filtros de linha e máscaras de coluna

Artigo
06/28/2024

Importante

Esta funcionalidade está em Pré-visualização Pública.

Este artigo fornece orientações e exemplos para o uso de filtros de linha, máscaras de coluna e tabelas de mapeamento para filtrar dados confidenciais em suas tabelas. Esses recursos exigem o Unity Catalog.

O que são filtros de linha?

Os filtros de linha permitem aplicar um filtro a uma tabela para que as consultas retornem apenas linhas que atendam aos critérios de filtro. Você implementa um filtro de linha como uma função SQL definida pelo usuário (UDF). UDFs Python e Scala também são suportados, mas somente quando são encapsulados em UDFs SQL.

O que são máscaras de coluna?

As máscaras de coluna permitem aplicar uma função de mascaramento a uma coluna de tabela. A função de mascaramento é avaliada no tempo de execução da consulta, substituindo cada referência da coluna de destino pelos resultados da função de mascaramento. Para a maioria dos casos de uso, as máscaras de coluna determinam se o valor da coluna original deve ser retornado ou editado com base na identidade do usuário que invoca. Máscaras de coluna são expressões escritas como UDFs SQL ou como UDFs Python ou Scala que são encapsuladas em UDFs SQL.

Cada coluna da tabela pode ter apenas uma função de mascaramento aplicada a ela. A função de mascaramento usa o valor desmascarado da coluna como entrada e retorna o valor mascarado como resultado. O valor de retorno da função de mascaramento deve ser do mesmo tipo que a coluna que está sendo mascarada. A função de mascaramento também pode tomar colunas adicionais como parâmetros de entrada e usá-las em sua lógica de mascaramento.

Qual é a diferença entre estes filtros e as vistas dinâmicas?

Modos de exibição dinâmicos, filtros de linha e máscaras de coluna permitem aplicar lógica complexa a tabelas e processar suas decisões de filtragem no tempo de execução da consulta.

Uma exibição dinâmica é uma exibição abstrata e somente leitura de uma ou mais tabelas de origem. O usuário pode acessar uma exibição dinâmica sem ter acesso às tabelas de origem diretamente. A criação de um modo de exibição dinâmico define um novo nome de tabela que não deve corresponder ao nome de nenhuma tabela de origem ou outras tabelas e exibições presentes no mesmo esquema.

Por outro lado, associar um filtro de linha ou máscara de coluna a uma tabela de destino aplica a lógica correspondente diretamente à própria tabela sem introduzir novos nomes de tabela. As consultas subsequentes podem continuar a referir-se diretamente à tabela de destino usando seu nome original.

Use modos de exibição dinâmicos se precisar aplicar lógica de transformação, como filtros e máscaras, a tabelas somente leitura e se for aceitável que os usuários se refiram às exibições dinâmicas usando nomes diferentes. Se você quiser filtrar dados ao compartilhá-los usando o Compartilhamento Delta, deverá usar exibições dinâmicas. Use filtros de linha e máscaras de coluna se quiser filtrar ou calcular expressões sobre dados específicos, mas ainda assim fornecer aos usuários acesso às tabelas usando seus nomes originais.

Antes de começar

Para adicionar filtros de linha e máscaras de coluna a tabelas, você deve ter:

Um espaço de trabalho habilitado para o Unity Catalog.
Uma função registrada no Unity Catalog. Pode ser um SQL UDF ou um Python ou Scala UDF registrado no Unity Catalog e encapsulado em um SQL UDF. Para obter detalhes, consulte O que são funções definidas pelo usuário (UDFs)?, Cláusula de máscara de coluna e Cláusula ROW FILTER.

Você também deve atender aos seguintes requisitos:

Para atribuir uma função que adiciona filtros de linha ou máscaras de coluna a uma tabela, você deve ter o EXECUTE privilégio na função, USE SCHEMA no esquema e USE CATALOG no catálogo pai.
Para adicionar filtros ou máscaras ao criar uma nova tabela, você também deve ter o CREATE TABLE privilégio no esquema.
Para adicionar filtros ou máscaras alterando uma tabela existente, você também deve ser o proprietário da tabela ou ter o MODIFY privilégio na tabela.

Para acessar uma tabela que tenha filtros de linha ou máscaras de coluna, seu recurso de computação deve atender a estes requisitos:

Um cluster de modo de acesso compartilhado no Databricks Runtime 12.2 LTS ou superior, ou um armazém SQL.

Aplicar um filtro de linha

Para criar um filtro de linha, escreva uma função (UDF) para definir a política de filtro e, em seguida, aplique-a a uma tabela. Cada tabela pode ter apenas um filtro de linha. Um filtro de linha aceita zero ou mais parâmetros de entrada onde cada parâmetro de entrada se liga a uma coluna da tabela correspondente.

Você pode aplicar um filtro de linha usando o Catalog Explorer ou comandos SQL. As instruções do Catalog Explorer pressupõem que você já criou uma função e que ela está registrada no Unity Catalog. As instruções SQL incluem exemplos de criação de uma função de filtro de linha e aplicá-la a uma tabela.

Explorador de Catálogos

No seu espaço de trabalho do Azure Databricks, clique em Catálogo.
Procure ou procure a tabela que pretende filtrar.
Na guia Visão geral, clique em Filtro de linha: Adicionar filtro.
Na caixa de diálogo Adicionar filtro de linha, selecione o catálogo e o esquema que contêm a função de filtro e, em seguida, selecione a função.
Na caixa de diálogo expandida, exiba a definição da função e selecione as colunas da tabela que correspondem às colunas incluídas na instrução da função.
Clique em Adicionar.

Para remover o filtro da tabela, clique em fx Filtro de linha e clique em Remover.

SQL

Para criar um filtro de linha e, em seguida, adicioná-lo a uma tabela existente, use CREATE FUNCTION e aplique a função usando ALTER TABLE. Você também pode aplicar uma função ao criar uma tabela usando CREATE TABLEo .

Crie o filtro de linha:

CREATE FUNCTION <function_name> (<parameter_name> <parameter_type>, ...)
RETURN {filter clause whose output must be a boolean};

Aplique o filtro de linha a uma tabela usando um nome de coluna:

ALTER TABLE <table_name> SET ROW FILTER <function_name> ON (<column_name>, ...);

Exemplos de sintaxe adicionais:

Remover um filtro de linha de uma tabela:

ALTER TABLE <table_name> DROP ROW FILTER;

Modificar um filtro de linha:

Run a DROP FUNCTION statement to drop the existing function, or use CREATE OR REPLACE FUNCTION to replace it.

Excluir um filtro de linha:
```
ALTER TABLE <table_name> DROP ROW FILTER;
DROP FUNCTION <function_name>;
```
Nota

Você deve executar o ALTER TABLE ... DROP ROW FILTER comando antes de soltar a função. Se não o fizer, a tabela estará num estado inacessível.

Se a tabela se tornar inacessível dessa forma, altere a tabela e solte a referência de filtro de linha órfã usando ALTER TABLE <table_name> DROP ROW FILTER;.

Consulte também a cláusula ROW FILTER.

Exemplos de filtros de linha

Este exemplo cria uma função SQL definida pelo usuário que se aplica aos membros do grupo admin na região US.

Quando essa função de exemplo é aplicada à tabela, os sales admin membros do grupo podem acessar todos os registros na tabela. Se a função for chamada por um não-administrador, a RETURN_IF condição falhará e a region='US' expressão será avaliada, filtrando a tabela para mostrar apenas registros na US região.

CREATE FUNCTION us_filter(region STRING)
RETURN IF(IS_ACCOUNT_GROUP_MEMBER('admin'), true, region='US');

Aplique a função a uma tabela como um filtro de linha. As consultas subsequentes da sales tabela retornam um subconjunto de linhas.

CREATE TABLE sales (region STRING, id INT);
ALTER TABLE sales SET ROW FILTER us_filter ON (region);

Desative o filtro de linha. Consultas de usuários futuros da sales tabela retornam todas as linhas da tabela.

ALTER TABLE sales DROP ROW FILTER;

Crie uma tabela com a função aplicada como um filtro de linha como parte da CREATE TABLE instrução. Consultas futuras da sales tabela e cada uma retorna um subconjunto de linhas.

CREATE TABLE sales (region STRING, id INT)
WITH ROW FILTER us_filter ON (region);

Aplicar uma máscara de coluna

Para aplicar uma máscara de coluna, crie uma função (UDF) e aplique-a a uma coluna da tabela.

Você pode aplicar uma máscara de coluna usando o Catalog Explorer ou comandos SQL. As instruções do Catalog Explorer pressupõem que você já criou uma função e que ela está registrada no Unity Catalog. As instruções SQL incluem exemplos de criação de uma função de máscara de coluna e aplicá-la a uma coluna de tabela.

Explorador de Catálogos

No seu espaço de trabalho do Azure Databricks, clique em Catálogo.
Navegue ou pesquise a tabela.
Na guia Visão geral, localize a linha à qual deseja aplicar a máscara de coluna e clique no ícone de edição Máscara.
Na caixa de diálogo Adicionar máscara de coluna, selecione o catálogo e o esquema que contêm a função de filtro e, em seguida, selecione a função.
Na caixa de diálogo expandida, exiba a definição da função. Se a função incluir quaisquer parâmetros além da coluna que está sendo mascarada, selecione as colunas da tabela para as quais você deseja converter esses parâmetros de função adicionais.
Clique em Adicionar.

Para remover a máscara de coluna da tabela, clique em fx Máscara de coluna na linha da tabela e clique em Remover.

SQL

Para criar uma máscara de coluna e adicioná-la a uma coluna de tabela existente, use CREATE FUNCTION e aplique a função de mascaramento usando ALTER TABLE. Você também pode aplicar uma função ao criar uma tabela usando CREATE TABLEo .

Você usa SET MASK para aplicar a função de mascaramento. Dentro da MASK cláusula, você pode usar qualquer uma das funções de tempo de execução internas do Azure Databricks ou chamar outras funções definidas pelo usuário. Casos de uso comuns incluem inspecionar a identidade do usuário que invoca a função usando current_user( ) ou obtendo os grupos dos quais eles são membros usando is_account_group_member( ). Para obter detalhes, consulte Cláusula de máscara de coluna e Funções internas.

Crie uma máscara de coluna:

CREATE FUNCTION <function_name> (<parameter_name> <parameter_type>, ...)
RETURN {expression with the same type as the first parameter};

Aplique a máscara de coluna a uma coluna em uma tabela existente:

ALTER TABLE <table_name> ALTER COLUMN <col_name> SET MASK <mask_func_name> USING COLUMNS <additional_columns>;

Exemplos de sintaxe adicionais:

Remover uma máscara de coluna de uma coluna de uma tabela:

ALTER TABLE <table_name> ALTER COLUMN <column where mask is applied> DROP MASK;

Modificar uma máscara de coluna: a DROP função existente ou use CREATE OR REPLACE TABLE.
Excluir uma máscara de coluna:
```
ALTER TABLE <table_name> ALTER COLUMN <column where mask is applied> DROP MASK;
DROP FUNCTION <function_name>;
```
Nota

Você deve executar o ALTER TABLE comando antes de soltar a função ou a tabela estará em um estado inacessível.

Se a tabela se tornar inacessível dessa maneira, altere a tabela e solte a referência de referência de máscara órfã usando ALTER TABLE <table_name> ALTER COLUMN <column where mask is applied> DROP MASK;.

Exemplos de máscara de coluna

Neste exemplo, você cria uma função definida pelo usuário que mascara a ssn coluna para que apenas os usuários que são membros do HumanResourceDept grupo possam exibir valores nessa coluna.

CREATE FUNCTION ssn_mask(ssn STRING)
  RETURN CASE WHEN is_member('HumanResourceDept') THEN ssn ELSE '***-**-****' END;

Aplique a nova função a uma tabela como uma máscara de coluna. Você pode adicionar a máscara de coluna ao criar a tabela ou depois.

--Create the `users` table and apply the column mask in a single step:

CREATE TABLE users (
  name STRING,
  ssn STRING MASK ssn_mask);

--Create the `users` table and apply the column mask after:

CREATE TABLE users
  (name STRING, ssn STRING);

ALTER TABLE users ALTER COLUMN ssn SET MASK ssn_mask;

As consultas nessa tabela agora retornam valores de coluna mascarados ssn quando o usuário que consulta não é membro do HumanResourceDept grupo:

SELECT * FROM users;
  James  ***-**-****

Para desativar a máscara de coluna para que as consultas retornem os valores originais na ssn coluna:

ALTER TABLE users ALTER COLUMN ssn DROP MASK;

Usar tabelas de mapeamento para criar uma lista de controle de acesso

Para obter segurança em nível de linha, considere definir uma tabela de mapeamento (ou lista de controle de acesso). Cada tabela de mapeamento é uma tabela de mapeamento abrangente que codifica quais linhas de dados na tabela original são acessíveis a determinados usuários ou grupos. As tabelas de mapeamento são úteis porque oferecem uma integração simples com suas tabelas de fatos por meio de junções diretas.

Esta metodologia revela-se benéfica na abordagem de muitos casos de uso com requisitos personalizados. Exemplos incluem:

Impor restrições com base no usuário conectado enquanto acomoda regras diferentes para grupos de usuários específicos.
Criar hierarquias intrincadas, como estruturas organizacionais, exigindo diversos conjuntos de regras.
Replicação de modelos de segurança complexos a partir de sistemas de origem externos.

Ao adotar tabelas de mapeamento dessa forma, você pode lidar com eficiência com esses cenários desafiadores e garantir implementações de segurança robustas em nível de linha e coluna.

Exemplos de tabelas de mapeamento

Use uma tabela de mapeamento para verificar se o usuário atual está em uma lista:

USE CATALOG main;

Crie uma nova tabela de mapeamento:

DROP TABLE IF EXISTS valid_users;

CREATE TABLE valid_users(username string);
INSERT INTO valid_users
VALUES
  ('fred@databricks.com'),
  ('barney@databricks.com');

Crie um novo filtro:

Nota

Todos os filtros são executados com direitos de definer, exceto para funções que verificam o contexto do usuário (por exemplo, as CURRENT_USER funções e IS_MEMBER ) que são executadas como o invocador.

Neste exemplo, a função verifica se o usuário atual está na valid_users tabela. Se o usuário for encontrado, a função retornará true.

DROP FUNCTION IF EXISTS row_filter;

CREATE FUNCTION row_filter()
  RETURN EXISTS(
    SELECT 1 FROM valid_users v
    WHERE v.username = CURRENT_USER()
);

O exemplo abaixo aplica o filtro de linha durante a criação da tabela. Você também pode adicionar o filtro posteriormente usando uma ALTER TABLE instrução. Ao aplicar a uma tabela inteira, use a ON () sintaxe. Para uma linha específica, use ON (row);.

DROP TABLE IF EXISTS data_table;

CREATE TABLE data_table
  (x INT, y INT, z INT)
  WITH ROW FILTER row_filter ON ();

INSERT INTO data_table VALUES
  (1, 2, 3),
  (4, 5, 6),
  (7, 8, 9);

Selecione os dados da tabela. Isso só deve retornar dados se o usuário estiver na valid_users tabela.

SELECT * FROM data_table;

Crie uma tabela de mapeamento composta por contas que devem sempre ter acesso para exibir todas as linhas da tabela, independentemente dos valores das colunas:

CREATE TABLE valid_accounts(account string);
INSERT INTO valid_accounts
VALUES
  ('admin'),
  ('cstaff');

Agora crie um SQL UDF que retorne true se os valores de todas as colunas na linha forem menores que cinco ou se o usuário que invoca for um membro da tabela de mapeamento acima.

CREATE FUNCTION row_filter_small_values (x INT, y INT, z INT)
  RETURN (x < 5 AND y < 5 AND z < 5)
  OR EXISTS(
    SELECT 1 FROM valid_accounts v
    WHERE IS_ACCOUNT_GROUP_MEMBER(v.account));

Finalmente, aplique o SQL UDF à tabela como um filtro de linha:

ALTER TABLE data_table SET ROW FILTER row_filter_small_values ON (x, y, z);

Recursos e formatos suportados

Há suporte para notebooks Databricks SQL e Databricks para cargas de trabalho SQL.
Há suporte para comandos DML de usuários com MODIFY privilégios. Filtros e máscaras são aplicados aos dados lidos por UPDATE e DELETE instruções e não são aplicados aos dados que são gravados (incluindo INSERT).
Formatos de dados suportados:
- Delta e Parquet para mesas gerenciadas e externas.
- Vários outros formatos de dados para tabelas estrangeiras registradas no Unity Catalog usando a Lakehouse Federation.
UDFs SQL, Python e Scala são suportados como funções de filtro de linha ou máscara de coluna, desde que estejam registrados no Unity Catalog. As UDFs Python e Scala devem ser encapsuladas em uma UDF SQL.
Há suporte para exibições em tabelas com máscaras de coluna ou filtros de linha.
Os feeds de dados de alteração Delta Lake são suportados, desde que o esquema seja compatível com os filtros de linha e máscaras de coluna que se aplicam à tabela de destino.
MERGE As instruções são suportadas quando tabelas de origem, tabelas de destino ou ambas usam filtros de linha e máscaras de coluna. Isso inclui tabelas com funções de filtro de linha que contêm subconsultas simples, mas há limitações, listadas na seção a seguir.
Exibições materializadas do Databricks SQL e tabelas de streaming do Databricks SQL suportam filtros de linha e máscaras de coluna (Visualização pública):
- Você pode adicionar filtros de linha e máscaras de coluna a uma exibição Databricks SQL Materialized ou tabela de streaming.
- Você pode definir exibições do Databricks SQL Materialized ou tabelas de streaming em tabelas que incluem filtros de linha e máscaras de coluna.

Limitações

As versões do Databricks Runtime abaixo de 12.2 LTS não suportam 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 de versões sem suporte desses tempos de execução, nenhum dado será retornado.
As visualizações materializadas e as tabelas de streaming declaradas em Delta Live Tables não suportam filtros de linha ou máscaras de coluna.
O Compartilhamento Delta não funciona com segurança em nível de linha ou máscaras de coluna.
A viagem no tempo não funciona com segurança em nível de linha ou máscaras de coluna.
A amostragem de tabela não funciona com segurança em nível de linha ou máscaras de coluna.
Não há suporte para acesso baseado em caminho a arquivos em tabelas com políticas.
Não há suporte para políticas de filtro de linha ou máscara de coluna com dependências circulares de volta às políticas originais.
Não há suporte para clones profundos e superficiais.
MERGE As instruções não oferecem suporte a tabelas com políticas de filtro de linha que contenham aninhamento, agregações, janelas, limites ou funções não determinísticas.
As APIs Delta Lake não são suportadas.
SHOW CREATE TABLE em exibições materializadas e tabelas de streaming não exibe informações de filtro de linha e máscara de coluna.

Limitação de computação de usuário único

Não adicione filtros de linha ou máscaras de coluna a qualquer tabela que esteja a aceder a partir de um cluster de utilizador único. Isso geralmente é feito no contexto de fluxos de trabalho (trabalhos). Durante a visualização pública, você não poderá acessar tabelas de um único cluster de usuário se um filtro ou máscara tiver sido aplicado.

Partilhar via

Filtrar dados confidenciais da tabela usando filtros de linha e máscaras de coluna

O que são filtros de linha?

O que são máscaras de coluna?

Qual é a diferença entre estes filtros e as vistas dinâmicas?

Antes de começar

Aplicar um filtro de linha

Explorador de Catálogos

SQL

Exemplos de filtros de linha

Aplicar uma máscara de coluna

Explorador de Catálogos

SQL

Exemplos de máscara de coluna

Usar tabelas de mapeamento para criar uma lista de controle de acesso

Exemplos de tabelas de mapeamento

Recursos e formatos suportados

Limitações

Limitação de computação de usuário único

Comentários

Comentários

Recursos adicionais