Filtres de ligne et masques de colonne

Les filtres de lignes et les masques de colonnes sont des contrôles d'accès de Unity Catalog qui restreignent les lignes et les valeurs de colonnes qu'un utilisateur peut voir au moment de la query. Cette page décrit la forme au niveau des tables de ces contrôles, qui sont configurés directement sur des tables individuelles à l'aide de SQL et gérés par le propriétaire de la table. Pour un filtrage de lignes et un masquage de colonnes cohérents sur de nombreuses tables, les politiques ABAC sont l'approche recommandée. Ils s'attachent au niveau du catalogue ou du schéma et s'appliquent automatiquement en fonction des tags gouvernés.

astuce

Databricks recommande les politiques ABAC lorsque vous avez besoin d'un filtrage de lignes et d'un masquage de colonnes cohérents sur de nombreuses tables. Les politiques ABAC s'appliquent au niveau du catalogue ou du schéma et s'appliquent automatiquement en fonction des tags gérés, plutôt que de nécessiter une configuration par table.

Que sont les filtres de ligne ?

Les filtres de ligne restreignent les lignes qu'un utilisateur peut voir dans une table. Le filtre est une fonction définie par l'utilisateur (UDF) SQL qui évalue chaque ligne au moment de la query. Les lignes où la fonction renvoie FALSE sont exclues des résultats de la query. Ceci est couramment utilisé pour la sécurité au niveau des lignes. Par exemple, vous pouvez restreindre les utilisateurs aux enregistrements d'une région, d'un service ou d'un compte spécifique.

Les filtres de ligne au niveau de la table sont liés à une seule table à l'aide de ALTER TABLE ... SET ROW FILTER et gérés par le propriétaire de la table. Pour un filtrage de ligne cohérent sur de nombreuses tables, utilisez plutôt les politiques ABAC.

Que sont les masques de colonne ?

Les masques de colonne contrôlent les valeurs qu'un utilisateur voit pour des colonnes spécifiques. Le masque est une UDF SQL qui prend la valeur de la colonne en entrée et renvoie la valeur d'origine ou une version masquée. Le type de retour doit correspondre ou être convertible en type de données de la colonne. Chaque colonne peut avoir un masque. Les masques de colonne peuvent prendre d'autres colonnes en entrée pour faire varier le comportement en fonction de plusieurs attributs.

Les masques de colonne au niveau de la table sont liés à une colonne à l'aide de ALTER TABLE ... ALTER COLUMN ... SET MASK et gérés par le propriétaire de la table. Ils s'appliquent uniquement à cette colonne sur cette table. Pour un masquage de colonne cohérent sur de nombreuses tables, utilisez plutôt les politiques ABAC.

Quand utiliser des politiques ABAC ou des vues dynamiques à la place

Unity Catalog fournit deux mécanismes connexes pour le contrôle d'accès au niveau des lignes et des colonnes :

• Les politiques ABAC se rattachent au niveau du catalogue ou du schéma et s'appliquent automatiquement aux tables et aux colonnes en fonction des tags gouvernés. Utilisez ABAC lorsque vous avez besoin de règles cohérentes sur de nombreuses tables, d'une séparation des tâches entre les auteurs de politiques et les data stewards, ou d'une couverture automatique des nouvelles tables lorsqu'elles sont taguées. Pour une comparaison côte à côte avec les filtres de lignes et les masques de colonnes au niveau des tables, consultez Quand utiliser ABAC par rapport aux filtres de lignes et aux masques de colonnes au niveau des tables.
• Les vues dynamiques encapsulent une ou plusieurs tables de base dans une vue SQL qui filtre les lignes, masque les colonnes ou remodèle les données, généralement limitées par des fonctions d'appartenance à un groupe comme is_account_group_member(). Utilisez les vues dynamiques lorsque vous souhaitez exposer une version organisée, transformée ou jointe de vos données à des utilisateurs qui n'ont pas accès aux tables sous-jacentes. Les cas d'utilisation incluent le partage d'une tranche expurgée d'une table de faits avec un groupe d'analystes, ou la combinaison de colonnes de plusieurs tables en une seule couche sécurisée.

Approche	S'applique à	Géré à l'aide de	Idéal pour
Filtres de ligne au niveau de la table et masques de colonne	Tables et colonnes individuelles	ALTER TABLE par le propriétaire de la table ou un utilisateur disposant de MANAGE	Logique spécifique aux tables
Politiques ABAC	Tables et colonnes correspondantes selon les conditions de balise	CREATE POLICY associé à un catalogue, un schéma ou une table par son propriétaire ou un utilisateur avec MANAGE	Règles centralisées appliquées automatiquement à de nombreuses tables
Vues dynamiques	Une vue construite à partir d'une ou plusieurs tables de base	Logique SQL dans la définition de la vue	Partager une version organisée ou transformée des données

Approche	S'applique à	Géré à l'aide de	Idéal pour
Filtres de ligne au niveau de la table et masques de colonne	Tables et colonnes individuelles	ALTER TABLE par le propriétaire de la table ou un utilisateur disposant de MANAGE	Logique spécifique aux tables
Politiques ABAC	Tables et colonnes correspondantes selon les conditions de balise	CREATE POLICY associé à un catalogue, un schéma ou une table par son propriétaire ou un utilisateur avec MANAGE	Règles centralisées appliquées automatiquement à de nombreuses tables
Vues dynamiques	Une vue construite à partir d'une ou plusieurs tables de base	Logique SQL dans la définition de la vue	Partager une version organisée ou transformée des données

Pour une comparaison plus détaillée avec les vues dynamiques et les politiques ABAC, consultez Quand utiliser ABAC ou les filtres de lignes et masques de colonnes au niveau de la table.

Comment appliquer les filtres de ligne et les masques de colonne

Appliquez les filtres de ligne et les masques de colonne de l'une des manières suivantes :

• Utilisation des politiques ABAC (recommandé) : Appliquez les filtres et les masques de manière centralisée à l'aide de tags gouvernés et de politiques réutilisables. ABAC s'applique aux catalogues et aux schémas et peut être défini par des administrateurs de niveau supérieur, de sorte que les propriétaires de tables ne peuvent pas les remplacer ou les supprimer. La logique de politique est également évaluée plus efficacement que les fonctions UDF spécifiques aux tables. Consultez le contrôle d'accès basé sur les attributs dans Unity Catalog.
• Affectation manuelle par table : Appliquez des filtres et des masques en affectant des UDF directement aux tables et colonnes individuelles. Cela permet un contrôle granulaire et spécifique à la table, mais il est plus difficile à monter en charge et à maintenir. Voir Appliquer manuellement des filtres de ligne et des masques de colonne.

Recommandations de performances

Les filtres de ligne et les masques de colonne contrôlent la visibilité des données en garantissant que les utilisateurs ne peuvent pas voir les valeurs de la table de base avant l'application du filtrage ou du masquage. Lorsque le moteur de requête doit choisir entre l'optimisation et la protection contre la fuite d'informations provenant de valeurs filtrées ou masquées, il fait toujours le choix sécurisé, ce qui peut affecter les performances des requêtes. Pour minimiser cet impact :

• Utilisez des UDF simples. Les fonctions avec moins d'expressions fonctionnent mieux. Préférez les expressions CASE simples aux tables de mappage ou aux sous-requêtes d'expression.
• Limitez le nombre de masques de colonne distincts sur les grandes tables. Chaque masque distinct est évalué lors des query. Appliquez les masques uniquement aux colonnes réellement sensibles et réutilisez les fonctions de masquage lorsque cela est possible.
• Réduisez le nombre d'arguments UDF. Databricks ne peut pas optimiser les références de colonne provenant des arguments UDF, même si ces colonnes ne sont pas utilisées dans la query. Utilisez des UDF avec moins d'arguments si possible.
• Évitez les filtres de ligne avec trop de conjonctions AND. Seul un filtre de ligne distinct peut être résolu à l'exécution pour un utilisateur et une table donnés, un modèle courant consiste donc à combiner la logique avec AND. Plus vous ajoutez de conjonctions, plus il est probable que le filtre combiné inclue l'un des modèles mentionnés ci-dessus. Utilisez moins de conjonctions lorsque cela est possible.
• Utilisez des expressions déterministes qui ne peuvent pas générer d'erreurs. Les expressions qui peuvent générer des erreurs (telles que la division ANSI) empêchent le compilateur SQL de pousser les Opérations dans le plan de query, car des erreurs comme "division par zéro" pourraient révéler des informations sur les valeurs avant le filtrage ou le masquage. Utilisez des expressions déterministes qui ne génèrent jamais d'erreurs, telles que try_divide.
• Préférez les fonctions UDF SQL aux fonctions UDF Python. Les UDF Python sont moins performantes que SQL et offrent moins d'opportunités d'optimisation. Si vous devez utiliser Python, marquez l'UDF comme DETERMINISTIC le cas échéant.

Pour obtenir des conseils complets sur les performances des UDF (y compris les détails sur le transfert de prédicat et l’optimisation au niveau du moteur), consultez Considérations sur les performances des stratégies de filtre de lignes et de masque de colonnes. La plupart des conseils s'appliquent également aux filtres de lignes et masques de colonnes appliqués manuellement. Pour les exemples d'UDF, consultez Modèles courants pour le filtrage de lignes et le masquage de colonnes.

Comportement d'incompatibilité de type de données

Lorsque vous créez un filtre de ligne ou un masque de colonne, le type de données de chaque colonne de table transmise à la fonction doit correspondre au type de paramètre correspondant dans l'UDF. S'il y a une incompatibilité de type, telle qu'une colonne STRING passée à un parameter INT, Databricks convertit implicitement la valeur de la colonne en type de parameter, ce qui peut entraîner un comportement inattendu lorsque la colonne contient des valeurs qui ne peuvent pas être converties.

Lorsque le mode ANSI est désactivé (spark.sql.ansi.enabled = false), les valeurs non castables sont silencieusement converties en NULL, aucune erreur n'est générée, et la UDF reçoit NULL au lieu de la valeur réelle de la colonne. Cela peut produire des résultats incorrects, tels qu'un filtre de ligne qui renvoie toutes les lignes au lieu de les filtrer, ou un masque de colonne qui masque les mauvaises valeurs. Databricks recommande d'activer le mode ANSI (spark.sql.ansi.enabled = true), ce qui génère une erreur lorsqu'un cast échoue, rendant le problème immédiatement visible, au lieu de renvoyer silencieusement NULL.

Exemple : Filtre de ligne avec une incompatibilité de type

Considérez une table avec une colonne STRING et un filtre de lignes dont le parameter est accidentellement déclaré comme INT au lieu de STRING:

SQL

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

Lorsqu'elles sont interrogées, les valeurs department 'exec' et 'engineering' ne peuvent pas être castées en INT, elles sont donc converties silencieusement en NULL. Étant donné que le filtre renvoie true lorsque l'entrée est NULL, toutes les lignes sont renvoyées au lieu de seulement les lignes où department est réellement NULL:

SQL

SELECT * FROM employees;

| ID | salaire | département | | -- | ------ | ----------- | | 91 | 200000 | null | | 1 | 200000 | exec | | 2 | 50000 | Data Engineering | | 3 | 150000 | exec |

La définition UDF correcte utilise STRING comme type de paramètre pour correspondre à la colonne :

SQL

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

Avec ce correctif, la query renvoie uniquement la ligne où department est NULL.

Limitations

• Les versions de Databricks Runtime inférieures à 12.2 LTS ne prennent pas en charge les filtres de lignes ou les masques de colonnes. Ces runtimes échouent en toute sécurité, ce qui signifie que si vous essayez d'accéder aux tables à partir de ces runtimes, aucune donnée n'est renvoyée.
• Vous ne pouvez pas appliquer de sécurité au niveau des lignes ou de masques de colonne à une vue.
• Vous ne pouvez pas utiliser le catalogue REST Iceberg ou les APIs REST Unity pour accéder aux tables avec des filtres de ligne ou des masques de colonne.
• Les APIs Delta Lake ne sont pas prises en charge.
• Les fournisseurs OpenSharing ne peuvent pas partager de tables avec des filtres de lignes au niveau de la table ou des masques de colonnes. Les tables avec des filtres de lignes ou des masques de colonnes basés sur ABAC peuvent être partagées si le propriétaire du partage est exempté de la politique. Consultez les tables OpenSharing avec des politiques ABAC ou les vues qui y font référence.
• Les destinataires OpenSharing peuvent appliquer des filtres de lignes et des masques de colonnes uniquement aux tables partagées et aux tables externes, et non aux tables de streaming ou aux vues matérialisées.
• L'accès basé sur le chemin aux fichiers dans les tables avec des stratégies n'est pas pris en charge.
• MERGE Les instructions ne prennent pas en charge les tables avec des politiques de filtre de ligne ou de masque de colonne qui contiennent des imbrications, des agrégations, des fenêtres, des limites ou des fonctions non déterministes.
• Les versions de Databricks Runtime antérieures à 17,2 ne prennent pas en charge DELETE, UPDATE et MERGE sur les tables partitionnées avec des filtres de ligne ou des politiques de masque de colonne définies sur la colonne de partition.
• Les politiques de filtrage de lignes ou de masquage de colonnes avec des dépendances circulaires vers les politiques d'origine ne sont pas prises en charge.
• Les filtres de lignes et les masques de colonnes ne peuvent pas faire référence à des tables qui ont également des filtres de lignes ou des masques de colonnes actifs. Dans les configurations ABAC, vous pouvez contourner ce problème en excluant le propriétaire de la fonction de politique de la politique de la table référencée.
• Time travel ne fonctionne pas avec la sécurité au niveau des lignes ou les masques de colonne. Dans les configurations ABAC, les utilisateurs qui sont explicitement exclus d'une politique peuvent toujours exécuter des queries time travel sur les données sous-jacentes.
• Les clones profonds et superficiels ne sont pas pris en charge sur les tables qui ont une sécurité au niveau des lignes ou des masques de colonne. Dans les configurations ABAC, les utilisateurs qui sont explicitement exclus d'une politique peuvent toujours effectuer des opérations de clonage sur les données sous-jacentes.
• Vous ne pouvez pas créer un index de recherche IA à partir d'une table à laquelle des filtres de lignes ou des masques de colonnes ont été appliqués.
• Les masques de colonne ne peuvent pas être appliqués aux colonnes référencées par des colonnes générées. Consultez Colonnes générées et masques de colonne.

Limitation du mode d'accès dédié

Vous ne pouvez pas accéder à une table avec des filtres de lignes ou des masques de colonnes à partir d’une ressource de compute avec accès dédié sur Databricks Runtime 15.3 ou version inférieure. Vous pouvez utiliser le mode d'accès dédié sur Databricks Runtime 15.4 LTS ou supérieur si votre Workspace est activé pour le compute Serverless. Cependant, seules les opérations de lecture sont prises en charge sur Databricks Runtime 15,4 à 16,2. Les opérations d'écriture (y compris INSERT, UPDATE et DELETE) nécessitent Databricks Runtime 16,3 ou une version ultérieure et doivent utiliser des modèles pris en charge tels que MERGE INTO.

Lorsque vous interrogez des tables avec des filtres de ligne ou des masques de colonne à partir du compute en mode d'accès dédié, Databricks utilise le compute serverless pour appliquer des contrôles d'accès précis (FGAC). Par conséquent, toutes les limitations et considérations du FGAC s'appliquent. Consultez le contrôle d'accès fin sur le compute dédié.

FGAC utilise Cloud Fetch pour écrire des jeux de résultats temporaires dans le stockage interne du Workspace. Si le versioning de votre compartiment S3 est activé, cela peut entraîner une croissance exponentielle du stockage. Voir les Considérations sur la gestion des versions des compartiments S3 pour les recommandations de configuration.