クリーンルームにカスタムテンプレートを追加する¶

プロバイダー記述のテンプレートを追加する¶

プロバイダーは、provider.add_custom_sql_template を呼び出すことでカスタムテンプレートを一度に1つ追加し、テンプレート JinjaSQL を文字列として渡します。カスタムテンプレートはクリーンルームのテンプレートリストに表示され、Snowflakeが提供するテンプレートと同じように動作します。クリーンルームには、カスタムテンプレートとSnowflakeが提供するテンプレートを自由に組み合わせて含めることができます。

呼び出すテンプレート用に カスタムPython UDFs をアップロードすることもできます。

以下の例は、プロバイダーがカスタムテンプレートをクリーンルームに追加する方法を示しています。

CALL samooha_by_snowflake_local_db.provider.add_custom_sql_template(
    $cleanroom_name,
    $basic_template_name,
    $$
    SELECT
      COUNT(*) AS total_count
    FROM IDENTIFIER({{ my_table[0] }}) AS c
      INNER JOIN IDENTIFIER({{ source_table[0] }}) AS p
      ON IDENTIFIER({{ consumer_id | join_policy }}) = IDENTIFIER({{ provider_id | join_policy }})
    {% if where_clause %}
    WHERE {{ where_clause | sqlsafe }}
    {% endif %};
  $$
);

前述の例を含め、ほとんどのテンプレートでは、列名の競合を避けるために、列名はテーブル名で完全修飾されていなければなりません。これは、テーブル名プレフィックスをプレフィックスの列名に連結し、有効な識別子を取得するのが簡単ではないためです（IDENTIFIER(p.{{col_name | sqlsafe }}) はエラー）。そのため、呼び出し元に列名だけではなく、完全修飾テーブル名を提供するように求める必要があります。テーブル名には承認された p および c エイリアスを使用する必要があります。

プロバイダー記述テンプレートを実行する¶

クリーンルーム API を使用する場合、コンシューマーは consumer.run_analysis を呼び出してテンプレートを実行し、プロバイダーは プロバイダー実行の分析 のために provider.submit_analysis_request を呼び出します。

クリーンルーム UI でテンプレートを実行できるようにしたい場合、プロバイダーはテンプレート用の ユーザー入力フォームを作成 する必要があります。クリーンルーム UI では、プロバイダー記述のテンプレートのみを実行できます。

プロバイダーが テンプレートを難読化 <dcr_provider_add_custom_sql_template>`しない限り、クリーンルームのコラボレーターは ``consumer.view_template_definition` を呼び出して、クリーンルーム内のテンプレートの JinjaSQL を確認できます。難読化できるのは、プロバイダー記述のテンプレートのみです。

consumer.get_arguments_from_template を呼び出して、テンプレートで使用される変数を解析してリスト化できます。ただし、大規模なテンプレートまたは複雑なテンプレートの場合、この手順ではすべてのテンプレート変数がリスト化されない可能性があるため、テンプレートユーザーに役立つドキュメントを提供するようにしてください。

次の例は、コンシューマーが先ほど示したプロバイダーのカスタムテンプレートをどのように実行するかを示しています。

 CALL samooha_by_snowflake_local_db.consumer.run_analysis(
  $cleanroom_name,
  'basic_template',
  ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS'],  -- Populates the my_table array.
  ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS'],  -- Populates the source_table array.
  OBJECT_CONSTRUCT(
  'consumer_id', 'c.hashed_email',  -- hashed_email column from the consumer's table.
  'provider_id', 'p.hashed_email',  -- hashed_email column from the provider's table.
  'where_clause','c.status = $$MEMBER$$ AND c.age_band > 30' -- $$...$$ is used to stringify the column value.
  )
);

プロバイダーテンプレートのサンプルコード¶

以下は、プロバイダーがカスタムテンプレートを追加する方法と、コンシューマーがそれを実行する方法を示した完全なコード例です。コードを実行するには、クリーンルーム API がインストールされた2つの別々のアカウントが必要です。1つのアカウントはプロバイダーとして機能し、もう1つのアカウントはコンシューマーとして機能します。

• プロバイダーサンプルコード

• コンシューマーサンプルコード

コンシューマーテンプレートの例¶

以下は、コンシューマーがカスタムテンプレートを送信し、実行する方法を示した完全なコード例です。次のワークブックファイルをSnowflakeアカウントにアップロードします。コードを実行するには、クリーンルーム API がインストールされた2つの別々のアカウントが必要です。1つのアカウントはプロバイダーとして機能し、もう1つのアカウントはコンシューマーとして機能します。

• プロバイダーサンプルコード

• コンシューマーサンプルコード

source_table および my_table を入力する¶

標準的な source_table および my_table テンプレート変数は以下のように入力できます。

• デフォルトのテーブルセレクタードロップダウンメニューを有効にする： これらのドロップダウンメニューは単一選択です。render_provider_table_dropdown および render_consumer_table_dropdown 設定を使用して、ドロップダウンメニューを表示または非表示にできます。ドロップダウンメニューは、完全修飾テーブル名を source_table および my_table テンプレート変数それぞれに渡します。

列名を修飾する¶

ほとんどのテンプレートでは、列名のあいまいさを避けるために、すべての列名が完全修飾されている必要があります。

テンプレートはすべてのテーブルを p または c としてエイリアスする必要があります。これは、プロバイダーかコンシューマーテーブルかによって異なります。テンプレートは、p または c エイリアスを使用してすべての列を参照する必要があります。エイリアスの詳細はご参照ください。

ドロップダウンの列セレクターを作成する場合は、ドロップダウンメニューの choices 配列で p または c テーブルエイリアスを明示的に指定するか、テンプレートにエイリアスを追加する必要があります。

以下の例は、ドロップダウンメニューでテーブルエイリアスを指定する方法を示しています。

  'provider_join_col': {
    'display_name': 'Provider Join Column',
    'choices': ['p.HASHED_EMAIL', 'p.HASHED_SSN'],
    'type': 'dropdown',
    'description': 'Select the provider column to join users on.',
    'infoMessage': 'We recommend using HASHED_EMAIL.',
    'size': 'M',
    'group': 'Enable Provider Features'
}

ただし、すべての列名を事前に知る必要があるため、この方法には限界があります。

代わりに、references プロパティを指定することで、列のドロップダウンメニューを動的に入力できます。しかし、そのようなセレクターは、そのままの列名を返します。たとえば、完全修飾列名の p.hashed_email ではなく hashed_email を返します。そのままの列名が返される場合は、テンプレートで明示的に列をテーブルのスコープに含める必要があります。たとえば、次のコードは、ユーザーがプロバイダーの結合ポリシーから列を選択できるドロップダウンメニューを作成します。

'p_join_col': {
  'type': 'dropdown',
  'references': ['PROVIDER_JOIN_POLICY']
}

Copy

テンプレートで列名を使用するには、次の例で示されているように、テンプレートが列名の前にテーブルエイリアスをハードコーディングする必要があります。

SELECT p.{{ p_join_col | sqlsafe }} FROM table_col AS p;

Copy

クリーンルーム UI で実行できるテンプレートの開発に関する推奨事項¶

以下のステップは、クリーンルーム UI で実行できるテンプレートを開発するための推奨ワークフローを示しています。

SELECT {{ col1 | sqlsafe | column_policy }}, {{ col2 | sqlsafe | column_policy }}
  FROM IDENTIFIER({{ source_table[0] }}) AS p
  JOIN IDENTIFIER({{ my_table[0] }}) AS c

SELECT
  {{ col1 | default('Undefined')}},
  {{ col2 | default('Undefined') }},
  {{ source_table[0] | default('Undefined') }},
  {{ my_table[0] | default('Undefined') }},
  {{ provider_join_col | default('Undefined') }},
  {{ consumer_join_col | default('Undefined') }}
;