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

Configuração do ambiente¶

Para usar a API, você deve usar um warehouse no qual SAMOOHA_APP_ROLE tenha privilégios. 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 de sala limpa, 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 oculta e segura dentro da sala limpa, baseada no objeto de origem vinculado. Você faz referência ao objeto vinculado pelo nome da origem dele, não pelo nome da exibição interna dele, em todos os procedimentos da sala limpa.

Os dados vinculados à sala limpa não podem ser acessados ​​diretamente por nenhum colaborador da sala limpa. Os dados vinculados são acessados ​​usando um modelo importado para a sala limpa (a menos que você habilite consultas SQL de formato livre em seus dados).

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 pai (como um banco de dados ou esquema) para acessar objetos filho. Você pode registrar um objeto na UI ou na API.

Os objetos são registrados no nível da conta, não no nível da sala limpa; você precisa registrar um objeto apenas uma vez por conta, e ele pode ser vinculado a qualquer sala limpa na conta. (Você só pode vincular objetos registrados em sua própria conta.) 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. A políticas de junção próprias não restringem suas próprias consultas.

As salas limpas são compatíveis com alguns tipos de políticas de dados que você pode definir em 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. Quaisquer políticas do Snowflake definidas nos dados de origem são propagadas para as exibições vinculadas a uma sala limpa. 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¶

Um modelo de sala limpa é um modelo JinjaSQL válido que normalmente resulta em 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 fornece alguns modelos padrão, mas você provavelmente fará seus próprios modelos personalizados.

Quaisquer políticas de sala limpa que você definir serão aplicadas somente se o modelo incluir filtros de política. Portanto, certifique-se de que os modelos adicionados a uma sala limpa incluam esses filtros. Para obter mais informações sobre políticas, consulte Compreensão das políticas de tabela de clean room.

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. 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¶

Somente os consumidores convidados pelo provedor podem acessar a sala limpa. Os consumidores não podem compartilhar uma sala limpa com outros consumidores. Os consumidores designados não podem acessar a sala limpa até que ela seja publicada. Os convites para participar de uma sala limpa são feitos no nível da conta, não do usuário.

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. No entanto, diferentemente do provedor, o consumidor pode usar a função SAMOOHA_APP_ROLE diretamente para acesso total à API, ou um administrador da 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. Saiba 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á os dados, vinculará os dados e definirá políticas da mesma forma que o provedor. Use as versões de consumer dos 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 preocupa em definir políticas nas tabelas que vinculam. No entanto, recomendamos que você considere adicionar políticas caso um provedor solicite a execução de um modelo posteriormente, pois você pode se esquecer de adicionar as políticas apropriadas nesse momento.

Se você definir políticas, elas serão aplicadas somente se o modelo incluir um filtro join_policy ou column_policy na coluna do modelo. Portanto, certifique-se de que os modelos que você adicionar a uma sala limpa incluam esses filtros para aplicar suas políticas. Para examinar os modelos em uma sala limpa, chame consumer.view_added_templates. Para obter mais informações sobre políticas, consulte Compreensão das políticas de tabela de clean room.

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 list of templates available in this clean room,
-- and the source 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
  )
);