Tabela sensível ao filtro uso de dados filtros de linha e máscaras de coluna

Prévia

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 Unity Catalog.

O que são filtros de linha?

Os filtros de linha permitem que o senhor aplique um filtro a uma tabela para que as consultas retornem apenas as linhas que atendam aos critérios do filtro. O senhor implementa um filtro de linha como uma função definida pelo usuário (UDF) SQL. As UDFs do Python e do Scala também são compatíveis, mas somente quando são agrupadas em UDFs do SQL.

O que são máscaras de coluna?

As máscaras de coluna permitem que o senhor aplique uma função de mascaramento a uma coluna da 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. Na maioria dos casos de uso, as máscaras de coluna determinam se o valor original da coluna deve ser retornado ou redigido com base na identidade do usuário que o invoca. As máscaras de coluna são expressões escritas como UDFs SQL ou como UDFs Python ou Scala que são agrupadas em UDFs SQL.

Cada coluna da tabela pode ter apenas uma função de mascaramento aplicada a ela. A função de mascaramento recebe o valor não mascarado 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 receber colunas adicionais como parâmetros de entrada e usá-las em sua lógica de mascaramento.

Qual é a diferença entre esses filtros e a exibição dinâmica?

A exibição dinâmica, os filtros de linha e as máscaras de coluna permitem que o senhor aplique uma lógica complexa às tabelas e processe suas decisões de filtragem no tempo de execução da consulta.

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

Por outro lado, associar um filtro de linha ou uma 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 se referir diretamente à tabela de destino usando seu nome original.

Use a visualização dinâmica se precisar aplicar a lógica de transformações, como filtros e máscaras, a tabelas somente de leitura e se for aceitável que os usuários se refiram à visualização dinâmica usando nomes diferentes. Se quiser filtrar os dados ao compartilhá-los usando Delta Sharing, o senhor deve usar a visualização dinâmica. Use filtros de linha e máscaras de coluna se quiser filtrar ou compute 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 às tabelas, o senhor deve ter:

Um workspace que está habilitado para Unity Catalog.
Uma função que está registrada no Unity Catalog. Pode ser uma UDF SQL ou uma UDF Python ou Scala registrada no Unity Catalog e envolvida em uma UDF SQL. 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.

O senhor 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, o senhor deve ter o privilégio EXECUTE 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, o senhor também deve ter o privilégio CREATE TABLE no esquema.
Para adicionar filtros ou máscaras alterando uma tabela existente, o senhor também deve ser o proprietário da tabela ou ter o privilégio MODIFY na tabela.

Para acessar uma tabela que tenha filtros de linha ou máscaras de coluna, o recurso compute deve atender a esses requisitos:

Um modo de acesso compartilhado cluster em Databricks Runtime 12.2 LTS ou acima, ou um SQL warehouse.

Aplicar um filtro de linha

Para criar um filtro de linha, o senhor escreve uma função (UDF) para definir a política de filtro e, em seguida, aplica-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 em que cada parâmetro de entrada se vincula a uma coluna da tabela correspondente.

O senhor pode aplicar um filtro de linha usando o Catalog Explorer ou SQL comando. As instruções do Catalog Explorer pressupõem que o senhor já tenha criado uma função e que ela esteja registrada no Unity Catalog. As instruções SQL incluem exemplos de como criar uma função de filtro de linha e aplicá-la a uma tabela.

Em seu site Databricks workspace, clique em Catalog.
Navegue ou pesquise a tabela que o senhor deseja filtrar.
Na Visão geral tab, clique em Row filter (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, view a definição de função e selecione as colunas da tabela que correspondem às colunas incluídas na instrução de função.
Clique em Adicionar.

Para remover o filtro da tabela, clique em fx Row filter e clique em Remove.

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

Crie o filtro de linha:

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

Aplicar 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 adicionais de sintaxe:

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>;
```
Observação

O senhor deve executar o comando ALTER TABLE ... DROP ROW FILTER antes de abandonar a função. Se o senhor não fizer isso, a tabela ficará em um estado inacessível.

Se a tabela se tornar inacessível dessa forma, altere a tabela e elimine 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 sales, os membros do grupo admin podem acessar todos os registros da tabela. Se a função for chamada por um não administrador, a condição RETURN_IF falha e a expressão region='US' é avaliada, filtrando a tabela para mostrar apenas os registros na região US.

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

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

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

Desativar o filtro de linha. As futuras consultas do usuário na tabela sales retornarão 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 instrução CREATE TABLE. As consultas futuras da tabela sales retornam, cada uma, 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, em seguida, aplique-a a uma coluna da tabela.

O senhor pode aplicar uma máscara de coluna usando o Catalog Explorer ou SQL comando. As instruções do Catalog Explorer pressupõem que o senhor já tenha criado uma função e que ela esteja registrada no Unity Catalog. As instruções SQL incluem exemplos de como criar uma função de máscara de coluna e aplicá-la a uma coluna de tabela.

Em seu site Databricks workspace, clique em Catalog.
Navegue ou pesquise a tabela.
Na Visão geral tab, localize a linha à qual deseja aplicar a máscara de coluna e clique no ícone de edição Mask.
Na caixa de diálogo Add column mask (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, view a definição da função. Se a função incluir outros parâmetros além da coluna que está sendo mascarada, selecione as colunas da tabela para as quais deseja converter esses parâmetros adicionais da função.
Clique em Adicionar.

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

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 máscara usando ALTER TABLE. O senhor também pode aplicar uma função ao criar uma tabela usando CREATE TABLE.

O senhor usa SET MASK para aplicar a função de mascaramento. Na cláusula MASK, o senhor pode usar qualquer uma das funções de tempo de execução da Databricks integrada ou chamar outras funções definidas pelo usuário. Os casos de uso comuns incluem a inspeção da identidade do usuário que invoca e executa a função usando current_user( ) ou a obtenção dos grupos dos quais ele é membro usando is_account_group_member( ). Para obter detalhes, consulte Cláusula de máscara de coluna e funções integradas.

Criar uma máscara de coluna:

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

Aplicar 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 adicionais de sintaxe:

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

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

Modificar uma máscara de coluna: O senhor pode usar DROP na função existente ou 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>;
```
Observação

O senhor deve executar o comando ALTER TABLE antes de descartar a função ou a tabela ficará em um estado inacessível.

Se a tabela se tornar inacessível dessa forma, altere a tabela e elimine 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áscaras de coluna

Neste exemplo, o senhor cria uma função definida pelo usuário que mascara a coluna ssn para que somente os usuários membros do grupo HumanResourceDept possam view 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. O senhor 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 ssn mascarados quando o usuário que faz a consulta não é membro do grupo HumanResourceDept:

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

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

ALTER TABLE users ALTER COLUMN ssn DROP MASK;

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

Para obter segurança no nível da 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ção direta.

Essa metodologia se mostra benéfica ao abordar muitos casos de uso com requisitos personalizados. Os exemplos incluem:

Impor restrições com base no usuário de login e, ao mesmo tempo, acomodar regras diferentes para grupos de usuários específicos.
Criar hierarquias complexas, como estruturas organizacionais, que exigem diversos conjuntos de regras.
Replicação de modelos de segurança complexos de sistemas de origem externa.

Ao adotar tabelas de mapeamento dessa forma, o senhor pode lidar efetivamente com esses cenários desafiadores e garantir implementações robustas de segurança no nível da linha e da 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;

Criar 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');

Criar um novo filtro:

Observação

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

Neste exemplo, a função verifica se o usuário atual está na tabela valid_users. 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. O senhor também pode adicionar o filtro posteriormente usando uma instrução ALTER TABLE. Ao aplicar a uma tabela inteira, use a sintaxe ON (). 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 tabela valid_users.

SELECT * FROM data_table;

Crie uma tabela de mapeamento que compreenda a conta que sempre deve ter acesso a view todas as linhas da tabela, independentemente dos valores da coluna:

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

Agora, crie um UDF SQL que retorne true se os valores de todas as colunas da linha forem menores que cinco ou se o usuário que o invocou for 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));

Por fim, 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

Databricks SQL e Databricks Notebook para SQL cargas de trabalho são suportadas.
O comando DML por usuários com privilégios MODIFY é suportado. Os filtros e as máscaras são aplicados aos dados lidos pelos comandos UPDATE e DELETE e não são aplicados aos dados gravados (inclusive INSERT).
Formatos de dados suportados:
- Delta e Parquet para gerenciar e tabelas externas.
- Vários outros formatos de dados para tabelas estrangeiras registradas em Unity Catalog usando lakehouse Federation.
As UDFs SQL, Python e Scala são suportadas como funções de filtro de linha ou máscara de coluna, desde que estejam registradas no Unity Catalog. As UDFs de Python e Scala devem ser agrupadas em uma UDF de SQL.
em tabelas com máscaras de coluna ou filtros de linha são suportados.
Os feeds de dados de alteração do Delta Lake são compatíveis, desde que o esquema seja compatível com os filtros de linha e as máscaras de coluna que se aplicam à tabela de destino.
MERGE são suportadas quando as tabelas de origem, as 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.

Limitações

As versões do Databricks Runtime abaixo da 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 o senhor tentar acessar tabelas de versões não suportadas desses tempos de execução, nenhum dado será retornado.
A visualização materializada e as tabelas de transmissão declaradas em Delta Live Tables não são compatíveis com filtros de linha ou máscaras de coluna.
O Delta Sharing não funciona com segurança em nível de linha ou máscaras de coluna.
viagem do 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 o 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 em relação às políticas originais.
Não há suporte para clones profundos e rasos.
MERGE não são compatíveis com tabelas com políticas de filtro de linha que contenham aninhamento, agregações, janelas, limites ou funções não determinísticas.
Não há suporte para as APIs do Delta Lake.
SHOW CREATE TABLE nas tabelas de exibição materializada e transmissão não exibe informações de filtro de linha e máscara de coluna.

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

Não adicione filtros de linha ou máscaras de coluna a nenhuma tabela que esteja acessando de um cluster de usuário único. Isso é comumente feito no contexto de fluxo de trabalho (Job). Durante a visualização pública, não será possível acessar tabelas de um cluster de usuário único se um filtro ou máscara tiver sido aplicado.