Usando a API do desenvolvedor para adicionar modelos definidos pelo consumidor¶

No fluxo tradicional do Snowflake Data Clean Rooms, um provedor usa a API do desenvolvedor para criar modelos personalizados e, em seguida, os adiciona à sala limpa que o provedor compartilha com um consumidor. O consumidor então usa esse modelo para executar análises na sala limpa.

Em alguns casos, o consumidor deseja poder criar seu próprio modelo personalizado para controlar o tipo de análise que pode ser executada na sala limpa. Nesse cenário, o provedor ainda cria e compartilha a sala limpa, mas o consumidor define um modelo dentro dessa sala limpa. Como se trata de uma sala limpa, o provedor deve permitir explicitamente que esse modelo definido pelo consumidor seja adicionado à sala limpa.

Os modelos de sala limpa contribuídos pelos consumidores incluem o código JinjaSQL e também podem incluir código Python personalizado.

A capacidade de adicionar um modelo definido pelo consumidor à sala limpa de um provedor geralmente é necessária em uma sala limpa com vários provedores, onde o consumidor está executando análises de dados de mais de um provedor ao mesmo tempo. Nesse ambiente, o consumidor pode estar na melhor posição para saber como extrair insights de dados provenientes de diversas partes e pode usar a API do desenvolvedor para criar um modelo personalizado para fazer isso. Com modelos definidos pelo consumidor em um ambiente de vários provedores, cada provedor deve aprovar o modelo antes que ele possa ser usado. Para um exemplo mais detalhado mostrando como usar uma sala limpa com vários provedores, consulte Análise de consumidores com vários provedores.

Fluxo de trabalho básico para modelos definidos pelo consumidor¶

O processo de usar a API do desenvolvedor para adicionar modelos definidos pelo consumidor à sala limpa de um provedor envolve ações coordenadas tanto pelo consumidor quanto pelo provedor. Este fluxo de trabalho básico é:

Consumidor:

Envia uma solicitação ao provedor da sala limpa para que um modelo personalizado seja adicionado. Esta solicitação inclui a definição do modelo, que é escrito na linguagem de modelos Jinja. Se o provedor e o consumidor estiverem em regiões de nuvem diferentes, eles deverão primeiro ativar as solicitações de modelos entre nuvens.

Provedor:

Verifica novas solicitações de consumidores que desejam adicionar modelos à sala limpa.
Após revisar a definição do modelo, aprova ou rejeita a solicitação.

Consumidor:

Verifica se a solicitação foi aprovada. O consumidor pode consultar o status da solicitação a qualquer momento.

Dica

Se o consumidor e provedor estiverem em regiões de nuvem diferentes, você precisará ativar o preenchimento automático entre nuvens em ambas as contas e para ambas as clean rooms.

Solicitação para adicionar um modelo¶

Um consumidor executa o comando consumer.create_template_request para enviar uma solicitação ao provedor de uma sala limpa. Esta solicitação inclui o nome do modelo junto com o código Jinja que define o modelo. O nome deve estar em letras minúsculas e não pode incluir espaços. [Conheça a sintaxe do modelo personalizado](/user-guide/cleanrooms/custom-templates)

Por exemplo, suponha que o provedor compartilhou uma sala limpa dcr_cleanroom com um consumidor. O consumidor deseja adicionar um modelo nomeado à sala limpa my_overlap_analysis. Para enviar uma solicitação ao provedor da sala limpa, o consumidor executa o seguinte comando:

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

Copy

O terceiro argumento é o código Jinja que define o modelo.

Para obter documentação de referência para o comando consumer.create_template_request, consulte a seção Modelos definidos pelo consumidor em Snowflake Data Clean Rooms: Guia de referência da API do consumidor.

Inclusão de código Python em seu modelo¶

Seu modelo JinjaSQL pode chamar funções Python se você incluir Python no modelo.

Para incluir o código Python em seu modelo:

Escreva seu código Python.
Chame consumer.generate_python_request_template, passando seu código, para produzir um modelo com um espaço reservado para seu código JinjaSQL. consumer.generate_python_request_template pode criar um código de modelo para apenas uma única função. Se precisar oferecer suporte a várias funções Python em seu modelo SQL, chame generate_python_request_template para cada função Python personalizada e combine os resultados em um único modelo.

Verificação se há novas solicitações dos consumidores¶

Para verificar novas solicitações de consumidores, um provedor executa o comando provider.list_template_requests e analisa os resultados para identificar solicitações com status PENDING. Um status PENDING indica que o consumidor enviou uma nova solicitação à qual o provedor ainda não tomou ação. A resposta a provider.list_template_requests inclui o código Jinja do modelo, que permite ao provedor decidir se deseja aprovar ou rejeitar a solicitação.

Por exemplo, suponha que o nome da sala limpa do provedor seja dcr_cleanroom. Para verificar se o consumidor enviou uma nova solicitação para adicionar um modelo, o provedor executa os seguintes comandos:

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

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

Copy

A resposta ao comando provider.list_template_requests inclui o seguinte para cada solicitação de modelo:

UUID que identifica exclusivamente a solicitação.
Conta do consumidor que enviou a solicitação, no formato do localizador de conta.
Nome do modelo, que foi especificado pelo consumidor quando ele enviou a solicitação.
Código Jinja que define o modelo.
Status da solicitação, que pode ser PENDING, APPROVED ou REJECTED.

Para obter documentação de referência para o comando provider.list_template_requests, consulte a seção Modelos definidos pelo consumidor em Snowflake Data Clean Rooms: Guia de referência da API do provedor.

Como aprovar ou rejeitar uma solicitação¶

Após receber uma solicitação para adicionar um modelo definido pelo consumidor, o provedor decide se aprova ou rejeita a solicitação.

Aprovar uma solicitação

Os provedores executam o comando provider.approve_template_request para aprovar uma solicitação para adicionar um modelo. O provedor especifica qual modelo aprovar passando o identificador da solicitação como um argumento.

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

Copy

Rejeitar uma solicitação

Os provedores executam o comando provider.reject_template_request para rejeitar uma solicitação para adicionar um modelo. O provedor especifica qual modelo rejeitar passando o identificador da solicitação como um argumento.

Por exemplo, suponha que o nome da sala limpa do provedor seja dcr_cleanroom e a solicitação do consumidor para adicionar um modelo recebeu o identificador 01b4d41d-0001-b572. Após examinar o modelo Jinja, o provedor determina que ele introduz um risco de segurança na sala limpa, então ele quer rejeitar a solicitação com um motivo descritivo. Para rejeitar a solicitação de adição do modelo, o provedor executa o seguinte comando:

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

Copy

Para obter documentação de referência para os comandos provider.approve_template_request e provider.reject_template_request, consulte a seção Modelos definidos pelo consumidor em Snowflake Data Clean Rooms: Guia de referência da API do provedor.

Verificação do status da solicitação como consumidor¶

A qualquer momento, o consumidor pode executar o comando consumer.list_template_requests para verificar o status da sua solicitação para adicionar um modelo. O comando retorna as seguintes informações:

UUID que identifica exclusivamente a solicitação.
Conta do provedor para a qual a solicitação foi enviada, no formato do localizador de conta.
Nome do modelo, que foi especificado pelo consumidor quando ele enviou a solicitação.
Código Jinja que define o modelo.
Status da solicitação, que pode ser PENDING, APPROVED ou REJECTED.
Se a solicitação foi rejeitada, o motivo da ação do provedor.

Por exemplo, suponha que o consumidor enviou uma solicitação para adicionar um modelo à sala limpa dcr_cleanroom. Para verificar o status da solicitação e determinar se ela foi aprovada, o consumidor executa o seguinte comando:

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

Copy

Para obter documentação de referência para o comando consumer.list_template_requests, consulte a seção Modelos definidos pelo consumidor em Snowflake Data Clean Rooms: Guia de referência da API do consumidor.

Listagem de todas as solicitações dos consumidores¶

Um provedor executa o comando provider.list_template_requests para exibição todas as solicitações, incluindo solicitações que foram aprovadas ou rejeitadas.

Por exemplo, suponha que o nome da sala limpa do provedor seja dcr_cleanroom. Para listar todas as solicitações feitas, independentemente do resultado, o provedor executa o seguinte comando:

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

Copy