メインコンテンツまでスキップ

行フィルターと列マスクを手動で適用する

このページでは、行フィルター、列マスク、マッピング テーブルを使用してテーブル内の機密データをフィルター処理するためのガイダンスと例を示します。これらの機能には Unity Catalog が必要です。フィルター処理とマスキングに対する一元化されたタグベースのアプローチを探している場合は、「 Unity Catalog 属性ベースのアクセス制御 (ABAC)」を参照してください。ABAC を使用すると、管理されたタグを使用してポリシーを管理し、多くのテーブルに一貫して適用できます。

始める前に​

テーブルに行フィルターと列マスクを追加するには、次のものが必要です。

  • Unity Catalog が有効になっているワークスペース。
  • Unity Catalog に登録されている関数。この関数は、SQL UDF、または Unity Catalog に登録され、SQL UDF でラップされた Python または Scala UDF にすることができます。詳細については、「ユーザー定義関数 (UDF) とは」、「列 mask 句」、および「ROW FILTER句」を参照してください。

また、次の要件を満たす必要があります。

  • 行フィルターまたは列マスクをテーブルに追加する関数を割り当てるには、関数のEXECUTE権限、スキーマのUSE SCHEMA権限、親カタログのUSE CATALOG権限が必要です。
  • 新しい テーブルの作成時にフィルターまたはマスクを追加する場合は、スキーマに対するCREATE TABLE権限が必要です。
  • 既存の テーブルにフィルターまたはマスクを追加する場合は、テーブルの所有者であるか、テーブルに対するMANAGE権限を持っている必要があります。

行フィルターや列マスクのあるテーブルにアクセスするには、コンピュートリソースが次の要件のいずれかを満たしている必要があります。

  • SQLウェアハウス。
  • Databricks Runtime 12.2 LTS 以降の標準アクセス モード (以前の共有アクセス モード)。
  • Databricks Runtime 15.4 LTS 以降の専用アクセス モード (以前のシングル ユーザー アクセス モード)。

Databricks Runtime 15.3以下では、専用コンピュートを使用して行フィルターや列マスクを読み込むことはできません。

Databricks Runtime 15.4 LTS以降で提供されているデータフィルタを利用するには、行フィルタと列マスクをサポートするデータフィルタ機能がサーバレスコンピュートで実行されるため、ワークスペースがサーバレスコンピュートに対して有効になっていることも確認する必要があります。専用アクセスモードとして設定されたコンピュートを使用して、行フィルタまたは列マスクを使用するテーブルを読み取る場合、サーバレス コンピュート リソースに対して課金されることがあります。 これらのテーブルへの書き込み操作は、DBR 16.3 以降でのみサポートされ、 MERGE INTOなどのサポートされているパターンを使用する必要があります。専用コンピュートのきめ細かなアクセス制御を参照してください。

注記

行フィルターと列マスクは、テーブルを置き換えるときに保持されます。

REPLACE TABLEを実行すると、スキーマの変更に関係なく、既存の行フィルターが保持されます。新しいテーブルに、元のテーブルにマスクがあった列と同じ名前の列が含まれている場合も、列マスクは保持されます。どちらの場合も、ポリシーは明示的に再定義されていなくても保持されます。これにより、データ アクセス ポリシーが誤って失われるのを防ぎます。

ただし、保持ポリシーが削除または変更された列を参照している場合、後続のクエリは失敗する可能性があります。これを解決するには、 を使用してポリシーを更新または削除します ALTER TABLE。

行フィルターを適用する​

行フィルターを作成するには、フィルターポリシーを定義する関数 (UDF) を記述し、それをテーブルに適用します。各テーブルに設定できる行フィルターは1つだけです。行フィルターは0個以上の入力パラメーターを受け入れます。各入力パラメーターは対応する表の1つの列にバインドされます。

行フィルターは、カタログ エクスプローラーまたは SQL コマンドを使用して適用できます。カタログ エクスプローラーの手順では、関数を既に作成し、Unity Catalog に登録していることを前提としています。SQL 命令には、行フィルター関数を作成してテーブルに適用する例が含まれています。

注記

Lakeflow 宣言型パイプラインを使用している場合は、Lakeflow 宣言型パイプライン Python APIを使用して、行フィルターと列マスクを使用するストリーミングテーブルまたはマテリアライズドビューを作成できます。行フィルターと列マスクを使用したテーブルのパブリッシュを参照してください。

  1. Databricks ワークスペースで、データアイコン。 カタログ をクリックします。
  2. フィルタリングするテーブルを参照または検索します。
  3. [ 概要 ] タブの [行フィルター] で、[ フィルターの追加 ] をクリックします。
  4. [ 行フィルターを追加 ] ダイアログで、フィルター機能を含むカタログとスキーマを選択し、関数を選択します。
  5. 展開されたダイアログで関数定義を表示して、関数ステートメントに含まれる列と一致するテーブル列を選択します。
  6. [ 追加 ] をクリックします。

テーブルからフィルターを削除するには、[ fx行フィルター ] をクリックして [ 削除 ] をクリックします。

行フィルターの例​

この例では、USリージョンのadminグループのメンバーに適用されるSQLユーザー定義関数を作成します。

このサンプル関数をsalesテーブルに適用すると、adminグループのメンバーはテーブル内のすべてのレコードにアクセスできます。関数が管理者以外の人によって呼び出された場合、RETURN_IF条件は失敗し、region='US'式が評価され、USリージョンのレコードのみが表示されるようにテーブルがフィルタリングされます。

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

関数を行フィルターとしてテーブルに適用します。salesテーブルからの後続のクエリでは、行のサブセットが返されます。

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

行フィルターを無効にします。今後、salesテーブルからユーザーがクエリーを実行すると、テーブル内のすべての行が返されます。

SQL
ALTER TABLE sales DROP ROW FILTER;

CREATE TABLEステートメントの一部として、行フィルターとして関数を適用したテーブルを作成します。salesテーブルからの以降のクエリーは、それぞれ行のサブセットを返します。

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

列マスクを適用する​

列マスクを適用するには、関数 (UDF) を作成し、それをテーブル列に適用します。

列マスクは、カタログ・エクスプローラーまたは SQL コマンドを使用して適用できます。カタログ エクスプローラーの手順では、関数を既に作成し、Unity Catalog に登録していることを前提としています。SQL 命令には、列マスク関数を作成し、それをテーブル列に適用する例が含まれています。

注記

Lakeflow 宣言型パイプラインを使用している場合は、Lakeflow 宣言型パイプライン Python APIを使用して、行フィルターと列マスクを使用するストリーミングテーブルまたはマテリアライズドビューを作成できます。行フィルターと列マスクを使用したテーブルのパブリッシュを参照してください。

  1. Databricks ワークスペースで、データアイコン。 カタログ をクリックします。
  2. テーブルを参照または検索します。
  3. [ 概要 ] タブで、列マスクを適用する行を見つけて、[ 編集アイコン マスク ] 編集アイコンをクリックします。
  4. [ 列マスクを追加 ] ダイアログで、フィルター関数を含むカタログとスキーマを選択し、関数を選択します。
  5. 展開されたダイアログで、関数定義を表示します。マスクされる列に加えて、関数にパラメーターが含まれている場合は、それらの追加関数パラメーターをキャストするテーブル列を選択します。
  6. [ 追加 ] をクリックします。

テーブルから列マスクを削除するには、テーブル行の fx列マスク をクリックし、[ 削除 ] をクリックします。

列マスクの例​

この例では、ssn列をマスクするユーザー定義関数を作成して、HumanResourceDeptグループのメンバーであるユーザーのみがその列の値を表示できるようにします。

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

新しい関数を列マスクとしてテーブルに適用します。列マスクは、テーブルの作成時または後で追加できます。

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;

クエリーを実行するユーザーがHumanResourceDeptグループのメンバーでない場合、そのテーブルに対するクエリーではマスクされたssn列の値が返されるようになりました。

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

列マスクを無効にして、クエリーがssn列の元の値を返すようにするには、次の手順を実行します。

SQL
ALTER TABLE users ALTER COLUMN ssn DROP MASK;

マッピング・テーブルを使用してアクセス制御リストを作成する​

行レベルのセキュリティーを実現するには、マッピング・テーブル (またはアクセス制御リスト) を定義することを検討してください。包括的なマッピング テーブルは、元のテーブル内のどのデータ行が特定のユーザーまたはグループからアクセスできるかをエンコードします。マッピング テーブルは、直接結合を通じてファクト テーブルと簡単に統合できるため便利です。

この方法論は、カスタム要件を含む多くのユースケースに対応します。例としては、次のようなものがあります。

  • ログインしたユーザーに基づいて制限を課し、特定のユーザーグループに対して異なるルールに対応する。
  • 組織構造など、多様なルールセットを必要とする複雑な階層を作成します。
  • 外部ソースシステムからの複雑なセキュリティモデルを複製する。

マッピング テーブルを採用することで、これらの困難なシナリオを実現し、堅牢な行レベルおよび列レベルのセキュリティ実装を確保できます。

マッピングテーブルの例​

マッピングテーブルを使用して、現在のユーザーがリストにあるかどうかを確認します。

SQL
USE CATALOG main;

新しいマッピングテーブルを作成します。

SQL
DROP TABLE IF EXISTS valid_users;

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

新しいフィルターを作成します。

注記

呼び出し元として実行されるユーザーコンテキストをチェックする関数(たとえば、 CURRENT_USER 関数や IS_ACCOUNT_GROUP_MEMBER 関数)を除き、すべてのフィルターは定義者の権限で実行されます。

この例では、関数は現在のユーザーが valid_users テーブルにいるかどうかをチェックします。ユーザーが見つかった場合、関数は 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()
);

次の例では、テーブルの作成時に行フィルターを適用します。後で ALTER TABLE ステートメントを使用してフィルターを追加することもできます。未指定の列にフィルターを適用する場合は、 ON () 構文を使用します。特定の列には、 ON (column);を使用します。詳細については、「 パラメーター」を参照してください。

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

テーブルからデータを選択します。このデータは、ユーザーがvalid_usersテーブルにいる場合にのみ返されます。

SQL
SELECT * FROM data_table;

列の値に関係なく、常にテーブルのすべての行を表示できるアカウントを含むマッピングテーブルを作成します。

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

次に、行内のすべての列の値が 5 未満の場合、または呼び出し元のユーザーが上記のマッピング テーブルのメンバーであるかどうかに true を返す SQL UDF を作成します。

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

最後に、SQL UDFを行フィルターとしてテーブルに適用します。

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

サポートと制限事項​

行フィルターと列マスクは、すべてのDatabricks機能、あるいはすべてのコンピュートリソースでサポートされているとは限りません。このセクションでは、サポートされている機能と制限事項を紹介します。

サポートされている機能と形式​

このサポートされている機能のリストは、すべてを網羅しているわけではありません。一部、パブリックプレビュー中にサポートされなかったためにリストされているアイテムもあります。

  • すべての言語ワークロードの Databricks SQL と Databricks ノートブックがサポートされています。

  • MODIFY権限を持つユーザーによるDMLコマンドがサポートされています。フィルターとマスクは、 UPDATE ステートメントと DELETE ステートメントによって読み取られたデータに適用され、書き込まれたデータ ( INSERTを含む) には適用されません。

  • サポートされているデータ形式は以下の通りです。

    • マネージドテーブルと外部テーブル用の Delta と Parquet。
    • レイクハウスフェデレーションを使用してUnity Catalogに登録されたフォーリンテーブルの他の複数のデータ形式。

  • ポリシーパラメーターには、定数式（文字列、数値、区間、ブーリアン、ヌル）を含めることができます。

  • SQL、Python、Scala UDF は、Unity Catalog に登録されている場合、行フィルターまたは列マスク関数としてサポートされます。 Python と Scala の UDF は SQL UDF でラップする必要があります。

  • 列マスクや行フィルターを参照するテーブルにビューを作成できますが、列マスクや行フィルターをビューに追加することはできません。

  • チェンジデータフィードDelta Lake、スキーマがターゲット表に適用される行フィルターおよび列マスクと互換性がある場合にサポートされます。

  • フォーリンテーブルがサポートされています。

  • テーブルサンプリングはサポートされています。

  • MERGE ステートメントは、ソース表、ターゲット表、またはその両方が行フィルタと列マスクを使用する場合にサポートされます。これには、単純なサブクエリを含む行フィルター関数を持つテーブルが含まれます。制限事項については、次のセクションに示します。

  • Databricks SQL マテリアライズドビューとDatabricks SQLストリーミングテーブルでは、行フィルターと列マスクがサポートされています (パブリック プレビュー):

    • 行フィルターと列マスクは、 Databricks SQL マテリアライズドビューまたはストリーミングテーブルに追加できます。 マスクの追加は、マテリアライズドビューまたはストリーミングテーブルが定義されているときに宣言的に行う必要があります。「CREATE MATERIALIZED VIEW」または「CREATE STREAMING TABLE」を参照してください。
    • 行フィルターと列マスクを含むテーブルで、Databricks SQLマテリアライズドビューまたはストリーミングテーブルを定義できます。

  • 宣言型パイプラインで宣言および公開されているマテリアライズドビュー とストリーミングテーブル Lakeflow 行フィルターまたは列マスクのサポート (パブリック プレビュー):

    • 行フィルターと列マスクは、 Lakeflow 宣言型パイプライン、マテリアライズドビュー、またはストリーミングテーブルに追加できます。
    • 行フィルターと列マスクを含むテーブルで、 Lakeflow 宣言型パイプライン マテリアライズドビュー または ストリーミングテーブルを定義できます。

    行フィルターと列マスクを使用したテーブルのパブリッシュを参照してください。

パフォーマンスに関する推奨事項​

行フィルターと列マスクは、フィルター処理とマスキング操作の前にユーザーがベース表の値の内容を表示できないようにすることで、データの可視性を制御します。これらは、一般的なユースケースでのクエリに応答して適切に機能します。あまり一般的ではないアプリケーションでは、クエリ エンジンがクエリ パフォーマンスの最適化と、フィルター処理/マスクされた値からの情報漏洩からの保護のどちらかを選択する必要があるため、クエリ パフォーマンスに何らかの影響を犠牲にして、常に安全な決定を行います。このパフォーマンスへの影響を最小限に抑えるには、次の推奨事項を適用します。

  • 単純なポリシー関数を使用する: 式が少ないポリシー関数は、多くの場合、複雑な式よりもパフォーマンスが優れています。 単純な CASE 関数を優先して、マッピング テーブルと式サブクエリの使用は避けてください。
  • 関数引数の数を減らします。 Databricks は、ポリシー関数の引数から生じるソース テーブルへの列参照を、これらの列がクエリで使用されていない場合でも最適化できません。引数の少ないポリシー関数を使用すると、これらのテーブルからのクエリのパフォーマンスが向上します。
  • AND 接続詞が多すぎる行フィルターを追加しないでください。 各テーブルは最大で 1 つの行フィルターの追加しかサポートしていないため、一般的なアプローチは、複数の目的のポリシー関数を ANDと組み合わせることです。ただし、接続ごとに、接続に、パフォーマンスに影響を与える可能性のあるこの表の他の場所で言及されているコンポーネント (マッピング テーブルなど) が含まれている可能性が高くなります。パフォーマンスを向上させるために、使用する接続詞の数を減らします。
  • テーブルポリシーでエラーをスローできない決定論的式を使用し、これらのテーブルからのクエリを使用します。 ANSI 除算など、指定された入力が無効な場合、一部の式でエラーがスローされる場合があります。このような場合、SQL コンパイラは、フィルター処理やマスキング操作の前に値に関する情報を明らかにする "ゼロ除算" などのエラーの可能性を回避するために、これらの式 (フィルターなど) を含む操作をクエリ プランの下に押しすぎないようにする必要があります。この例の try_divide のように、エラーをスローしない決定論的な式を使用します。
  • テーブルに対してテストクエリを実行してパフォーマンスを測定する： 行フィルタや列マスクを使用して、テーブルに期待される作業負荷を表す現実的なクエリを構築し、パフォーマンスを測定します。フィルタリングとマスキングロジックのパフォーマンスと表現力のバランスが取れるまでポリシー関数を少しずつ修正し、その効果を観察してください。

制限​

  • 12.2 LTS以前のDatabricks Runtimeバージョンでは、行フィルターまたは列マスクはサポートされません。これらのランタイムは安全に失敗します。つまり、サポートされていないバージョンのランタイムのテーブルにアクセスしようとしても、データは返されません。
  • Delta Sharing は、行レベルのセキュリティまたは列マスクでは機能しません。ただし、行レベルのセキュリティまたは列マスクを持つテーブルに依存するデータ資産を共有できます。
  • カタログ Iceberg REST Unity REST API を使用して、行フィルターや列マスクを持つテーブルにアクセスすることはできません。
  • ビューに行レベルのセキュリティまたは列マスクを適用することはできません。
  • タイムトラベルは、行レベルのセキュリティまたは列マスクでは機能しません。
  • ポリシーを持つテーブル内のファイルへの、パスベースのアクセスはサポートされていません。
  • 元のポリシーに戻る循環依存性を持つ行フィルターまたは列マスクポリシーはサポートされていません。
  • ディープ・クローンとシャロー・クローンは、行レベルのセキュリティまたは列マスクを持つ表ではサポートされません。
  • MERGE ステートメントは、ネスト、集計、ウィンドウ、制限、または非決定論的関数を含む行フィルターまたは列マスクポリシーを持つテーブルをサポートしません。
  • Delta Lake APIはサポートされていません。

専用アクセスモードの制限​

Databricks Runtime 15.3 以前の専用アクセス コンピュート リソースから、行フィルターまたは列マスクを持つテーブルにアクセスすることはできません。Databricks Runtime 15.4 LTS以降では、ワークスペースがサーバレス コンピュートで有効になっている場合、専用アクセスモードを使用できます。ただし、読み取り操作のみが Databricks Runtime 15.4 から 16.2 でサポートされています。書き込み操作 ( INSERT、 UPDATE、 DELETEを含む ) には DBR 16.3 以降が必要であり、 MERGE INTOなどのサポートされているパターンを使用する必要があります。

詳細については、 情報 「専用コンピュートでのきめ細かなアクセス制御」を参照してください。

に最終更新