Snowflake Data Clean Rooms: Guia de referência da API do consumidor¶
O conteúdo a seguir detalha todos as APIs de desenvolvedor fornecidas pelas Snowflake Data Clean Rooms para consumidores. Todas as funções residem dentro do seguinte esquema:
samooha_by_snowflake_local_db.consumer
Configuração do ambiente¶
Execute os seguintes comandos para configurar o ambiente Snowflake antes de usar as APIs de desenvolvedor para trabalhar com uma Snowflake Data Clean Room. Se você não tiver a função SAMOOHA_APP_ROLE, entre em contato com o administrador de sua conta.
use role samooha_app_role;
use warehouse app_wh;
Atribua um nome para a sala limpa que o provedor compartilhou com você:
set cleanroom_name = 'Test Cleanroom 1';
Instalação da sala limpa¶
Instale a sala limpa que o provedor compartilhou por meio dos seguintes comandos:
consumidor.install_cleanroom¶
Descrição: Instala a sala limpa na conta do consumidor com o provedor associado e a sala limpa selecionada.
Argumentos: cleanroom_name (string), provider_account_locator (string)
Retorna: mensagem de sucesso (string)
Exemplo:
call samooha_by_snowflake_local_db.consumer.install_cleanroom($cleanroom_name, '<PROVIDER_ACCOUNT_LOCATOR>');
consumer.is_enabled¶
Descrição: Após a instalação da sala limpa, o provedor leva cerca de 1 minuto para concluir a configuração e habilitá-la. Esta função permite ao usuário verificar o status da sala limpa e ver se ela está habilitada ou não. O sinalizador geralmente muda para Verdadeiro cerca de 1 minuto após a instalação da sala limpa.
Argumentos: cleanroom_name (string)
Retorna: está ativado (boolean)
Exemplo:
call samooha_by_snowflake_local_db.consumer.is_enabled($cleanroom_name);
consumer.uninstall_cleanroom¶
Descrição: Desinstala a sala limpa na conta do consumidor. Isso remove todos os bancos de dados associados à sala limpa, incluindo o banco de dados da sala limpa compartilhada. Observe que a sala limpa sempre pode ser instalada novamente com consumer.install_cleanroom.
Argumentos: cleanroom_name (string)
Retorna: mensagem de sucesso (string)
Exemplo:
call samooha_by_snowflake_local_db.consumer.uninstall_cleanroom($cleanroom_name);
Configuração da análise de execução do provedor¶
library.is_provider_run_enabled¶
Descrição: Verifica se esta sala limpa tem Provider Run Analysis habilitado. Observação: a aprovação explícita ainda precisa ser dada chamando consumer.enable_templates_for_provider_run (consulte abaixo).
Argumentos: cleanroom_name (string)
Retorna: mensagem ativada (string)
Exemplo:
call samooha_by_snowflake_local_db.library.is_provider_run_enabled($cleanroom_name)
biblioteca.is_consumer_run_enabled¶
Descrição: Verifica se esta sala limpa tem Consumer Run Analysis habilitado. Este sinalizador determina se o consumidor da sala limpa (instalador) pode executar análises ou atuar como um colaborador de dados.
Argumentos: cleanroom_name (string)
Retorna: mensagem ativada (string)
Exemplo:
call samooha_by_snowflake_local_db.library.is_consumer_run_enabled($cleanroom_name)
consumer.enable_templates_for_provider_run¶
Descrição: Se uma sala limpa tiver Provider Run Analysis habilitado (ou seja, o provedor da sala limpa marcou a sala limpa para permitir que os provedores executem a análise), este procedimento deve ser chamado pelo consumidor para habilitá-lo. Este procedimento é necessário para conceder aprovação explícita, modelo por modelo, aos provedores que desejam executar análises.
O parâmetro booliano final permite que o consumidor habilite a privacidade diferencial para as análises do provedor, se definido como TRUE.
Argumentos:
cleanroom_name (string) – Nome da sala limpa.
template_names (matriz de cadeias de caracteres) – Uma matriz de um ou mais modelos na sala limpa que deve ser habilitada para análise do provedor
enable_differential_privacy(booliano) – Se TRUE, habilite a privacidade diferencial para todos os modelos listados em
template_names
. A privacidade diferencial pode ser ativada para esses modelos somente se a ela estiver ativada para a própria sala limpa. É possível verificar o status de privacidade diferencial de uma sala limpa chamandoconsumer.is_dp_enabled
.
Retorna: mensagem de sucesso (string)
Exemplo:
call samooha_by_snowflake_local_db.consumer.enable_templates_for_provider_run($cleanroom_name, ['prod_overlap_analysis'], FALSE);
Registro e cancelamento de registro de dados¶
Use o comando a seguir para registrar e cancelar o registro de bancos de dados, esquemas e objetos. Tabelas e exibições devem ser registradas antes de poderem ser vinculadas à sala limpa. Se você registrar um banco de dados ou esquema, todos os objetos naquele banco de dados ou esquema serão registrados.
consumer.register_db¶
Descrição: Ao adicionar um banco de dados à sala limpa, você pode vincular qualquer conjunto de dados do banco de dados. Se não for chamado, as concessões terão que ser feitas para samooha_app_role individualmente.
Argumentos: db_name (string)
Retorna: mensagem de sucesso (string)
Exemplo:
call samooha_by_snowflake_local_db.consumer.register_db('SAMOOHA_SAMPLE_DATABASE');
library.register_schema¶
Descrição: semelhante a register_db
, mas opera em nível de esquema. Uma matriz ou cadeia de caracteres representando o nome do esquema totalmente qualificado pode ser passado, e seleções de concessão para a função SAMOOHA_APP_ROLE são feitas, permitindo que o usuário vincule os objetos no esquema à sala limpa.
Se você quiser registrar um esquema de acesso gerenciado (ou seja, um esquema criado com o parâmetro WITH MANAGED ACCESS), use library.register_managed_access_schema
.
Argumentos: schema_name (array)
Retorna: mensagem de sucesso (string)
Exemplo:
call samooha_by_snowflake_local_db.library.register_schema(['SAMOOHA_SAMPLE_DATABASE.DEMO']);
library.register_managed_access_schema¶
Descrição: semelhante a register_schema
, mas registra um esquema que foi criado com o parâmetro WITH MANAGED ACCESS. Uma matriz ou cadeia de caracteres representando o nome do esquema totalmente qualificado pode ser passado, e seleções de concessão para a função SAMOOHA_APP_ROLE são feitas, permitindo que o usuário vincule os objetos no esquema à sala limpa.
Argumentos: schema_name (array)
Retorna: mensagem de sucesso (string)
Exemplo:
call samooha_by_snowflake_local_db.library.register_managed_access_schema(['SAMOOHA_SAMPLE_DATABASE.DEMO']);
library.register_objects¶
Descrição: concede à sala limpa acesso a tabelas e exibições de todos os tipos, tornando-as disponíveis para serem vinculadas à sala limpa por meio da chamada de consumer.link_datasets
. É possível registrar grupos mais amplos de objetos chamando library.register_schema
, library.register_managed_access_schema
ou consumer.register_db
.
Argumentos:
object_names (array) – Matriz de nomes de objeto totalmente qualificados. Esses objetos podem então ser conectados à sala limpa.
Retorna: mensagem de sucesso (string)
Exemplos
Para registrar uma tabela e uma exibição:
call samooha_by_snowflake_local_db.library.register_objects(
['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS','SAMOOHA_SAMPLE_DATABASE.INFORMATION_SCHEMA.FIELDS']);
library.register_table_or_view – Obsoleto¶
Atenção
Esse comando está obsoleto. Use library.register_objects.
Descrição: registra tabelas e exibições de todos os tipos.
Argumentos: object_names (array), is_view (boolean), is_iceberg (boolean), is_external (boolean), is_under_managed_access_schema (boolean)
Saída mensagem de sucesso (string)
Exemplos
Para registrar uma tabela:
call samooha_by_snowflake_local_db.library.register_table_or_view(
['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS'],
false,
false,
false,
false);
Para registrar uma tabela Iceberg:
call samooha_by_snowflake_local_db.library.register_table_or_view(
['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS'],
false,
true,
false,
false);
library.register_table – Obsoleto¶
Atenção
Esse comando está obsoleto. Use library.register_objects.
Descrição: Semelhante a register_db
, mas opera ao nível de tabela. Uma matriz ou cadeia de caracteres representando o nome da tabela totalmente qualificado pode ser passada, e serão concedidos privilégios de seleção à função SAMOOHA_APP_ROLE são criadas, permitindo que o usuário vincule a tabela à sala limpa.
Se você quiser registrar tabelas em um esquema de acesso gerenciado (ou seja, um esquema criado com o parâmetro WITH MANAGED ACCESS), use library.register_managed_access_table
.
Argumentos: table_name (array)
Retorna: mensagem de sucesso (string)
Exemplo:
call samooha_by_snowflake_local_db.library.register_table(['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);
library.register_managed_access_table – Obsoleto¶
Atenção
Esse comando está obsoleto. Use library.register_objects.
Descrição: semelhante a register_table
, mas registra tabelas que foram criadas com o parâmetro WITH MANAGED ACCESS. Uma matriz ou cadeia de caracteres representando o nome da tabela totalmente qualificado pode ser passada, e serão concedidos privilégios de seleção à função SAMOOHA_APP_ROLE são criadas, permitindo que o usuário vincule a tabela à sala limpa.
Argumentos: table_name (array)
Retorna: mensagem de sucesso (string)
Exemplo:
call samooha_by_snowflake_local_db.library.register_managed_access_table(['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);
library.register_view – Obsoleto¶
Atenção
Esse comando está obsoleto. Use library.register_objects.
Descrição: semelhante a register_db
, mas opera em nível de exibição. Uma matriz ou cadeia de caracteres representando o nome da exibição totalmente qualificado pode ser passada, e seleções de concessão para a função SAMOOHA_APP_ROLE são feitas, permitindo que o usuário link a exibição à sala limpa.
Se você quiser registrar exibições em um esquema de acesso gerenciado (ou seja, um esquema criado com o parâmetro WITH MANAGED ACCESS), use library.register_managed_access_view
.
Argumentos: view_name (array)
Retorna: mensagem de sucesso (string)
Exemplo:
call samooha_by_snowflake_local_db.library.register_view(['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);
library.register_managed_access_view – Obsoleto¶
Atenção
Esse comando está obsoleto. Use library.register_objects.
Descrição: semelhante a register_view
, mas registra exibições que foram criadas com o parâmetro WITH MANAGED ACCESS. Uma matriz ou cadeia de caracteres representando o nome da exibição totalmente qualificado pode ser passada, e seleções de concessão para a função SAMOOHA_APP_ROLE são feitas, permitindo que o usuário link a exibição à sala limpa.
Argumentos: view_name (array)
Retorna: mensagem de sucesso (string)
Exemplo:
call samooha_by_snowflake_local_db.library.register_managed_access_view(['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);
library.unregister_db¶
Descrição: Inverte o procedimento register_db
e remove as concessões ao nível de banco de dados concedidas à função SAMOOHA_APP_ROLE e ao aplicativo nativo de Snowflake Data Clean Room. Isso também remove qualquer banco de dados do menu suspenso de UI.
Argumentos: db_name (string)
Retorna: mensagem de sucesso (string)
Exemplo:
call samooha_by_snowflake_local_db.library.unregister_db('SAMOOHA_SAMPLE_DATABASE');
library.unregister_schema¶
Descrição: cancela o registro de um esquema, o que impede que os usuários vinculem suas tabelas e exibições à sala limpa.
Se você quiser cancelar o registro de um esquema de acesso gerenciado (ou seja, um esquema criado com o parâmetro WITH MANAGED ACCESS), use library.unregister_managed_access_schema
.
Argumentos: schema_name (array)
Retorna: mensagem de sucesso (string)
Exemplo:
call samooha_by_snowflake_local_db.library.unregister_schema(['SAMOOHA_SAMPLE_DATABASE.DEMO']);
library.unregister_managed_access_schema¶
Descrição: semelhante a unregister_schema
, mas cancela o registro em um esquema que foi criado com o parâmetro WITH MANAGED ACCESS.
Argumentos: schema_name (array)
Retorna: mensagem de sucesso (string)
Exemplo:
call samooha_by_snowflake_local_db.library.unregister_managed_access_schema(['SAMOOHA_SAMPLE_DATABASE.DEMO']);
library.unregister_objects¶
Descrição: revoga o acesso de sala limpa a tabelas e exibições de todos os tipos. Os objetos não estarão mais disponíveis para nenhum usuário em nenhuma sala limpa gerenciada por essa conta.
Argumentos:
object_names (array) – Matriz de nomes de objetos totalmente qualificados para os quais o acesso deve ser revogado.
Retorna: mensagem de sucesso (string)
Exemplos
Para cancelar o registro de uma tabela e de uma exibição:
call samooha_by_snowflake_local_db.library.unregister_objects(
['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS','SAMOOHA_SAMPLE_DATABASE.INFORMATION_SCHEMA.FIELDS']);
library.unregister_table_or_view – Obsoleto¶
Atenção
Esse comando está obsoleto. Use library.unregister_objects.
Descrição: cancela o registro de tabelas e exibições de todos os tipos.
Argumentos: object_names (array), is_view (boolean), is_iceberg (boolean), is_external (boolean), is_under_managed_access_schema (boolean)
Saída mensagem de sucesso (string)
Exemplos
Para cancelar o registro de uma tabela:
call samooha_by_snowflake_local_db.library.unregister_table_or_view(
['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS'],
false,
false,
false,
false);
library.unregister_table – Obsoleto¶
Atenção
Esse comando está obsoleto. Use library.unregister_objects
Descrição: semelhante a unregister_db
, mas opera em nível de tabela. Uma matriz ou cadeia de caracteres representando o nome da tabela totalmente qualificado pode ser passada para cancelar o registro das tabelas. Os usuários não podem vincular tabelas não registradas a uma sala limpa.
Se você quiser cancelar o registro de tabelas em um esquema de acesso gerenciado (ou seja, um esquema criado com o parâmetro WITH MANAGED ACCESS), use library.unregister_managed_access_table
.
Argumentos: table_name (array)
Retorna: mensagem de sucesso (string)
Exemplo:
call samooha_by_snowflake_local_db.library.unregister_table(['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);
library.unregister_managed_access_table – Obsoleto¶
Atenção
Esse comando está obsoleto. Use library.unregister_objects
Descrição: semelhante a unregister_table
, mas cancela o registro de tabelas em um esquema de acesso gerenciado (ou seja, um esquema criado com o parâmetro WITH MANAGED ACCESS).
Argumentos: table_name (array)
Retorna: mensagem de sucesso (string)
Exemplo:
call samooha_by_snowflake_local_db.library.unregister_managed_access_table(['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);
library.unregister_view – Obsoleto¶
Atenção
Esse comando está obsoleto. Use library.unregister_objects
Descrição: semelhante a unregister_db
, mas opera em nível de exibição. Uma matriz ou cadeia de caracteres representando o nome de exibição totalmente qualificado pode ser passada para cancelar o registro das exibições. Os usuários não podem vincular exibições não registradas a uma sala limpa.
Se você quiser cancelar o registro de exibições em um esquema de acesso gerenciado (ou seja, um esquema criado com o parâmetro WITH MANAGED ACCESS), use library.unregister_managed_access_view
.
Argumentos: view_name (array)
Retorna: mensagem de sucesso (string)
Exemplo:
call samooha_by_snowflake_local_db.library.unregister_view(['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);
library.unregister_managed_access_view – Obsoleto¶
Atenção
Esse comando está obsoleto. Use library.unregister_objects
Descrição: semelhante a unregister_view
, mas cancela o registro de exibições em um esquema de acesso gerenciado (ou seja, um esquema criado com o parâmetro WITH MANAGED ACCESS).
Argumentos: view_name (array)
Retorna: mensagem de sucesso (string)
Exemplo:
call samooha_by_snowflake_local_db.library.unregister_managed_access_view(['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);
Vinculação e desvinculação de conjuntos de dados¶
Após o registro de um conjunto de dados, é possível vincular tabelas ou exibições desse conjunto de dados a uma sala limpa específica. Também é possível desvincular uma tabela ou exibição de uma sala limpa específica para remover o acesso a esses dados de sala limpa.
consumer.link_datasets¶
Descrição: vincule uma tabela ou exibição à sala limpa, dando aos modelos dessa sala limpa acesso à tabela, de acordo com as políticas de junção e coluna que você especificar.
Argumentos:
cleanroom_name (string) – Nome da sala limpa para conceder acesso
tables_list (matriz de cadeias de caracteres) – Lista de nomes de tabelas ou exibições totalmente qualificados a serem expostos na sala limpa. Esses objetos devem primeiro ser registrados (disponibilizados para o ambiente de sala limpa) com o método de registro apropriado.
Retorna: mensagem de sucesso (string)
Exemplo:
call samooha_by_snowflake_local_db.consumer.link_datasets($cleanroom_name, ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS', 'SAMOOHA_SAMPLE_DATABASE.DEMO.EXPOSURES']);
consumer.unlink_datasets¶
Descrição: remove o acesso às tabelas ou exibições especificadas na sala limpa especificada para todos os usuários. Isso só funciona para dados fornecidos pelo consumidor.
Argumentos:
cleanroom_name (string) – Nome da sala limpa cujo acesso deve ser removido.
tables_list (matriz de cadeias de caracteres) – Lista de nomes de tabelas ou exibições totalmente qualificados para os quais o acesso deve ser bloqueado.
Retorna: mensagem de sucesso (string)
Exemplo:
call samooha_by_snowflake_local_db.consumer.unlink_datasets($cleanroom_name, ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS', 'SAMOOHA_SAMPLE_DATABASE.DEMO.EXPOSURES']);
consumer.view_consumer_datasets¶
Descrição: exibe todas as tabelas e exibições vinculadas à sala limpa especificada por qualquer consumidor nessa conta.
Argumentos:
cleanroom_name (string) – Nome da sala limpa.
Retorna: tabela de objetos vinculados à sala limpa especificada, juntamente com o nome da exibição interna da sala limpa para cada objeto.
Exemplo:
call samooha_by_snowflake_local_db.consumer.view_consumer_datasets($cleanroom_name);
Análise executada pelo provedor¶
consumer.set_join_policy¶
Descrição: Especifica em quais colunas o provedor tem permissão para executar uma junção ao executar modelos na sala limpa, quando estiver usando Provider Run Analysis. 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 atual.
Observe que as verificações são realizadas analisando a consulta SQL a ser executada nos dados para quaisquer colunas não autorizadas. Consultas com curingas podem não ser detectadas usando essas verificações, e ainda assim é preciso ter cautela ao projetar o modelo de análise.
Argumentos: cleanroom_name(cadeia de caracteres), table_and_col_names(matriz)
Retorna: mensagem de sucesso (string)
Exemplo:
call samooha_by_snowflake_local_db.consumer.set_join_policy($cleanroom_name, ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:EMAIL', 'SAMOOHA_SAMPLE_DATABASE.DEMO.EXPOSURES:EMAIL']);
consumer.set_column_policy¶
Descrição: Define em quais colunas de dados o provedor pode realizar operações. Isso só deve ser chamado depois que o modelo for adicionado. Esta também é uma função de modelo, portanto as entradas precisam estar no formato template_name:full_table_name:column_name. Observe que a política de coluna é somente substituição, portanto, se a função for recuperada, a política de coluna definida anteriormente será completamente substituída pela atual.
A política de coluna não deve ser chamada em colunas de identidade como e-mail. Ela deve ser usada somente em colunas agregadas e agrupadas.
Observe que as verificações são realizadas analisando a consulta SQL a ser executada nos dados para quaisquer colunas não autorizadas. Consultas com curingas podem não ser detectadas usando essas verificações, e ainda assim é preciso ter cautela ao projetar o modelo de análise.
As verificações são realizadas em argumentos SQL Jinja chamados dimensions ou measure_columns. Certifique-se de usar essas tags para habilitar essa verificação.
Argumentos: cleanroom_name(cadeia de caracteres), analysis_and_table_and_columns(matriz)
Retorna: mensagem de sucesso (string)
Exemplo:
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.EXPOSURES:CAMPAIGN']);
Modelos¶
Os comandos a seguir permitem que os usuários trabalhem com modelos disponíveis na sala limpa.
consumer.view_template_definition¶
Descrição: As definições do modelo de sala limpa estão disponíveis para ajudar a determinar quais parâmetros precisam ser passados ao modelo.
Nota
Observe que todos os procedimentos do Samooha são criptografados e não podem ser visualizados por padrão. No entanto, todos os modelos personalizados que você adicionar ficarão visíveis para você.
Argumentos: cleanroom_name (string), template_name (string)
Retorna: a definição do modelo (string)
Exemplo:
call samooha_by_snowflake_local_db.consumer.view_template_definition($cleanroom_name, 'prod_overlap_analysis');
consumer.get_arguments_from_template¶
Descrição: Define como os dados devem ser organizados e quais dados são necessários para cada modelo para garantir que a saída seja facilmente digerível.
Argumentos: cleanroom_name (string), template_name (string)
Retorna: lista de argumentos e especificação (tabela)
Exemplo:
call samooha_by_snowflake_local_db.consumer.get_arguments_from_template($cleanroom_name, 'prod_overlap_analysis');
Encadeamentos de modelos¶
Os comandos a seguir permitem que os usuários trabalhem com cadeias de modelos disponíveis na sala limpa. Para obter informações gerais sobre o uso de cadeias de modelos, consulte Como usar APIs do desenvolvedor para executar modelos sequencialmente.
consumer.view_added_template_chains¶
Descrição: exibe as cadeias de modelos atualmente ativas na sala limpa.
Argumentos: cleanroom_name (string)
Retorna: cadeias de modelos adicionadas (tabela)
Exemplo:
call samooha_by_snowflake_local_db.consumer.view_added_template_chains($cleanroom_name);
consumer.view_template_chain_definition¶
Descrição: retorna os atributos de uma cadeia de modelos.
Argumentos: cleanroom_name (string), template_chain_name (string)
Retorna: definição da cadeia de modelos (string)
Exemplo:
call samooha_by_snowflake_local_db.consumer.view_template_chain_definition($cleanroom_name, 'insights_chain');
consumer.get_arguments_from_template_chain¶
Descrição: retorna os argumentos esperados para todos os modelos na cadeia de modelos.
Argumentos: cleanroom_name (string), template__chain_name (string)
Retorna: lista de argumentos e especificação (tabela)
Exemplo:
call samooha_by_snowflake_local_db.consumer.get_arguments_from_template_chain($cleanroom_name, 'insights_chain');
Execução de análises¶
Os comandos a seguir executam uma análise ou ativação específica com base no modelo especificado.
consumer.run_analysis¶
Descrição: executa uma análise usando um modelo ou cadeia de modelos e retorna a tabela de resultados.
Se a privacidade diferencial estiver ativada, a consulta poderá falhar se você tiver atingido o limite de orçamento para esse modelo.
Argumentos:
cleanroom_name (cadeia de caracteres) – Nome da sala limpa que tem o modelo a ser executado.
template_name (cadeia de caracteres) – nome do modelo ou da cadeia de modelos a ser executada na sala limpa.
consumer_tables (matriz de cadeia de caracteres) – matriz de nomes de tabelas de consumidor totalmente qualificados. Elas são atribuídas à variável de modelo
my_table
. Essas tabelas já devem estar vinculadas à sala limpa. Veja as tabelas disponíveis chamandoconsumer.view_consumer_datasets
. Por exemplo, se você passar [“mytable1”,”mytable2”,”mytable3”], o modelo poderá acessar esses valores como{{my_table[0]}}
,{{my_table[1]}}
e{{my_table[2]}}
, respectivamente.provider_tables (matriz de cadeia de caracteres) – Matriz de nomes de tabela de provedor totalmente qualificados. Elas são atribuídas à variável de modelo
source_table
. Essas tabelas já devem estar vinculadas à sala limpa. Veja as tabelas disponíveis chamandoconsumer.view_provider_datasets
. Por exemplo, se você passar [“sourcetable1”,”sourcetable2”,”sourcetable3”], o modelo poderá acessar esses valores como{{source_table[0]}}
,{{source_table[1]}}
e{{source_table[2]}}
, respectivamente.analysis_arguments (objeto) – Um objeto com pares chave-valor passados para o modelo. O modelo pode acessar a variável pelo nome da chave. Se você passar o endereço
{'age': 20}
, o modelo acessará o valor como{{age}}
. Passe um objeto vazio se nenhum valor for necessário. Para ver quais valores são necessários, examine o modelo em questão chamandoconsumer.view_template_definition
. Esse objeto tem um valor reservado opcional:epsilon
(float, opcional) – especifica o valor de epsilon para privacidade diferencial, se a privacidade diferencial estiver ativada para essa sala limpa. O padrão é 0.1.
use_cache (booliano, opcional) – Se você deve ou não usar resultados em cache para a mesma consulta. O padrão é TRUE. Defina como FALSE ao testar e editar um modelo para garantir que a consulta seja executada novamente usando a versão mais recente do modelo todas as vezes.
Retorna: (tabela) resultados de consulta.
Exemplo:
call samooha_by_snowflake_local_db.consumer.run_analysis(
$cleanroom_name,
'prod_overlap_analysis',
['SAMOOHA_SAMPLE_DATABASE.MYDATA.CONVERSIONS'], -- Consumer tables
['SAMOOHA_SAMPLE_DATABASE.DEMO.EXPOSURES'], -- Provider tables
object_construct(
'max_age', 30
)
);
Ativação¶
Para obter mais informações sobre a ativação de resultados, consulte Usando as APIs de desenvolvedor para enviar resultados a uma conta Snowflake para ativação.
consumer.set_activation_policy¶
Descrição: define quais colunas podem ser usadas nos modelos de ativação. Isso garante que somente as colunas aprovadas pelo consumidor possam ser usadas com o modelo de ativação.
Entrada: cleanroom_name (string), columns (array)
O argumento columns é passado no formato <template_name>:<fully_qualified_table_name>:<column_name>
.
Saída: mensagem de sucesso
Exemplo:
call samooha_by_snowflake_local_db.consumer.set_activation_policy('my_cleanroom', [
'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE_NAME.DEMO.CUSTOMERS:HASHED_EMAIL',
'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE_NAME.DEMO.CUSTOMERS:REGION_CODE' ]);
consumer.approve_provider_activation_consent¶
Descrição: aprova a solicitação do provedor para permitir a ativação do provedor, que é a capacidade de enviar resultados para a conta Snowflake do provedor. Pressupõe que o provedor já tenha chamado provider.request_provider_activation_consent
para solicitar permissão.
Entrada: cleanroom_name (string), activation_template_name (string)
Saída: mensagem de sucesso
Exemplo:
call consumer.approve_provider_activation_consent('my_cleanroom', 'activation_my_template');
consumer.run_activation¶
Descrição: executa um modelo que envia os resultados de volta para uma conta Snowflake para ativação.
Argumentos: cleanroom_name (string), segment_name (string), template_name (string), consumer_tables (array), provider_tables (array), activation_arguments (objeto), consumer_direct_activation (boolean), application_id (string)
Se o consumidor estiver enviando os resultados para sua própria conta Snowflake para ativação, defina o argumento consumer_direct_activation como TRUE
.
Passe uma cadeia de caracteres vazia como argumento para application_id.
Retorna: mensagem de sucesso
Exemplo:
call samooha_by_snowflake_local_db.consumer.run_activation(
$cleanroom_name,
'my_activation_segment',
'activation_custom_template',
['consumer_source_table'],
['provider_source_table'],
object_construct( -- Custom arguments needed for the template
'dimensions', ['p.CAMPAIGN'], -- always use p. to refer to fields in provider tables, and c. to refer to fields in consumer tables. Use p2, p3, etc. for more than one provider table and c2, c3, etc. for more than one consumer table.
'where_clause', 'p.EMAIL=c.EMAIL'
));
Modelos definidos pelo consumidor¶
As seguintes APIs permitem que você adicione modelos definidos pelo consumidor a uma sala limpa. Para obter mais informações, consulte Como usar a API do desenvolvedor para adicionar modelos definidos pelo consumidor.
consumer.create_template_request¶
Descrição: envia uma solicitação ao provedor de uma sala limpa solicitando que ele aprove um modelo personalizado para que ele possa ser adicionado à sala limpa.
Argumentos: cleanroom_name (string), template_name (string), template_definition (string)
Retorna: mensagem de sucesso (string)
Exemplo:
CALL samooha_by_snowflake_local_db.consumer.create_template_request('dcr_cleanroom',
'my_analysis',
$$
SELECT
identifier({{ dimensions[0] | column_policy }})
FROM
identifier({{ my_table[0] }}) c
INNER JOIN
identifier({{ source_table[0] }}) p
ON
c.identifier({{ consumer_id }}) = identifier({{ provider_id | join_policy }})
{% if where_clause %} where {{ where_clause | sqlsafe | join_and_column_policy }} {% endif %};
$$);
consumer.generate_python_request_template¶
Descrição: gera um modelo de sala limpa para o consumidor que inclui código Python personalizado. O modelo gerado inclui seu código Python e um espaço reservado para seu modelo JinjaSQL. Passe seu modelo final para consumer.list_template_requests
.
Saiba mais sobre modelos definidos pelo consumidor.
Argumentos:
function_name (string) – O nome da função Python que o modelo SQL deve chamar para executar a função.
arguments (matriz de cadeia de caracteres) – Lista de argumentos para sua função Python, em que cada argumento é um par de cadeia de caracteres delimitado por espaço no formato «<argument_name> <argument_type>». Por exemplo:
['data variant', 'scale integer']
.packages (matriz de cadeia de caracteres) – Matriz de nomes de pacote necessários para o seu código Python. Se não houver, especifique uma matriz vazia. Exemplo:
['pandas','numpy']
.imports (matriz de cadeias de caracteres) – Quaisquer bibliotecas Python personalizadas necessárias para o código Python. Deve ser uma matriz de zero ou mais endereços de estágio. Exemplo:
['@db.schema.stage/my_python_sproc.py']
rettype (string) – O tipo de retorno SQL de sua função. Exemplos:
'integer'
,'varchar'
.handler (string) – O nome da função principal do manipulador em seu código Python. Normalmente, isso é
'main'
.code (string) – Sua implementação de código Python. Se você incluir uma importação e o manipulador designado for definido dentro de uma importação, isso poderá ser uma cadeia de caracteres vazia.
Retorna: modelo Python gerado (string). Substitua o espaço reservado pelo seu código SQL.
Exemplo:
Chame a função auxiliar com um exemplo trivial em Python.
call SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.CONSUMER.GENERATE_PYTHON_REQUEST_TEMPLATE(
'my_func', // SQL should use this name to call your function
['data variant', 'index integer'], // Arguments and types for the function
['pandas', 'numpy'], // Standard libraries used
[], // No custom libraries needed.
'integer', // Return type integer
'main', // Standard main handler
// Python implementation as UDF
$$
import pandas as pd
import numpy as np
def main(data, index):
df = pd.DataFrame(data) # you can do something with df but this is just an example
return np.random.randint(1, 100)
$$
);
Aqui está a resposta à chamada anterior. Insira seu JinjaSQL conforme indicado no espaço reservado e passe-o para consumer.create_template_request
.
BEGIN
-- First define the Python UDF
CREATE OR REPLACE FUNCTION CLEANROOM.my_func(data variant, index integer)
RETURNS integer
LANGUAGE PYTHON
RUNTIME_VERSION = 3.10
PACKAGES = ('pandas', 'numpy')
HANDLER = 'main'
AS '
import pandas as pd
import numpy as np
def main(data, index):
df = pd.DataFrame(data) # you can do something with df but this is just an example
return np.random.randint(1, 100)
';
-- Then define and execute the SQL query
LET SQL_TEXT varchar := '<INSERT SQL TEMPLATE HERE>';
-- Execute the query and return the result
LET RES resultset := (EXECUTE IMMEDIATE :SQL_TEXT);
RETURN TABLE(RES);
END;
consumer.list_template_requests¶
Descrição: lista as solicitações que o consumidor fez para adicionar um modelo a uma sala limpa.
Argumentos: cleanroom_name (string)
Retorna: request_id(cadeia de caracteres), provider_identifier(cadeia de caracteres), template_name(cadeia de caracteres), template_definition(cadeia de caracteres), request_status(cadeia de caracteres), reason(cadeia de caracteres)
Exemplo:
CALL samooha_by_snowflake_local_db.consumer.list_template_requests('dcr_cleanroom');
Métodos de obtenção de metadados de sala limpa¶
Os métodos a seguir mostram as propriedades relevantes da sala limpa:
consumer.describe_cleanroom¶
Descrição: Cria um resumo de texto com todas as informações sobre o que foi adicionado à sala limpa, incluindo modelos, conjuntos de dados, políticas etc.
Argumentos: cleanroom_name(cadeia de caracteres)
Retorna: cadeia de caracteres de descrição extensa da sala limpa (tabela)
Exemplo:
call samooha_by_snowflake_local_db.consumer.describe_cleanroom($cleanroom_name);
consumer.view_provider_datasets¶
Descrição: Exibe todos os conjuntos de dados adicionados à sala limpa pelo provedor.
Argumentos: cleanroom_name(cadeia de caracteres)
Retorna: todos os nomes de conjuntos de dados do provedor na sala limpa (tabela)
Exemplo:
call samooha_by_snowflake_local_db.consumer.view_provider_datasets($cleanroom_name);
consumer.view_join_policy¶
Descrição: Descreve quais colunas os usuários podem unir com segurança em uma sala limpa, definidas pelo consumidor nos conjuntos de dados do consumidor.
Argumentos: cleanroom_name (string)
Retorna: política de junção (tabela)
Exemplo:
call samooha_by_snowflake_local_db.consumer.view_join_policy($cleanroom_name);
consumer.view_provider_join_policy¶
Descrição: Descreve quais colunas os usuários podem unir com segurança em uma sala limpa, definidas pelo provedor nos conjuntos de dados do provedor.
Argumentos: cleanroom_name (string)
Retorna: política de junção (tabela)
Exemplo:
call samooha_by_snowflake_local_db.consumer.view_provider_join_policy($cleanroom_name);
consumer.view_added_templates¶
Descrição: Exibe todos os modelos ativos na sala limpa.
Argumentos: cleanroom_name (string)
Retorna: modelos adicionados (tabela)
Exemplo:
call samooha_by_snowflake_local_db.consumer.view_added_templates($cleanroom_name);
consumer.view_column_policy¶
Descrição: Exibe todas as políticas de coluna aplicadas à sala limpa pelo consumidor.
Argumentos: cleanroom_name (string)
Retorna: política de coluna (tabela)
Exemplo:
call samooha_by_snowflake_local_db.consumer.view_column_policy($cleanroom_name);
consumer.view_provider_column_policy¶
Descrição: Exibe todas as políticas de coluna aplicadas à sala limpa pelo provedor.
Argumentos: cleanroom_name (string)
Retorna: política de coluna (tabela)
Exemplo:
call samooha_by_snowflake_local_db.consumer.view_provider_column_policy($cleanroom_name);
consumer.view_cleanrooms¶
Descrição: mostra todas as salas limpas associadas (instaladas) ou que podem ser associadas por essa conta. As salas limpas com falha não são mostradas. Na tabela de resultados:
IS_ALREADY_INSTALLED: verdadeiro se você tiver ingressado na sala limpa (guia Ingressado no aplicativo da Web), falso se você tiver sido convidado a participar da sala limpa, mas ainda não tiver ingressado nela (guia Convidado no aplicativo da Web).
Problema conhecido: – Às vezes, esse método pode não mostrar as salas limpas desinstaladas. Se você sabe que uma sala limpa foi compartilhada com você, mas ela não está aparecendo na lista, chame
consumer.describe_cleanroom
para ver se essa sala limpa está disponível para ingresso.
Argumentos: nenhum
Retorna: todas as salas limpas existentes ordenadas por data de criação (tabela)
Exemplo:
call samooha_by_snowflake_local_db.consumer.view_cleanrooms();
-- Now filter out invitations that have not been accepted
SELECT cleanroom_name FROM TABLE(RESULT_SCAN(LAST_QUERY_ID())) WHERE is_already_installed = TRUE;
Privacidade diferencial¶
Esses comandos controlam a privacidade diferencial na sala limpa. Você também pode especificar a privacidade diferencial no nível do modelo ao chamar consumer.enable_templates_for_provider_run
.
Saiba mais sobre como gerenciar a privacidade diferencial.
consumer.is_dp_enabled¶
Descrição: Verifica se a privacidade diferencial foi habilitada na sala limpa.
Argumentos: cleanroom_name(cadeia de caracteres)
Retorna: se a sala limpa tem DP ativado (boolean)
Exemplo:
call samooha_by_snowflake_local_db.consumer.is_dp_enabled($cleanroom_name);
consumer.view_remaining_privacy_budget¶
Descrição: Exibe o orçamento de privacidade restante que pode ser usado para fazer consultas na sala limpa. Uma vez esgotadas, outras chamadas para run_analysis não serão permitidas até que o orçamento seja redefinido. O orçamento é redefinido diariamente.
SELECT cleanroom_name FROM TABLE(RESULT_SCAN(LAST_QUERY_ID())) WHERE is_already_installed = TRUE;
Argumentos: cleanroom_name (string)
Retorna: orçamento de privacidade restante (float)
Exemplo:
call samooha_by_snowflake_local_db.consumer.view_remaining_privacy_budget($cleanroom_name);
Métodos auxiliares gerais¶
Use os métodos a seguir para ajudar na funcionalidade geral da sala limpa.
consumer.set_cleanroom_ui_accessibility¶
Descrição: mostra ou oculta salas limpas no aplicativo da Web para consumidores na conta corrente.
Argumentos:
cleanroom_name(cadeia de caracteres) – O nome da sala limpa.
visibility_status(cadeia de caracteres) – Um dos seguintes valores que diferenciam maiúsculas de minúsculas:
HIDDEN – Oculta a sala limpa especificada no aplicativo da Web de todos os usuários da conta de consumidor atual. A sala limpa ainda estará acessível por meio de chamadas de API.
EDITABLE – Torna a sala limpa visível no aplicativo da Web.
Retorna: mensagem de sucesso (string)
Exemplo:
call samooha_by_snowflake_local_db.consumer.set_cleanroom_ui_accessibility($cleanroom_name, 'HIDDEN');
library.enable_local_db_auto_upgrades¶
Descrição: habilita a tarefa, samooha_by_snowflake_local_db.admin.expected_version_task
, que atualiza automaticamente o Snowflake Native App para Snowflake Data Clean Rooms conforme novas versões são lançadas.
Argumentos: nenhum
Retorna: mensagem de sucesso (string)
Exemplo:
CALL samooha_by_snowflake_local_db.library.enable_local_db_auto_upgrades();
library.disable_local_db_auto_upgrades¶
Descrição: desabilita a tarefa, samooha_by_snowflake_local_db.admin.expected_version_task
, que atualiza automaticamente o Snowflake Native App para Snowflake Data Clean Rooms conforme novas versões são lançadas.
Argumentos: nenhum
Retorna: mensagem de sucesso (string)
Exemplo:
CALL samooha_by_snowflake_local_db.library.disable_local_db_auto_upgrades();