Filtrare i dati sensibili table usando filtri di riga e maschere di column

Articolo
01/23/2025

Questo articolo fornisce indicazioni ed esempi per l'uso di filtri di riga, maschere column e mapping tables per filtrare i dati sensibili nel tables. Queste funzionalità richiedono Unity Catalog.

Che cosa sono i filtri di riga?

I filtri di riga consentono di applicare un filtro a un table in modo che le query restituisca solo righe che soddisfano i criteri di filtro. Si implementa un filtro di riga come funzione definita dall'utente SQL. Sono supportate anche funzioni definite dall'utente Python e Scala, ma solo quando vengono incluse in funzioni definite dall'utente sql.

Che cosa sono le maschere column?

Column maschere consentono di applicare una funzione di mascheramento a un tablecolumn. La funzione di mascheramento viene valutata al momento dell'esecuzione della query, sostituendo ogni riferimento del column di destinazione con i risultati della funzione di mascheramento. Per la maggior parte dei casi d'uso, la maschera column determina se restituire il valore column originale o oscurarlo in base all'identità dell'utente chiamante. Column maschere sono espressioni scritte come funzioni definite dall'utente di SQL o come funzioni definite dall'utente Python o Scala di cui è stato eseguito il wrapping nelle funzioni definite dall'utente di SQL.

A ogni tablecolumn può essere applicata una sola funzione di maschera. La funzione masking accetta il valore non mascherato del column come input e restituisce il valore mascherato come risultato. Il valore restituito della funzione masking deve essere lo stesso tipo del column mascherato. La funzione di mascheramento può anche accettare columns come dati di input aggiuntivi parameters e usarli nella logica di maschera.

Qual è la differenza tra questi filtri e viewsdinamici?

Le maschere viewsdinamiche, i filtri di riga e le maschere di column consentono di applicare logica complessa per tables ed elaborare le decisioni di filtro in fase di esecuzione delle query.

Un visualizzazione dinamica è una visualizzazione astratta di sola lettura di una o più fonti di dati tables. L'utente può accedere a una visualizzazione dinamica senza accesso diretto having alla sorgente tables. La creazione di una visualizzazione dinamica definisce un nuovo nome di table che non deve corrispondere al nome di qualsiasi tables di origine o di altri tables e views presenti nella stessa schema.

D'altra parte, l'associazione di un filtro di riga o column mask a un table di destinazione applica la logica corrispondente direttamente al table senza introdurre nuovi nomi di table. Le domande successive possono continuare a fare riferimento direttamente al target table usando il nome originale.

Usare views dinamici se è necessario applicare la logica di trasformazione, ad esempio filtri e maschere, per tables di sola lettura e se è accettabile che gli utenti facciano riferimento al views dinamico usando nomi diversi. Se si desidera filtrare i dati quando lo si condivide usando Delta Sharing, è necessario usare viewsdinamico. Usare filtri di riga e maschere column se si desidera filtrare o calcolare espressioni su dati specifici, ma fornire comunque agli utenti l'accesso al tables usando i nomi originali.

Operazioni preliminari

Per aggiungere filtri di riga e maschere di column a tables, è necessario disporre di:

Area di lavoro abilitata per l'uso con Unity Catalog.
Funzione registrata in Unity Catalog. Questa funzione può essere una funzione definita dall'utente SQL, oppure una funzione definita dall'utente Python o Scala registrata in Unity Catalog e incapsulata in una funzione definita dall'utente SQL. Per informazioni dettagliate, vedere Che cosa sono le funzioni definite dall'utente?, clausola Column maschera, e clausola ROW FILTER.

Si devono soddisfare anche i requisiti seguenti:

Per assegnare una funzione che aggiunge filtri di riga o maschere di column a un table, è necessario disporre del privilegio EXECUTE per la funzione, USE SCHEMA nel schemae USE CATALOG nel catalogpadre .
Se si aggiungono filtri o maschere quando si crea un nuovotable, è necessario disporre del privilegio di CREATE TABLE nel schema.
Se si aggiungono filtri o maschere a un tableesistente, è necessario essere il proprietario table.

Per accedere a un table con filtri di riga o maschere di column, la risorsa di calcolo deve soddisfare uno dei requisiti seguenti:

Un'istanza di SQL Warehouse.
Modalità di accesso condiviso in Databricks Runtime 12.2 LTS o versione successiva.
Modalità di accesso utente singolo in Databricks Runtime 15.4 LTS o versione successiva.

Non è possibile leggere filtri di riga o maschere di column usando il calcolo configurato con la modalità di accesso utente singolo in Databricks Runtime 15.3 o versione successiva.

Per sfruttare i vantaggi del filtro dei dati fornito in Databricks Runtime 15.4 LTS e versioni successive, è anche necessario verificare che 'area di lavoro sia abilitata per l'elaborazione serverless, perché la funzionalità di filtro dei dati che supporta i filtri di riga e le maschere column vengono eseguite nel calcolo serverless. È possibile che vengano addebitati costi per le risorse di calcolo serverless quando si usa la modalità di calcolo configurata come modalità di accesso utente singolo per leggere tables che usano filtri di riga o maschere column. Vedere Controllo di accesso con granularità fine per il calcolo di un singolo utente.

Applica un filtro della riga

Per creare un filtro di riga, scrivere una funzione (UDF) per definire i criteri di filtro e quindi applicarla a un table. Ogni table può avere un solo filtro di riga. Un filtro di riga accetta zero o più input parameterswhere, e ogni parametro di input viene associato a un column del tablecorrispondente.

È possibile applicare un filtro di riga usando Catalog Explorer o i comandi SQL. Le istruzioni Catalog Explorer presuppongono che sia già stata creata una funzione e registrata in Unity Catalog. Le istruzioni SQL includono esempi di creazione di una funzione di filtro di riga e applicazione a un table.

Esploratore Catalog

Nell'area di lavoro di Azure Databricks fare clic sull'icona Catalog.
Esplora o cerca il table che vuoi filtrare.
Nella scheda Panoramica fare clic su Filtro di riga: Aggiungi filtro.
Nella finestra di dialogo Aggiungi filtro di riga e che contengono la funzione di filtro, quindi la funzione .
Nella finestra di dialogo espansa, esamina la definizione della funzione e select i tablecolumns che corrispondono ai columns inclusi nell'istruzione della funzione.
Fare clic su Aggiungi.

Per remove il filtro dall'table, fare clic su fx Filtro riga e fare clic su Remove.

SQL

Per creare un filtro di riga e quindi aggiungerlo a un tableesistente, usare CREATE FUNCTION e applicare la funzione usando ALTER TABLE. È anche possibile applicare una funzione quando si crea un table usando CREATE TABLE.

Creare il filtro di riga:

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

Applicare il filtro di riga a un table usando un nome di column:

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

Esempi di sintassi aggiuntivi:

Applicare il filtro di riga a un table usando un valore letterale costante che corrisponde a un parametro di funzione:
```
ALTER TABLE <table_name> SET ROW FILTER <function_name> ON (<constant_literal>, ...);
```

Remove un filtro di riga da un table:

ALTER TABLE <table_name> DROP ROW FILTER;

Modificare un filtro di riga:

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

Eliminare un filtro di riga:
```
ALTER TABLE <table_name> DROP ROW FILTER;
DROP FUNCTION <function_name>;
```
Nota

È necessario eseguire il comando ALTER TABLE ... DROP ROW FILTER prima di eliminare la funzione. In caso contrario, il table sarà inaccessibile.

Se il table diventa inaccessibile in questo modo, modificare il table ed eliminare il riferimento al filtro di riga orfano usando ALTER TABLE <table_name> DROP ROW FILTER;.

Si veda anche ROW FILTER clausola.

Esempi di filtro di riga

In questo esempio viene creata una funzione sql definita dall'utente che si applica ai membri del gruppo admin nell'area US.

Quando questa funzione di esempio viene applicata al salestable, i membri del gruppo admin possono accedere a tutti i record nel table. Se la funzione viene chiamata da un utente non amministratore, la condizione di RETURN_IF ha esito negativo e l'espressione region='US' viene valutata, filtrando il table in modo da visualizzare solo i record nell'area US.

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

Applicare la funzione a un table come filtro di riga. Le query successive provenienti dalla salestable quindi restituiscono un sottoinsieme di righe.

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

Disabilitare il filtro di riga. Le query future dell'utente dal salestable quindi restituiscono tutte le righe nella table.

ALTER TABLE sales DROP ROW FILTER;

Creare un table con la funzione applicata come filtro di riga come parte dell'istruzione CREATE TABLE. Le query future dei salestable restituiscono quindi un sottoinsieme di righe.

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

Applicare una maschera di column

Per applicare una maschera di column, creare una funzione (UDF) e applicarla a un tablecolumn.

È possibile applicare una maschera column usando Catalog Explorer o i comandi SQL. Le istruzioni Catalog Explorer presuppongono che sia già stata creata una funzione e registrata in Unity Catalog. Le istruzioni SQL includono esempi di creazione di una funzione maschera column e di applicarla a un tablecolumn.

Catalog Esploratore

Nell'area di lavoro di Azure Databricks fare clic sull'icona Catalog.
Esplorare o cercare table.
Nella scheda di Panoramica , individuare la riga a cui si desidera applicare la maschera di column e fare clic sull'icona per la maschera.
Nella finestra di dialogo Aggiungi maschera e che contengono la funzione di filtro, quindi la funzione .
Nella finestra di dialogo espansa visualizzare la definizione della funzione. Se la funzione include qualsiasi parameters oltre al column mascherato, select il tablecolumns in cui si desidera eseguire il cast di tali funzioni aggiuntive parameters.
Fare clic su Aggiungi.

Per remove maschera di column dalla table, fare clic su fx Column mask nella riga table e fare clic su Remove.

SQL

Per creare una maschera di column e aggiungerla a un tablecolumnesistente, usare CREATE FUNCTION e applicare la funzione di maschera usando ALTER TABLE. È anche possibile applicare una funzione quando si crea un table usando CREATE TABLE.

Si usa SET MASK per applicare la funzione di mascheramento. All'interno della clausola MASK è possibile usare una qualsiasi delle funzioni di runtime predefinite di Azure Databricks o chiamare altre funzioni definite dall'utente. I casi d'uso comuni includono l'ispezione dell'identità dell'utente chiamante che esegue la funzione usando current_user( ) o ottenendo i gruppi di cui sono membri tramite is_account_group_member( ). Per informazioni dettagliate, vedere la clausola maschera e le funzioni predefinite.

Creare una maschera column:

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

Applicare la maschera di column a un column in un tableesistente:

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

Esempi di sintassi aggiuntivi:

Applicare la maschera di column a un column in un table esistente usando un valore letterale costante che corrisponde a un parametro di funzione:
```
ALTER TABLE <table_name> ALTER COLUMN <col_name> SET MASK <mask_func_name> USING COLUMNS (<constant_name>, ...);
```

Remove una maschera di column da un column in un table:

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

Modificare una maschera di column, DROP la funzione esistente o usare CREATE OR REPLACE TABLE.
Eliminare una maschera di column:
```
ALTER TABLE <table_name> ALTER COLUMN <column where mask is applied> DROP MASK;
DROP FUNCTION <function_name>;
```
Nota

È necessario eseguire il comando ALTER TABLE prima di eliminare la funzione o il table sarà inaccessibile.

Se il table diventa inaccessibile in questo modo, modificare il table ed eliminare il riferimento alla maschera orfana usando ALTER TABLE <table_name> ALTER COLUMN <column where mask is applied> DROP MASK;.

esempi di maschera Column

In questo esempio viene creata una funzione definita dall'utente che maschera il ssncolumn in modo che solo gli utenti membri del gruppo HumanResourceDept possano visualizzare values in tale column.

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

Applicare la nuova funzione a un table come maschera column. È possibile aggiungere la maschera di column quando si crea il table o versione successiva.

--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;

Le query su tale table ora restituiscono ssncolumnvalues mascherate quando l'utente che esegue query non è membro del gruppo di HumanResourceDept:

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

Per disabilitare la maschera column in modo che le query restituiscano l'values originale nel ssncolumn:

ALTER TABLE users ALTER COLUMN ssn DROP MASK;

Usare la mappatura tables per creare un list di controllo di accesso

Per ottenere la sicurezza a livello di riga, è consigliabile definire un mapping table (o controllo di accesso list). Un mapping completo table codifica quali righe di dati nel table originale sono accessibili a determinati utenti o gruppi. Il mapping tables è utile perché offre un'integrazione semplice con il tuo fatto tables tramite join diretti.

Questa metodologia risolve molti casi d'uso che includono requisiti personalizzati. Alcuni esempi:

Imposizione di restrizioni in base all'utente connesso, mantenendo al tempo stesso regole diverse per gruppi di utenti specifici.
Creazione di gerarchie complesse, ad esempio strutture organizzative, che richiedono set diversi di regole.
Replica di modelli di sicurezza complessi da sistemi di origine esterni.

Adottando il mapping tables, è possibile affrontare questi scenari complessi e garantire implementazioni affidabili a livello di riga e implementazioni di sicurezza a livello di column.

Esempi di mappatura table

Usare un mapping table per verificare se l'utente corrente si trova in un list:

USE CATALOG main;

Creare un nuovo mapping table:

DROP TABLE IF EXISTS valid_users;

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

Creare un nuovo filtro:

Nota

Tutti i filtri vengono eseguiti con i diritti del definer, ad eccezione delle funzioni che controllano il contesto utente (ad esempio, le funzioni CURRENT_USER e IS_MEMBER ) eseguite come invoker.

In questo esempio la funzione controlla se l'utente corrente si trova nel valid_userstable. Se l’utente viene trovato, la funzione restituisce true.

DROP FUNCTION IF EXISTS row_filter;

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

Nell'esempio seguente viene applicato il filtro di riga durante la creazione di table. È anche possibile aggiungere il filtro in un secondo momento usando un'istruzione ALTER TABLE. Quando viene applicato a un intero table, usare la sintassi ON (). Per una riga specifica, usare 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);

Select dati dal table. Deve restituire i dati solo se l'utente si trova nel valid_userstable.

SELECT * FROM data_table;

Crea un mapping table che includa gli account che devono sempre avere accesso per visualizzare tutte le righe in table, indipendentemente dal columnvalues.

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

Ora, crea una funzione definita dall'utente SQL che restituisce true se il values di tutte le columns nella riga sono minori di cinque o se l'utente chiamante è membro della mappatura sopra table.

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

Infine, applica la UDF SQL al table come filtro di riga.

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

Supporto e limitazioni

I filtri di riga e le maschere di column non sono supportati con tutte le funzionalità di Azure Databricks o in tutte le risorse di calcolo. Questa sezione elenca le funzionalità e le limitazioni supportate.

Funzionalità e formati supportati

Questo elenco list delle funzionalità supportate non è esaustivo. Alcuni elementi sono elencati perché non sono stati supportati durante l'anteprima pubblica.

Sono supportati i notebook di Databricks SQL e Databricks per i carichi di lavoro SQL.
Sono supportati i comandi DML da parte degli utenti con privilegi MODIFY. I filtri e le maschere vengono applicati ai dati letti da UPDATE e da DELETE e non vengono applicati ai dati scritti (incluso INSERT).
Formati di dati supportati:
- Delta e Parquet per tablesgestiti ed esterni.
- Più altri formati di dati per i tables stranieri registrati in Unity Catalog usando Lakehouse Federation.
I criteri parameters possono includere espressioni costanti (stringhe, numeri, intervalli, valori booleani, valori Null).
Le FDU SQL, Python e Scala sono supportate come funzioni di filtro riga o funzioni maschera column se sono registrate in Unity Catalog. Le funzioni definite dall'utente Python e Scala devono essere incapsulate in una funzione definita dall'utente SQL.
È possibile creare views su tables che fanno riferimento a maschere column o filtri di riga, ma non è possibile aggiungere maschere column o filtri di riga a una visualizzazione.
I feed di dati delle modifiche Delta Lake sono supportati se l'schema è compatibile con i filtri di riga e le maschere column applicabili al tabledi destinazione.
Sono supportate tables straniere.
Il campionamento Table è supportato.
Le istruzioni MERGE sono supportate quando l'origine tables, la destinazione tables, o entrambi i sistemi usano filtri di riga e maschere column. Questa include tables con funzioni di filtro di riga che contengono semplici sottoquery. Le limitazioni sono elencate nella sezione seguente.
Databricks SQL materializzati views e Databricks SQL streaming tables supportano filtri di riga e maschere column (anteprima pubblica):
- È possibile aggiungere filtri di riga e maschere di column a una vista materializzata di SQL Databricks o a uno streaming table. L'aggiunta di maschere deve essere eseguita in modo dichiarativo quando viene definita la visualizzazione materializzata o lo streaming table. Vedere CREATE MATERIALIZED VIEW o CREATE STREAMING TABLE.
- È possibile definire viste materializzate views o di streaming tables per Databricks SQL in tables che includono filtri di riga e maschere column.
I views materializzati e i tables di streaming dichiarati e pubblicati in Delta Live Tables supportano filtri di riga o maschere di column (anteprima pubblica):
- È possibile aggiungere filtri di riga e maschere di column a una vista Delta Live Tables materializzata o una vista in streaming table.
- È possibile definire Tables Delta Live materializzati views o in streaming tables su tables che includono filtri di riga e maschere column.
Vedere Pubblicare tables con filtri di riga e maschere di column.

Raccomandazioni sulle prestazioni

I filtri di riga e le maschere column controllano la visibilità dei dati, assicurando che gli utenti non possano vedere il contenuto di values del tables base prima che vengano eseguite le operazioni di filtro e mascheramento. Offrono buone prestazioni rispondendo alle query nei casi d'uso comuni. Nelle applicazioni meno comuni, where il motore di query deve scegliere tra l'ottimizzazione delle prestazioni delle query e la protezione dalla perdita di informazioni dall'valuesfiltrata/mascherata, sarà sempre necessario prendere la decisione sicura a scapito di un certo impatto sulle prestazioni delle query. Per ridurre al minimo questo impatto sulle prestazioni, applicare le raccomandazioni seguenti:

Usare funzioni di criteri semplici: funzioni dei criteri con meno espressioni spesso offrono prestazioni migliori rispetto a espressioni più complesse. Evitare l'uso del mapping tables e delle sottoquery delle espressioni, preferendo invece funzioni CASE semplici.
Ridurre il numero di argomenti della funzione: Azure Databricks non può optimizecolumn riferimenti all'origine table risultante dagli argomenti della funzione dei criteri, anche se questi columns non vengono usati nella query. Utilizzare funzioni di criteri con un minor numero di argomenti, poiché le query di questi tables avranno prestazioni migliori.
Evitare di aggiungere filtri di riga con troppi congiunzioni AND: Poiché ogni table supporta solo l'aggiunta al massimo di un filtro di riga, un approccio comune consiste nel combinare più funzioni dei criteri desiderate con AND. Tuttavia, per ogni congiunzione, le probabilità aumentano che le congiunzioni includano componenti menzionati altrove in questo documento table che potrebbero influire sulle prestazioni (come il mapping tables). Usare meno congiunzioni per migliorare le prestazioni.
Usare espressioni deterministiche che non possono generare errori nei criteri table e nelle query da questi tables: Alcune espressioni possono generare errori se gli input forniti non sono validi, ad esempio la divisione ANSI. In questi casi, il compilatore SQL non deve eseguire il push delle operazioni con tali espressioni (ad esempio filtri) troppo in basso nel piano di query per evitare la possibilità di errori come "divisione per zero" che rivelano informazioni sui values prima di filtrare e/o mascherare le operazioni. Usare espressioni deterministiche che non generano mai errori, ad esempio try_divide in questo esempio.
Esegui query di test sui table per misurare le prestazioni: Costruisci query realistiche che rappresentano il carico di lavoro previsto per i table con filtri di riga e/o maschere di column e misura le prestazioni. Apportare piccole modifiche alle funzioni dei criteri e osservare i relativi effetti fino a raggiungere un buon equilibrio tra prestazioni ed espressività della logica di filtro e mascheramento.

Limitazioni

Le versioni di Databricks Runtime inferiori alla 12.2 LTS non supportano filtri di riga o maschere column. I runtime in questione falliscono in modo sicuro, il che significa che se si tenta di accedere a tables da versioni non supportate di questi runtime, non vengono restituiti dati.
Delta Sharing non funziona con la sicurezza a livello di riga o le maschere column.
Non è possibile applicare la sicurezza a livello di riga o le maschere column a una vista.
Il viaggio in tempo non funziona con la sicurezza a livello di riga o maschere column.
L'accesso basato sul percorso ai file in tables con politiche non è supportato.
Le politiche di filtro di riga o column-mask con dipendenze circolari che riportano alle politiche originali non sono supportate.
I cloni profondi e superficiali non sono supportati.
Le istruzioni MERGE non supportano tables con filtro di riga o criteri column-mask che contengono annidamenti, aggregazioni, finestre, limiti o funzioni non deterministiche.
Le API Delta Lake non sono supportate.

Limitazione delle risorse di calcolo per utente singolo

Non è possibile accedere a un table con filtri di riga o maschere column da una singola risorsa di calcolo utente in Databricks Runtime 15.3 o versione successiva. È possibile usare la modalità di accesso utente singolo in Databricks Runtime 15.4 LTS o versione successiva, se l'area di lavoro è abilitata per il calcolo serverless. Per altre informazioni, vedere Controllo di accesso con granularità fine per il calcolo di un singolo utente.

Condividi tramite