Snowflake Data Clean Rooms: execução de uma análise como um provedor¶

Configuração do ambiente¶

Antes de usar as APIs de desenvolvedor, você precisa assumir a função SAMOOHA_APP_ROLE e especificar o warehouse usado para executar as APIs. Se você não tem a função SAMOOHA_APP_ROLE, entre em contato com o administrador da sua conta.

Execute os seguintes comandos para configurar seu ambiente:

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.

Primeiro, execute o seguinte comando para definir um nome de sala limpa para a sala limpa de exemplo:

SET cleanroom_name = 'Provider Run Analysis Overlap';

Se já existir uma sala limpa com o nome especificado, esse processo falhará.

Este procedimento pode demorar um pouco mais para ser executado, normalmente cerca de meio minuto.

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, poderá usar INTERNAL para ignorar a verificação de segurança automatizada que deve ocorrer antes que um pacote de aplicativo seja liberado para os 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 exibição o status da verificação de segurança, execute o seguinte comando:

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 diretriz de versão, execute o seguinte comando:

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

Vincule o conjunto de dados¶

Você pode vincular tabelas à sala limpa especificando nomes de tabela totalmente qualificados (<Banco de dados>.<Esquema>.<Tabela>) como uma matriz. Por exemplo, para vincular uma tabela em ambas as salas limpas, execute o seguinte comando:

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;

Você pode verificar se os conjuntos de dados foram vinculados à sala limpa executando o seguinte comando:

CALL samooha_by_snowflake_local_db.provider.view_provider_datasets($cleanroom_name);

Defina a política de junção para o conjunto de dados¶

Para determinar quais colunas usar como política de junção, você pode analisar seu conjunto de dados para determinar as colunas PII. Por exemplo, para ver as 10 primeiras linhas de uma tabela, execute a seguinte consulta:

SELECT * FROM SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS LIMIT 10;

Em seguida, especifique em quais colunas o consumidor tem permissão para unir ao executar os modelos na sala limpa. Este procedimento deve ser chamado em colunas de identidade como e-mail. Se você definir a política de junção uma segunda vez, 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 exibição a política de junção que foi adicionada à sala limpa, execute o seguinte comando:

CALL samooha_by_snowflake_local_db.provider.view_join_policy($cleanroom_name);

Adição de modelo de análise à sala limpa¶

Os modelos determinam o tipo de análises que podem ser executadas em uma sala limpa. Neste exemplo, você está usando um modelo predefinido que permite que os colaboradores executem uma análise sobre a sobreposição entre os conjuntos de dados do provedor e os conjuntos de dados do consumidor.

Observe que este modelo implementa nativamente as garantias de segurança adicionais fornecidas pela privacidade diferencial.

CALL samooha_by_snowflake_local_db.provider.add_templates($cleanroom_name, ['prod_overlap_analysis']);

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

Antes de definir uma política de coluna em uma tabela, execute uma consulta para exibir as colunas da tabela. Por exemplo, para visualizar as 10 primeiras linhas, execute o seguinte comando:

SELECT * FROM SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS LIMIT 10;

Para cada combinação de tabela e modelo, defina as colunas que o analista pode usar em uma análise, por exemplo, as colunas nas quais elas podem ser agrupadas ou agregadas. Isso proporciona flexibilidade para que a mesma tabela possa permitir diferentes seleções de coluna dependendo do modelo subjacente. Aguarde até adicionar um modelo para definir a política de coluna em uma tabela.

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.

As políticas de coluna não devem ser usadas em colunas de identidade como e-mail, HEM ou RampID porque você não quer que o analista consiga agrupar por essas colunas. No ambiente de produção, o Snowflake infere colunas PII e bloqueia esta operação, mas esta inferência não está disponível em um ambiente sandbox. Ele só deve ser usado em colunas que você deseja que o analista possa agregar e agrupar, por exemplo, Status, Faixa etária, Código de região ou Dias ativos.

Para definir a política de coluna para uma combinação de modelo/tabela, execute o seguinte comando:

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

Se você quiser visualizar a política de coluna adicionada à sala limpa, execute o seguinte comando:

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_Run_Analysis_Overlap;

Para compartilhar a sala limpa com um consumidor, execute os seguintes comandos:

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 consumidores 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 você quiser exibir os consumidores que foram adicionados à sala limpa, execute o seguinte comando:

CALL samooha_by_snowflake_local_db.provider.view_consumers($cleanroom_name);

Configuração de quem pode executar análises¶

Neste exemplo, você vai configurar a sala limpa para que o provedor possa executar análises, mas o consumidor não. Isso significa que o consumidor só poderá adicionar conjuntos de dados e definir políticas de segurança.

Para configurar a sala limpa para que o provedor possa executar uma análise, execute o seguinte comando:

CALL samooha_by_snowflake_local_db.provider.enable_provider_run_analysis($cleanroom_name, ['<CONSUMER_ACCOUNT_LOCATOR>']);

Por padrão, um consumidor pode executar análises em uma sala limpa. Para configurar a sala limpa para impedir que o consumidor execute análises, execute o seguinte comando:

CAll samooha_by_snowflake_local_db.provider.disable_consumer_run_analysis($cleanroom_name, ['<CONSUMER_ACCOUNT_LOCATOR>']);

Configuração do ambiente¶

Antes de usar as APIs de desenvolvedor, você precisa assumir a função SAMOOHA_APP_ROLE e especificar o warehouse usado para executar as APIs. Se você não tem a função SAMOOHA_APP_ROLE, entre em contato com o administrador da sua conta.

Execute os seguintes comandos para configurar seu ambiente:

USE ROLE samooha_app_role;
USE WAREHOUSE app_wh;

Instalação da sala limpa¶

Antes de instalar a sala limpa que o provedor compartilhou com você, atribua um nome para ela.

SET cleanroom_name = 'Provider Run Analysis Overlap';

O comando a seguir instala a sala limpa na conta do consumidor:

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

Vincule o conjunto de dados¶

Agora você pode vincular alguns dos seus conjuntos de dados à sala limpa. O provedor usará esses dados ao executar uma análise na sala limpa.

CALL samooha_by_snowflake_local_db.consumer.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 que adicionou à sala limpa, chame o procedimento a seguir.

CALL samooha_by_snowflake_local_db.consumer.view_consumer_datasets($cleanroom_name);

Definição das políticas de junção seguras para seu conjunto de dados¶

Nesta seção, você especificará quais colunas o provedor tem permissão para unir ao executar análises na sala limpa. Você deve executar o seguinte comando 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.consumer.set_join_policy($cleanroom_name, ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:HEM']);

Definição das políticas de coluna para seu conjunto de dados¶

Para cada combinação de tabela e modelo, defina as colunas que o provedor pode usar em uma análise, por exemplo, as colunas nas quais ele pode agrupar ou agregar. Isso proporciona flexibilidade para que a mesma tabela possa permitir diferentes seleções de coluna dependendo do modelo subjacente. Aguarde até adicionar um modelo para definir a política de coluna em uma tabela.

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.

As políticas de coluna não devem ser usadas em colunas de identidade como e-mail, HEM ou RampID porque você não quer que o provedor consiga agrupar por essas colunas. No ambiente de produção, o Snowflake infere colunas PII e bloqueia esta operação, mas esta inferência não está disponível em um ambiente sandbox. Ele só deve ser usado em colunas que você deseja que o provedor possa agregar e agrupar, por exemplo, Status, Faixa etária, Código de região ou Dias ativos.

Para definir a política de coluna para uma combinação de modelo/tabela, execute o seguinte comando:

CALL samooha_by_snowflake_local_db.consumer.set_column_policy($cleanroom_name, [
    'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:STATUS', 
    'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:AGE_BAND', 
    'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:DAYS_ACTIVE', 
    'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:REGION_CODE'
]);

Permitir que o provedor execute análises¶

Um consumidor precisa aprovar explicitamente a capacidade de um provedor de executar análises modelo por modelo. Sem essa aprovação, o provedor não pode executar uma análise, mesmo que tenha configurado a sala limpa para isso.

Primeiro, você pode verificar se o provedor configurou a sala limpa para que ele possa executar análises.

CALL samooha_by_snowflake_local_db.library.is_provider_run_enabled($cleanroom_name)

Em seguida, você pode executar o seguinte comando para permitir que o provedor execute análises. Você deve executar o comando para cada modelo que deseja que o provedor possa usar. Você deve dar sua aprovação depois de configuração as políticas de junção e coluna para impedir que o provedor execute uma análise em dados desprotegidos.

CALL samooha_by_snowflake_local_db.consumer.enable_templates_for_provider_run($cleanroom_name, ['prod_overlap_analysis']);

Ter acesso às informações do consumidor¶

Executar uma análise como um provedor processa dados na conta do consumidor. Para recuperar os resultados da análise, o provedor precisa ter acesso às informações que o consumidor envia ao provedor. Execute o seguinte comando para obter acesso às informações originárias do consumidor:

CALL samooha_by_snowflake_local_db.provider.mount_request_logs_for_all_consumers($cleanroom_name);

Execute a análise¶

O provedor executa o comando provider.submit_analysis_request quando deseja executar uma análise.

CALL samooha_by_snowflake_local_db.provider.submit_analysis_request(
    $cleanroom_name, 
    '<CONSUMER_ACCOUNT>',
    'prod_overlap_analysis', 
    ['SAMOOHA_SAMPLE_DATABASE.demo.customers'], 
    ['SAMOOHA_SAMPLE_DATABASE.demo.customers'], 
    object_construct(       
      'dimensions', ['c.REGION_CODE'],        
      'measure_type', ['AVG'],           
      'measure_column', ['c.DAYS_ACTIVE'],
      'where_clause', 'p.hem=c.hem'                                         
    ));

O comando provider.submit_analysis_request do provedor retorna um identificador de solicitação. Você deve salvar este identificador para poder verificar o status da solicitação de análise e recuperar os resultados da análise. Por exemplo, você pode executar o seguinte para salvar o identificador em uma variável local:

SET request_id = '<REQUEST_ID>';

Depois de enviar a solicitação para executar uma análise, você pode verificar o status da solicitação executando o seguinte comando. Observe que pode haver um atraso quando você executar o comando pela primeira vez.

CALL samooha_by_snowflake_local_db.provider.check_analysis_status(
    $cleanroom_name, 
    $request_id, 
    '<CONSUMER_ACCOUNT_LOCATOR>'
);

Quando o status retornado pelo comando provider.check_analysis_status for COMPLETED, você pode recuperar os resultados da análise executando o seguinte comando:

CALL samooha_by_snowflake_local_db.provider.get_analysis_result(
    $cleanroom_name, 
    $request_id, 
    '<CONSUMER_ACCOUNT_LOCATOR>'
);