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

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

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

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

The following SQL example shows how a provider adds a simple custom template to a clean room:

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 %};
  $$
);

This template takes four required parameters (my_table array, source_table array, consumer_id column name, and provider_id column name) and an optional where_clause parameter that specifies a WHERE clause.

In most templates, including the previous example, column names provided by the user must be fully qualified with the table name to avoid column name conflicts. This is because it is not easy to concatenate a table name prefix to a column name in the prefix and get a valid identifier (IDENTIFIER(p.{{ col_name | sqlsafe }}) is an error). Therefore, you might need the caller to provide a fully qualified table name rather than just a column name. Table names should use the approved lowercases p and c aliases.

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

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

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

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

You can call consumer.get_arguments_from_template to parse and list the variables used in a template. However, for large or complex templates this procedure might not list all template variables, so be sure to provide helpful documentation for your template users.

The following example shows how a consumer runs the provider's custom template shown previously:

 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',  -- Populates the consumer_id variable.
  'provider_id', 'p.hashed_email',  -- Populates the provider_id variable.
  'where_clause','c.status = $$MEMBER$$ AND c.age_band > 30' -- Populates the where_clause variable.
                                                             -- $$...$$ is used to stringify the column value.
  )
);

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

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

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

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

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

Here is a full code example showing how a consumer can submit and run a custom template. Upload the following worksheet files into your Snowflake account. You need two separate accounts with the clean rooms API installed to run the code; one account to act as the provider and the other to act as the consumer.

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

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

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