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

Configuração do ambiente¶

To use the API, you must use a warehouse that SAMOOHA_APP_ROLE has privileges in. app_wh is one of a number of warehouses with access to the API. Choose the warehouse that is appropriate for your needs. (You can also use your own warehouse, if you choose.)

The SAMOOHA_APP_ROLE role is required to access the API.

USE WAREHOUSE app_wh;
USE ROLE SAMOOHA_APP_ROLE;

Crie a sala limpa¶

The next step is to create a new clean room. This is done with a single API call that specifies whether the clean room is for internal or external use. Internal clean rooms can be accessed only by consumers within the same organization; external clean rooms can be used by consumers outside the organization. For both clean room types, consumers must be invited to use the clean room to be able to access it.

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¶

Both the provider and consumer can link (import) tables, views, and other supported data objects into a clean room. When you link data, the API creates a hidden, secure view inside the clean room that is based on the linked source object. You reference the linked object by its source name, not its internal view name, in all clean room procedures.

Data linked into the clean room can’t be accessed directly by any clean room collaborators. Linked data is accessed using a template imported into the clean room (unless you enable free-form SQL queries on your data).

Before an object can be linked into a clean room, the object must be registered. Registering an object grants proper access privileges to the SAMOOHA_APP_ROLE on the object. You can either register an object directly, or register a parent object (such as a database or schema) to access child objects. You can register an object in either the UI or the API.

Objects are registered at the account level, not the clean room level; you need to register an object only once per account, and it can be linked into any clean room in the account. (You can link only objects registered in your own account.) After you register an object, the object is available for linking by any clean room in the account. Learn more about registration.

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¶

If you add a template to the clean room that allows the consumer to join on your data, you should set a clean room join policy on your data. A clean room join policy specifies which columns can be joined on in queries run by collaborators. Your own join policies don’t constrain your own queries.

Clean rooms support a few types of data policies that you can set on linked data. These policies are similar to, but not the same as, the equivalent Snowflake policies, and are applied only on the internal view, not on the source data. Any Snowflake policies that are set on the source data are propagated to the views linked into a clean room. Clean room policies are set on the linked data only, not on the source data.

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¶

A clean room template is a valid JinjaSQL template that typically evaluates to a SQL query. A template, sometimes called an analysis, can be passed arguments by the caller, and can access any data linked into the clean room. Both providers and consumers can add templates into a clean room and run them.

Snowflake provides a few standard templates, but you will probably write your own custom templates.

Any clean room policies that you set are enforced only if the template includes policy filters in the template, so make sure that the templates you add to a clean room include these filters. For more information about policies, see 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.

Column policies, like all policies, are overwrite-only; this means that setting column policies completely overwrites any existing column policies set by that account. Both the provider and the consumer can set column policies on their data. Learn more about column policies.

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¶

Only consumers invited by the provider can access the clean room. Consumers can’t share a clean room with other consumers. Designated consumers can’t access the clean room until it is published. Invitations to join a clean room are at the account level, not at the user level.

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¶

Like the provider, the consumer must use a warehouse that SAMOOHA_APP_ROLE can access. However, unlike the provider, the consumer can either use the SAMOOHA_APP_ROLE role directly for full API access, or a clean room administrator in that account can grant a more limited role that gives privileges to run a subset of the API for consumers. This limited role, sometimes generically called a «run role,» is granted by a user with full clean room privileges. Learn how to grant limited API access.

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¶

If the clean room templates allow the consumer to include their own data in a query, the consumer registers data, links data, and sets policies like the provider does. Be sure to use the consumer versions of the procedures, as shown in the following example:

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

A provider needs the consumer’s approval to run a template in the clean room. As a result, most consumers don’t bother setting policies on the tables that they link in. Nevertheless, we recommend that you consider adding policies in case a provider asks to run a template later, because you might forget to add appropriate policies at that time.

If you do set policies, they are enforced only if the template includes a join_policy or column_policy filter to the column in the template, so make sure that the templates you add to a clean room include these filters to enforce your policies. To examine the templates in a clean room, call consumer.view_added_templates. For more information about policies, see 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
  )
);