Activating query results¶

Visão geral da ativação¶

O provedor ou consumidor pode enviar os resultados do modelo para fora da clean room em um processo chamado ativação. O Snowflake é compatível com três tipos de ativação:

A ativação do provedor, em que os resultados são enviados para uma tabela na conta Snowflake do provedor.
A ativação do consumidor, em que os resultados são enviados para uma tabela na conta Snowflake do consumidor.
Ativação de terceiros, em que o provedor ou o consumidor envia os resultados para um terceiro aprovado pelo Snowflake, como o LiveRamp ou o Meta Ads Manager, por meio de um conector de ativação.

In all cases, the template must support activation, and parties should approve activation for any columns of their own data that will be activated. Data providers specify which columns of their data are activated by setting an activation policy. For more about clean room policies see Compreensão das políticas de tabela de clean room.

A ativação é compatível com a privacidade diferencial, se ativada, e respeita as regras e os orçamentos de privacidade diferencial.

Importante

Se o consumidor e o provedor estiverem em regiões de nuvem diferentes, você precisará habilitar o preenchimento automático entre nuvens em ambas as contas e salas limpas.

Ativação de provedor e consumidor¶

Você pode configurar uma clean room para salvar os resultados do modelo na conta Snowflake do provedor ou do consumidor. Tanto o provedor quanto o consumidor devem aprovar a ativação de quaisquer dados fora da clean room.

Activation is implemented using a dedicated activation template. In the clean rooms UI, an activation template can be associated with an analysis template, and the user can run the analysis template, view the results, then run the associated activation template. The Snowflake-provided Audience Overlap & Segmentation flow does this.

An activation template need not be identical to any associated analysis template. The activation template is often a subset of the analysis template.

Modelos compatíveis¶

Os modelos a seguir oferecem suporte à ativação de provedores e consumidores:

Audience Overlap & Segmentation
Modelos personalizados

Combinações compatíveis¶

Activation can be run either by the provider or the consumer. (Learn more about provider-run analyses.)

As seguintes combinações são compatíveis:

	Ativação do provedor	Ativação do consumidor	Ativação de terceiros
Executada pelo provedor	✅	❌	UI only
Executada pelo consumidor	✅	✅	UI only

Resultados¶

Os resultados da ativação do provedor são salvos na conta do provedor na tabela SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.PUBLIC.PROVIDER_ACTIVATION_SUMMARY.

Os resultados da ativação do consumidor são salvos na conta do consumidor na tabela SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.PUBLIC.CONSUMER_DIRECT_ACTIVATION_SUMMARY.

Consulte os resultados de exibição para saber como ler os dados.

Implementação da ativação de provedor ou consumidor¶

Configuração

A ativação ao usar a UI de clean rooms exige que a conta das clean rooms permita a ativação.
Para a ativação executada pelo provedor, a clean room deve ser configurada para oferecer suporte à análise executada pelo provedor.

1. Criar ou ingressar em uma clean room

Ao criar ou ingressar em uma clean room, na etapa Configure Analysis & Query, em Activation Settings, especifique quais colunas devem ser adicionadas aos resultados ativados em sua conta.

2. Execute o modelo e ative os resultados

Para executar a ativação associada à sua análise, conclua as etapas a seguir:

Faça sua análise.
Após executar uma análise, selecione Results » Activate.
Em Activation Hub, selecione o nome da conta de provedor ou consumidor a ser ativada.
Forneça informações específicas ao modelo de ativação, como nomes descritivos de segmentação ou a seleção de colunas de ativação.
Provide a segment name: this is an arbitrary string used to identify a set of results from a given run. You can provide a different string for each activation to group each run’s results separately, or you can use the same segment name over multiple runs if you want to combine results.
Selecione Push Data.
To learn how to view activated results, see Exibição dos resultados da ativação de provedor e consumidor.

A ativação é realizada de forma diferente, dependendo de quem a executa e se é uma ativação de consumidor ou provedor.

Importante

Na primeira vez em que um consumidor ativar dados para uma conta de provedor em uma clean room, o provedor deverá estabelecer um pipeline de dados entrando na UI de clean room para essa conta e permanecendo conectado por até 30 minutos. Isso precisa ser feito apenas uma vez por clean room e por consumidor. Até que isso seja feito, os dados não aparecerão na conta de provedor, mesmo que a ativação seja bem-sucedida.

Veja como um consumidor pode enviar resultados para sua própria conta Snowflake.

Provedor

Crie a clean room, vincule conjuntos de dados e defina políticas de junção, como em uma clean room padrão.

Você pode escolher um modelo padrão Snowflake compatível ou adicionar um modelo de ativação personalizado à clean room. Se essa clean room for usada na UI, você deverá fornecer um formulário Web com os campos de ativação adequados, conforme descrito na documentação do modelo.

Acione o modelo para ativação do consumidor chamando provider.enable_template_for_consumer_activation.

To specify which provider columns can be activated, set the activation policy in the clean room for the enabled template by calling provider.set_activation_policy.

Adicione colaboradores consumidores, defina a diretiva de lançamento padrão e publique a clean room, como de costume.

Consumidor

Instale a clean room, vincule conjuntos de dados e defina políticas de junção, como em uma clean room padrão.

To specify which consumer columns can be activated, set the activation policy in the clean room for that template by calling consumer.set_activation_policy.

Execute a ativação chamando consumer.run_activation, com o último parâmetro definido como TRUE para indicar uma ativação do consumidor.

Veja os resultados, conforme descrito abaixo.

Exemplos

Download the following examples and upload them as worksheet files in your Snowflake account. You will need separate accounts for the provider and consumer, each with the clean rooms API installed. Replace the information as noted in the sample files. See instructions to upload a SQL worksheet into your Snowflake account.

Veja como um consumidor pode enviar resultados para a conta Snowflake de um provedor.

Importante

Se o consumidor e o provedor não tiverem ambos a UI de clean rooms instalada, e o consumidor estiver ativando para o provedor:

O consumidor deve executar o seguinte comando SQL:
```
ALTER SHARE SAMOOHA_INTERNAL_GOVERNANCE_SUMMARY_SHARE_NAV2
  ADD ACCOUNTS = $provider_account_data_sharing_id;
```
Copy
em que $provider_account_data_sharing_id é o identificador de conta do Data Sharing do provedor
O provedor deve executar o seguinte procedimento:
```
CALL samooha_by_snowflake_local_db.provider.mount_provider_activations_share(
  $consumer_account_data_sharing_id, TRUE, FALSE);
```
Copy
em que $consumer_account_data_sharing_id é o identificador de conta do Data Sharing do consumidor.

1. Provedor

Crie a clean room da maneira padrão.

Vincule os conjuntos de dados. O provedor também deve vincular a tabela samooha_by_snowflake_local_db.library.temp_public_key à clean room.

Defina a política de junção da maneira padrão.

Escolha um modelo padrão do Snowflake compatível ou adicione um modelo de ativação personalizado à sala limpa. Se a sala limpa vai ser usada na UI de salas limpas, você deve providenciar um formulário da Web com os campos de ativação adequados.

To specify which provider columns can be activated, set the activation policy in the clean room for that template by calling provider.set_activation_policy.

Adicione colaboradores consumidores, defina a diretiva de lançamento padrão e publique a clean room, como de costume. (Se você não tiver a UI de clean room instalada, chame provider.setup_provider_activation_share_mount_task após adicionar os consumidores)

2. Consumidor

Instale a clean room, vincule conjuntos de dados e defina políticas de junção, como em uma clean room padrão.

Set the activation policy in the clean room for that template to specify which consumer columns can be activated by calling consumer.set_activation_policy.

Execute a ativação chamando consumer.run_activation, com o último argumento definido como FALSE para indicar uma ativação de provedor.

Nota

Uma versão criptografada dos dados ativados fica armazenada na conta do consumidor por 28 dias na tabela SAMOOHA_LOCAL_DB_NAME_PLACEHOLDER.PUBLIC.CONSUMER_ACTIVATION_SUMMARY. Os dados com mais de 28 dias são eliminados da conta do consumidor.

3. Provedor

Na primeira vez em que um consumidor ativar os dados em sua conta, você deverá permanecer conectado na UI das clean rooms para essa conta por cerca de 30 minutos após o consumidor ter ativado os dados. Depois disso, os dados aparecerão em sua conta. Isso é feito apenas uma vez por clean room e por conta de consumidor. As ativações posteriores pelo mesmo consumidor na mesma clean room não precisam dessa etapa.

Os resultados devem ser descriptografados antes de serem salvos em sua conta, o que pode levar algum tempo. A tarefa de descriptografia atinge o tempo limite após 60 minutos; se isso acontecer, chame provider.update_activation_warehouse para aumentar o tamanho do warehouse usado para descriptografia.

Veja os resultados, conforme descrito abaixo.

Exemplos

Veja como um provedor pode enviar resultados para sua própria conta Snowflake. Isso combina várias técnicas, incluindo modelos personalizados, análise executada pelo provedor e ativação do provedor, e, portanto, envolve várias rodadas de solicitação e aprovação entre o provedor e o consumidor.

1. Provedor

Crie a clean room, vincule conjuntos de dados e defina políticas de junção, como em uma clean room padrão, com uma exceção: você deve criar o link na tabela samooha_by_snowflake_local_db.library.temp_public_key. Os dados executados pelo provedor são criptografados, o que permite a criptografia e descriptografia dos resultados.

Você pode escolher um modelo padrão Snowflake compatível ou adicionar um modelo de ativação personalizado à clean room. Se essa clean room for usada na UI, você deverá fornecer um formulário Web com os campos adequados para oferecer suporte à ativação, conforme descrito na documentação do modelo.

Set the activation policy in the clean room for that template to specify which provider columns can be activated by calling provider.set_activation_policy.

Adicione colaboradores consumidores da maneira padrão. Se você não tiver a UI da clean room instalada, deverá chamar provider.setup_provider_activation_share_mount_task após adicionar usuários.

Permita a análise executada pelo provedor na clean room, chamando provider.enable_provider_run_analysis. Isso deve ser feito após adicionar colaboradores, mas antes de os colaboradores instalarem a clean room. Se você alterar essa configuração depois que um consumidor instalar a clean room, o consumidor deverá reinstalar a clean room para que a alteração tenha efeito.

Defina a diretiva de lançamento padrão e publique a clean room, como de costume.

2. Consumidor

Instale a clean room, vincule os conjuntos de dados e defina as políticas de junção como em uma clean room padrão.

Set the activation policy in the clean room for that template to specify which consumer columns can be activated by calling consumer.set_activation_policy.

3. Provedor

Solicite permissão do consumidor para executar seu modelo de ativação, chamando provider.request_provider_activation_consent.

4. Consumidor

Conceda ao provedor permissão para executar um determinado modelo nessa clean room, chamando consumer.enable_templates_for_provider_run.

Conceda ao provedor permissão para ativar os resultados de um determinado modelo nessa clean room, chamando consumer.approve_provider_activation_consent.

5. Provedor

Permita que os dados do consumidor sejam compartilhados em uma ativação de provedor, chamando provider.mount_request_logs_for_all_consumers.

Execute o modelo de ativação chamando provider.submit_analysis_request). A solicitação leva vários minutos para aparecer nos registros; verifique o status chamando provider.check_analysis_status. Observe que, mesmo após o status ser informado como SUCCESS, é necessário um tempo adicional para que os resultados sejam descriptografados e gravados na tabela Snowflake do provedor. Todos os dados descriptografados são anexados de uma só vez à tabela de resultados. Continue verificando periodicamente a tabela de resultados de seu ID de segmento ou ativação. A tarefa de descriptografia atinge o tempo limite após 60 minutos; se isso acontecer, chame provider.update_activation_warehouse para aumentar o tamanho do warehouse usado para descriptografia.

Nota

Para modificar um modelo após a aprovação do consumidor, você deve seguir os seguintes passos, caso contrário, provider.submit_analysis_request continuará executando a última versão aprovada do modelo.

O provedor atualiza o modelo chamando provider.add_custom_sql_template. Não é necessário chamar create_or_update_cleanroom_listing novamente.

O consumidor chama consumer.enable_templates_for_provider_run.

O consumidor chama consumer.approve_provider_activation_consent.

O modelo atualizado agora está pronto para ser ativado pelo provedor.

Erros comuns

Object cleanroom_name.CLEANROOM.TEMP_RESULT_DATA does not exist or not authorized – A tabela de resultados temporários não pôde ser gerada por algum motivo. Pode ser um erro de SQL no modelo ou seu modelo não gerou explicitamente uma tabela; veja os detalhes do erro.
Query validation checks failed – Algumas colunas usadas no modelo que não estavam nas políticas de ativação.

Exemplos

Exibição dos resultados da ativação de provedor e consumidor¶

Local e formato dos resultados da ativação¶

All activation results are appended to a clean room designated table in the provider’s or consumer’s account. Each row in the table maps to a row in the query result. Results from each run are appended to the table (the table is not cleared before each run). You can distinguish between different runs by the ACTIVATION_ID column, which is unique per activation, or the SEGMENT column, which can be specified by the caller for each activation run.

Nota

Provider activation results are written in encrypted format to a temporary table in the consumer’s localDB. The results are then copied over to the provider’s account and decrypted before saving. This extra move and decryption step can cause delays with large result sets.

Os resultados da ativação do provedor são armazenados em SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.PUBLIC.PROVIDER_ACTIVATION_SUMMARY na conta de provedor.
Os resultados da ativação do consumidor são armazenados em SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.PUBLIC.CONSUMER_DIRECT_ACTIVATION_SUMMARY na conta de consumidor.

Essas tabelas contêm as seguintes colunas:

USER_ID:: Uma linha de resultados, no formato JSON, em que as chaves são os nomes das colunas e os valores são o valor dessa coluna nessa linha. O objeto também contém uma coluna para cada argumento passado para o modelo.
ACTIVATION_ID:: Um ID exclusivo para cada solicitação. O ID é retornado de uma solicitação de ativação bem-sucedida. Você pode filtrar por essa coluna para obter todos os resultados da mesma execução de ativação ou filtrar por SEGMENT se reutilizar o mesmo nome de segmento em várias execuções. Isso é o mesmo que o ID de solicitação de consulta retornado por submit_analysis_request ou run_activation.
CLEANROOM_NAME:: Nome da clean room onde a consulta foi executada.
CONSUMER:: (Somente ativação do provedor) O consumidor que aprovou essa ativação.
PROVIDER:: (Somente ativação do consumidor) O provedor que aprovou essa ativação.
SEGMENT:: Um valor de cadeia de caracteres arbitrário que você atribui quando executa a ativação. Essa coluna permite que você junte os resultados de várias execuções de consulta.
TIMESTAMP:: Quando a ativação foi executada.

Exemplo de ativação do provedor

SELECT * FROM SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.PUBLIC.PROVIDER_ACTIVATION_SUMMARY WHERE segment = 'my_segment';

                             USER_ID                          |   CLEANROOM_NAME |   SEGMENT  | CONSUMER |          TIMESTAMP      |  ACTIVATION_ID
"{""AGE_BAND"":55,""ITEM_COUNT"":2328,""STATUS"":""MEMBER""}" |  test activation | my_segment | ABC1234  | 2025-04-01 16:27:14.068 | cleanroomactivationdataanalysisresults20250401231728469
"{""AGE_BAND"":20,""ITEM_COUNT"":88,""STATUS"":""PLATINUM""}" |  test activation | my_segment | ABC1234  | 2025-04-01 16:27:14.068 | cleanroomactivationdataanalysisresults20250401231728469
"{""AGE_BAND"":80,""ITEM_COUNT"":18,""STATUS"":""GOLD""}"     |  test activation | my_segment | ABC1234  | 2025-04-01 16:27:14.068 | cleanroomactivationdataanalysisresults20250401231728469
...

Leitura dos resultados da ativação do provedor ou consumidor¶

Execute o comando SQL apropriado para visualizar os resultados ativados em sua conta Snowflake:

Veja os resultados da ativação do provedor

SELECT *
   FROM SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.PUBLIC.PROVIDER_ACTIVATION_SUMMARY
   [WHERE segment = <SEGMENT_NAME>] [AND activation_id = <ACTIVATION_ID>];

Copy

Veja os resultados da ativação do consumidor

SELECT *
   FROM SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.PUBLIC.CONSUMER_DIRECT_ACTIVATION_SUMMARY
   [WHERE segment = <SEGMENT_NAME>] [AND activation_id = <ACTIVATION_ID>];

Copy

Cada linha de dados é combinada em um objeto na coluna USER_ID. Você pode nivelar os resultados usando uma consulta como a seguinte:

-- Assuming columns AGE_BAND, STATUS, and ITEM_COUNT
SELECT
  item:"AGE_BAND",
  item:"STATUS",
  item:"ITEM_COUNT"
FROM (SELECT parse_json(user_id)
      AS item
      FROM SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.PUBLIC.PROVIDER_ACTIVATION_SUMMARY
      WHERE segment = $segment_name)
ORDER BY item:"AGE_BAND", item:"STATUS" ASC
LIMIT 20 ;

Copy

Veja as últimas 10 linhas de resultados no Snowsight:

Faça login no Snowsight.

No menu de navegação, selecione Catalog » Database Explorer.

Para ativação do provedor, navegue até SAMOOHA_BY_SNOWFLAKE_LOCAL_DB » PUBLIC » Tables » PROVIDER_ACTIVATION_SUMMARY.

Para ativação do consumidor, navegue até SAMOOHA_BY_SNOWFLAKE_LOCAL_DB » PUBLIC » Tables » CONSUMER_DIRECT_ACTIVATION_SUMMARY.

Selecione Data Preview.

Ativação de terceiros¶

A ativação de terceiros deposita os resultados de consulta na conta de um terceiro aprovado pelo Snowflake usando um conector de ativação de terceiros.

A ativação de terceiros é compatível apenas com a UI das clean rooms, e não com o uso de modelos personalizados.

A ativação durante o uso da UI das clean rooms é compatível somente se a conta das clean rooms permitir a ativação.

O administrador de clean rooms deve configurar o ambiente para oferecer suporte a conectores de ativação de terceiros, selecionar os conectores permitidos e configurá-los, antes que possam ser usados em qualquer clean room.

A ativação de terceiros oferece suporte a análises conduzidas por consumidor e provedor.

Modelos compatíveis¶

Os modelos a seguir oferecem suporte à ativação de terceiros:

Audience Overlap & Segmentation

Implementação da ativação de terceiros¶

Crie ou ingresse na clean room: ao criar ou ingressar na clean room, na etapa Configure Analysis & Query, em Activation Settings, especifique quais colunas devem ser adicionadas aos resultados ativados em sua conta.
Ativar resultados:
1. Faça sua análise.
2. Após executar uma análise, selecione Results » Activate.
3. Em Activation Hub, selecione o nome do provedor de terceiros para o qual deseja ativar.
4. Forneça informações específicas ao provedor. Isso pode ser feito fornecendo nomes descritivos ou selecionando quais colunas serão ativadas. As dicas de ferramentas na página devem fornecer informações adicionais sobre esse provedor.
5. Selecione Push Data.