Using the developer API to add consumer-defined templates¶

Send requests to a provider¶

A consumer executes the consumer.create_template_request command to send a request to the provider of a clean room. This request includes the name of the template along with the Jinja code that defines the template.

For example, suppose the provider shared a clean room dcr_cleanroom with a consumer. The consumer wants to add a template named my_overlap_analysis to the clean room. To send a request to the provider of the clean room, the consumer executes the following command:

CALL samooha_by_snowflake_local_db.consumer.create_template_request('dcr_cleanroom',
  'my_analysis',
  $$
  SELECT
      identifier({{ dimensions[0] | column_policy }})
  FROM
      identifier({{ my_table[0] }}) c
    INNER JOIN
      identifier({{ source_table[0] }}) p
        ON
          c.identifier({{ consumer_id  }}) = identifier({{ provider_id | join_policy }})
       {% if where_clause %} where {{ where_clause | sqlsafe | join_and_column_policy }} {% endif %};
  $$);

The third argument is the Jinja code that defines the template.

For reference documentation for the consumer.create_template_request command, see the Consumer-defined Templates section in Snowflake Data Clean Rooms: Consumer API reference guide.

Check for new requests from consumers¶

To check for new requests from consumers, a provider executes the provider.list_template_requests command, then parses the results to identify requests with a status of PENDING. A PENDING status indicates that the consumer has sent a new request that the provider has not taken action upon. The response to provider.list_template_requests includes the Jinja code of the template, which lets the provider decide whether they want to approve or reject the request.

For example, suppose the name of the provider’s clean room is dcr_cleanroom. To check whether the consumer has sent a new request to add a template, the provider executes the following commands:

CALL samooha_by_snowflake_local_db.provider.list_template_requests('dcr_cleanroom');

SELECT * FROM TABLE(RESULT_SCAN(LAST_QUERY_ID())) WHERE status = 'PENDING';

The response to the provider.list_template_requests command includes the following for every template request:

• UUID that uniquely identifies the request.

• Consumer account that sent the request, in the account locator format.

• Template name, which was specified by the consumer when they sent the request.

• Jinja code that defines the template.

• Status of the request, which can be one of PENDING, APPROVED, or REJECTED.

For reference documentation for the provider.list_template_requests command, see the Consumer-defined Templates section in Snowflake Data Clean Rooms: Provider API reference guide.

Approve or reject a request¶

After receiving a request to add a consumer-defined template, the provider decides whether to approve or reject the request.

Approve a request

Providers execute the provider.approve_template_request command to approve a request to add a template. The provider specifies which template to approve by passing the request identifier as an argument.

For example, suppose the name of the provider’s clean room is dcr_cleanroom and the consumer’s request to add a template was assigned the identifier 01b4d41d-0001-b572. To approve the request and add the template to the clean room, the provider executes the following command:

CALL samooha_by_snowflake_local_db.provider.approve_template_request('dcr_cleanroom',
  '01b4d41d-0001-b572');

Reject a request

Providers execute the provider.reject_template_request command to reject a request to add a template. The provider specifies which template to reject by passing the request identifier as an argument.

For example, suppose the name of the provider’s clean room is dcr_cleanroom and the consumer’s request to add a template was assigned the identifier 01b4d41d-0001-b572. After examining the Jinja template, the provider determines that it introduces a security risk into the clean room, so they want to reject the request with a descriptive reason. To reject the request to add the template, the provider executes the following command:

CALL samooha_by_snowflake_local_db.provider.reject_template_request('dcr_cleanroom',
  '01b4d41d-0001-b572',
  'Failed security assessment');

For reference documentation for the provider.approve_template_request and provider.reject_template_request commands, see the Consumer-defined Templates section in Snowflake Data Clean Rooms: Provider API reference guide.

Check status of request as a consumer¶

At any time, the consumer can execute the consumer.list_template_requests command to check the status of their request to add a template. The command returns the following information:

• UUID that uniquely identifies the request.

• Provider account to which the request was sent, in the account locator format.

• Template name, which was specified by the consumer when they sent the request.

• Jinja code that defines the template.

• Status of the request, which can be one of PENDING, APPROVED, or REJECTED.

• If the request was rejected, the reason for the provider’s action.

For example, suppose the consumer sent a request to add a template to the dcr_cleanroom clean room. To check the status of the request to determine if it was approved, the consumer executes the following command:

CALL samooha_by_snowflake_local_db.consumer.list_template_requests('dcr_cleanroom');

For reference documentation for the consumer.list_template_requests command, see the Consumer-defined Templates section in Snowflake Data Clean Rooms: Consumer API reference guide.