Guia do desenvolvedor do Snowflake Data Clean Rooms¶
This topic provides guidelines for users who want to create or manage Snowflake Data Clean Rooms programmatically.
Snowflake exposes an API of stored procedures for creating and controlling clean rooms. These stored procedures can be run in any interface that can access the Snowflake account associated with your clean room environment, including Snowsight notebooks and worksheets, as well as the Snowflake CLI. These procedures can be called in SQL or in any language supported by your Snowflake environment.
Configurando seu ambiente¶
Ferramentas de desenvolvimento¶
Aqui estão as principais ferramentas de desenvolvimento para clean rooms:
Ambiente de codificação: qualquer ambiente de codificação que possa executar procedimentos armazenados em sua conta Snowflake funcionará. A maioria dos desenvolvedores usa planilhas no Snowsight (a ferramenta baseada em navegador) ou no Snowflake CLI.
The clean rooms UI: Use the clean rooms UI to configure, manage, or create clean rooms. Most clean room analysts use the UI rather than code, so it’s important to see and test the experience of your clean rooms in the UI. Additionally, there are a handful of features that are available only in the clean rooms UI.
O Snowsight é útil para explorar bancos de dados e outros objetos e pesquisar objetos.
Clean rooms API: API documentation is divided into provider and consumer topic pages.
Configuração de codificação¶
Função e warehouse necessários¶
The clean rooms API requires the SAMOOHA_APP_ROLE role for full API access. Ask your clean rooms administrator to grant you full API access. Clean rooms also supports creating roles with access to a subset of API procedures.
Você deve usar a API de salas limpas em um warehouse que SAMOOHA_APP_ROLE pode usar. O app_wh é um dos vários warehouses com acesso à API. Escolha o warehouse apropriado às suas necessidades.
-- Set up environment.
USE ROLE SAMOOHA_APP_ROLE;
USE WAREHOUSE app_wh;
-- Call your clean rooms API functions.
...
Se você usar qualquer outro warehouse, certifique-se de conceder o uso do SAMOOHA_APP_ROLE nesse warehouse:
GRANT USAGE ON WAREHOUSE <your_warehouse> TO SAMOOHA_APP_ROLE;`
Sobre a API de clean rooms¶
Snowflake Data Clean Rooms exposes a set of stored procedures that let a provider create, configure, and share a clean room. These procedures can be called in any command-line environment that supports Snowflake procedures, including notebooks, worksheets, and the Snowflake CLI. The documentation here shows SQL usage, but you can also use Python or any other supported Snowflake language.
Os procedimentos existem nos seguintes esquemas:
samooha_by_snowflake_local_db.provider– Procedimentos específicos do provedor. Esses procedimentos podem ser chamados apenas em clean rooms criadas na conta atual.samooha_by_snowflake_local_db.consumer– Procedimentos específicos do consumidor. Estes procedimentos podem ser acionados somente em salas limpas para as quais a conta corrente foi convidada como consumidor.samooha_by_snowflake_local_db.library- General procedures called by either the clean room creator (provider) or a clean room collaborator (consumer). These procedures are documented in both the provider and consumer reference pages.
Some procedures have both provider and consumer versions. The results are appropriate to the schema: for example,
provider.view_cleanrooms lists all clean rooms in the current account for which you are a provider, and consumer.view_cleanrooms lists
all clean rooms in the current account for which you are a consumer. Be sure to call the procedure in the namespace that you need.
Sobre nomes de clean rooms em procedimentos de API¶
Muitos procedimentos de API de clean room têm um argumento cleanroom_name.
Use o nome da sala limpa se ela foi criada usando a API. Se usado como parte do nome de um pacote, substitua os espaços por sublinhados:
-- Spaces work here: CALL samooha_by_snowflake_local_db.provider.describe_cleanroom('my code created clean room'); -- Underscores required here: SHOW VERSIONS IN APPLICATION PACKAGE SAMOOHA_CLEANROOM_my_code_created_clean_room;
Use o ID da sala limpa se ela foi criada usando a UI de salas limpas.
Você pode ver o nome e o ID da sala limpa chamando describe_cleanroom ou view_cleanrooms.
Clean rooms created using the API are labeled in the clean rooms UI as Supported with Developer APIs.
Configuração de contas, usuários e funções¶
You aren’t required to use the clean rooms UI to develop clean rooms: most clean room functionality is available by calling the API. However, a few features are available only in the UI, and some are faster to perform in the UI. And because many users use the UI exclusively, it’s important to see how your clean room behaves in the UI. Therefore, you should ask a clean room administrator to add you as a clean room manager or higher in the appropriate clean room accounts.
Dependendo do seu caso de uso, você também pode configurar uma conta Snowflake adicional em diferentes regiões de hospedagem na Web para testar o comportamento entre nuvens.
Name your test Snowflake accounts meaningfully to indicate their typical usage: for example, «Consumer account,» «Provider account,» and «Cross-cloud account.» This can help when you have multiple test accounts and must choose an account on the clean rooms login page.
Salas limpas de teste interno¶
You can test a clean room during development by sharing the clean room with yourself. Such a clean room is called an internal testing clean room. Using a single account for both provider and consumer is convenient for quick feature testing.
To create an internal testing clean room, simply pass the provider account information to provider.add_consumers as the sole consumer.
Internal testing clean rooms have the following restrictions:
An internal testing clean room cannot later be shared with other accounts. An internal testing clean room always is an internal testing clean room.
Não há suporte para os seguintes recursos nas salas limpas de teste interno:
Ativação do provedor
Análises executadas pelo provedor
Montagem ou visualização de logs de solicitação (
provider.mount_request_logs_for_all_consumersouprovider.view_request_logs)Modelos definidos pelo consumidor
Análises multiprovedor
Privacidade diferencial
Se você quiser testar recursos para os quais não há suporte em uma sala de teste interno, deverá configurar contas Snowflake de provedor e de consumidor separadas para testar os dois lados de uma sala limpa.
Download a sample worksheet that demonstrates using a clean room in a
single account for both provider and consumer.
Veja o que está instalado com o ambiente de salas limpas¶
O Snowflake Data Clean Rooms cria muitos bancos de dados locais após a instalação. Você encontra os detalhes sobre as tarefas e os objetos executados ou instalados com um pacote de sala limpa em Snowflake Data Clean Rooms: objetos instalados.
Amostra de dados¶
O ambiente de salas limpas instala alguns conjuntos de dados de amostra que você pode usar.
Você também pode gerar dados de teste sintéticos usando o Snowflake.
Diretrizes e recomendações¶
Confirme se você está usando a mesma conta na UI de clean rooms e no código¶
Muitas vezes, você precisa abrir um ambiente de codificação e a UI de clean rooms para a mesma conta Snowflake, por exemplo, ao criar uma clean room no código e depois verificar sua aparência na UI de clean rooms. É importante confirmar que você está usando a mesma conta Snowflake em cada uma delas.
Snowsight does not have a shortcut to open the clean rooms UI for the same account, or the reverse, so you must be sure to log in to the same account in each environment.
Nome de clean room vs. ID de clean room¶
When using the API, for procedures that take a clean room name argument, determine whether to use the clean room name or the clean room ID as follows:
Se a clean room tiver sido criada usando a API, use o nome de clean room.
Se a sala limpa foi criada na UI de salas limpas, use o ID dela. Você pode ver o nome e o ID da sala limpa chamando
provider.view_cleanroomsouprovider.describe_cleanroom.
Update your clean room whenever you make UI changes¶
When you change any clean room properties that affect the UI, call
provider.create_or_update_cleanroom_listing to propagate the changes.
Interoperabilidade entre clean rooms criadas em código ou na UI¶
When you create a clean room using the API, some features are not modifiable in the clean rooms UI. For example, you cannot add additional templates, even stock Snowflake templates, in code for a UI-created clean room. You also cannot change the differential privacy settings.
Solução de problemas¶
O consumidor não pode definir políticas de junção ou executar outras ações básicas em uma sala limpa unida¶
Confirme se você instalou sua clean room com a função adequada (SAMOOHA_APP_ROLE). Se você não tiver usado SAMOOHA_APP_ROLE ao instalar a clean room, encontrará muitos problemas, geralmente erros de permissão. Se esse for o caso, até mesmo consumer.uninstall_cleanroom falhará e você deverá tomar medidas adicionais para desinstalar e reinstalar a clean room com a função correta.
-- Who owns the clean room?
SHOW SHARES LIKE 'SAMOOHA_CLEANROOM_REQUESTS_<cleanroom_name>';
-- If the owner role is not SAMOOHA_APP_ROLE, you must drop the share, then
-- uninstall the clean room.
DROP SHARE SAMOOHA_CLEANROOM_REQUESTS_<cleanroom_name>;
CALL samooha_by_snowflake_local_db.consumer.uninstall_cleanroom($cleanroom_name);
USE ROLE SAMOOHA_APP_ROLE;
CALL samooha_by_snowflake_local_db.consumer.install_cleanroom($cleanroom_name, '<provider_locator>');
Não é possível encontrar uma clean room que você tenha criado¶
Se você criou uma clean room em uma conta, mas não consegue vê-la na conta de colaborador, aqui estão alguns motivos possíveis:
A clean room foi criada em uma região de hospedagem em nuvem diferente e você não habilitou o preenchimento automático entre nuvens.
Você não publicou sua clean room chamando
provider.create_or_update_cleanroom_listing.Você está chamando
consumer.view_cleanrooms()em vez deprovider.view_cleanrooms()(ou o contrário).Você não compartilhou a clean room, compartilhou a clean room com a conta errada ou abriu a conta de colaborador errada no Snowsight ou na UI/CLI de Clean rooms. Confirme se a conta com a qual espera ver sua clean room é aquela com a qual compartilhou a clean room e se você está conectado a essa conta compartilhada.
Há um pequeno atraso entre a publicação de uma clean room e o momento em que ela se torna visível ao colaborador.
Função desconhecida¶
Se você chamar um procedimento e receber um erro parecido com este trecho de código:
Unknown user-defined function SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.CONSUMER.<procedure name>
Estas são algumas causas possíveis:
- Você digitou o namespace errado.
Certifique-se de chamar a versão de
consumerouprovideradequada de seu procedimento. Muitos procedimentos têm versões para provedores e consumidores.- Você cometeu um erro no nome da função.
Consulte o guia de referência para ver a nomenclatura adequada.
- Você recebeu uma função de execução com acesso limitado, e a função que chamou não é permitida por sua função.
Para testar isso, execute o seguinte código SQL:
USE DATABASE samooha_by_snowflake_local_db; CALL IS_DATABASE_ROLE_IN_SESSION('samooha_run_role');
Se o trecho do código retornar TRUE, você tem permissões de função de execução com acesso limitado na API de sala limpa. Se você precisar de acesso mais amplo, peça acesso total ao administrador da sala limpa. Consulte a lista de procedimentos da função de execução permitidos na documentação consumer.grant_run_on_cleanrooms_to_role.
- Você não tem a SAMOOHA_APP_ROLE
Para ver se você pode usar a SAMOOHA_APP_ROLE, execute o seguinte comando:
-- Get current user name. SELECT current_user(); -- Add current user name in place as indicated. SHOW GRANTS TO USER <current_user_name> ->> select * from $1 where "role" = 'SAMOOHA_APP_ROLE';
Se não aparecer nenhum resultado, peça que o administrador lhe conceda acesso de API à sala limpa.
Verificar se um usuário instalou a sala limpa¶
Você pode verificar se um determinado usuário instalou a sala limpa especificada executando o código SQL a seguir. Substitua $consumer_locator e $cleanroom_name pelo localizador do consumidor e pelo nome da sala limpa.
SELECT * FROM snowflake.data_sharing_usage.application_state
WHERE consumer_account_locator = $consumer_locator
AND CONTAINS(package_name, UPPER(REPLACE($cleanroom_name, ' ', '_')));
Verificar seu histórico de consultas ou análises¶
Você pode ver seu histórico de consultas para análises executadas na UI ou no código. Esses históricos são armazenados e verificados separadamente.
Histórico de análises da UI¶
A UI de salas limpas mostra uma lista de todas as análises anteriores desta conta na página Analyses & Queries. Estes resultados são apenas para consultas executadas na UI.
Se você modificar ou excluir uma sala limpa, os relatórios de análise na UI dela serão excluídos, a menos que o relatório use um dos seguintes modelos:
Audience Overlap & Segmentation
SQL Query
Um modelo personalizado.
O histórico de consultas dos modelos listados acima será mantido mesmo que uma sala limpa seja modificada ou excluída.
Histórico de consultas da API¶
Para ver o histórico da conta de todas as chamadas executadas usando a API, incluindo as análises de modelo, faça o seguinte:
Faça login na Snowsight.
No menu de navegação, selecione Monitoring » Query History.
Use os filtros para encontrar a consulta associada à análise e selecione a consulta ou a análise.
Exemplos estendidos¶
To help you understand how to use various features of the Developer APIs, you can refer to the examples in the Use cases and Features sections of the clean rooms documentation.