Filtri di riga e maschere di colonna

I filtri di riga e le maschere di colonna sono controlli di accesso al catalogo Unity che limitano le righe e i valori di colonna che un utente può visualizzare in fase di query. Questa pagina descrive il formato a livello di tabella di questi controlli, configurati direttamente nelle singole tabelle usando SQL e gestiti dal proprietario della tabella. Per garantire un filtro delle righe e un mascheramento delle colonne coerenti in molte tabelle, i criteri ABAC sono l'approccio consigliato. Si collegano a livello di catalogo o schema e si applicano automaticamente in base ai tag regolati.

Cosa sono i filtri a fila?

I filtri di riga limitano le righe che un utente può visualizzare in una tabella. Il filtro è una funzione definita dall'utente (UDF) SQL che valuta ogni riga in fase di query. Le righe in cui la funzione restituisce FALSE vengono escluse dai risultati della query. Viene comunemente usato per la sicurezza a livello di riga. Ad esempio, è possibile limitare gli utenti ai record da un'area, un reparto o un account specifici.

I filtri di riga a livello di tabella sono associati a una singola tabella usando ALTER TABLE ... SET ROW FILTER e gestiti dal proprietario della tabella. Per un filtraggio coerente delle righe in più tabelle, utilizzare invece i criteri ABAC.

Cosa sono le maschere a colonna?

Le maschere di colonna controllano i valori visualizzati da un utente per colonne specifiche. La maschera è una UDF SQL che accetta in input il valore della colonna e restituisce il valore originale o una versione mascherata. Il tipo restituito deve corrispondere o essere convertibile al tipo di dati della colonna. Ogni colonna può avere una maschera. Le maschere di colonna possono accettare altre colonne come input per variare il comportamento in base a più attributi.

Le maschere di colonna a livello di tabella sono associate a una colonna usando ALTER TABLE ... ALTER COLUMN ... SET MASK e gestite dal proprietario della tabella. Si applicano solo a tale colonna nella tabella. Per un mascheramento coerente delle colonne tra molte tabelle, utilizza invece i criteri ABAC.

Quando usare criteri ABAC o visualizzazioni dinamiche

Il catalogo unity offre due meccanismi correlati per il controllo di accesso a livello di riga e a livello di colonna:

• I criteri ABAC si collegano a livello di catalogo o di schema e si applicano automaticamente a tabelle e colonne in base ai tag gestiti. Usa ABAC quando hai bisogno di regole coerenti tra molte tabelle, della separazione dei compiti tra autori delle policy e responsabili dei dati, oppure della copertura automatica delle nuove tabelle man mano che vengono etichettate. Per un confronto affiancato con ABAC, i filtri di riga a livello di tabella e le maschere di colonna, consulta Quando usare ABAC rispetto ai filtri di riga a livello di tabella e alle maschere di colonna.
• Le viste dinamiche eseguono il wrapping di una o più tabelle di base in una vista SQL che filtra le righe, maschera le colonne o modifica i dati, in genere gestiti da funzioni di appartenenza a gruppi come is_account_group_member(). Usare le visualizzazioni dinamiche quando si vuole esporre una versione curata, trasformata o unita ai dati agli utenti che non hanno accesso alle tabelle sottostanti. I casi d'uso di esempio includono la condivisione di una sezione di una tabella dei fatti con un gruppo di analisti o la combinazione di colonne da più tabelle in un unico livello sicuro.

Per un confronto più dettagliato con viste dinamiche e policy ABAC, consulta Quando usare ABAC rispetto ai filtri di riga a livello di tabella e alle maschere di colonna.

Come applicare filtri di riga e maschere di colonna

Applicare filtri di riga e maschere di colonna in uno dei modi seguenti:

• Utilizzo dei criteri ABAC (consigliato): Applicare filtri e maschere in modo centralizzato utilizzando tag governati e criteri riutilizzabili. Il controllo degli accessi basato su attributi (ABAC) si applica a cataloghi e schemi e può essere definito da amministratori di livello superiore, quindi i proprietari delle tabelle non possono sostituire o rimuovere queste regole. Anche la logica delle policy viene valutata in modo più efficiente rispetto alle UDF specifiche della tabella. Vedere Controllo degli accessi in base agli attributi in Unity Catalog.
• Assegnazione manuale per tabella: Applicare filtri e maschere assegnando UDF direttamente a singole tabelle e colonne. Ciò consente un controllo specifico della tabella con granularità fine, ma è più difficile da ridimensionare e gestire. Vedere Applicare manualmente filtri di riga e maschere di colonna.

Raccomandazioni sulle prestazioni

I filtri di riga e le maschere di colonna controllano la visibilità dei dati assicurando che gli utenti non possano visualizzare i valori della tabella di base prima di applicare filtri o maschere. Quando il motore di query deve scegliere tra ottimizzazione e protezione dalla perdita di informazioni da valori filtrati o mascherati, fa sempre la scelta sicura, che può influire sulle prestazioni delle query. Per ridurre al minimo l'impatto:

• Usa UDF semplici. Le funzioni con un minor numero di espressioni offrono prestazioni migliori. Preferisce espressioni semplici CASE rispetto alle tabelle di mapping o alle sottoquery delle espressioni.
• Limitare il numero di maschere di colonna distinte in tabelle di grandi dimensioni. Ogni maschera distinta viene valutata durante l'esecuzione delle query. Applicare maschere solo alle colonne realmente sensibili e riutilizzare le funzioni di maschera laddove possibile.
• Ridurre il numero di argomenti UDF. Azure Databricks non può eliminare tramite ottimizzazione i riferimenti alle colonne che provengono da argomenti di funzioni definite dall'utente, anche se tali colonne non vengono utilizzate nella query. Usare UDF con meno argomenti, ove possibile.
• Evitare filtri di riga con AND troppe congiunzioni. Un solo filtro di riga distinto può essere risolto in fase di esecuzione per un determinato utente e una tabella, quindi un modello comune consiste nel combinare la logica con AND. Più sono le congiunzioni aggiunte, più è probabile che il filtro combinato includa uno dei modelli avvisati in precedenza. Usare un minor numero di congiunzioni, se possibile.
• Usare espressioni deterministiche che non possono generare errori. Le espressioni che possono generare errori (ad esempio la divisione ANSI) impediscono al compilatore SQL di eseguire il push delle operazioni nel piano di query, perché gli errori come "divisione per zero" potrebbero rivelare informazioni sui valori prima di filtrare o mascherare. Usare espressioni deterministiche che non generano mai errori, ad esempio try_divide.
• Preferisci SQL alle UDF Python. Le UDF Python sono meno performanti delle funzioni SQL e offrono minori opportunità di ottimizzazione. Se devi usare Python, contrassegna la UDF come DETERMINISTIC se applicabile.

Per indicazioni complete sulle prestazioni delle UDF (inclusi il pushdown dei predicati e i dettagli sull'ottimizzazione a livello di motore di esecuzione), vedere Considerazioni sulle prestazioni per i criteri di filtro delle righe e di mascheramento delle colonne. La maggior parte delle indicazioni si applica allo stesso modo ai filtri di riga applicati manualmente e alle maschere di colonna. Per esempi di UDF, vedi Schemi comuni per il filtraggio delle righe e il mascheramento delle colonne.

Comportamento di mancata corrispondenza del tipo di dati

Quando si crea un filtro di riga o una maschera di colonna, il tipo di dati di ogni colonna di tabella passata alla funzione deve corrispondere al tipo di parametro corrispondente nella UDF. Se esiste una mancata corrispondenza di tipo, ad esempio una STRING colonna passata a un INT parametro, Databricks esegue il cast implicito del valore della colonna nel tipo del parametro, il che può causare un comportamento imprevisto quando la colonna contiene valori che non possono essere convertiti.

Con la modalità ANSI disabilitata (spark.sql.ansi.enabled = false), i valori noncastabili vengono convertiti automaticamente in NULL, non viene generato alcun errore e la funzione definita dall'utente riceve NULL anziché il valore effettivo della colonna. Ciò può produrre risultati non corretti, ad esempio un filtro di riga che restituisce tutte le righe anziché filtrarle o una maschera di colonna che maschera i valori errati. Databricks consiglia di abilitare la modalità ANSI (spark.sql.ansi.enabled = true), che genera un errore quando un cast ha esito negativo, rendendo immediatamente visibile il problema, anziché restituire NULLautomaticamente .

Esempio: Filtro di riga con una mancata corrispondenza del tipo

Si consideri una tabella con una STRING colonna e un filtro di INTriga il cui parametro viene accidentalmente dichiarato come STRING anziché :

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 viene eseguita una query, i valori department e 'exec' non possono essere sottoposti a cast in 'engineering', quindi vengono convertiti automaticamente in INT. Poiché il filtro restituisce true quando l'input è NULL, vengono restituite tutte le righe anziché solo le righe in cui department è effettivamente NULL:

SELECT * FROM employees;

La definizione corretta della funzione definita dall'utente usa STRING come tipo di parametro per corrispondere alla colonna.

CREATE FUNCTION salary_filter(dept STRING) RETURNS BOOLEAN
RETURN dept IS NULL;

Con questa correzione, la query restituisce solo la riga in cui department è NULL.

Limitazioni

• Le versioni di Databricks Runtime inferiori alla 12.2 LTS non supportano filtri di riga o maschere di colonna. Questi runtime si interrompono in modo sicuro, ovvero se si tenta di accedere alle tabelle da questi runtime, non vengono forniti dati.
• Non è possibile applicare maschere di sicurezza a livello di riga o di colonna a una visualizzazione.
• Non è possibile usare il catalogo REST Di Iceberg o le API REST di Unity per accedere alle tabelle con filtri di riga o maschere di colonna.
• Le API Delta Lake non sono supportate.
• I provider OpenSharing non possono condividere tabelle con filtri di riga a livello di tabella o maschere di colonna. Le tabelle con filtri di riga o maschere di colonna basate su ABAC possono essere condivise se il proprietario della condivisione è esente dai criteri. Vedi le tabelle OpenSharing con policy ABAC o viste che fanno riferimento a esse.
• I destinatari OpenSharing possono applicare filtri di riga e maschere di colonna solo alle tabelle condivise e alle tabelle esterne, non alle tabelle di streaming o alle viste materializzate.
• L'accesso basato sul percorso ai file nelle tabelle con criteri non è supportato.
• Le istruzioni MERGE non supportano tabelle con politiche di filtro sulle righe o mascheramento delle colonne che contengono annidamenti, aggregazioni, finestre, limiti o funzioni non deterministiche.
• Le versioni di Databricks Runtime precedenti alla 17.2 non supportano DELETE, UPDATEe MERGE nelle tabelle partizionate con criteri di filtro di riga o maschera di colonna definiti nella colonna di partizione.
• Le politiche di filtro di riga o maschera di colonna con dipendenze circolari rispetto alle politiche originali non sono supportate.
• I filtri di riga e le maschere di colonna non possono fare riferimento a tabelle con filtri di riga o maschere di colonna attive. Nelle configurazioni ABAC, è possibile risolvere questo problema escludendo il proprietario della funzione di policy dai criteri della tabella a cui si fa riferimento.
• Il viaggio nel tempo non funziona con la sicurezza a livello di riga o le maschere di colonna. Nelle configurazioni del controllo degli accessi basato sugli attributi (ABAC), gli utenti esclusi in modo esplicito da un criterio possono comunque eseguire query di viaggio nel tempo sui dati sottostanti.
• I cloni profondi e superficiali non sono supportati nelle tabelle con maschere di sicurezza a livello di riga o di colonna. Nelle configurazioni di controllo degli accessi basato sugli attributi, gli utenti esclusi in modo esplicito da una policy possono comunque eseguire operazioni di clonazione sui dati sottostanti.
• Non è possibile creare un indice di ricerca di intelligenza artificiale da una tabella con filtri di riga o maschere di colonna applicate.
• Le maschere di colonna non possono essere applicate alle colonne a cui fa riferimento le colonne generate. Consulta Colonne generate e maschere di colonna.

Limitazione della modalità di accesso dedicato

Non è possibile accedere a una tabella con filtri di riga o maschere di colonna da una risorsa di calcolo di accesso dedicata in Databricks Runtime 15.3 o versione successiva. È possibile usare la modalità di accesso dedicato in Databricks Runtime 15.4 LTS o versione successiva se l'area di lavoro è abilitata per il calcolo serverless. Tuttavia, sono supportate solo le operazioni di lettura in Databricks Runtime da 15.4 a 16.2. Le operazioni di scrittura (inclusi INSERT, UPDATEe DELETE) richiedono Databricks Runtime 16.3 o versione successiva e devono usare modelli supportati, ad MERGE INTOesempio .

Quando si eseguono query su tabelle con filtri di riga o maschere di colonna da calcolo in modalità di accesso dedicato, Azure Databricks usa il calcolo serverless per applicare controlli di accesso con granularità fine (FGAC). Di conseguenza, si applicano tutte le limitazioni e le considerazioni di FGAC. Vedere Controllo di accesso con granularità fine in calcolo dedicato.