Using the developer APIs to send results to a Snowflake account for activation¶

Create a template for provider activation¶

A template used to activate results is similar to a template used to run an analysis. For example, it is added to the clean room with the provider.add_custom_sql_template command like an analysis template. However, an activation template has the following important differences:

• Name of the activation template must begin with the string activation. For example, an activation template named activation_my_template meets the requirement.

• Activation template must create a table with a name that conforms to specific conventions and explicitly returns the table name.

Define the table in an activation template¶

To hold the activation results in the clean room, every activation template must create a table. There are two requirements for this table:

• Name of the table must begin with the string cleanroom.activation_data_. For example, a table named cleanroom.activation_data_analysis_results meets the requirement.

• The portion of the template definition that creates the table must return the string that was appended to cleanroom.activation_data_ to form the name of the table. For example, if the table name is cleanroom.activation_data_analysis_results, then the string analysis_results must be returned.

The following is an example of what must be included in the template definition to define a table and export it:

BEGIN
  CREATE OR REPLACE TABLE cleanroom.activation_data_analysis_results AS
    SELECT * FROM identifier({{ my_table[0] }})
  RETURN 'analysis_results';
END;

For more information about the calling the provider.add_custom_sql_template command to add an activation template to a clean room, see Snowflake Data Clean Rooms: Provider API reference guide.

Link the required table (Provider activation only)¶

If the provider or consumer is going to push results to the provider’s Snowflake account, the provider must link the samooha_by_snowflake_local_db.library.temp_public_key table into the clean room. For example, to link the required table into a clean room my_activation_cleanroom, execute:

CALL samooha_by_snowflake_local_db.provider.link_datasets(
    'my_activation_cleanroom',
    ['samooha_by_snowflake_local_db.library.temp_public_key']);

The provider could also use a single call to link the required table when linking their other tables and views.

Set an activation policy¶

An activation policy defines which columns can be used in activation templates. This can be used with activation templates to ensure that only the columns that are approved by the provider can be used with the activation template.

A provider uses the provider.set_activation_policy API to set the activation policy. For example:

CALL samooha_by_snowflake_local_db.provider.set_activation_policy('my_cleanroom', [
    'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE_NAME.DEMO.CUSTOMERS:HASHED_EMAIL',
    'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE_NAME.DEMO.CUSTOMERS:STATUS',
    'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE_NAME.DEMO.CUSTOMERS:AGE_BAND',
    'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE_NAME.DEMO.CUSTOMERS:DAYS_ACTIVE',
    'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE_NAME.DEMO.CUSTOMERS:REGION_CODE' ]);

Enable consumer activation (Consumer-run analyses only)¶

If the consumer is going to push results to their own account, the provider must execute the provider.enable_template_for_consumer_activation API. For example:

CALL samooha_by_snowflake_local_db.provider.enable_template_for_consumer_activation(
    'my_cleanroom', 'activation_my_template');

Request permission from the consumer (Provider activation only)¶

If the provider configures the activation template to allow themselves or the consumer to push results to the provider’s Snowflake account, the provider must execute the provider.request_provider_activation_consent API. This API requests that the consumer approve the template for this purpose. For example,

CALL samooha_by_snowflake_local_db.provider.request_provider_activation_consent('my_cleanroom', 'activation_my_template');

The consumer has to approve the request before the provider can activate the results of a provider-run analysis.

Set up activation in the web app (Optional)¶

If the provider is creating a user interface for the clean room so users can run analyses in the web app, they can also configure the clean room so users can activate the results using the Activation Hub in the web app. When the provider executes the provider.add_ui_form_customizations API to create the user interface, they specify the name of the activation template and whether the template is being used for provider activation, consumer activation, or both.

For example, the following example allows users to use the Activation Hub for both provider activation and consumer activation.

CALL samooha_by_snowflake_local_db.provider.add_ui_form_customizations(
    $cleanroom_name,
    'prod_test_references_1',
    {
      'display_name': 'PROD TEST REFERENCE FIRST',
      'description': 'Use our customized ML techniques to find lookalike audiences.',
      'methodology': 'Specify your own seed audience, while matching against our users. Then customize the lookalike model across number of boosting rounds and removing outliers.',
      'render_table_dropdowns': {
          'render_consumer_table_dropdown': TRUE,
          'render_provider_table_dropdown': TRUE
        },
     'activation_template_name': 'activation_my_template',
     'enabled_activations': ['consumer', 'provider']
    },
    {
    'reference_provider_join': {
        'display_name': 'Provider join column',
        'order': 4,
        'description': 'Which provider col do you want to join on',
        'size': 'S',
        'group': 'Seed Audience Selection',
        'references': ['PROVIDER_JOIN_POLICY'],
        'provider_parent_table_field': 'source_table',
        'type': 'dropdown'
    },
    'reference_consumer_join': {
        'display_name': 'Consumer join column',
        'order': 4,
        'description': 'Which consumer col do you want to join on',
        'size': 'S',
        'group': 'Seed Audience Selection',
        'references': ['CONSUMER_COLUMNS'],
        'consumer_parent_table_field': 'my_table',
        'type': 'dropdown'
    }
  },
  {
    'measure_columns': ['count'],
    'default_output_type': 'BAR'
  });

Set activation policy¶

An activation policy defines which columns can be used within activation templates. This policy can be used with activation templates to ensure that only the columns that are approved by the consumer can be used with the activation template.

A consumer uses the consumer.set_activation_policy API to set the activation policy. For example:

CALL samooha_by_snowflake_local_db.consumer.set_activation_policy('my_cleanroom', [
    'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE_NAME.DEMO.CUSTOMERS:HASHED_EMAIL',
    'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE_NAME.DEMO.CUSTOMERS:REGION_CODE' ]);

Approve the provider’s request (Provider activation only)¶

If the provider executed the provider.request_provider_activation_consent API for an activation template intended to be used to send results to the provider’s Snowflake account, then the consumer must approve the request. This approval is required regardless of whether it is the provider or the consumer who is sending the results to the provider’s account.

If the consumer is using the web app, installing the clean room provides the consent that the provider needs.

If the consumer is using the developer APIs, the consumer executes the consumer.approve_provider_activation_consent API. For example:

CALL samooha_by_snowflake_local.consumer.approve_provider_activation_consent('my_cleanroom', 'activation_my_template');