Análise de dados básica executada pelo consumidor¶

Configuração do ambiente¶

Para usar a API, você deve usar um warehouse no qual a função SAMOOHA_APP_ROLE tenha privilégios. O app_wh é um dos vários warehouses com acesso à API. Escolha o warehouse apropriado às suas necessidades. (Você também pode usar o próprio warehouse, se preferir.)

A função samooha_app_role é necessária para acessar a API.

USE WAREHOUSE app_wh;
USE ROLE samooha_app_role;

Crie a sala limpa¶

A próxima etapa é criar uma nova sala limpa. Isso é feito com uma única chamada de API que especifica se a sala limpa é para uso interno ou externo. As salas limpas internas podem ser acessadas somente por consumidores da mesma organização. As salas limpas externas podem ser usadas por consumidores de fora da organização. Para ambos os tipos, os consumidores devem ser convidados a usar a sala limpa para poderem acessá-la.

As salas limpas externas acionam verificações de segurança adicionais quando determinadas ações são executadas. Quando isso acontece, é necessário chamar provider.view_cleanroom_scan_status para ver quando a verificação de segurança é concluída, para que você possa continuar com a próxima ação.

O seguinte exemplo cria uma sala limpa interna:

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

Vinculação de dados à sala limpa¶

Tanto o provedor quanto o consumidor podem vincular (importar) tabelas, exibições e outros objetos de dados compatíveis a uma sala limpa. Quando você vincula dados, a API cria uma exibição dentro da sala limpa baseada no objeto de origem especificado. No entanto, você deve referenciar um objeto vinculado por seu nome de origem, não pelo nome da exibição interna, em todos os procedimentos de sala limpa.

Os dados vinculados à sala limpa não podem ser acessados diretamente por nenhum colaborador da sala limpa, mas só podem ser acessados por meio de um modelo dentro da sala limpa.

O objeto deve ser registrado para que possa ser vinculado a uma sala limpa. O registro de um objeto concede privilégios de acesso adequados à SAMOOHA_APP_ROLE no objeto. Você pode registrar um objeto diretamente ou registrar um objeto que o contém (como um banco de dados ou esquema) para acessar os objetos filho. Você pode registrar um objeto na UI ou na API, e o registro é feito no nível da conta, não da sala limpa. É mais fácil realizar e gerenciar o registro na UI. Depois de registrar um objeto, ele fica disponível para vinculação por qualquer sala limpa na conta. Saiba mais sobre o registro.

Os links de exemplo a seguir na tabela CUSTOMERS do banco de dados de amostra SAMOOHA_SAMPLE_DATABASE. Esse banco de dados é registrado automaticamente quando você instala o ambiente de sala limpa em uma conta, portanto, não é necessário registrá-lo. É possível vincular ou desvincular objetos a qualquer momento em uma sala limpa, e os resultados se propagam rapidamente para todos os colaboradores.

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

Definição da política de junção¶

Se você adicionar um modelo à sala limpa que permita que o consumidor una seus dados, deverá definir uma política de junção de sala limpa para seus dados. A política de junção de sala limpa especifica quais colunas podem ser unidas nas consultas executadas por colaboradores. Se você não definir nenhuma política de junção para seus dados, por padrão, todas as colunas poderão ser unidas. As colunas protegidas por uma política de junção não podem ser projetadas. A políticas de junção próprias não restringem suas próprias consultas.

As salas limpas oferecem suporte a poucas políticas de dados, que você pode definir nos dados vinculados. Essas políticas são semelhantes, mas não iguais, às políticas equivalentes do Snowflake e são aplicadas somente à exibição interna, não aos dados de origem. As políticas do Snowflake definidas nos dados de origem são propagadas para as exibições criadas quando você vincula os dados. As políticas de sala limpa são definidas somente nos dados vinculados, não nos dados de origem.

Você pode definir políticas somente nos dados vinculados, e não nos dados da outra parte.

O seguinte exemplo mostra como definir uma política de junção para permitir que duas colunas da tabela vinculada possam ser unidas:

CALL samooha_by_snowflake_local_db.provider.set_join_policy(
  $cleanroom_name,
  ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:HASHED_EMAIL',
   'SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:HASHED_PHONE']);

Saiba mais sobre as políticas de junção.

Adição de modelos a uma sala limpa¶

O modelo de sala limpa é um JinjaSQL válido que é quase sempre avaliado como uma consulta SQL. O modelo, às vezes chamado de análise, pode receber argumentos do autor da chamada e acessar todos os dados vinculados à sala limpa. Tanto provedores quanto consumidores podem adicionar e executar modelos a uma sala limpa.

O Snowflake oferece alguns modelos padrão, mas a maioria deles pode ser usada somente na UI. Portanto, é provável que você escreva os próprios modelos personalizados para consumidores (ou para você mesmo) para execução na API.

Por padrão, somente consumidores podem executar modelos. Se um provedor quiser executar um modelo, ele deverá solicitar permissão do consumidor. Da mesma forma, se um consumidor quiser carregar um modelo, ele deverá solicitar permissão do provedor.

Para obter mais informações sobre a criação de um modelo personalizado, leia Adição de modelos personalizados a uma sala limpa e Referência de modelo de sala limpa personalizado.

O seguinte exemplo mostra como adicionar um modelo fornecido pelo Snowflake à sala limpa:

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

Definição de políticas de coluna¶

As políticas de coluna de sala limpa especificam quais colunas das tabelas podem ser projetadas nas consultas executadas por colaboradores. Uma política de coluna está vinculada a uma coluna e a um modelo, portanto, colunas diferentes podem ser definidas como projetáveis com modelos distintos. Um modelo deve estar presente em uma sala limpa para que você possa definir políticas de coluna para ele.

As políticas de coluna, como todas as políticas, são somente substituição; isso significa que a definição de políticas de coluna substitui completamente todas as políticas de coluna existentes definidas por essa conta. Tanto o provedor quanto o consumidor podem definir políticas de coluna em seus dados. Se você não especificar uma política de coluna para seus dados, todas as colunas poderão ser projetadas. Saiba mais sobre as políticas de coluna.

O seguinte exemplo mostra como permitir que quatro colunas sejam projetadas do banco de dados de amostra de salas limpas que foi vinculado:

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']);

Compartilhamento com consumidores¶

O provedor define quem pode acessar a sala limpa como consumidor. Os consumidores designados não podem acessar a sala limpa até que ela seja publicada. Somente as contas adicionadas pelo provedor podem acessar a sala limpa. Os consumidores não podem compartilhar uma sala limpa com outros consumidores.

O exemplo a seguir mostra como compartilhar uma sala limpa com dois consumidores. O procedimento usa duas listas paralelas delimitadas por vírgulas de localizadores de contas de consumidor e a conta de compartilhamento de dados do consumidor IDs.

CALL samooha_by_snowflake_local_db.provider.add_consumers(
  $cleanroom_name,
  'CONSUMER_LOCATOR1,CONSUMER_LOCATOR2',
  'CONSUMER_DATA_SHARING_ACCOUNT_ID1,CONSUMER_DATA_SHARING_ACCOUNT_ID2');

Definição da versão padrão¶

As salas limpas são aplicativos nativos com controle de versão. Determinadas ações, como adicionar código a uma sala limpa, geram uma nova versão de patch do aplicativo. Os consumidores devem instalar a sala limpa em sua conta. A versão que eles instalam é baseada no número da versão padrão que você especifica. Posteriormente, se você publicar uma nova versão da sala limpa e incrementar o número da versão padrão, todas as versões instaladas pelos consumidores serão atualizadas automaticamente, e as novas instalações assumirão como padrão a nova versão. Leia mais sobre o controle de versão de sala limpa.

O seguinte exemplo mostra como definir a versão padrão de uma sala limpa como V1.0.0, que é a versão inicial, se você não carregou nenhum código:

CALL samooha_by_snowflake_local_db.provider.set_default_release_directive(
  $cleanroom_name,
  'V1_0',          -- Version number: Never changes.
  '0'              -- Patch number: Can change.
  );

Publicação da sala limpa¶

Publique ou republique a sala limpa, conforme mostrado no exemplo a seguir. A primeira vez que esse procedimento é chamado, ele torna a sala limpa visível e instalável por qualquer consumidor com quem você a compartilhou. Você deve chamar esse procedimento sempre que fizer alterações significativas, como atualizar a versão padrão ou fazer alterações específicas na UI de salas limpas.

CALL samooha_By_snowflake_local_db.provider.create_or_update_cleanroom_listing(
  $cleanroom_name);

Agora o consumidor pode instalar a sala limpa, vincular dados, definir políticas e executar modelos, conforme descrito a seguir.

Configuração do ambiente¶

Assim como o provedor, o consumidor deve usar um warehouse que a SAMOOHA_APP_ROLE possa acessar. Entretanto, ao contrário do provedor, o consumidor pode usar a função SAMOOHA_APP_ROLE diretamente para acesso completo à API, ou um administrador de sala limpa nessa conta pode conceder uma função mais limitada que dá privilégios para executar um subconjunto da API para consumidores. Essa função limitada, às vezes chamada genericamente de «função de execução», é concedida por um usuário com todos os privilégios de sala limpa. Leia como conceder acesso limitado à API.

Uma função de execução não permite que você instale uma sala limpa, portanto, é necessário usar SAMOOHA_APP_ROLE, conforme mostrado no seguinte exemplo:

USE WAREHOUSE app_wh;
USE ROLE samooha_app_role;

Instalação da sala limpa¶

O seguinte trecho mostra como listar todas as salas limpas instaladas que você foi convidado a instalar:

-- See all clean rooms, installed and not.
CALL samooha_by_snowflake_local_db.consumer.view_cleanrooms();

-- See only clean rooms that aren't installed.
CALL samooha_by_snowflake_local_db.consumer.view_cleanrooms() ->>
  SELECT * FROM $1
    WHERE IS_ALREADY_INSTALLED = false;

Instale a sala limpa que o provedor compartilhou com você, conforme mostrado no exemplo a seguir. Você deve especificar o localizador da conta do provedor ao instalar uma sala limpa.

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

Adição de dados e definição de políticas¶

Se os modelos de sala limpa permitirem que o consumidor inclua os próprios dados em uma consulta, o consumidor registrará e vinculará os dados, e definirá políticas semelhantes às do provedor. Use as versões de consumer desses procedimentos, conforme mostrado no seguinte exemplo:

-- You must use a role with MANAGE GRANTS privilege on an object to register it.
USE ROLE ACCOUNTADMIN;
CALL samooha_by_snowflake_local_db.consumer.register_db('MY_DATABASE');

-- Link some tables.
CALL samooha_by_snowflake_local_db.consumer.link_datasets(
$cleanroom_name,
['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS', 'MY_DATABASE.PUBLIC.EXPOSURES']);

A política de junção do provedor mostra quais colunas do provedor é possível unir. Este exemplo mostra como verificar quais colunas do provedor você pode unir:

CALL samooha_by_snowflake_local_db.consumer.view_provider_join_policy($cleanroom_name);

O provedor precisa da aprovação do consumidor para executar um modelo na sala limpa. Como resultado, a maioria dos consumidores não se importa em definir políticas nas tabelas que eles vinculam.

No entanto, recomendamos que você considere adicionar políticas caso um provedor peça para executar um modelo mais tarde, porque você pode esquecer de adicionar as políticas adequadas na ocasião. Se você não definir propriedades de junção ou de coluna em seus dados, todas as colunas poderão ser unidas e projetadas.

Execute a análise¶

Antes de executar um modelo, normalmente você o examina para ver o que ele faz e quais variáveis ele aceita e, depois disso, examina quais tabelas de provedor estão disponíveis na sala limpa.

-- View the templates available in this clean room.
-- Also shows the template code for each template.
CALL samooha_by_snowflake_local_db.consumer.view_added_templates($cleanroom_name);

-- Show which variables can be passed in when running the specified template.
CALL samooha_by_snowflake_local_db.consumer.get_arguments_from_template(
  $cleanroom_name,
  $template_name
);

-- See which datasets you have linked into the clean room.
CALL samooha_by_snowflake_local_db.consumer.view_consumer_datasets($cleanroom_name);

-- See which datasets the provider has linked into the clean room.
CALL samooha_by_snowflake_local_db.consumer.view_provider_datasets($cleanroom_name);

CALL samooha_by_snowflake_local_db.consumer.run_analysis(
$cleanroom_name,
$template_name,
[],                                              -- This template doesn't accept consumer tables.
['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS'],      -- Provider tables.
object_construct(                                -- Template-specific arguments.
  'dimensions', ['p.STATUS'],                    -- Template takes a variable named 'dimensions'.
  'where_clause', 'p.REGION_CODE=$$REGION_10$$'  -- Template allows you to pass in a WHERE clause.
                                                 -- $$ is used to wrap string literals
  )
);