Snowflake Data Clean Rooms: análise de dados do provedor¶

Configuração do ambiente¶

Execute os seguintes comandos para configurar o ambiente Snowflake antes de usar as APIs de desenvolvedor para trabalhar com uma Snowflake Data Clean Room. Se você não tem a função SAMOOHA_APP_ROLE, entre em contato com o administrador da sua conta.

use role samooha_app_role;
use warehouse app_wh;

Crie a sala limpa¶

Crie um nome para a sala limpa. Insira um novo nome de salas limpas para evitar colisões com nomes de salas limpas. Observe que os nomes dos salas limpas só podem ser alfanuméricos. Os nomes de salas limpas não podem conter caracteres especiais além de espaços e sublinhados.

set cleanroom_name = 'Provider Data Analysis Demo Clean room';

Você pode criar uma nova sala limpa com o nome de sala limpa definido acima. Se o nome da sala limpa definido acima já existir como uma sala limpa, este processo falhará.

Este procedimento leva aproximadamente 45 segundos para ser executado.

O segundo argumento para provider.cleanroom_init é a distribuição da sala limpa. Ele pode ser INTERNAL ou EXTERNAL. Para fins de teste, se você estiver compartilhando a sala limpa com uma conta na mesma organização, você pode usar INTERNAL para ignorar a verificação de segurança automatizada que deve ocorrer antes que um pacote de aplicativo seja liberado aos colaboradores. No entanto, se você estiver compartilhando esta sala limpa com uma conta em uma organização diferente, você deve usar uma distribuição de sala limpa EXTERNAL.

call samooha_by_snowflake_local_db.provider.cleanroom_init($cleanroom_name, 'INTERNAL');

Para visualizar o status da verificação de segurança, use:

call samooha_by_snowflake_local_db.provider.view_cleanroom_scan_status($cleanroom_name);

Após criar sua sala limpa, você deve definir sua diretiva de lançamento para que ela possa ser compartilhada com qualquer colaborador. No entanto, se sua distribuição tiver sido definida como EXTERNAL, você deverá primeiro aguardar a conclusão da verificação de segurança antes de definir a diretiva de lançamento. Você pode continuar executando o restante das etapas e retornar aqui antes da etapa provider.create_cleanroom_listing enquanto a verificação é executada.

Para definir a diretiva de lançamento, chame:

call samooha_by_snowflake_local_db.provider.set_default_release_directive($cleanroom_name, 'V1_0', '0');

Compartilhamento entre regiões¶

Para compartilhar uma sala limpa com um cliente Snowflake cuja conta está em uma região diferente da sua conta, você deve habilitar o Preenchimento automático entre nuvens. Para obter mais informações sobre os custos adicionais associados à colaboração com consumidores em outras regiões, consulte Custos de preenchimento automático entre nuvens.

Ao usar as APIs de desenvolvedor, o processo para habilitar o compartilhamento entre regiões ocorre em duas etapas.

1. Um administrador Snowflake com a função ACCOUNTADMIN habilita o preenchimento automático entre nuvens para sua conta Snowflake. Para obter instruções, consulte Colaboração com contas em diferentes regiões.

2. Execute o comando provider.enable_laf_for_cleanroom para habilitar o preenchimento automático entre nuvens para a sala limpa. Por exemplo:

   call samooha_by_snowflake_local_db.provider.enable_laf_for_cleanroom($cleanroom_name);
   

   Copy

Após habilitar o preenchimento automático entre nuvens para a sala limpa, você pode adicionar consumidores à sua listagem normalmente usando o comando provider.create_cleanroom_listing. A listagem é replicada automaticamente para nuvens e regiões remotas, conforme necessário.

Vincule e defina a política de junção para o conjunto de dados¶

Conecte as tabelas Snowflake à sala limpa. Navegue pela lista de tabelas em sua conta Snowflake e insira os nomes de tabela totalmente qualificados (Database.Schema.Table) como uma matriz. O procedimento torna a tabela automaticamente acessível à sala limpa, criando uma exibição segura da tabela de dentro da sala limpa, evitando assim a necessidade de fazer uma cópia da tabela.

call samooha_by_snowflake_local_db.provider.link_datasets($cleanroom_name, ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);

use role accountadmin;
call samooha_by_snowflake_local_db.provider.register_db('<DATABASE_NAME>');
use role samooha_app_role;

Se quiser visualizar os conjuntos de dados adicionados à sala limpa, chame o procedimento a seguir.

call samooha_by_snowflake_local_db.provider.view_provider_datasets($cleanroom_name);

Você pode ver os conjuntos de dados vinculados à sala limpa usando o seguinte procedimento:

select * from SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS limit 10;

Especifique em quais colunas o consumidor tem permissão para unir ao executar modelos na sala limpa. Este procedimento deve ser chamado em colunas de identidade como e-mail. A política de junção é “somente substituição”, portanto, se a função for chamada novamente, a política de junção definida anteriormente será completamente substituída pela nova.

call samooha_by_snowflake_local_db.provider.set_join_policy($cleanroom_name, ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:HEM']);

Se você quiser visualizar a política de junção adicionada à sala limpa, chame o procedimento a seguir.

call samooha_by_snowflake_local_db.provider.view_join_policy($cleanroom_name);

Como adicionar modelos de análise à sala limpa¶

Adicione uma lista de modelos especificados previamente usando seus identificadores de nome. Nesse fluxo, você adiciona um modelo predefinido que permite realizar análises de dados nos conjuntos de dados do provedor de maneira segura e aprovada pelo provedor em colunas aprovadas pelo provedor.

call samooha_by_snowflake_local_db.provider.add_templates($cleanroom_name, ['prod_provider_data_analysis']);

Se você quiser visualizar os modelos atualmente ativos na sala limpa, chame o procedimento a seguir.

call samooha_by_snowflake_local_db.provider.view_added_templates($cleanroom_name);

Qualquer modelo adicionado à sala limpa também pode ser removido, se necessário. Consulte o Guia de referência da API do provedor para mais detalhes.

Definição da política de coluna em cada tabela¶

Visualize os dados vinculados para ver as colunas presentes na tabela. Para exibir as 10 primeiras linhas, chame o procedimento a seguir.

select * from SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS limit 10;

Defina as colunas que o consumidor pode agrupar, agregar (por exemplo, SUM ou AVG) e geralmente usa em uma análise para cada combinação de tabela e modelo. Isso proporciona flexibilidade para que a mesma tabela possa permitir diferentes seleções de colunas, dependendo do modelo subjacente. Isso só deve ser chamado depois que o modelo for adicionado.

Observe que a política de coluna é somente substituição, portanto, se a função for chamada novamente, a política de coluna definida anteriormente será completamente substituída pela nova.

A política de coluna não deve ser usada em colunas de identidade como e-mail, HEM, ou RampID porque você não quer que o consumidor consiga agrupar por essas colunas. No ambiente de produção, o sistema irá inferir de forma inteligente as colunas PII e bloquear esta operação, mas esse recurso não está disponível no ambiente sandbox. Ele só deve ser usado nas colunas que você deseja que o consumidor possa agregar e agrupar, como Status, Faixa etária, Canal ou Dias ativos.

call samooha_by_snowflake_local_db.provider.set_column_policy($cleanroom_name, [
    'prod_provider_data_analysis:SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:STATUS', 
    'prod_provider_data_analysis:SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:AGE_BAND', 
    'prod_provider_data_analysis:SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:DAYS_ACTIVE',
    'prod_provider_data_analysis:SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:REGION_CODE']);

Se você quiser visualizar a política de coluna adicionada à sala limpa, chame o procedimento a seguir.

call samooha_by_snowflake_local_db.provider.view_column_policy($cleanroom_name);

Compartilhamento com um consumidor¶

Por fim, adicione um consumidor de dados à sala limpa adicionando o localizador de conta Snowflake e os nomes de conta, conforme mostrado abaixo. O nome da conta Snowflake deve ter o formato <ORGANIZATION>.<ACCOUNT_NAME>.

show versions in application package samooha_cleanroom_Provider_Data_Analysis_Demo_clean_room;

call samooha_by_snowflake_local_db.provider.add_consumers($cleanroom_name, '<CONSUMER_ACCOUNT_LOCATOR>', '<CONSUMER_ACCOUNT_NAME>');
call samooha_By_snowflake_local_db.provider.create_cleanroom_listing($cleanroom_name, '<CONSUMER_ACCOUNT_NAME>');

Vários localizadores de contas de consumidor podem ser passados para a função provider.add_consumers como uma cadeia de caracteres separada por vírgulas ou como chamadas separadas para provider.add_consumers.

Se quiser visualizar os consumidores adicionados a esta sala limpa, chame o procedimento a seguir.

call samooha_by_snowflake_local_db.provider.view_consumers($cleanroom_name);

Veja as salas limpas que foram criadas recentemente por meio do seguinte procedimento:

call samooha_by_snowflake_local_db.provider.view_cleanrooms();

Veja mais informações sobre a sala limpa criada recentemente por meio do procedimento a seguir.

call samooha_by_snowflake_local_db.provider.describe_cleanroom($cleanroom_name);

Uma sala limpa criada também pode ser excluída. O comando a seguir descarta completamente a sala limpa, de modo que os consumidores que anteriormente tinham acesso à sala limpa não poderão mais usá-la. Se uma sala limpa com o mesmo nome for desejada no futuro, ela deverá ser reinicializada usando o fluxo acima.

call samooha_by_snowflake_local_db.provider.drop_cleanroom($cleanroom_name);

Configuração do ambiente¶

Execute os seguintes comandos para configurar o ambiente Snowflake antes de usar as APIs de desenvolvedor para trabalhar com uma Snowflake Data Clean Room. Se você não tem a função SAMOOHA_APP_ROLE, entre em contato com o administrador da sua conta.

use role samooha_app_role;
use warehouse app_wh;

Instalação da sala limpa¶

Depois que um compartilhamento de sala limpa for instalado, a lista de salas limpas disponíveis poderá ser visualizada usando o comando abaixo.

call samooha_by_snowflake_local_db.consumer.view_cleanrooms();

Atribua um nome para a sala limpa que o provedor compartilhou com você.

set cleanroom_name = 'Provider Data Analysis Demo Clean room';

O comando a seguir instala a sala limpa na conta do consumidor com o provedor associado e a sala limpa selecionada.

Esse procedimento pode levar cerca de 45 segundos para ser executado.

call samooha_by_snowflake_local_db.consumer.install_cleanroom($cleanroom_name, '<PROVIDER_ACCOUNT_LOCATOR>');

Após a instalação da sala limpa, o provedor precisa terminar de configurá-la do seu lado antes que ela seja habilitada para uso. A função abaixo permite que você verifique o status da sala limpa. Depois que ela for habilitada, você poderá executar o comando Run Analysis abaixo. Normalmente, leva cerca de 1 minuto para que a sala limpa seja habilitada.

call samooha_by_snowflake_local_db.consumer.is_enabled($cleanroom_name);

Execute a análise¶

Agora que a sala limpa está instalada, você pode executar o modelo de análise fornecido à sala limpa pelo provedor usando o comando “run_analysis”. Você pode ver como cada campo é determinado nas seções abaixo.

-- Example run analysis procedure with single provider dataset

call samooha_by_snowflake_local_db.consumer.run_analysis(
  $cleanroom_name,                    -- cleanroom
  'prod_provider_data_analysis',      -- template name

  [],                                 -- consumer tables - this is empty since this template operates only on provider data
  
  ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS'],    -- the provider table we want to carry out analysis on

  object_construct(                        -- The keyword arguments needed for the SQL Jinja template
      'dimensions', ['p.STATUS'],          -- Group by column

      'measure_type', ['COUNT'],           -- Aggregate function you want to perform like COUNT, AVG, etc.

      'measure_column', ['p.DAYS_ACTIVE'], -- The column that you want to perform aggregate function on

      'where_clause', 'p.REGION_CODE=$$REGION_10$$'  -- Acts as a filter to consider only certain records
                                                      -- $$ is used to pass string literals
    )
);

Para cada uma das colunas que você precisar consultar na filtragem do conjunto de dados “where_clause” ou dimensions ou measure_columns, você pode usar p. para consultar campos nas tabelas do provedor e c. para consultar campos nas tabelas do consumidor. Use p2, p3 etc. para mais de uma tabela de provedores e c2, c3 etc. para mais de uma tabela de consumidores.

Observação: neste fluxo, você pode ver que a sala limpa tem a análise de dados do provedor habilitada, o que significa que você pode executar análises de dados seguras e privatizadas nos conjuntos de dados do provedor na sala limpa. Você não precisa vincular seu conjunto de dados. Verifique o fluxo Análise de sobreposição de ponta a ponta para ver um exemplo em que ambas as partes podem vincular conjuntos de dados para análise de junção.

Como determinar as entradas para run_analysis¶

Para executar a análise, você precisa passar vários parâmetros para a função run_analysis. Esta seção mostrará como determinar quais parâmetros devem ser passados.

Nomes dos modelos

Primeiramente, você pode ver os modelos de análise compatíveis chamando o procedimento a seguir.

call samooha_by_snowflake_local_db.consumer.view_added_templates($cleanroom_name);

Ao executar uma análise com um modelo, você não sabe quais argumentos especificar neste ponto e quais tipos são esperados. Assim, você pode visualizar o modelo com isso, caso ele seja um modelo personalizado.

call samooha_by_snowflake_local_db.consumer.view_template_definition($cleanroom_name, 'prod_provider_data_analysis');

Isso geralmente também pode conter um grande número de diferentes parâmetros SQL Jinja. A funcionalidade a seguir analisa o modelo SQL Jinja e extrai os argumentos que precisam ser especificados em run_analysis, organizando-os em uma conveniente lista.

call samooha_by_snowflake_local_db.consumer.get_arguments_from_template($cleanroom_name, 'prod_provider_data_analysis');

Nomes dos conjuntos de dados

Se você quiser visualizar os nomes dos conjuntos de dados adicionados à sala limpa pelo provedor, chame o procedimento a seguir. Observe que você não pode visualizar os dados presentes nos conjuntos de dados adicionados à sala limpa pelo provedor devido às propriedades de segurança da sala limpa.

call samooha_by_snowflake_local_db.consumer.view_provider_datasets($cleanroom_name);

Colunas de dimensão e medida

Ao executar a análise, você pode querer filtrar, agrupar e agregar em determinadas colunas. Se você quiser visualizar a política de coluna adicionada à sala limpa pelo provedor, chame o procedimento a seguir.

call samooha_by_snowflake_local_db.consumer.view_provider_column_policy($cleanroom_name);

Erros comuns

Se você estiver recebendo o erro Não aprovado: colunas não autorizadas usadas como resultado da análise de execução, talvez seja necessário visualizar novamente a política de junção e a política de coluna definidas pelo provedor.

call samooha_by_snowflake_local_db.consumer.view_provider_join_policy($cleanroom_name);
call samooha_by_snowflake_local_db.consumer.view_provider_column_policy($cleanroom_name);

Também é possível que você tenha esgotado seu orçamento de privacidade e, portanto, não possa executar mais consultas. Seu orçamento de privacidade restante pode ser visualizado usando o comando abaixo. Ele é redefinido diariamente, mas o provedor de sala limpa pode redefini-lo, se necessário.

call samooha_by_snowflake_local_db.consumer.view_remaining_privacy_budget($cleanroom_name);

Você pode verificar se a privacidade diferencial foi habilitada para sua sala limpa usando a seguinte API:

call samooha_by_snowflake_local_db.consumer.is_dp_enabled($cleanroom_name);