Aplique manualmente filtros de linha e máscaras de coluna

Esta página fornece orientação e exemplos de 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.

Se você estiver procurando por uma abordagem centralizada baseada em tagpara filtragem e mascaramento, consulte Controle de acesso baseado em atributos (ABAC)Unity Catalog. O ABAC permite que você gerencie políticas usando tags governadas e as aplique consistentemente em muitas tabelas.

Antes de começar

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

• Um espaço de trabalho preparado para o Unity Catalog.
• Um UDF SQL registrado no Unity Catalog. Para usar a lógica Python ou Scala, primeiro crie uma UDF Python ou Scala e, em seguida, crie uma UDF SQL que a chame. O SQL UDF é o que você aplica como filtro de linha ou máscara de coluna. Para um exemplo, veja Máscara de coluna com Python UDF. Para melhores práticas e limitações de UDFs, consulte Filtros de linha e máscaras de coluna.

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 privilégio EXECUTE na função, USE SCHEMA no esquema e USE CATALOG no catálogo principal.
• Se você estiver adicionando filtros ou máscaras ao criar uma nova tabela, deverá ter o privilégio CREATE TABLE no esquema.
• Se você estiver adicionando filtros ou máscaras a uma tabela existente , deverá ser o proprietário da tabela ou ter o privilégio MANAGE na tabela.

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

• SQL warehouse.
• Modo de acesso padrão (anteriormente modo de acesso compartilhado) no Databricks Runtime 12.2 LTS ou superior.
• Modo de acesso dedicado (anteriormente modo de acesso de usuário único) em Databricks Runtime 15.4 LTS ou superior.

Não é possível ler filtros de linha ou máscaras de coluna utilizando o comando dedicado “ compute ” no “ Databricks Runtime ” 15.3 ou versões anteriores.

Para aproveitar a filtragem de dados fornecida em Databricks Runtime 15.4 LTS e acima, é necessário também verificar se o seu workspace está habilitado para serverless compute, pois a funcionalidade de filtragem de dados que suporta filtros de linha e máscaras de coluna é executada em serverless compute. Poderá ser cobrado por um recurso serverless compute quando utilizar compute configurado como modo de acesso dedicado para ler tabelas que utilizam filtros de linha ou máscaras de coluna. As operações de gravação nessas tabelas são suportadas apenas no DBR 16.3 e superior, e devem utilizar padrões suportados, como MERGE INTO. Consulte Controle de acesso refinado em compute.

nota

Os filtros de linha e as máscaras de coluna são mantidos ao substituir uma tabela.

Se você executar REPLACE TABLE, qualquer filtro de linha existente será mantido, independentemente das alterações no esquema. As máscaras de coluna também serão mantidas se a nova tabela incluir colunas com os mesmos nomes das que tinham máscaras na tabela original. Em ambos os casos, as políticas são preservadas mesmo que não sejam explicitamente redefinidas. Isso evita a perda acidental das políticas de acesso aos dados.

No entanto, se uma política retida fizer referência a uma coluna que foi removida ou alterada, as consultas subsequentes poderão falhar. Para resolver isso, atualize ou descarte a política usando ALTER TABLE.

Aplicar um filtro de linha

Para criar um filtro de linha, você escreve uma função (UDF) para definir a política de filtro e, em seguida, aplica 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.

É possível aplicar um filtro de linha utilizando o Catalog Explorer ou o comando SQL. As instruções do Catalog Explorer pressupõem que você já criou uma função e a registrou no Unity Catalog. As instruções SQL incluem exemplos de criação de uma função de filtro de linha e sua aplicação a uma tabela.

nota

Se estiver utilizando um pipeline declarativ LakeFlow, é possível utilizar o pipeline declarativ LakeFlow Python API para criar tabelas de transmissão ou visualizações materializadas que utilizam filtros de linha e máscaras de coluna. Consulte Publicar tabelas com filtros de linha e máscaras de coluna.

Catalog Explorer

1. Em Databricks workspace, clique em Catalog .
2. Navegue ou pesquise a tabela que você deseja filtrar.
3. Na tela Visão geral ( tab), em Filtro de linha , clique em Adicionar filtro .
4. 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.
5. Na caixa de diálogo expandida, consulte a definição da função e selecione as colunas da tabela correspondentes às colunas incluídas na instrução da função.
6. Clique em Adicionar .

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

SQL

Para criar um filtro de linha e 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 TABLE.

1. Criar o filtro de linha:

   SQL

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

2. Aplicar o filtro de linha a uma tabela utilizando um nome de coluna:

   SQL

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

**Exemplos adicionais de sintaxe**:

• Aplique o filtro de linha a uma tabela usando um literal constante que corresponda a um parâmetro de função:

  SQL

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

• Remover um filtro de linha de uma tabela:

  SQL

  ALTER TABLE <table_name> DROP ROW FILTER;

• Modificar um filtro de linha:

  SQL

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

• Excluir um filtro de linha:

  SQL

  ALTER TABLE <table_name> DROP ROW FILTER;
  DROP FUNCTION <function_name>;

nota

É necessário executar o comando " ALTER TABLE ... DROP ROW FILTER " antes de excluir a função. Caso contrário, a tabela ficará em um estado inacessível.

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

Veja também a cláusulaROW FILTER.

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

SQL

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. Consultas subsequentes da tabela sales retornam um subconjunto de linhas.

SQL

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

Desativar o filtro de linha. Em seguida, consultas futuras de usuários da tabela sales retornam todas as linhas na tabela.

SQL

ALTER TABLE sales DROP ROW FILTER;

Crie uma tabela com a função aplicada como filtro de linha como parte da instrução CREATE TABLE. Em seguida, consultas futuras da tabela sales retornam um subconjunto de linhas.

SQL

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

Aplique 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.

É possível aplicar uma máscara de coluna utilizando o Catalog Explorer ou o comando SQL. As instruções do Catalog Explorer pressupõem que você já criou uma função e a registrou no Unity Catalog. As instruções SQL incluem exemplos de criação de uma função de máscara de coluna e sua aplicação a uma coluna da tabela.

nota

Se estiver utilizando um pipeline declarativ LakeFlow, é possível utilizar o pipeline declarativ LakeFlow Python API para criar tabelas de transmissão ou visualizações materializadas que utilizam filtros de linha e máscaras de coluna. Consulte Publicar tabelas com filtros de linha e máscaras de coluna.

Catalog Explorer

1. Em Databricks workspace, clique em Catalog .
2. Navegue ou pesquise a tabela.
3. Na visão tab geral, localize a linha à qual deseja aplicar a máscara de coluna e clique no ícone de edição Máscara de coluna.
4. 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.
5. Na caixa de diálogo expandida, selecione a definição da função “ view ”. Se a função incluir qualquer parâmetro além da coluna que está sendo mascarada, selecione as colunas da tabela nas quais você deseja converter esses parâmetros adicionais da função.
6. 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 ).

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 utilizando ALTER TABLE. Você também pode aplicar uma função ao criar uma tabela utilizando CREATE TABLE.

Você usa SET MASK para aplicar a função de mascaramento. Dentro da cláusula " MASK ", é possível utilizar qualquer uma das funções de tempo de execução do " Databricks " ou chamar outras funções definidas pelo usuário. Casos de uso comuns incluem inspecionar a identidade do usuário que está invocando a função usando current_user( ) ou obter os grupos dos quais ele é membro usando is_account_group_member( ). Para obter detalhes,consulte as funções cláusula e mask integrada.

1. Criar uma máscara de coluna:

   SQL

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

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

   SQL

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

**Exemplos adicionais de sintaxe**:

• Aplique a máscara de coluna a uma coluna em uma tabela existente usando um literal constante que corresponda a um parâmetro de função:

  SQL

  ALTER TABLE <table_name> ALTER COLUMN <col_name> SET MASK <mask_func_name> USING COLUMNS (<constant_name>, ...);

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

  SQL

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

• Modifique uma máscara de coluna, DROP na função existente ou use CREATE OR REPLACE TABLE.

• Excluir máscara da coluna:

  SQL

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

nota

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

Se a tabela ficar inacessível dessa forma, altere a tabela e elimine a referência da 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, você cria uma função definida pelo usuário que mascara a coluna ssn para que somente usuários que são membros do grupo HumanResourceDept possam visualizar valores nessa coluna.

SQL

CREATE FUNCTION ssn_mask(ssn STRING)
  RETURN CASE WHEN is_account_group_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 posteriormente.

SQL

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

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

SQL

--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 consulta não é membro do grupo HumanResourceDept :

SQL

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

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

SQL

ALTER TABLE users ALTER COLUMN ssn DROP MASK;

Máscara de coluna com Python UDF

Para usar a lógica Python ou Scala em uma máscara de coluna, você deve criar uma UDF Python ou Scala e, em seguida, envolvê-la em uma UDF SQL. A função wrapper SQL é o que você aplica como máscara de coluna.

Este exemplo cria uma UDF Python para mascarar endereços email e, em seguida, a envolve em uma UDF SQL :

SQL

-- Step 1: Create the Python UDF with masking logic
CREATE OR REPLACE FUNCTION email_mask_python(email STRING)
RETURNS STRING
LANGUAGE PYTHON
AS $$
import re
return re.sub(r'^[^@]+', lambda m: '*' * len(m.group()), email)
$$;

-- Step 2: Create a SQL wrapper function that calls the Python UDF
CREATE OR REPLACE FUNCTION email_mask_sql(email STRING)
RETURN email_mask_python(email);

Em seguida, aplique o wrapper SQL como máscara de coluna na sua tabela:

SQL

-- Create the `contacts` table and apply the SQL wrapper as the column mask
CREATE TABLE contacts (
  name STRING,
  email STRING MASK email_mask_sql);

important

Você deve aplicar a função wrapper SQL (email_mask_sql) como máscara de coluna, não a UDF do Python diretamente. Se você tentar usar o UDF do Python (email_mask_python) diretamente como uma máscara de coluna, receberá um erro [ROUTINE_NOT_FOUND] .

Use 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). Uma tabela de mapeamento abrangente codifica quais linhas de dados na tabela original podem ser acessadas por determinados usuários ou grupos. As tabelas de mapeamento são úteis porque oferecem integração simples com suas tabelas de fatos por meio de junção direta.

Essa metodologia aborda muitos casos de uso que incluem requisitos personalizados. Os exemplos incluem:

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

Ao adotar tabelas de mapeamento, você pode realizar esses cenários desafiadores e garantir implementações robustas de segurança 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:

SQL

USE CATALOG main;

Criar uma nova tabela de mapeamento:

SQL

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:

nota

Todos os filtros são executados com os direitos do definidor, exceto as funções que verificam o contexto do usuário (por exemplo, as funções CURRENT_USER e IS_ACCOUNT_GROUP_MEMBER ), que são executadas como o 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.

SQL

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 instrução ALTER TABLE. Ao aplicar o filtro em colunas não especificadas, use a sintaxe ON (). Para uma coluna específica, use ON (column);. Para obter mais detalhes, consulte Parâmetros.

SQL

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 .

SQL

SELECT * FROM data_table;

Crie uma tabela de mapeamento com contas que sempre devem ter acesso para visualizar todas as linhas na tabela, independentemente dos valores das colunas:

SQL

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

Agora, crie uma UDF SQL que retorne “ true ” se os valores de todas as colunas na linha forem menores que cinco ou se o usuário que invocou estiver presente na tabela de mapeamento acima.

SQL

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:

SQL

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