Snowflake Data Clean Rooms: Guia de referência da API do provedor¶
Esta página descreve os procedimentos usados pelos consumidores de API de clean rooms para gerenciar suas clean rooms. Para obter as instruções de configuração de codificação, consulte Configuração de codificação.
Criação, configuração e exclusão de salas limpas¶
view_cleanrooms¶
- Esquema:
PROVIDER
Descrição: lista todas as salas limpas existentes criadas por esta conta de provedor.
Argumentos: nenhum
Retorna: (tabela) uma lista de salas limpas criadas por esta conta de provedor. As salas limpas não precisam ser compartilhadas, instaladas ou usadas pelos consumidores. As salas limpas excluídas são eliminadas do banco de dados e não aparecem nesta lista.
Exemplo:
CALL samooha_by_snowflake_local_db.provider.view_cleanrooms();
describe_cleanroom¶
- Esquema:
PROVIDER
Descrição: obtenha um resumo das informações sobre uma sala limpa, como modelos, políticas de junção, políticas de coluna e consumidores.
Argumentos:
cleanroom_name (cadeia de caracteres) – Nome da sala limpa sobre a qual você deseja obter informações.
Retorna: (cadeia de caracteres) um resumo dos metadados da sala limpa.
Exemplo:
CALL samooha_by_snowflake_local_db.provider.describe_cleanroom($cleanroom_name);
cleanroom_init¶
- Esquema:
PROVIDER
Descrição: cria uma sala limpa com o nome especificado em sua conta. Este procedimento pode levar um minuto ou mais para ser executado. A sala limpa só ficará visível na UI de salas limpas ou para os colaboradores depois que você chamar create_or_update_cleanroom_listing
.
Argumentos:
cleanroom_name (cadeia de caracteres) – nome da sala limpa, com no máximo 80 caracteres. O nome inclui [A‑Z,a‑z,0‑9, ,_].
distribution (cadeia de caracteres, opcional) – um dos seguintes valores:
INTERNAL (padrão): a sala limpa fica visível apenas para usuários da mesma organização e não aciona uma verificação de segurança antes de alterar a versão padrão.
EXTERNAL – A sala limpa está pronta para a produção e pode ser compartilhada fora da organização. A sala limpa aciona uma verificação de segurança antes de alterar a versão padrão. Se você quiser alterar a distribuição após a criação da sala limpa, chame
ALTERPACKAGE
conforme mostrado aqui:ALTER APPLICATION PACKAGE samooha_cleanroom_<CLEANROOM_ID> SET DISTRIBUTION = EXTERNAL;
Retorna: (cadeia de caracteres) mensagem de sucesso ou falha.
Exemplo:
-- Create an internal clean room
CALL samooha_by_snowflake_local_db.provider.cleanroom_init($cleanroom_name, 'INTERNAL');
set_default_release_directive¶
- Esquema:
PROVIDER
Descrição: especifica a versão e o patch de uma sala limpa carregada pelos colaboradores quando eles iniciam uma nova sessão do navegador na UI de salas limpas ou quando acessam a sala limpa da API. Isso deve ser feito antes que a sala limpa possa ser compartilhada com os consumidores.
O aplicativo de sala limpa cria uma nova versão de uma sala limpa sempre que você faz upload ou altera o código Python. Se você quiser que os usuários recebam a versão mais recente, chame esse procedimento com o número da nova versão. Para ver as versões disponíveis e saber qual é a versão padrão atual, execute:
Se você esqueceu o número do patch mais recente, pode executar o seguinte código para ver quais versões estão disponíveis (o mais provável é que você queira usar a mais recente como padrão):
SHOW VERSIONS IN APPLICATION PACKAGE SAMOOHA_CLEANROOM_<cleanroom_name>
Em que <cleanroom_name>
segue este formato.
Todas as salas limpas são criadas com os seguintes números de versão e patch:
versão: V1_0
patch: 0
Nota
Se a distribuição da sala limpa estiver definida como EXTERNAL, este procedimento só poderá ser chamado depois que a varredura de segurança da sala limpa passar para o estado APPROVED. Para ver o status de segurança, chame view_cleanroom_scan_status
.
Argumentos:
cleanroom_name (cadeia de caracteres) – Nome da sala limpa.
version (cadeia de caracteres) – Versão. Deve ser sempre «V1_0».
patch (cadeia de caracteres) – Número do patch carregado pelo consumidor. Ele começa com 0 e você deve incrementá-lo sempre que uma nova versão de sala limpa estiver disponível. É possível ver as versões disponíveis conforme descrito acima.
Retorna: (string) Mensagem de sucesso.
Exemplo:
CALL samooha_by_snowflake_local_db.provider.set_default_release_directive($cleanroom_name, 'V1_0', '0');
drop_cleanroom¶
- Esquema:
PROVIDER
Descrição: excluir a sala limpa. Os colaboradores que têm a sala limpa instalada não podem mais acessá-la ou usá-la. A sala limpa não aparece mais na UI de salas limpas na próxima vez que o navegador é atualizado.
Argumentos:
cleanroom_name (cadeia de caracteres) – Nome da sala limpa a ser excluída.
Retorna: (cadeia de caracteres) mensagem de sucesso ou falha.
Exemplo:
CALL samooha_by_snowflake_local_db.provider.drop_cleanroom($cleanroom_name);
enable_consumer_run_analysis¶
- Esquema:
PROVIDER
Descrição: permite que o consumidor execute análises na sala limpa. Este recurso é ativado por padrão em todas as novas salas limpas, portanto, este procedimento só precisa ser executado se você tiver desativado explicitamente a análise de execução do consumidor para uma sala limpa.
Argumentos:
cleanroom_name (cadeia de caracteres) – Nome da sala limpa na qual são permitidas análises executadas pelo consumidor.
consumer_accounts (matriz de cadeias de caracteres): localizadores das contas de todos os consumidores para os quais esse recurso deve ser habilitado. NOTE: Os consumidores já os devem ter adicionado à sala limpa.
Retorna: (cadeia de caracteres) mensagem de sucesso ou falha.
Exemplo:
CALL samooha_by_snowflake_local_db.provider.enable_consumer_run_analysis($cleanroom_name, ['<CONSUMER_ACCOUNT_LOCATOR_1>']);
disable_consumer_run_analysis¶
- Esquema:
PROVIDER
Descrição: impede que os consumidores especificados executem análises na sala limpa especificada. Por padrão, todos os consumidores têm permissão para executar uma análise em uma sala limpa.
Argumentos:
cleanroom_name (cadeia de caracteres) – Sala limpa onde a análise executada pelo consumidor está sendo desativada.
consumer_accounts (matriz de cadeia de caracteres) – Localizadores de contas de consumidores que não podem executar uma análise nesta sala limpa. NOTE: esses consumidores já devem ter sido adicionados à sala limpa.
Retorna: (cadeia de caracteres) mensagem de sucesso ou falha.
Exemplo:
CALL samooha_by_snowflake_local_db.provider.disable_consumer_run_analysis($cleanroom_name, ['<CONSUMER_ACCOUNT_LOCATOR_1>']);
is_consumer_run_enabled¶
- Esquema:
LIBRARY
Descrição: verifica se esta sala limpa permite análises executadas pelo consumidor.
Argumentos:
cleanroom_name (cadeia de caracteres) – Nome da sala limpa a ser verificada.
Retorna: (cadeia de caracteres) se esta sala limpa permite ou não análises executadas pelo consumidor.
Exemplo:
CALL samooha_by_snowflake_local_db.library.is_consumer_run_enabled($cleanroom_name)
create_or_update_cleanroom_listing¶
- Esquema:
PROVIDER
Descrição: publica uma nova sala limpa ou atualiza uma sala limpa existente. É necessário chamar este método sempre que fizer alterações em uma sala limpa para garantir que as alterações sejam propagadas aos consumidores.
Ao publicar uma sala limpa pela primeira vez, pode levar até 15 minutos para que ela fique visível na UI de salas limpas.
Se você fizer atualizações em uma sala limpa sem depois chamar esse método, não haverá garantia de que as alterações serão propagadas aos consumidores.
Há um limite para o número de salas limpas + colaboradores que você pode criar em uma única conta. Se você criar muitas salas limpas de teste, talvez seja necessário excluir algumas para criar novas. Se você precisar de mais salas limpas do que sua conta pode armazenar, entre em contato com o suporte Snowflake.
Nota
É necessário definir a diretiva de lançamento pelo menos uma vez antes de chamar este procedimento. Para obter mais informações, consulte provider.set_default_release_directive.
Argumentos:
cleanroom_name (cadeia de caracteres) – Nome da sala limpa a ser publicada ou atualizada.
Retorna: (cadeia de caracteres) mensagem de sucesso ou falha.
Tratamento de erros:
se você receber um erro informando que o «preenchimento automático entre nuvens não está habilitado para esta conta», isso significa que um dos consumidores está em outra região de hospedagem na nuvem. Você deve habilitar o preenchimento automático entre nuvens, conforme descrito em Gerenciando o preenchimento automático entre nuvens em Snowflake Data Clean Rooms.
Exemplo:
CALL samooha_by_snowflake_local_db.provider.create_or_update_cleanroom_listing($cleanroom_name);
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.
Saiba mais sobre o registro de dados
register_db¶
- Esquema:
PROVIDER
Descrição: permite que um banco de dados e todos os objetos dele sejam vinculados a salas limpas individuais neste ambiente de sala limpa. Esse procedimento concede os privilégios USAGE e SELECT no banco de dados para SAMOOHA_APP_ROLE, que é a função usada pelo ambiente de sala limpa para acessar os dados.
É necessário ter acesso a MANAGE GRANTS no banco de dados para chamar este procedimento. Outros provedores neste ambiente de sala limpa podem, então, vincular estes objetos às suas próprias salas limpas sem precisar de seu próprio privilégio SELECT.
Saiba mais sobre o registro de dados
Importante
Este procedimento não registra nenhum objeto criado após sua chamada. Se novos objetos foram adicionados ao banco de dados e você quiser registrá-los também, deverá chamar este procedimento novamente.
Argumentos:
db_name (cadeia de caracteres) – Nome do banco de dados a ser registrado.
Retorna: (cadeia de caracteres) mensagem de sucesso ou falha.
Exemplo:
USE ROLE <ROLE_WITH_MANAGE_GRANTS>;
CALL samooha_by_snowflake_local_db.provider.register_db('SAMOOHA_SAMPLE_DATABASE');
register_schema¶
- Esquema:
LIBRARY
Descrição: semelhante ao register_db
, mas opera no nível do esquema. É necessário ter o privilégio MANAGE GRANTS no esquema para chamar este procedimento.
Esse procedimento concede os privilégios USAGE e SELECT no esquema para SAMOOHA_APP_ROLE, que é a função usada pelo ambiente de sala limpa para acessar os dados.
Se quiser registrar um esquema de acesso gerenciado (ou seja, um esquema criado usando o parâmetro WITH MANAGED ACCESS), use library.register_managed_access_schema
.
Importante
Este procedimento não registra nenhum objeto criado após sua chamada. Se novos objetos foram adicionados ao banco de dados e você quiser registrá-los também, deverá chamar este procedimento novamente.
Argumentos:
schema_name (matriz de cadeia de caracteres) – Uma matriz de um ou mais nomes de esquema totalmente qualificados a serem registrados.
Retorna: (cadeia de caracteres) mensagem de sucesso ou falha.
Exemplo:
USE ROLE <ROLE_WITH_MANAGE GRANTS>;
CALL samooha_by_snowflake_local_db.library.register_schema(['SAMOOHA_SAMPLE_DATABASE.DEMO']);
register_managed_access_schema¶
- Esquema:
LIBRARY
Descrição: semelhante a register_schema
, mas registra um esquema criado usando o parâmetro WITH MANAGED ACCESS. É necessário ter os privilégios MANAGE GRANTS no esquema para chamar esse procedimento.
Este procedimento concede privilégios de uso no esquema gerenciado para SAMOOHA_APP_ROLE, que é usado pelo ambiente de sala limpa para acessar os dados.
Importante
Este procedimento não registra nenhum objeto criado após sua chamada. Se novos objetos foram adicionados ao banco de dados e você quiser registrá-los também, deverá chamar este procedimento novamente.
Argumentos:
schema_name (matriz de cadeia de caracteres) – Uma matriz de um ou mais nomes de esquema totalmente qualificados.
Retorna: (cadeia de caracteres) mensagem de sucesso ou falha.
Exemplo:
USE ROLE <ROLE_WITH_MANAGE GRANTS>;
CALL samooha_by_snowflake_local_db.library.register_managed_access_schema(['SAMOOHA_SAMPLE_DATABASE.DEMO']);
register_objects¶
- Esquema:
LIBRARY
Descrição: concede à sala limpa acesso a tabelas e exibições de todos os tipos, tornando-as disponíveis para serem vinculadas à sala limpa, chamando provider.link_datasets
. É possível registrar grupos mais amplos de objetos chamando library.register_schema
, library.register_managed_access_schema
ou provider.register_db
.
Este procedimento concede privilégios de uso no objeto para SAMOOHA_APP_ROLE, que é usado pelo ambiente da sala limpa para acessar os dados.
É necessário ter o privilégio MANAGE GRANTS no objeto para chamar este procedimento. Este procedimento não pode ser usado para registrar um banco de dados.
Se você registrar uma exibição baseada em um objeto em outro banco de dados, também deverá conceder permissão ao aplicativo nativo para acessar o objeto de origem.
Argumentos:
object_names (array) – Matriz de nomes de objeto totalmente qualificados. Esses objetos podem então ser conectados à sala limpa.
Retorna: (cadeia de caracteres) mensagem de sucesso ou falha.
Exemplos
Para registrar uma tabela e uma exibição:
USE ROLE <ROLE_WITH_MANAGE GRANTS>;
CALL samooha_by_snowflake_local_db.library.register_objects(
['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS',
'SAMOOHA_SAMPLE_DATABASE.INFORMATION_SCHEMA.FIELDS'
]
);
enable_external_tables_on_account¶
- Esquema:
LIBRARY
Descrição: habilita o uso de tabelas Iceberg ou externas em todas as clean rooms dessa conta. Deve ser chamado por um ACCOUNTADMIN em ambas as contas, provedor e consumidor, para permitir que tabelas Iceberg ou externas sejam vinculadas por ambas as contas. Para limitar essa capacidade às clean rooms específicas nessa conta, chame enable_external_tables_for_cleanroom
em vez disso.
Se tudo der certo e todas as verificações de segurança forem aprovadas, será gerada uma nova versão de patch da sala limpa.
Argumentos: nenhum
Retorna: (cadeia de caracteres) mensagem de sucesso ou falha. Se for bem-sucedido, ele aciona uma varredura de segurança e também fornece o número do patch que será gerado se a varredura de segurança for bem-sucedida.
Exemplo:
USE ROLE ACCOUNTADMIN;
CALL samooha_by_snowflake_local_db.library.enable_external_tables_on_account();
enable_external_tables_for_cleanroom¶
- Esquema:
PROVIDER
Descrição: permite que o provedor vincule tabelas Iceberg ou externas à clean room especificada nessa conta. Para permitir tabelas Iceberg e externas para todas as clean rooms dessa conta, chame enable_external_tables_on_account
em vez disso.
Se for bem-sucedido, isso gerará uma nova versão do patch da clean room.
Argumentos:
cleanroom_name (string) – O nome da clean room à qual o provedor pode vincular as tabelas Iceberg ou externas.
Retorna: (cadeia de caracteres) mensagem de sucesso ou falha. Se for bem-sucedido, ele aciona uma varredura de segurança e também fornece o número do patch que será gerado se a varredura de segurança for bem-sucedida.
Exemplo:
CALL samooha_by_snowflake_local_db.provider.enable_external_tables_for_cleanroom(
$cleanroom_name);
unregister_db¶
- Esquema:
LIBRARY
Descrição: reverte o procedimento register_db
e remove as concessões no nível do banco de dados feitas para a função SAMOOHA_APP_ROLE e o aplicativo nativo Snowflake Data Clean Room. Isso também remove qualquer banco de dados do seletor na UI de salas limpas.
Argumentos:
db_name (cadeia de caracteres) – Nome do banco de dados para cancelar o registro.
Retorna: (cadeia de caracteres) mensagem de sucesso ou falha.
Exemplo:
USE ROLE <ROLE_WITH_MANAGE GRANTS>;
CALL samooha_by_snowflake_local_db.library.unregister_db('SAMOOHA_SAMPLE_DATABASE');
unregister_schema¶
- Esquema:
LIBRARY
Descrição: cancela o registro de um esquema, o que impede que os usuários vinculem suas tabelas e exibições à sala limpa.
Se quiser cancelar o registro de um esquema de acesso gerenciado (ou seja, um esquema criado usando o parâmetro WITH MANAGED ACCESS), use library.unregister_managed_access_schema
.
Argumentos:
schema_name (array) – Esquemas para cancelar o registro.
Retorna: (cadeia de caracteres) mensagem de sucesso ou falha.
Exemplo:
USE ROLE <ROLE_WITH_MANAGE GRANTS>;
CALL samooha_by_snowflake_local_db.library.unregister_schema(['SAMOOHA_SAMPLE_DATABASE.DEMO']);
unregister_managed_access_schema¶
- Esquema:
LIBRARY
Descrição: semelhante a unregister_schema
, mas cancela o registro de um esquema que foi criado usando o parâmetro WITH MANAGED ACCESS.
Argumentos:
schema_name (array) – Esquemas gerenciados para cancelar o registro.
Retorna: (cadeia de caracteres) mensagem de sucesso ou falha.
Exemplo:
USE ROLE <ROLE_WITH_MANAGE GRANTS>;
CALL samooha_by_snowflake_local_db.library.unregister_managed_access_schema(['SAMOOHA_SAMPLE_DATABASE.DEMO']);
unregister_objects¶
- Esquema:
LIBRARY
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: (cadeia de caracteres) mensagem de sucesso ou falha.
Exemplos
Para cancelar o registro de uma tabela e de uma exibição:
USE ROLE <ROLE_WITH_MANAGE GRANTS>;
CALL samooha_by_snowflake_local_db.library.unregister_objects(
['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS',
'SAMOOHA_SAMPLE_DATABASE.INFORMATION_SCHEMA.FIELDS'
]
);
Vinculação de dados e tabelas¶
Use os comandos a seguir para adicionar ou remover tabelas e exibições em uma sala limpa.
link_datasets¶
- Esquema:
PROVIDER
Descrição: vincula uma tabela ou exibição do Snowflake à sala limpa. O procedimento torna a tabela automaticamente acessível à sala limpa, criando uma exibição segura da tabela dentro da sala limpa, evitando assim a necessidade de fazer uma cópia da tabela. A tabela ainda fica vinculada à sua origem, portanto, as atualizações na origem serão refletidas na versão segura da sala limpa.
Todos os itens vinculados aqui devem ser registrados primeiro, no nível do banco de dados, do esquema ou do objeto.
Argumentos:
cleanroom_name (cadeia de caracteres) – Nome da sala limpa com acesso aos objetos.
tables_list (matriz de cadeia de caracteres) – Lista de tabelas ou exibições a serem vinculadas à sala limpa. Os objetos devem ser registrados antes de poderem ser vinculados.
consumer_list (matriz de cadeia de caracteres, opcional) – Se presente, permite que somente os consumidores listados aqui acessem estes objetos. Se não estiver presente, permite que qualquer pessoa com acesso à sala limpa acesse estes dados.
Retorna: (cadeia de caracteres) mensagem de sucesso ou falha.
Exemplo:
CALL samooha_by_snowflake_local_db.provider.link_datasets(
$cleanroom_name,
['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS',
'MYDB.MYSCH.EXPOSURES'
]
);
Nota
Se você vincular uma exibição à clean room e a exibição for baseada em uma tabela de outro banco de dados, deverá registrar a exibição e a origem da exibição
unlink_datasets¶
- Esquema:
PROVIDER
Descrição: remove o acesso às tabelas especificadas na sala limpa especificada para todos os usuários. As tabelas especificadas devem ter sido vinculadas pelo provedor.
Argumentos:
cleanroom_name (cadeia de caracteres) – Nome da sala limpa vinculada a estes conjuntos de dados.
tables_list (array) – Matriz de nomes de tabela ou exibição a serem desvinculadas da sala limpa.
Retorna: (cadeia de caracteres) mensagem de sucesso ou falha.
Exemplo:
CALL samooha_by_snowflake_local_db.provider.unlink_datasets(
$cleanroom_name,
['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS',
'MYDB.MYSCH.EXPOSURES'
]
);
view_provider_datasets¶
- Esquema:
PROVIDER
Descrição: exibe todas as tabelas e exibições vinculadas à sala limpa especificada por qualquer provedor nesta 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.provider.view_provider_datasets($cleanroom_name);
restrict_table_options_to_consumers¶
- Esquema:
PROVIDER
Descrição: controla se um determinado consumidor pode acessar uma tabela na sala limpa. Esse procedimento é somente substituição, o que significa que ele substitui completamente todos os valores definidos em uma chamada anterior.
Os consumidores que obtiveram acesso por meio de provider.link_datasets
, provider.restrict_table_options_to_consumers
ou qualquer outro método, perderão o acesso a uma tabela se ela não for especificada ao chamar esse método.
Nota
As restrições que você cria ao chamar esse procedimento podem não se comportar como esperado na UI de salas limpas. Você não deve chamar esse procedimento em uma sala limpa que pode ser usada na UI de salas limpas.
Argumentos:
cleanroom_name (string) – Nome da clean room a ser restringida.
*access_details (objeto) – Um objeto JSON, em que cada nome de campo é o nome totalmente qualificado de uma tabela ou exibição e o valor do campo é uma matriz de localizadores de conta de usuários que podem acessar essa tabela ou exibição.
Retorna: (cadeia de caracteres) mensagem de sucesso ou falha.
Exemplo:
CALL samooha_by_snowflake_local_db.provider.restrict_table_options_to_consumers(
$cleanroom_name,
{
'DB.SCHEMA.TABLE1': ['CONSUMER_1_LOCATOR'],
'DB.SCHEMA.TABLE2': ['CONSUMER_1_LOCATOR', 'CONSUMER_2_LOCATOR']
}
);
Gerenciamento de políticas¶
As políticas de junção em clean rooms de dados não são iguais às políticas de junção em todo o Snowflake. As políticas de junção para clean rooms são definidas somente por meio deste procedimento; as políticas de junção definidas em tabelas fora das clean rooms são ignoradas pelas clean rooms.
Saiba mais sobre as políticas de tabela em clean rooms.
view_join_policy¶
- Esquema:
PROVIDER
Descrição: mostra as políticas de junção atualmente aplicadas à sala limpa.
Argumentos:
cleanroom_name (cadeia de caracteres) – Nome da sala limpa a ser consultada.
Retorna: (tabela) lista de linhas juntáveis em todas as tabelas ou exibições na sala limpa.
Exemplo:
CALL samooha_by_snowflake_local_db.provider.view_join_policy($cleanroom_name);
set_join_policy¶
- Esquema:
PROVIDER
Descrição: especifica em quais colunas o consumidor pode se unir ao executar modelos dentro desta sala limpa. Observe que a política é somente substituição, portanto, se o procedimento for chamado novamente, a política de junção definida anteriormente será completamente substituída pela nova.
Importante
As políticas de junção são aplicadas somente quando o modelo aplica os filtros JinjaSQL join_policy
ou join_and_column_policy
às linhas de junção.
Nota
As políticas de junção em salas limpas de dados não são as mesmas que as políticas de junção em todo o Snowflake. As políticas de junção para salas limpas são definidas somente por meio deste procedimento; as políticas de junção definidas em tabelas fora das salas limpas são ignoradas pelas salas limpas.
Argumentos:
cleanroom_name (cadeia de caracteres) – nome da sala limpa onde a política de junção deve ser aplicada.
table_and_col_names (matriz de cadeia de caracteres) – Nome de coluna totalmente qualificado no formato
database_name.schema_name.table_or_view_name:column_name
. Observe o uso correto dos marcadores de ponto (.) e dois pontos (:).
Retorna: (cadeia de caracteres) mensagem de sucesso ou falha.
Exemplo:
CALL samooha_by_snowflake_local_db.provider.set_join_policy(
$cleanroom_name,
['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:HASHED_EMAIL',
'MYDB.MYSCH.EXPOSURES:HASHED_EMAIL'
]
);
Gerenciamento de modelos de provedores¶
Use os seguintes comandos para adicionar os modelos/análises compatíveis nesta sala limpa.
view_added_templates¶
- Esquema:
PROVIDER
Descrição: exibe os modelos adicionados pelo provedor na sala limpa. Não existe um método para listar todos os modelos em todas as salas limpas para este provedor.
Argumentos:
cleanroom_name (cadeia de caracteres) – Sala limpa a ser consultada.
Retorna: (tabela) – Lista de modelos disponíveis na sala limpa especificada, com detalhes sobre cada modelo.
Exemplo:
CALL samooha_by_snowflake_local_db.provider.view_added_templates($cleanroom_name);
view_template_definition¶
- Esquema:
PROVIDER
Descrição: mostra informações sobre um modelo específico. Os consumidores que estiverem consultando um modelo de provedor devem usar consumer.view_template_definition
.
Argumentos:
cleanroom_name (cadeia de caracteres) – Nome da sala limpa com este modelo.
template_name (cadeia de caracteres) – Nome do modelo sobre o qual você deseja solicitar informações.
Retorna: a definição do modelo (string)
Exemplo:
CALL samooha_by_snowflake_local_db.provider.view_template_definition(
$cleanroom_name,
$template_name);
add_templates¶
- Esquema:
PROVIDER
Descrição: adiciona uma lista de modelos à sala limpa. Isso não substitui a lista de modelos existente.
Argumentos:
cleanroom_name (cadeia de caracteres) – Nome da sala limpa à qual os modelos serão adicionados.
template_names (matriz de cadeia de caracteres): nome dos modelos a serem adicionados. Esses são apenas modelos fornecidos pela Snowflake. Para adicionar um modelo personalizado, chame
add_custom_sql_template
.
Retorna: (cadeia de caracteres) mensagem de sucesso ou falha.
Exemplo:
CALL samooha_by_snowflake_local_db.provider.add_templates(
$cleanroom_name,
['my_custom_template']);
clear_template¶
- Esquema:
PROVIDER
Descrição: Remove um modelo especificado da sala limpa.
Argumentos:
cleanroom_name (string) – Nome da sala limpa.
template_name (cadeia de caracteres) – Nome do modelo a ser removido dessa sala limpa.
Retorna: (cadeia de caracteres) mensagem de sucesso ou falha.
Exemplo:
CALL samooha_by_snowflake_local_db.provider.clear_template(
$cleanroom_name,
'prod_custom_template');
clear_all_templates¶
- Esquema:
PROVIDER
Descrição: remove todos os modelos que foram adicionados à sala limpa.
Argumentos:
cleanroom_name (cadeia de caracteres) – Nome da sala limpa da qual serão removidos todos os modelos.
Retorna: (cadeia de caracteres) mensagem de sucesso ou falha.
Exemplo:
CALL samooha_by_snowflake_local_db.provider.clear_all_templates($cleanroom_name);
set_column_policy¶
- Esquema:
PROVIDER
Descrição: define quais colunas nos dados estão disponíveis para um modelo especificado na sala limpa como linhas não unidas. As colunas devem ser declaradas aqui ou em set_join_policy
para serem usadas na sala limpa. As colunas listadas aqui podem ser usadas em qualquer lugar do modelo, exceto como uma coluna de junção. Uma coluna não pode ser listada em uma política de coluna e em uma política de junção.
Por padrão, a política de coluna de uma tabela é vazia, o que significa que nenhuma coluna pode ser visualizada nos resultados.
Este procedimento tem o comportamento de substituição completa, portanto, toda vez que é chamado, ele substitui totalmente a lista de colunas anterior.
Observe que as verificações de política de coluna são realizadas analisando a consulta SQL a ser executada nos dados para quaisquer colunas não autorizadas. As consultas com curingas podem não ser detectadas com estas verificações, e você deve ter cuidado ao criar o modelo de análise. Se houver colunas que realmente nunca devem ser consultadas, considere criar uma exibição de sua tabela de origem que elimine essas colunas confidenciais e crie um link nessa exibição.
Argumentos:
cleanroom_name (string) – Nome da sala limpa.
analysis_and_table_and_cols (matriz de cadeia de caracteres) – Matriz de colunas que podem ser usadas por modelos. O formato é:
template_name:full_table_name:column_name
Retorna: (cadeia de caracteres) mensagem de sucesso ou falha.
Exemplo:
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']);
-- Same example, but using a variable name for the template.
CALL samooha_by_snowflake_local_db.provider.set_column_policy($cleanroom_name,
[$template_name || ':SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:STATUS',
$template_name || ':SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:AGE_BAND',
$template_name || ':SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:DAYS_ACTIVE']);
view_column_policy¶
- Esquema:
PROVIDER
Descrição: lista as políticas de coluna atualmente ativas na sala limpa. Uma política de coluna informa quais colunas da tabela podem ser exibidas em quais modelos.
**Argumentos:**cleanroom_name (string)
Retorna: (tabela) quais colunas podem ser usadas em quais modelos.
Exemplo:
CALL samooha_by_snowflake_local_db.provider.view_column_policy($cleanroom_name);
add_custom_sql_template¶
- Esquema:
PROVIDER
Descrição: adiciona um modelo JinjaSQL personalizado à sala limpa. Isso faz com que o modelo possa ser chamado pelo consumidor. Saiba como criar modelos personalizados
Você pode chamar esta API mais de uma vez para adicionar vários modelos personalizados à sala limpa. O procedimento substitui qualquer modelo anterior com o mesmo nome nesta sala limpa.
Se o modelo for usado pelo consumidor para ativar os resultados de volta ao provedor, o comando deverá atender aos seguintes requisitos:
O nome do modelo personalizado deve começar com a cadeia de caracteres
activation
. Por exemplo,activation_custom_template
.O modelo deve criar uma tabela que comece com
cleanroom.activation_data_
. Por exemplo,CREATE TABLE cleanroom.activation_data_analysis_results AS ...
.O modelo deve retornar a parte exclusiva do nome da tabela que foi criada na definição, que é a cadeia de caracteres anexada a
cleanroom.activation_data_
. Por exemplo,retorne 'data_analysis_results'
.
Argumentos:
cleanroom_name (cadeia de caracteres) – Nome da sala limpa à qual este modelo é aplicado.
template_name (cadeia de caracteres) – Nome do modelo. Devem ser todas letras minúsculas, números, espaços ou sublinhados. Os modelos de ativação devem ter um nome que comece com «activation».
template (cadeia de caracteres) – O modelo JinjaSQL.
sensitivity (float, opcional) – Se a privacidade diferencial estiver ativada para essa clean room, ela controlará a quantidade de ruído de privacidade diferencial aplicada aos dados retornados por esse modelo. Deve ser um número maior que 0. O padrão é 1,0. A tarefa de privacidade diferencial deve estar em execução nessa clean room para que esse argumento tenha algum efeito.
consumer_locators (matriz de cadeia de caracteres, opcional) – Uma matriz de um ou mais localizadores de conta. Se estiver presente, esse modelo será adicionado à sala limpa somente para essas contas. É possível modificar essa lista posteriormente chamando
provider.restrict_template_options_to_consumers
. Se você não especificar uma lista de consumidores, todos os consumidores poderão usar o modelo personalizado na sala limpa especificada.is_obfuscated (booliano, opcional) – Se TRUE, evita que os consumidores consigam visualizar o corpo do modelo. Observe que você deve estar usando o Snowflake Enterprise Edition ou superior para executar um modelo ofuscado. Se esse modelo for usado para uma análise conduzida pelo provedor, o consumidor deverá aprovar novamente a solicitação de análise sempre que você alterar o estado
is_obfuscated
.is_obfuscated
não pode ser usado junto comsensitivity
.
Retorna: (cadeia de caracteres) mensagem de sucesso ou falha.
Exemplo:
CALL samooha_by_snowflake_local_db.provider.add_custom_sql_template(
$cleanroom_name, 'prod_custom_template',
$$
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 %};
$$);
add_ui_form_customizations¶
- Esquema:
PROVIDER
Descrição: define um formulário de personalização para um modelo em uma sala limpa quando a sala limpa é executada na UI de salas limpas. Isso é útil para permitir que os consumidores escolham parâmetros de modelo, como tabelas ou colunas. No mínimo, é necessário especificar valores para display_name
, description
e methodology
no argumento template_information
.
Recomenda-se colocar os elementos de seleção de tabela antes dos elementos de seleção de coluna, especialmente quando os seletores de coluna são preenchidos com base na seleção de tabela.
Saiba como criar formulários de entrada do usuário para modelos personalizados.
Você deve atualizar a clean room após chamar essa função. Se você não chamar provider.create_or_update_cleanroom_listing
depois de atualizar a UI, os colaboradores não verão nenhuma atualização.
Argumentos:
cleanroom_name (cadeia de caracteres): o nome da sala limpa com este modelo. O formulário enviado aplica-se somente ao modelo especificado na sala limpa especificada.
template_name (cadeia de caracteres): Nome do modelo ao qual esta UI se aplica. Esse não é o título visível ao usuário, que é especificado no campo
template_information.display_name
.template_information (dict): Informações de metadados sobre o modelo para mostrar na UI de salas limpas. As seguintes propriedades devem ou podem ser definidas:
display_name
(obrigatório): nome de exibição do modelo na UI de salas limpas.description
(obrigatório): descrição do modelo.methodology
(obrigatório): descrição dos argumentos e apresentação do resultado.warehouse_hints
(objeto): recomenda o tipo de warehouse a ser usado para executar a análise. Este é um objeto com os seguintes campos:warehouse_size
: consulte warehouse_size em CREATE WAREHOUSE para obter os valores válidos.snowpark_optimized
(booliano): se um warehouse otimizado para Snowpark deve ou não ser usado para processar a consulta. Para a maioria dos casos de uso de machine learning, a Snowflake recomenda TRUE.
render_table_dropdowns
(objeto): se devem ou não ser mostradas as listas suspensas padrão que permitem ao usuário selecionar quais tabelas de provedor ou consumidor devem ser usadas na consulta. Esse objeto tem os seguintes campos:render_consumer_table_dropdown
: (booliano) se TRUE, mostra o seletor de tabelas de consumidor padrão. Se FALSE, oculte o seletor de tabelas do consumidor. O modelo pode acessar os valores escolhidos como uma lista usando a variável de modelomy_table
. Se algum elemento definirreferences=CONSUMER_TABLES
, o padrão será FALSE, caso contrário, será TRUE.render_provider_table_dropdown
: (booliano) se TRUE, mostra o seletor de tabelas de provedor padrão. Se FALSE, oculte o seletor de tabelas do provedor. O modelo pode acessar os valores escolhidos como uma lista usando a variável de modelosource_table
. Se algum elemento definirreferences=PROVIDER_TABLES
, o padrão será FALSE, caso contrário, será TRUE.
activation_template_name
: (cadeia de caracteres) nome de um modelo de ativação nesta sala limpa. Use o nome do modelo sem um prefixocleanroom
. Saiba mais sobre os modelos de ativação.enabled_activations
: (string) Quais tipos de ativações estão ativadas. Valores possíveis:consumidor
,provedor
. Sem padrão; deve ser fornecido seactivation_template_name
for especificado.
details (dict, opcional): define os campos de entrada configuráveis pelo usuário que passam valores ao modelo. Trata-se de um dicionário de pares chave-objeto, cada par representando um elemento de formulário. A chave é um nome de variável disponível para o modelo JinjaSQL vinculado. O valor é um objeto que define o elemento de formulário. Se uma variável de modelo não tiver um elemento de formulário equivalente definido aqui, as salas limpas vão gerar automaticamente um elemento de formulário padrão. Cada objeto pode definir os seguintes campos:
<field_name>: { ['display_name': <string>,] ['order': <number>,] ['description': <string>,] ['type': <enum>,] ['default': <value>,] ['choices': <string array>,] ['infoMessage': <string>,] ['size': <enum>,] ['required': <bool>,] ['group': <string>,] ['references': <array of string>,] ['provider_parent_table_field': <string>,] ['consumer_parent_table_field': <string>] }
display_name
: texto do rótulo desse item no formulário de UI.order
: ordem baseada em 1 em que esse elemento deve ser mostrado no formulário. Se não for especificado, os elementos serão renderizados na ordem em que aparecem no objeto.description
: uma descrição da finalidade do elemento, mostrada abaixo do rótulo. Insira aqui uma breve ajuda ou exemplos. Se nada for inserido, nada será exibido.type
: o tipo de UI de elemento. Se referências forem especificadas para este campo de entrada, omita esta entrada (o tipo é determinado para você). Valores com suporte:any
(padrão): campo de entrada de texto normal.boolean
: seletor verdadeiro/falsointeger
: Use as setas para alterar o númeromultiselect
: seleciona vários itens em uma lista suspensadropdown
: seleciona um item em uma lista suspensadate
: Seletor de data
default
: valor padrão deste elementochoices
: (matriz de cadeia de caracteres) lista de opções para elementos dropdown e multiselectinfoMessage
: texto informativo mostrado ao lado do elemento. Se não for fornecida, nenhuma dica de ferramenta será fornecida.size
: tamanho do elemento. Valores compatíveis:XS
,S
,M
,L
,XL
required
: se um valor é exigido do usuário. Especificar TRUE ou FALSE.group
: um nome de grupo, usado para agrupar itens na UI. Use o mesmo nome de grupo para os itens que devem ser agrupados na UI. Se você ocultar as listas suspensas padrão, poderá usar os argumentos especiais{{ source_table }}
e{{ my_table}}
no modelo personalizado e definir a própria lista suspensa com as tabelas desejadas. Para obter mais informações sobre o uso dessas variáveis especiais para definir o modelo personalizado, consulte provider.add_custom_sql_template.references
: preenche uma lista suspensa com tabelas ou colunas do tipo especificado na sala limpa. Se for usado,type
deverá sermultiselect
oudropdown
. Os seguintes valores de cadeia de caracteres são permitidos:PROVIDER_TABLES
: liste todas as tabelas do provedor na sala limpa. Se especificado,render_table_dropdowns.render_provider_table_dropdown
deverá ser FALSE.PROVIDER_JOIN_POLICY
: liste todas as colunas na política de junção do provedor para a tabela que está selecionada no elementoprovider_parent_table_field
.PROVIDER_COLUMN_POLICY
: liste todas as colunas na política de coluna do provedor para o modelo atual e a tabela selecionada no elementoprovider_parent_table_field
.PROVIDER_ACTIVATION_POLICY
: liste todas as colunas na política de ativação do provedor.CONSUMER_TABLES
: liste todas as tabelas de consumidor na sala limpa. Se especificado,render_table_dropdowns.render_consumer_table_dropdown
deverá ser FALSE.CONSUMER_COLUMNS
: liste todas as colunas na tabela de consumidor especificadas porconsumer_parent_table_field
. Você não deve usar referências de coluna de consumidor em modelos executados pelo provedor, pois o consumidor pode aplicar políticas de junção e de coluna a essas colunas. Em vez disso, useCONSUMER_JOIN_POLICY
ouCONSUMER_COLUMN_POLICY
para modelos executados pelo provedor.CONSUMER_JOIN_POLICY
: liste todas as colunas na política de junção do consumidor da tabela selecionada no elementoconsumer_parent_table_field
.CONSUMER_COLUMN_POLICY
: liste todas as colunas na política de coluna do consumidor para o modelo atual e a tabela selecionada no campoconsumer_parent_table_field
.
provider_parent_table_field
: O nome do elemento da UI em que o usuário seleciona uma tabela de provedor. Não insira o próprio nome da tabela aqui. Use somente quandoreferences
está definido comoPROVIDER_COLUMN_POLICY
ouPROVIDER_JOIN_POLICY
. Para fazer referência ao seletor de tabelas padrão de provedor, especifiquesource_table
aqui e definarender_table_dropdowns.render_provider_table_dropdown
como TRUE.consumer_parent_table_field
: o nome do elemento da UI em que o usuário seleciona uma tabela de consumidor. Não insira o próprio nome da tabela aqui. Use somente quandoreferences
está definido comoCONSUMER_COLUMNS
,CONSUMER_JOIN_POLICY
ouCONSUMER_COLUMN_POLICY
. Para fazer referência ao seletor de tabelas padrão de consumidor, especifiquemy_table
aqui e definarender_table_dropdowns.render_provider_table_dropdown
como TRUE.
output_config (dict): define como exibir graficamente os resultados do modelo no aplicativo da Web. Se não for fornecido, os resultados não serão exibidos em um gráfico, apenas em uma tabela. Se você não quiser um gráfico, forneça um objeto vazio {} para esse argumento. Campos permitidos:
measure_columns
: nomes das colunas que contêm medidas e dimensões a serem usadas no gráfico gerado pela UI de salas limpas.default_output_type
: o formato padrão para exibir os resultados. Normalmente, o usuário poderá alterar o formato de exibição na UI se os dados estiverem no formato adequado. Tipos suportados:TABLE
: (padrão) formato tabularBAR
: gráfico de barras, que é bom para comparar diferentes categoriasLINE
: gráfico de linhas, que é bom para mostrar tendências ao longo do tempo ou dados contínuosPIE
: gráfico de pizza, que é adequado para mostrar proporções ou porcentagens
A tabela a seguir mostra uma matriz de valores permitidos no objeto details
para os valores que podem entrar em conflito:
|
|
|
|
|
|
---|---|---|---|---|---|
|
|
Não permitido |
Não permitido |
FALSE |
TRUE ou FALSE |
|
|
Não permitido |
TRUE |
TRUE ou FALSE |
|
|
|
Não permitido |
TRUE ou FALSE |
TRUE ou FALSE |
|
|
|
Não permitido |
TRUE |
TRUE ou FALSE |
|
|
|
Não permitido |
TRUE ou FALSE |
TRUE ou FALSE |
|
|
Não permitido |
Não permitido |
TRUE ou FALSE |
FALSE |
|
|
Não permitido |
|
TRUE ou FALSE |
TRUE |
|
|
Não permitido |
|
TRUE ou FALSE |
TRUE |
|
|
Não permitido |
|
TRUE ou FALSE |
TRUE |
|
|
Não permitido |
Não permitido |
TRUE ou FALSE |
TRUE ou FALSE |
Retorna: (cadeia de caracteres) mensagem de sucesso ou falha.
Exemplo:
-- Specify the display name, description, and warehouse, and hide the default table dropdown lists.
-- Define the following two fields in the UI:
-- A provider table selector that shows all provider tables. Chosen tables can be accessed by the template with the variable 'a_provider_table'
-- (This dropdown list is equivalent to setting `render_table_dropdowns.render_provider_table_dropdown: True`)
-- A column selector for the tables chosen in 'a_provider_table'. Chosen columns can be accessed by the template with the variable 'a_provider_col'
CALL samooha_by_snowflake_local_db.provider.add_ui_form_customizations(
$cleanroom_name,
'prod_custom_template',
{
'display_name': 'Custom Analysis Template',
'description': 'Use custom template to run a customized analysis.',
'methodology': 'This custom template dynamically renders a form for you to fill out, which are then used to generate a customized analysis fitting your request.',
'warehouse_hints': {
'warehouse_size': 'xsmall',
'snowpark_optimized': FALSE
},
'render_table_dropdowns': {
'render_consumer_table_dropdown': false,
'render_provider_table_dropdown': false
},
'activation_template_name': 'activation_my_template',
'enabled_activations': ['consumer', 'provider']
},
{
'a_provider_table': {
'display_name': 'Provider table',
'order': 3,
'description': 'Provider table selection',
'size': 'S',
'group': 'Seed Audience Selection',
'references': ['PROVIDER_TABLES'],
'type': 'dropdown'
},
'a_provider_col': {
'display_name': 'Provider column',
'order': 4,
'description': 'Which col do you want to count on',
'size': 'S',
'group': 'Seed Audience Selection',
'references': ['PROVIDER_COLUMN_POLICY'],
'provider_parent_table_field': 'a_provider_table',
'type': 'dropdown'
}
},
{
'measure_columns': ['col1', 'col2'],
'default_output_type': 'PIE'
}
);
restrict_template_options_to_consumers¶
- Esquema:
PROVIDER
Descrição: controla quais usuários podem acessar um determinado modelo em uma determinada sala limpa. Esse procedimento substitui qualquer lista de acesso especificada anteriormente por qualquer outro procedimento para um par de sala limpa/modelo.
Nota
As restrições que você cria ao chamar esse procedimento podem não se comportar como esperado na UI de salas limpas. Você não deve chamar esse procedimento em uma sala limpa que pode ser usada na UI de salas limpas.
Argumentos:
cleanroom_name (string) – Nome da sala limpa.
access_details (objeto JSON) – O nome de um modelo e os usuários que podem acessar esse modelo nessa sala limpa. Se um modelo for especificado, somente os usuários listados aqui poderão acessar esse modelo nessa sala limpa. Esse é um objeto com um objeto filho por modelo no seguinte formato:
{'template_name': ['user1_locator','user2_locator','userN_locator']}
Retorna: (cadeia de caracteres) mensagem de sucesso ou falha.
Exemplo:
CALL samooha_by_snowflake_local_db.provider.restrict_template_options_to_consumers(
$cleanroom_name,
{
'prod_template_1': ['CONSUMER_1_LOCATOR', 'CONSUMER_2_LOCATOR']
}
);
Modelos definidos pelo consumidor¶
As seguintes APIs permitem que você aprove ou rejeite uma solicitação de um consumidor para adicionar um modelo à sala limpa. Um modelo definido pelo consumidor é adicionado a uma sala limpa somente se o provedor aprovar a solicitação do consumidor para adicioná-lo. Para obter mais informações, consulte Modelos personalizados escritos pelo consumidor.
list_pending_template_requests¶
- Esquema:
PROVIDER
Descrição: Lista todas as solicitações não aprovadas de consumidores que desejam adicionar um modelo definido pelo consumidor a uma clean room. Isso inclui solicitações pendentes, aprovadas e rejeitadas. Use esse procedimento para verificar se há solicitações pendentes e aprová-las (provider.approve_template_request
) ou rejeitá-las (provider.reject_template_request
).
Argumentos:
cleanroom_name (cadeia de caracteres) – Exibe solicitações de consumidores para adicionar um modelo a essa sala limpa.
Retorna: uma tabela com os seguintes valores, entre outros:
request_id (cadeia de caracteres): ID da solicitação, necessário para aceitá-la ou rejeitá-la.
consumer_locator (cadeia de caracteres): localizador da conta da pessoa que faz a solicitação.
template_name (cadeia de caracteres): nome do modelo fornecido pelo consumidor.
template_definition (cadeia de caracteres): definição completa do modelo proposto pelo consumidor.
Exemplo:
CALL samooha_by_snowflake_local_db.provider.list_pending_template_requests($template_name);
list_template_requests¶
- Esquema:
PROVIDER
Descrição: lista todas as solicitações de consumidores que desejam adicionar um modelo definido pelo consumidor a uma sala limpa. Isso inclui solicitações pendentes, aprovadas e rejeitadas. Use isso para verificar se há solicitações pendentes e aprová-las (provider.approve_template_request
) ou rejeitá-las (provider.reject_template_request
).
Argumentos:
cleanroom_name (cadeia de caracteres) – Exibe solicitações de consumidores para adicionar um modelo a essa sala limpa.
Retorna: uma tabela com os seguintes valores, entre outros:
request_id (cadeia de caracteres): ID da solicitação, necessário para aceitá-la ou rejeitá-la.
consumer_identifier (cadeia de caracteres): localizador da conta da pessoa que faz a solicitação.
template_name (cadeia de caracteres): nome do modelo fornecido pelo consumidor.
template_definition (cadeia de caracteres): definição completa do modelo proposto pelo consumidor.
status (cadeia de caracteres): status da solicitação: PENDING, APPROVED, REJECTED.
Exemplo:
CALL samooha_by_snowflake_local_db.provider.list_template_requests($template_name);
approve_template_request¶
- Esquema:
PROVIDER
Descrição: aprova uma solicitação para adicionar um modelo à sala limpa.
Argumentos:
cleanroom_name (cadeia de caracteres) – Nome da sala limpa à qual o usuário deseja adicionar o modelo.
request_id (cadeia de caracteres) – ID da solicitação a ser aprovada. Chame
provider.list_template_requests
para ver as IDs de solicitação.
Retorna: (cadeia de caracteres) mensagem de sucesso ou falha.
Exemplo:
CALL samooha_by_snowflake_local_db.provider.approve_template_request($cleanroom_name,
'815324e5-54f2-4039-b5fb-bb0613846a5b');
approve_multiple_template_requests¶
- Esquema:
PROVIDER
Descrição: aprova várias solicitações de consumidores para adicionar um modelo a uma clean room. Todas as solicitações devem ser para uma única clean room.
Argumentos:
cleanroom_name (string) – O nome da clean room à qual essa solicitação se aplica.
request_ids (matriz de cadeia de caracteres) – Os IDs de todas as solicitações de modelo a serem aprovadas. Para obter um ID de solicitação, chame
provider.list_template_requests
.
Retorna: (cadeia de caracteres) mensagem de sucesso ou falha.
Exemplo:
CALL samooha_by_snowflake_local_db.provider.approve_multiple_template_requests(
$cleanroom_name,
['cfd538e2-3a17-48e3-9773-14275e7d2cc9',
'2982fb0a-02b7-496b-b1c1-56e6578f5eac']);
reject_template_request¶
- Esquema:
PROVIDER
Descrição: rejeita uma solicitação para adicionar um modelo a uma sala limpa.
Argumentos:
cleanroom_name (cadeia de caracteres) – Nome da sala limpa à qual o usuário deseja adicionar o modelo.
request_id (cadeia de caracteres) – ID da solicitação a ser rejeitada. Chame
provider.list_template_requests
para ver as IDs de solicitação.reason_for_rejection (cadeia de caracteres) – Motivo da rejeição da solicitação.
Retorna: (cadeia de caracteres) mensagem de sucesso ou falha.
Exemplo:
CALL samooha_by_snowflake_local_db.provider.reject_template_request(
$cleanroom_name,
'cfd538e2-3a17-48e3-9773-14275e7d2cc9',
'Failed security assessment');
reject_multiple_template_requests¶
- Esquema:
PROVIDER
Descrição: rejeita várias solicitações de consumidores para adicionar um modelo a uma clean room. Todas as solicitações devem ser para a mesma clean room.
Argumentos:
cleanroom_name (string) – Nome da clean room à qual essa solicitação se aplica.
rejected_templates (matriz de objetos) – Uma matriz de objetos com os seguintes campos, um por rejeição:
request_id (string) – ID da solicitação a ser rejeitada. Para obter um ID de solicitação, chame
provider.list_template_requests
.reason_for_rejection (string) – Uma descrição em texto livre do motivo pelo qual a solicitação está sendo rejeitada.
Retorna: (cadeia de caracteres) mensagem de sucesso ou falha.
Exemplo:
CALL samooha_by_snowflake_local_db.provider.reject_multiple_template_requests($cleanroom_name,
[OBJECT_CONSTRUCT('request_id', '815324e5-54f2-4039-b5fb-bb0613846a5b', 'reason_for_rejection', 'Failed security assessment'),
OBJECT_CONSTRUCT('request_id', '2982fb0a-02b7-496b-b1c1-56e6578f5eac', 'reason_for_rejection', 'Some other reason')
]);
Encadeamentos de modelos¶
Use os seguintes comandos para criar e gerenciar as cadeias de modelos.
add_template_chain¶
- Esquema:
PROVIDER
Descrição: cria uma nova cadeia de modelos. Os modelos devem existir antes de serem adicionados à cadeia de modelos. Depois que uma cadeia de modelos é criada, ela não pode ser modificada, mas é possível criar uma nova cadeia de modelos com o mesmo nome para substituir a antiga.
Argumentos:
cleanroom_name (cadeia de caracteres) – Nome da sala limpa onde a cadeia de modelos deve ser adicionada.
template_chain_name (cadeia de caracteres) – Nome da cadeia de modelos.
templates (matriz de objetos) – matriz de objetos, um por modelo. O objeto pode conter os seguintes campos:
template_name
(cadeia de caracteres) – Especifica o modelo que está sendo adicionado à cadeia de modelos. O modelo já deve ter sido adicionado à sala limpa chamandoprovider.add_template_chain
.cache_results
(booliano) – Determina se os resultados do modelo são salvos temporariamente para que outros modelos na cadeia de modelos possam acessá-los. Para armazenar os resultados em cache, especifique TRUE.output_table_name
(cadeia de caracteres) – Quandocache_results
= TRUE, especifica o nome da tabela Snowflake onde os resultados do modelo são armazenados.jinja_output_table_param
(cadeia de caracteres) – Quandocache_results
= TRUE, especifica o nome do parâmetro Jinja que outros modelos devem incluir para aceitar os resultados armazenados emoutput_table_name
.cache_expiration_hours
(inteiro) – Quandocache_results
= TRUE, especifica o número de horas antes que os resultados no cache sejam descartados. Quando o cache expira, na próxima vez em que a cadeia de modelos for executada, o cache será atualizado com os resultados do modelo.
Retorna: (cadeia de caracteres) mensagem de sucesso ou falha.
Exemplo:
CALL samooha_by_snowflake_local_db.provider.add_template_chain(
$cleanroom_name,
'my_chain',
[
{
'template_name': 'crosswalk',
'cache_results': True,
'output_table_name': 'crosswalk',
'jinja_output_table_param': 'crosswalk_table_name',
'cache_expiration_hours': 2190
},
{
'template_name': 'transaction_insights',
'cache_results': False
}
]
);
view_added_template_chains¶
- Esquema:
PROVIDER
Descrição: lista as cadeias de modelos na sala limpa especificada.
Argumentos:
cleanroom_name (string) – Nome da sala limpa.
Retorna: (tabela) descrição de todas as cadeias de modelos adicionadas a essa sala limpa.
Exemplo:
CALL samooha_by_snowflake_local_db.provider.view_added_template_chains($cleanroom_name);
view_template_chain_definition¶
- Esquema:
PROVIDER
Descrição: retorna a definição de uma cadeia de modelos.
Argumentos:
cleanroom_name (cadeia de caracteres) – Nome da sala limpa associada a essa cadeia de modelos.
template_chain_name (cadeia de caracteres) – Nome da cadeia de modelos associada a essa sala limpa.
Retorna: (tabela) Descrição da cadeia de modelos especificada.
Exemplo:
CALL samooha_by_snowflake_local_db.provider.view_template_chain_definition(
$cleanroom_name,
'my_chain');
clear_template_chain¶
- Esquema:
PROVIDER
Descrição: exclui uma cadeia de modelos especificada de uma sala limpa especificada. A cadeia não é armazenada em nenhum lugar, portanto, se você quiser recriar a cadeia, deverá recriá-la do zero.
Argumentos:
cleanroom_name (cadeia de caracteres) – A sala limpa que é atribuída a essa cadeia de modelos.
template_chain_name (cadeia de caracteres) – A cadeia de modelos a ser removida dessa sala limpa.
Retorna: (cadeia de caracteres) mensagem de sucesso ou falha.
Exemplo:
CALL samooha_by_snowflake_local_db.provider.clear_template_chain($cleanroom_name, 'my_chain');
Análise multiprovedor¶
Esses procedimentos permitem a análise de vários provedores.
enable_multiprovider_computation¶
- Esquema:
PROVIDER
Descrição: esse procedimento permite que as tabelas da sua sala limpa sejam usadas em combinação com o modelo especificado, quando solicitadas pelo usuário especificado, e em combinação com as tabelas das salas limpas especificadas. Esse procedimento permite que um consumidor execute uma consulta nos dados de várias salas limpas. Esse procedimento não aprova automaticamente as solicitações, mas permite que o processo de aprovação manual ou automatizado seja iniciado para o usuário e as salas limpas especificados registrando as solicitações no log de solicitações multiprovedor desta sala limpa.
Todas as chamadas feitas para essa clean room usando consumer.prepare_multiprovider_flow
serão salvas e estarão visíveis mesmo antes de você chamar enable_multiprovider_computation
para essa clean room.
Para permitir que um consumidor acesse várias clean rooms em sua conta, especifique uma clean room no argumento cleanroom_name
e as outras no argumento approved_other_cleanrooms
.
Esse procedimento exige a definição de uma política de associação na clean room.
Quando uma solicitação é registrada, a aprovação ocorrerá de acordo com o fluxo de solicitação para um determinado usuário e consulta.
Não há como desativar o registro de solicitações depois que ele é iniciado, mas você pode suspender a aprovação automatizada para um determinado usuário (se a tiver concedido chamando provider.suspend_multiprovider_tasks
) e, em seguida, não aprovar mais nenhuma solicitação.
Argumentos:
cleanroom_name (cadeia de caracteres) – Nome de uma sala limpa que você possui. Todos os dados dessa clean room podem ser compartilhados com as clean rooms listadas em
approved_other_cleanrooms
em solicitações de vários provedores porconsumer_account
.consumer_account (cadeia de caracteres) – Localizador da conta de um consumidor que tem permissão para fazer a solicitação e, se aprovada, executar uma consulta em qualquer tabela dessa sala limpa combinada com dados de qualquer sala limpa listada em
approved_other_cleanrooms
.approved_other_cleanrooms (matriz de cadeia de caracteres) – Matriz de nomes de salas limpas totalmente qualificadas com as quais os dados dessa sala limpa podem ser combinados. O formato de cada entrada é
provider_org_name.provider_account_name.cleanroom_name
. Importante: forneça o nome da conta, e não o localizador da conta, em cada descrição de clean room.
Retorna: (cadeia de caracteres) mensagem de sucesso ou falha.
Exemplo:
CALL samooha_by_snowflake_local_db.provider.enable_multiprovider_computation(
$cleanroom_name,
$consumer_account_locator,
<org_name>.<account_locator>.<cleanroom_name>);
view_multiprovider_requests¶
- Esquema:
PROVIDER
Descrição: mostra todas as solicitações de análise de vários provedores de uma determinada conta e sala limpa. Isso inclui tanto as solicitações aprovadas quanto as negadas. Os provedores podem usar esse procedimento para pesquisar solicitações a fim de aprová-las manualmente, chamando provider.process_multiprovider_request
, ou como uma forma de ver todas as solicitações de um determinado consumidor em uma determinada clean room.
Você deve chamar enable_multiprovider_computation
para essa clean room e conta de consumidor antes de poder chamar view_multiprovider_requests
.
Argumentos:
cleanroom_name (string) – Mostra solicitações do consumidor especificado dessa clean room.
consumer_account (string) – Mostra solicitações desse localizador de conta de consumidor da clean room especificada.
Retorna: (cadeia de caracteres) mensagem de sucesso ou falha.
Exemplo:
CALL samooha_by_snowflake_local_db.provider.view_multiprovider_requests(
$cleanroom_name,
$consumer_locator);
process_multiprovider_request¶
- Esquema:
PROVIDER
Descrição: aprova a execução da consulta de vários provedores especificada, se todas as verificações forem aprovadas. As verificações incluem a idade da solicitação e se o provedor aprovou ou não a solicitação em uma chamada anterior para o provedor enable_multiprovider_computation
. O consumidor ainda deve chamar consumer.execute_multiprovider_flow
para executar a consulta. Se não for aprovada, a solicitação será descartada após quatro horas.
Por padrão, todas as solicitações de vários provedores devem ser tratadas usando esse procedimento. Se você preferir que todas as solicitações desse consumidor nessa clean room sejam aprovadas automaticamente, especifique -1
para request_id
. Se quiser que todas as solicitações de todos os consumidores dessa clean room sejam aprovadas, chame provider.resume_multiprovider_tasks
. Saiba como revogar solicitações aprovadas anteriormente.
Depois que a solicitação é avaliada, a solicitação e o status da avaliação são gravados na tabela de registro para essa clean room.
Argumentos:
cleanroom_name (cadeia de caracteres) – O nome da sua sala limpa, que um consumidor está pedindo para incluir em uma análise de vários provedores.
consumer_account (cadeia de caracteres) – O localizador da conta do consumidor do usuário que solicita a análise de vários provedores. Esse localizador deve ter sido aprovado para essa sala limpa e para as outras salas limpas listadas na solicitação em uma chamada para
provider.enable_multiprovider_computation
.request_id (cadeia de caracteres) – ID de solicitação para aprovação, de
provider.view_multiprovider_requests
. Você pode aprovar em-1
todas as solicitações para esse consumidor nessa clean room.
Retorna: (cadeia de caracteres) mensagem de sucesso ou falha.
Exemplo:
CALL samooha_by_snowflake_local_db.provider.process_multiprovider_request(
$cleanroom_name_1,
$consumer_account_locator,
$request_id);
suspend_multiprovider_tasks¶
- Esquema:
PROVIDER
Descrição: interrompe a revisão e a aprovação automatizadas (para consultas qualificadas) em uma consulta de vários provedores na clean room especificada. As consultas de vários provedores ainda estão habilitadas para a clean room, mas agora cada solicitação deve ser explicitamente aprovada pelo provedor, chamando provider.process_multiprovider_request
.
O status padrão para todas as clean rooms é que a aprovação automatizada de vários provedores esteja desativada. Para ativá-la, chame provider.resume_multiprovider_tasks
.
Argumentos:
cleanroom_name (string) – Nome da sala limpa.
consumer_account (string) – Localizador da conta de consumidor cujas solicitações de vários provedores devem ser suspensas para todos os modelos nessa clean room. As solicitações posteriores desse usuário nessa clean room serão descartadas.
Retorna: (cadeia de caracteres) mensagem de sucesso ou falha.
Exemplo:
CALL samooha_by_snowflake_local_db.provider.suspend_multiprovider_tasks(
$cleanroom_name,
$consumer_locator);
resume_multiprovider_tasks¶
- Esquema:
PROVIDER
Descrição: permite a revisão automatizada e a aprovação (para consultas qualificadas) de análises multiprovedor para o usuário especificado na sala limpa fornecida. Por padrão, a revisão automatizada está desabilitada para uma sala limpa.
Para interromper a aprovação automatizada, acesse provider.suspend_multiprovider_tasks
.
Argumentos:
cleanroom_name (string) – Nome da sala limpa.
consumer_account (string) – Localizador da conta de consumidor cujas solicitações de vários provedores nessa clean room agora serão colocadas na fila.
Retorna: (cadeia de caracteres) mensagem de sucesso ou falha.
Exemplo:
CALL samooha_by_snowflake_local_db.provider.resume_multiprovider_tasks(
$cleanroom_name,
$consumer_locator);
Ativação¶
Ativação significa exportar resultados para um provedor, um consumidor ou um terceiro. Leia mais sobre ativação.
set_activation_policy¶
- Esquema:
PROVIDER
Descrição: define quais colunas do provedor podem ser usadas em um modelo de ativação. Somente as colunas listadas em uma política de ativação podem ser ativadas a partir do conjunto de dados do provedor. A não configuração de uma política de ativação impede que qualquer dado do provedor seja ativado.
A chamada desse procedimento elimina qualquer política de ativação anterior definida pelo provedor.
Argumentos:
cleanroom_name (cadeia de caracteres) – Nome da sala limpa onde a ativação deve ser permitida.
columns (matriz da cadeia de caracteres) – Somente as colunas listadas aqui podem ser usadas em um modelo de ativação nessa sala limpa. O formato do nome da coluna é
template_name:fully_qualified_table_name:column_name
. Observe o uso correto dos marcadores de ponto (.) e dois pontos (:).
Retorna: (cadeia de caracteres) mensagem de sucesso ou falha.
Exemplo:
CALL samooha_by_snowflake_local_db.provider.set_activation_policy('my_cleanroom', [
'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:HASHED_EMAIL',
'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:REGION_CODE' ]);
request_provider_activation_consent¶
- Esquema:
PROVIDER
Descrição: envia uma solicitação ao consumidor para permitir que o provedor execute um modelo especificado e envie os resultados para a conta Snowflake do provedor. Em segundo plano, ele adiciona um modelo à lista de modelos de ativação de provedor na clean room. Quando um modelo é designado como um modelo de ativação, ele só pode ser usado em solicitações de ativação.
Argumentos:
cleanroom_name (cadeia de caracteres) – Sala limpa com o modelo de ativação.
template_name (cadeia de caracteres) – Nome do modelo de ativação para o qual deseja solicitar aprovação. Esse modelo deve ter sido adicionado à sala limpa em uma chamada anterior. O nome do modelo deve começar com “activation_”.
Retorna: (cadeia de caracteres) mensagem de sucesso ou falha.
Exemplo:
CALL samooha_by_snowflake_local_db.provider.request_provider_activation_consent(
$cleanroom_name, 'activation_my_activation_template');
update_activation_warehouse¶
- Esquema:
PROVIDER
Descrição: especifique qual tamanho de warehouse deve ser usado ao descriptografar os resultados na tabela de saída em uma ativação de provedor. O warehouse usado para descriptografia é DCR_ACTIVATION_WAREHOUSE. O provedor paga por esse warehouse.
Argumentos:
size (string) – Tamanho do warehouse. Escolha um dos valores WAREHOUSE_SIZE do comando CREATE WAREHOUSE.
Retorna: (string) Mensagem de sucesso.
Exemplo:
CALL samooha_by_snowflake_local_db.provider.update_activation_warehouse('LARGE');
dcr_health.provider_run_provider_activation_history¶
Descrição: retorna um histórico de solicitações de ativação do provedor para a sala limpa especificada. As solicitações de ativação do provedor iniciadas pelo provedor e pelo consumidor são mostradas. Esse procedimento fornece informações extras para ajudar na depuração de problemas com a ativação do provedor.
Argumentos:
cleanroom_name (cadeia de caracteres): nome da sala limpa na qual a ativação foi solicitada. Você deve ser um provedor ou consumidor nessa sala limpa.
Retorna: (tabela): uma lista de solicitações de ativação com informações sobre cada uma, incluindo o modelo e o nome do segmento, o status, o localizador da conta do consumidor e qualquer mensagem de erro retornada pela solicitação.
Exemplo:
CALL samooha_by_snowflake_local_db.dcr_health.provider_run_provider_activation_history(
$cleanroom_name);
view_external_activation_history¶
- Esquema:
LIBRARY
Descrição: exibe o histórico de solicitações de ativação na conta atual.
Argumentos: nenhum
Retorna: uma tabela com os detalhes e o status das solicitações de ativação.
Exemplo:
CALL samooha_by_snowflake_local_db.library.view_external_activation_history();
Execução de análises como provedor¶
Saiba como executar uma análise de provedor
enable_provider_run_analysis¶
- Esquema:
PROVIDER
Descrição: permite que o provedor (criador da sala limpa) execute análises em uma sala limpa especificada. Isso é desativado por padrão. O consumidor deve então chamar consumer.enable_templates_for_provider_run
para habilitar as análises executadas pelo provedor para modelos específicos na clean room. Depois disso, o provedor pode executar uma análise chamando provider.submit_analysis_request
.
Saiba mais sobre as análises executadas pelo provedor.
Importante
Esse procedimento deve ser chamado após provider.add_consumers
e antes que um consumidor instale uma sala limpa. Se isso for alterado depois que o consumidor já tiver instalado sua sala limpa, ele deverá reinstalar a sala limpa para refletir a nova configuração.
Argumentos:
cleanroom_name (cadeia de caracteres) – Nome da sala limpa que deve permitir a análise executada pelo provedor.
consumer_accounts (matriz de cadeia de caracteres) – Localizadores de contas de todos os consumidores que adicionaram dados a essa sala limpa.
Retorna: (cadeia de caracteres) mensagem de sucesso ou falha.
Exemplo:
CALL samooha_by_snowflake_local_db.provider.enable_provider_run_analysis($cleanroom_name, ['<CONSUMER_ACCOUNT_LOCATOR>']);
disable_provider_run_analysis¶
- Esquema:
PROVIDER
Descrição: impede que o provedor (criador da sala limpa) execute uma análise na sala limpa (está desativado por padrão).
Importante
Esse procedimento deve ser chamado após provider.add_consumers
e antes que um consumidor instale uma sala limpa. Se isso for alterado depois que um consumidor já tiver instalado sua sala limpa, ele precisará reinstalar a sala limpa para refletir a nova configuração.
Argumentos:
cleanroom_name (cadeia de caracteres) – Nome da sala limpa em que a análise executada pelo provedor deve ser desativada.
consumer_account_locator (cadeia de caracteres) – A mesma lista de nomes de contas de consumidores passada para
provider.enable_provider_run_analysis
.
Retorna: (cadeia de caracteres) mensagem de sucesso ou falha.
Exemplo:
CALL samooha_by_snowflake_local_db.provider.disable_provider_run_analysis(
$cleanroom_name,
['<CONSUMER_ACCOUNT_LOCATOR>']);
is_provider_run_enabled¶
- Esquema:
LIBRARY
Descrição: verifica se essa sala limpa permite análises executadas pelo provedor.
Argumentos:
cleanroom_name (cadeia de caracteres) – Nome da sala limpa a ser verificada.
Retorna: (cadeia de caracteres) Se essa sala limpa permite ou não análises executadas pelo provedor.
Exemplo:
CALL samooha_by_snowflake_local_db.library.is_provider_run_enabled($cleanroom_name)
view_warehouse_sizes_for_template¶
- Esquema:
PROVIDER
Descrição: visualize a lista de tamanhos e tipos de warehouse disponíveis para uso em análises executadas pelo provedor com um determinado modelo. O consumidor deve primeiro preencher a lista em sua chamada para consumer.enable_templates_for_provider_run
.
Argumentos:
consumer_account (string) – Localizador da conta de consumidor que aprovará a solicitação executada pelo provedor.
cleanroom_name (string) – Nome da sala limpa.
template_name (string) – Nome do modelo que o provedor deseja executar.
consumer_account (string) – Localizador da conta de consumidor que aprovará a solicitação executada pelo provedor.
Devoluções: uma tabela de tamanhos e tipos de warehouses permitidos. As cadeias de caracteres de tipo e tamanho de warehouse compatíveis são as usadas pelas propriedades WAREHOUSE_TYPE e WAREHOUSE_SIZE no comando CREATE WAREHOUSE.
Exemplo:
CALL samooha_by_snowflake_local_db.PROVIDER.VIEW_WAREHOUSE_SIZES_FOR_TEMPLATE(
$cleanroom_name,
$template_name,
$consumer_account_loc);
submit_analysis_request¶
- Esquema:
PROVIDER
Descrição: envia uma análise para ser executada na clean room. Todas as condições a seguir devem ser atendidas antes de chamar esse procedimento:
O provedor deve ter habilitado as análises executadas pelo provedor nessa sala limpa.
O consumidor deve ter análises aprovadas de execução pelo provedor para o modelo especificado.
Todas as políticas de junção e coluna dos dados do consumidor e do modelo devem ser respeitadas.
O modelo é executado dentro da sala limpa e os resultados são armazenados com segurança dentro da sala limpa. Os resultados são criptografados para que somente o provedor possa vê-los.
Argumentos:
cleanroom_name (cadeia de caracteres) – Nome da sala limpa onde o modelo deve ser executado.
consumer_account_locator (cadeia de caracteres) – Localizador da conta do consumidor nesta sala limpa que permitiu análises executadas pelo provedor chamando
consumer.enable_templates_for_provider_run
.template_name (cadeia de caracteres) – Nome do modelo a ser executado.
provider_tables (array) – Lista de tabelas de provedores a serem expostas ao modelo. Essa lista preencherá a variável de matriz
source_table
.consumer_tables (array) – Lista de tabelas de consumidor a serem expostas ao modelo. Essa lista preencherá a variável de matriz
my_table
.analysis_arguments (objeto) – Objeto JSON em que cada chave é um nome de argumento usado no modelo que você criou. Se quiser usar um tipo e tamanho de warehouse específicos, escolha um tipo e tamanho listados em
provider.view_warehouse_sizes_for_template
e, em seguida, especifique-os usando os campos a seguir:warehouse_type
(string) – Um tipo de warehouse que o consumidor oferece suporte para análises executadas pelo provedor com o modelo especificado.warehouse_size
(string) – Um tamanho de warehouse que o consumidor oferece suporte para análises executadas pelo provedor com o modelo especificado.
Retorna: (cadeia de caracteres) um ID de solicitação que é usado para verificar o status da solicitação e também para acessar os resultados. Salve esse ID porque você precisará dele para ver os resultados da análise.
Exemplo:
CALL samooha_by_snowflake_local_db.provider.submit_analysis_request(
$cleanroom_name,
'<CONSUMER_ACCOUNT>',
'prod_overlap_analysis',
['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS'],
['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS'],
object_construct(
'dimensions', ['c.REGION_CODE'],
'measure_type', ['AVG'],
'measure_column', ['c.DAYS_ACTIVE'],
'warehouse_type', 'STANDARD', -- If this type and size pair were not listed by view_warehouse_sizes_for_template,
'warehouse_size', 'LARGE' -- the request will automatically fail.
));
check_analysis_status¶
- Esquema:
PROVIDER
Descrição: o provedor chama esse procedimento para verificar o status da solicitação de análise do provedor. Pode haver um atraso significativo antes que você possa começar a ver o status de uma solicitação. Quando uma análise for marcada como concluída, chame provider.get_analysis_result
para ver os resultados.
Argumentos:
cleanroom_name (cadeia de caracteres) – Nome da sala limpa onde a solicitação foi feita.
request_id (cadeia de caracteres) – ID da solicitação, retornado por
provider.submit_analysis_request
.consumer_account_locator (cadeia de caracteres) – Localizador da conta do consumidor para o qual a solicitação foi enviada.
Retorna: (cadeia de caracteres) status da solicitação, em que COMPLETED
significa uma conclusão bem-sucedida da análise. Status possíveis:
IN-PROGRESS: a análise está em andamento.
PENDING: Indica um dos seguintes casos:
A solicitação ainda está sendo propagada, o que pode levar alguns minutos. Tente novamente em alguns minutos.
O usuário não aprovou a solicitação chamando
consumer.enable_templates_for_provider_run
. Tente novamente em alguns minutos.Você não montou os logs de solicitação para este consumidor. Chame
provider.is_request_back_share_mounted
. Se esse procedimento não retornar SUCCESS, chameprovider.mount_request_logs_for_all_consumers
.
COMPLETED: a análise foi concluída. Você pode chamar
provider.get_analysis_result
.
Exemplo:
-- It can take up to 2 minutes for this to pick up the request ID after the initial request
CALL samooha_by_snowflake_local_db.provider.check_analysis_status(
$cleanroom_name,
$request_id,
'<CONSUMER_ACCOUNT>'
);
get_analysis_result¶
- Esquema:
PROVIDER
Descrição: obtém os resultados de uma análise executada pelo provedor. Não chame get_analysis_result
antes de provider.check_analysis_status
retornar COMPLETED. Os resultados da análise são mantidos na sala limpa indefinidamente.
Argumentos:
cleanroom_name (cadeia de caracteres) – Nome da sala limpa para a qual a solicitação foi enviada.
request_id (cadeia de caracteres) – ID da solicitação, retornado por
submit_analysis_request
.consumer_account_locator (cadeia de caracteres) – Localizador da conta do consumidor passado para
submit_analysis_request
.
Retorna: (tabela) resultados de consulta.
Exemplo:
CALL samooha_by_snowflake_local_db.provider.get_analysis_result(
$cleanroom_name,
$request_id,
$locator
);
Gerenciamento do compartilhamento de salas limpas¶
Use os comandos a seguir para gerenciar o compartilhamento de uma sala limpa com os consumidores.
view_consumers¶
- Esquema:
PROVIDER
Descrição: lista os consumidores que têm acesso à sala limpa. Ele não mostra se um consumidor instalou a sala limpa.
Argumentos:
cleanroom_name (cadeia de caracteres) – A sala limpa de interesse.
Retorna: (tabela) – Lista de contas de consumidores que podem acessar a sala limpa.
Exemplo:
CALL samooha_by_snowflake_local_db.provider.view_consumers($cleanroom_name);
add_consumers¶
- Esquema:
PROVIDER
Descrição: concede aos usuários especificados acesso à sala limpa indicada. A sala limpa pode ser acessada tanto pela UI quanto pela API de salas limpas. Isso não substitui as listas de consumidores das chamadas anteriores. O acesso à sala limpa é concedido a um usuário específico, não a uma conta inteira. A conta do consumidor deve estar na mesma região Snowflake que o provedor para poder acessar uma sala limpa. É possível verificar sua região chamando select current_region();
É possível ver a lista atual de consumidores chamando provider.view_consumers
.
Argumentos:
cleanroom_name (cadeia de caracteres): nome da sala limpa a ser compartilhada com os usuários especificados. Os usuários podem instalar a sala limpa usando a API ou a UI de salas limpas.
consumer_account_locators (cadeia de caracteres) – Uma lista delimitada por vírgulas de localizadores de contas de consumidores, conforme retornado por CURRENT_ACCOUNT. Essa lista deve incluir o mesmo número de entradas, na mesma ordem, que a contida em
consumer_account_names
.consumer_account_names (string) – Uma lista delimitada por vírgulas de IDs de conta de compartilhamento de dados do consumidor para o consumidor no formato
org_name.account_name
Nome da organização pode ser recuperado chamando CURRENT_ORGANIZATION_NAME. O nome da conta pode ser recuperado chamando CURRENT_ACCOUNT_NAME. Essa lista deve incluir o mesmo número de itens, na mesma ordem, conforme listado emconsumer_account_locators
.enable_differential_privacy_tasks (booliano, opcional) – TRUE para aplicar privacidade diferencial em todas as consultas dos usuários listados nessa clean room. Essa é uma maneira simples de ativar a privacidade diferencial com valores padrão para os usuários listados. Para especificar configurações avançadas, forneça o argumento
privacy_settings
. A tarefa de privacidade diferencial deve estar em execução nessa clean room para permitir a privacidade diferencial. O padrão é FALSE.privacy_settings (cadeia de caracteres, opcional) – Se presente, aplica configurações de privacidade a modelos personalizados quando usados por qualquer um dos usuários em
consumer_account_names
. Essa é uma versão em cadeia de caracteres de um objeto com uma única chave NULL e um valor que especifica várias configurações de privacidade. Não especifique ambosenable_differential_privacy_tasks
eprivacy_settings
. A tarefa de privacidade diferencial deve estar em execução nessa clean room para ativar a privacidade diferencial. Veja os campos disponíveis para esse objeto.
Retorna: mensagem de sucesso. Observe que o procedimento não valida os localizadores de usuário ou os nomes de conta, portanto, o sucesso indica apenas que os localizadores enviados foram adicionados ao banco de dados dessa sala limpa.
Exemplos:
-- Add consumer without differential privacy.
CALL samooha_by_snowflake_local_db.provider.add_consumers($cleanroom_name,
'LOCATOR1,LOCATOR2',
'ORG1.NAME1,ORG2.NAME2');
-- Add consumer and turn on differential privacy for all their queries.
CALL samooha_by_snowflake_local_db.provider.add_consumers($cleanroom_name,
'LOCATOR1',
'ORGNAME.ACCOUNTNAME',
'{
"null": {
"threshold_value": 5000,
"differential": 1,
"privacy_budget": 10,
"epsilon": 0.1,
"noise_mechanism": "Laplace"
}}');
remove_consumers¶
- Esquema:
PROVIDER
Descrição: remove o acesso da conta a uma determinada sala limpa. Esse método bloqueia o acesso de todos os usuários nas contas fornecidas.
É possível ver a lista atual de consumidores chamando provider.view_consumers
.
Argumentos:
cleanroom_name (cadeia de caracteres) – O ID da sala limpa (não o nome amigável).
cleanroom_account_locators (cadeia de caracteres) – Uma lista delimitada por vírgulas de localizadores de contas de usuário. Todos os usuários da conta perderão o acesso à sala limpa.
Retorna: (cadeia de caracteres) – Mensagem de sucesso ou falha.
Exemplo:
CALL samooha_by_snowflake_local_db.provider.remove_consumers($cleanroom_name, 'locator1,locator2,locator3');
set_cleanroom_ui_accessibility¶
- Esquema:
PROVIDER
Descrição: mostra ou oculta a sala limpa na UI de salas limpas para todos os usuários conectados a essa conta de provedor.
Argumentos:
cleanroom_name (string) – 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 na UI de salas limpas de todos os usuários na conta do provedor atual. A sala limpa ainda está acessível para chamadas de API.
EDITABLE: torna a sala limpa visível na UI de salas limpas.
Retorna: (cadeia de caracteres) mensagem de sucesso ou falha.
Exemplo:
CALL samooha_by_snowflake_local_db.provider.set_cleanroom_ui_accessibility($cleanroom_name, 'HIDDEN');
Colaboração entre nuvens¶
Permita que uma clean room seja compartilhada com um consumidor em outra região de nuvem. Saiba mais.
enable_laf_on_account¶
- Esquema:
LIBRARY
Descrição: habilita o preenchimento automático entre nuvens na conta atual. A execução desse procedimento requer a função ACCOUNTADMIN.
Importante
Primeiro você deve habilitar o preenchimento automático entre nuvens na conta chamando SYSTEM$ENABLE_GLOBAL_DATA_SHARING_FOR_ACCOUNT. Saiba mais sobre o preenchimento automático e gerenciamento dos privilégios de preenchimento automático.
Argumentos: nenhum
Retorna: (string) Mensagem de sucesso.
Exemplo:
USE ROLE ACCOUNTADMIN;
CALL samooha_by_snowflake_local_db.library.enable_laf_on_account();
disable_laf_on_account¶
- Esquema:
LIBRARY
Descrição: desabilita o preenchimento automático entre nuvens na conta atual. A execução desse procedimento requer a função ACCOUNTADMIN.
Importante
Primeiro você deve chamar SYSTEM$ENABLE_GLOBAL_DATA_SHARING_FOR_ACCOUNT antes de desabilitar o preenchimento automático entre nuvens em uma conta. Saiba mais sobre o preenchimento automático e gerenciamento dos privilégios de preenchimento automático.
Argumentos: nenhum
Retorna: (string) Mensagem de sucesso.
Exemplo:
USE ROLE ACCOUNTADMIN;
CALL samooha_by_snowflake_local_db.library.disable_laf_on_account();
is_laf_enabled_on_account¶
- Esquema:
LIBRARY
Descrição: retorna se o preenchimento automático entre nuvens está ativado para essa conta.
Argumentos: nenhum
Retorna: TRUE se o preenchimento automático entre nuvens estiver ativado para essa conta, FALSE caso contrário.
Exemplo:
CALL samooha_by_snowflake_local_db.library.is_laf_enabled_on_account();
set_laf_dcr_refresh_schedule¶
- Esquema:
PROVIDER
Descrição: define o intervalo de atualização para os dados da sala limpa entre o provedor e o consumidor quando eles estão localizados em regiões de nuvem diferentes. Esses dados incluem conjuntos de dados do provedor, solicitações de execução do provedor, políticas e metadados de sala limpa. Se precisar de uma atualização imediata, você pode chamar SYSTEM$TRIGGER_LISTING_REFRESH.
Argumentos:
schedule (inteiro): intervalo, em minutos, entre as atualizações. O valor mínimo permitido é 10.
Retorna: (cadeia de caracteres): mensagem de sucesso.
Exemplo:
CALL samooha_by_snowflake_local_db.provider.set_laf_dcr_refresh_schedule(10);
Como usar Python em uma sala limpa¶
load_python_into_cleanroom¶
- Esquema:
PROVIDER
Descrição: carrega um código Python personalizado na sala limpa. O código carregado na sala limpa usando esse procedimento não é visível para os consumidores. Seu modelo Jinja pode chamar o código carregado. O código pode incluir várias definições de função, mas apenas uma função é exposta para que um modelo a chame.
Saiba como carregar e usar o código Python em uma sala limpa.
Esse procedimento aumenta o número do patch de sua sala limpa e aciona uma verificação de segurança. É necessário aguardar que o status da varredura seja APPROVED para poder compartilhar a versão mais recente com os colaboradores.
Esse procedimento é sobrecarregado e tem duas assinaturas que diferem no tipo de dados do quinto argumento, que determina se você está carregando o código em linha ou carregando-o de um arquivo em um estágio:
load_python_into_cleanroom
tem a assinatura a seguir para carregamento de código em linha. Passe sua cadeia de caracteres de código para o argumento code
.
(cleanroom_name String, function_name String, arguments Array, packages Array, rettype String, handler String, code String)
Argumentos:
cleanroom_name (cadeia de caracteres) – Nome da sala limpa onde o script deve ser carregado.
function_name (cadeia de caracteres): nome que um modelo usa para chamar a função especificada por
handler
. O modelo deve qualificar o nome da função com o namespacecleanroom
. Por exemplo:cleanroom.my_func(val1, val2)
.arguments (matriz de pares de cadeias de caracteres): uma matriz de argumentos exigidos pela função
function_name
. Cada elemento é um par delimitado por espaço de «nome
tipo de dados
» que especifica o nome do argumento e o tipo de dados SQL do Snowflake. Por exemplo:['size INT', 'start_date DATE']
.packages (matriz de cadeias de caracteres): lista de nomes de pacotes Python usados pelo código. As salas limpas oferecem suporte nativo a todos os pacotes nesta lista ou a Snowpark API. Se você precisar de um pacote que não consta nessa lista, deverá usar Snowpark Container Services em uma sala limpa.
ret_type (cadeia de caracteres): tipo de dados SQL do valor retornado pela função
handler
. (Veja alguns tipos Python e SQL equivalentes. Sinônimos de tipos SQL do Snowflake são aceitos, como STRING para VARCHAR.) Para uma UDF, o tipo de retorno é um SQL único. Para uma UDTF, o tipo de retorno é uma função TABLE com os pares<column name> <SQL column type>
. Por exemplo:TABLE (item_name STRING, FLOAT total)
.handler (cadeia de caracteres): a função chamada no seu código quando um modelo chama
function_name
. Para uma UDF, deve ser o próprio nome da função. Para uma UDTF, deve ser o nome da classe que implementa a UDTF.code (cadeia de caracteres): o código Python como uma cadeia de caracteres. Deve ser uma UDF Python.
Carregue seu código em uma área de preparação Snowflake e forneça a localização dessa área à API de sala limpa. Você deve usar a área de preparação habilitada para sua sala limpa específica chamando provider.get_stage_for_python_files
.
load_python_into_cleanroom
tem a assinatura a seguir para carregar o código de uma área de preparação para a sala limpa.
(cleanroom_name String, function_name String, arguments Array, packages Array, imports Array, rettype String, handler String)
Argumentos:
cleanroom_name (cadeia de caracteres) – Nome da sala limpa onde o script deve ser carregado.
function_name (cadeia de caracteres): nome que um modelo usa para chamar a função especificada por
handler
. O modelo deve qualificar o nome da função com o namespacecleanroom
. Por exemplo:cleanroom.my_func(val1, val2)
.arguments (matriz de pares de cadeias de caracteres): uma matriz de argumentos exigidos pela função
function_name
. Cada elemento é um par delimitado por espaço de «nome
tipo de dados
» que especifica o nome do argumento e o tipo de dados SQL do Snowflake. Por exemplo:['size INT', 'start_date DATE']
.packages (matriz de cadeias de caracteres): lista de nomes de pacotes Python usados pelo código. As salas limpas oferecem suporte nativo a todos os pacotes nesta lista ou a Snowpark API.
imports (matriz de cadeias de caracteres): lista de arquivos a serem importados da área de preparação. Cada endereço de arquivo é relativo à área de preparação na qual você carregou o código, por exemplo:
['/my_func.py']
. Para encontrar a área de preparação da sala limpa, chameprovider.get_stage_for_python_files
.ret_type (cadeia de caracteres): tipo de dados SQL do valor retornado pela função
handler
. (Veja alguns tipos Python e SQL equivalentes. Sinônimos de tipos SQL do Snowflake são aceitos, como STRING para VARCHAR.) Para uma UDF, o tipo de retorno é um SQL único. Para uma UDTF, o tipo de retorno é uma função TABLE com os pares<column name> <SQL column type>
. Por exemplo:TABLE (item_name STRING, FLOAT total)
.handler (cadeia de caracteres): a função chamada no seu código quando um modelo chama
function_name
. Para uma UDF, deve ser o próprio nome da função. Para uma UDTF, deve ser o nome da classe que implementa a UDTF.
Retorna: (cadeia de caracteres) mensagem de sucesso ou falha.
Exemplos:
-- Inline UDF
CALL samooha_by_snowflake_local_db.provider.load_python_into_cleanroom(
$cleanroom_name,
'assign_group', -- Name of the UDF.
['data STRING', 'index INTEGER'], -- Arguments of the UDF, along with their type.
['pandas', 'numpy'], -- Packages UDF will use.
'INTEGER', -- Return type of UDF.
'main', -- Handler.
$$
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)
$$
);
-- Upload from stage
CALL samooha_by_snowflake_local_db.provider.load_python_into_cleanroom(
$cleanroom_name,
'myfunc', -- Name of the UDF.
['data STRING', 'index INTEGER'], -- Arguments of the UDF.
['numpy', 'pandas'], -- Packages UDF will use.
['/assign_group.py'] -- Python file to import from a stage.
'INTEGER', -- Return type of UDF.
'assign_group.main' -- Handler, scoped to file name.
);
get_stage_for_python_files¶
- Esquema:
PROVIDER
Descrição: retorna o caminho do estágio no qual os arquivos Python devem ser carregados, se você planeja usar arquivos de código carregados em um estágio em vez de definições de código em linha para definir o código Python personalizado em uma sala limpa. O estágio não existe e não pode ser examinado até que os arquivos sejam carregados por meio da chamada provider.load_python_into_cleanroom
.
Saiba como carregar e usar o código Python em uma sala limpa.
Argumentos:
cleanroom_name (cadeia de caracteres) – Nome da sala limpa em que você deseja carregar os arquivos.
Retorna: (cadeia de caracteres) o caminho para onde você deve carregar os arquivos de código. Use isso para o argumento imports em provider.load_python_into_cleanroom
.
Exemplo:
CALL samooha_by_snowflake_local_db.provider.get_stage_for_python_files($cleanroom_name);
view_cleanroom_scan_status¶
- Esquema:
PROVIDER
Descrição: informa o status da varredura de ameaças para uma sala limpa com DISTRIBUTION definido como EXTERNAL. A varredura precisa ser marcada como «APPROVED» antes que você possa definir ou alterar a diretiva de lançamento padrão. O status da varredura precisa ser verificado somente com as salas limpas EXTERNAL.
Argumentos:
cleanroom_name (cadeia de caracteres) – Nome da sala limpa para verificar o status.
Retorna: (cadeia de caracteres) o status da verificação. Os seguintes valores são possíveis:
NOT_REVIEWED
: a verificação está em andamento.APPROVED
: a verificação foi aprovada.REJECTED
: a verificação falhou. Uma nova versão da sala limpa não será publicada. Tente encontrar os problemas em seu código e repita a última ação.MANUAL_REVIEW
: a verificação requer a revisão manual pela Snowflake. Isso pode levar alguns dias, portanto, consulte com frequência.
Exemplo:
CALL samooha_by_snowflake_local_db.provider.view_cleanroom_scan_status($cleanroom_name);
Logs de solicitações¶
Use os comandos a seguir para gerenciar os logs de solicitações do consumidor. Os logs de solicitações permitem que o consumidor envie mensagens ao provedor e devem ser montados para habilitar funcionalidades, como solicitações de modelo personalizado do consumidor, aprovação do consumidor de solicitações executadas pelo provedor e preenchimento automático entre nuvens.
mount_request_logs_for_all_consumers¶
- Esquema:
PROVIDER
Descrição: concede aos provedores acesso às solicitações do consumidor. Você deve montar os logs de solicitações para oferecer suporte a várias funcionalidades, incluindo solicitações de modelo personalizado do consumidor, aprovação do consumidor de solicitações executadas pelo provedor e preenchimento automático entre nuvens.
Esse procedimento monta os logs de solicitações somente para consumidores que já instalaram a sala limpa especificada. Se um consumidor instalar uma sala limpa depois que o provedor chamar esse procedimento, o provedor deverá chamar o procedimento novamente.
Argumentos:
cleanroom_name (cadeia de caracteres) – Nome da sala limpa na qual montar os registros de solicitação.
Retorna: (tabela) uma tabela de consumidores, com o status de montagem do log de solicitações de cada um. Se o consumidor recebeu acesso a uma sala limpa, mas ainda não a instalou, o status é descrito como pendente, e você deverá chamar mount_request_logs_for_all_consumers
novamente após a instalação da sala limpa.
Exemplo:
CALL samooha_by_snowflake_local_db.provider.mount_request_logs_for_all_consumers($cleanroom_name);
view_request_mount_status_for_all_consumers¶
- Esquema:
PROVIDER
Descrição: mostra o status de montagem dos logs de solicitações para todos os consumidores na sala limpa especificada. Somente os consumidores que foram incluídos em uma chamada para provider.mount_request_logs_for_all_consumers
são mostrados. Os logs de solicitações permitem que as mensagens sejam passadas do consumidor para o provedor.
Argumentos:
cleanroom_name (string) – Nome da sala limpa.
Retorna: (tabela): uma tabela de consumidores e o status de montagem do log de solicitações de cada consumidor.
Exemplo:
CALL samooha_by_snowflake_local_db.provider.view_request_mount_status_for_all_consumers($cleanroom_name);
view_request_logs¶
- Esquema:
PROVIDER
Descrição: mostra os logs das solicitações enviadas pelos consumidores nesta sala limpa. Somente solicitações de consumidores que foram incluídos em uma chamada anterior bem-sucedida para mount_request_logs_for_all_consumers
são mostrados.
Argumentos:
cleanroom_name (cadeia de caracteres) – Nome da sala limpa para a qual os registros de solicitação devem ser revisados.
Retorna: (tabela) as solicitações enviadas pelo consumidor ao provedor na sala limpa especificada.
Exemplo:
CALL samooha_by_snowflake_local_db.provider.view_request_logs($cleanroom_name);
Privacidade diferencial¶
Esses comandos controlam a privacidade diferencial no nível do usuário ou da conta de provedor. Saiba mais sobre privacidade diferencial.
set_privacy_settings¶
- Esquema:
PROVIDER
Descrição: define (ou redefine) as configurações de privacidade aplicadas quando o consumidor especificado executa um modelo personalizado. Isso substitui todas as configurações existentes para esse consumidor.
Argumentos:
cleanroom_name (string) – Nome da sala limpa.
consumer_account_locator (string) – Localizador de contas de um ou mais consumidores, em uma lista delimitada por vírgulas.
privacy_settings (objeto) – Um objeto JSON que especifica configurações de privacidade diferenciadas para um ou mais modelos. As configurações são aplicadas a todos os modelos executados pelo consumidor especificado. Veja os campos disponíveis para esse objeto.
Retorna: mensagem de sucesso.
Exemplo:
-- Enforce differential privacy on queries by this consumer
-- with the settings provided.
CALL samooha_by_snowflake_local_db.provider.set_privacy_settings(
$cleanroom_name,
$consumer_locator,
{ 'differential': 1,
'epsilon': 0.1,
'privacy_budget': 3 });
is_dp_enabled_on_account¶
- Esquema:
PROVIDER
Descrição: descreve se a privacidade diferencial está ou não ativada para essa conta.
Argumentos: nenhum
Retorna: TRUE se a privacidade diferencial estiver ativada para essa conta, FALSE caso contrário.
Exemplo:
CALL samooha_by_snowflake_local_db.provider.is_dp_enabled_on_account();
suspend_account_dp_task¶
- Esquema:
PROVIDER
Descrição: desabilita a tarefa que monitora e aplica orçamentos de privacidade diferencial. Isso é usado para controlar os custos associados à privacidade diferencial em sua conta. Se a tarefa de privacidade diferencial estiver desabilitada, o ruído ainda será adicionado às consultas por usuários, modelos ou salas limpas em que a privacidade diferencial foi especificada, mas os limites de orçamento não serão aplicados, e você não terá os custos da privacidade diferencial. Saiba mais como gerenciar a privacidade diferencial.
Argumentos: nenhum
Retorna: (cadeia de caracteres) mensagem de sucesso ou falha.
Exemplo:
CALL samooha_by_snowflake_local_db.provider.suspend_account_dp_task();
resume_account_dp_task¶
- Esquema:
PROVIDER
Descrição: reinicia o ouvinte da tarefa de privacidade diferencial na conta atual, e os orçamentos de privacidade diferencial serão aplicados. Todos os valores diferenciais de privacidade definidos anteriormente (como sensibilidade ou usuários associados) são mantidos.
Argumentos: nenhum
Retorna: (cadeia de caracteres) mensagem de sucesso ou falha.
Exemplo:
CALL samooha_by_snowflake_local_db.provider.resume_account_dp_task();
Comandos do Snowpark Container Services¶
Esses procedimentos permitem que você use o Snowpark Container Services dentro de uma clean room.
load_service_into_cleanroom¶
- Esquema:
PROVIDER
Descrição: cria ou atualiza um servidor de contêiner em uma clean room. A chamada desse procedimento atualiza o número do patch da clean room; portanto, você deve chamar provider.set_default_release_directive
após chamar esse procedimento. Você deve chamar esse procedimento sempre que criar ou atualizar o serviço. O cliente deve então chamar consumer.start_or_update_service
para ver as atualizações.
Saiba mais como usar o Snowpark Container Services em uma sala limpa.
Argumentos:
cleanroom_name (string) – Nome da sala limpa.
service_spec (string) – Uma especificação YAML para o serviço, com raiz no elemento
spec
.service_config (string) – Uma configuração no formato YAML para o serviço. As seguintes propriedades são compatíveis:
default_service_options
– Uma matriz opcional de valores padrão de nível de serviço. Esses valores podem ser substituídos pelo consumidor quando ele cria seu serviço. Há suporte para as seguintes propriedades secundárias:min_instances
(inteiro, opcional)max_instances
(inteiro, opcional)allow_monitoring
(booliano, opcional) – Se TRUE, permite que o consumidor veja os registros do serviço. O padrão é FALSE.
functions
– Uma matriz de funções expostas pelo serviço. Cada definição de função é mapeada para a definição de função de serviço SPCS. Consulte essa documentação para saber os detalhes de cada elemento. Há suporte para as seguintes propriedades secundárias:nome
args
retornos
ponto de extremidade
caminho
max_batch_rows
(opcional)context_headers
(opcional)
Retorna: (string) mensagem de sucesso, se bem-sucedido. Gera um erro se não for bem-sucedido.
Exemplo:
CALL samooha_by_snowflake_local_db.provider.load_service_into_cleanroom(
$cleanroom_name,
$$
spec:
containers:
- name: lal
image: /dcr_spcs/repos/lal_example/lal_service_image:latest
env:
SERVER_PORT: 8000
readinessProbe:
port: 8000
path: /healthcheck
endpoints:
- name: lalendpoint
port: 8000
public: false
$$,
$$
default_service_options:
min_instances: 1
max_instances: 1
allow_monitoring: true
functions:
- name: train
args: PROVIDER_TABLE VARCHAR, PROVIDER_JOIN_COL VARCHAR, CONSUMER_TABLE VARCHAR, CONSUMER_JOIN_COL VARCHAR, DIMENSIONS ARRAY, FILTER VARCHAR
returns: VARCHAR
endpoint: lalendpoint
path: /train
- name: score
args: PROVIDER_TABLE VARCHAR, PROVIDER_JOIN_COL VARCHAR, CONSUMER_TABLE VARCHAR, CONSUMER_JOIN_COL VARCHAR, DIMENSIONS ARRAY
returns: VARCHAR
endpoint: lalendpoint
path: /score
- name: score_batch
args: ID VARCHAR, FEATURES ARRAY
returns: VARIANT
max_batch_rows: 1000
endpoint: lalendpoint
path: /scorebatch
$$);
Gerenciamento de ambientes¶
Use os comandos a seguir para ajudar, de modo geral, a aproveitar a funcionalidade da sala limpa e os fluxos compatíveis.
manage_datastats_task_on_account¶
- Esquema:
PROVIDER
Descrição: habilita ou desabilita a tarefa em segundo plano que calcula as estatísticas da sala limpa. A tarefa é executada por padrão, mas você pode desabilitá-la para reduzir custos. Para gerenciar a tarefa, todos os colaboradores devem chamar a versão de provedor
ou consumidor
adequada deste procedimento com o mesmo valor.
Argumentos:
enable (booliano): TRUE para habilitar ou FALSE para desabilitar a tarefa.
Retorna: mensagem de sucesso.
Exemplo:
-- Disable the task in this account.
CALL samooha_by_snowflake_local_db.provider.manage_datastats_task_on_account(FALSE);
enable_local_db_auto_upgrades¶
- Esquema:
LIBRARY
Descrição: habilita a tarefa que atualiza automaticamente o ambiente Snowflake Data Clean Rooms quando há lançamento de novos procedimentos ou funcionalidades (a tarefa é samooha_by_snowflake_local_db.admin.expected_version_task
). Chame esse procedimento para automatizar as atualizações, em vez de chamar library.apply_patch
a cada novo lançamento.
Você pode desabilitar essa tarefa para reduzir os custos, mas recomendamos deixá-la em execução para garantir que tenha a versão mais recente do ambiente de salas limpas em seu sistema.
Argumentos: nenhum
Retorna: (cadeia de caracteres) mensagem de sucesso ou falha.
Exemplo:
CALL samooha_by_snowflake_local_db.library.enable_local_db_auto_upgrades();
disable_local_db_auto_upgrades¶
- Esquema:
LIBRARY
Descrição: desabilita a tarefa que atualiza automaticamente o ambiente Snowflake Data Clean Rooms quando novas versões são lançadas. Se você desabilitar as atualizações automáticas, deverá chamar library.apply_patch
a cada novo lançamento.
Argumentos: nenhum
Retorna: (cadeia de caracteres) mensagem de sucesso ou falha.
Exemplo:
CALL samooha_by_snowflake_local_db.library.disable_local_db_auto_upgrades();
apply_patch¶
- Esquema:
LIBRARY
Descrição: atualiza seu ambiente de salas limpas habilitando novos recursos e correções em seu ambiente. Chame esse procedimento quando uma nova versão do ambiente de salas limpas for lançada. (Em geral, isso ocorre semanalmente. Consulte as entradas de salas limpas em Atualizações recentes de recursos.) Esse procedimento atualiza samooha_by_snowflake_local_db.
Você pode automatizar as atualizações de patch chamando library.enable_local_db_auto_upgrades
. Recomendamos habilitar as atualizações automáticas.
Argumentos: nenhum
Retorna: (string) Mensagem de sucesso.
Exemplo:
CALL samooha_by_snowflake_local_db.library.apply_patch();
patch_cleanroom¶
- Esquema:
PROVIDER
Descrição: atualiza a sala limpa especificada para a versão mais recente habilitando novos recursos e correções na sala limpa. Normalmente, você chama esse procedimento somente quando é orientado pelo suporte Snowflake.
O provedor deve chamar library.patch_cleanroom
antes que o consumidor chame library.patch_cleanroom
. Caso contrário, não haverá patch para ser aplicado.
Argumentos:
cleanroom_name (cadeia de caracteres): nome da sala limpa à qual o patch será aplicado.
Retorna: (string) Mensagem de sucesso.
Exemplo:
CALL samooha_by_snowflake_local_db.provider.patch_cleanroom($cleanroom_name);
dcr_health.dcr_tasks_health_check¶
Descrição: mostra informações sobre as tarefas de sala limpa em execução ou recém-interrompidas.
Argumentos: nenhum
Retorna: (tabela) informações sobre as tarefas de sala limpa, incluindo o cronograma, o nome e o tamanho do warehouse.
Exemplo:
CALL samooha_by_snowflake_local_db.dcr_health.dcr_tasks_health_check();
Procedimentos obsoletos¶
Os procedimentos a seguir são obsoletos e estão listados aqui apenas para fins de completude. Se for indicado um procedimento de substituição, use o mais recente.
request_laf_cleanroom_requests (obsoleto)¶
- Esquema:
PROVIDER
Essa função agora está obsoleta. Em vez dela, chame provider.mount_request_logs_for_all_consumers
.
Descrição: configura o compartilhamento de solicitações entre nuvens no lado do provedor para um determinado consumidor. Um administrador de conta deve primeiro habilitar o preenchimento automático entre nuvens, e o consumidor deve ter chamado consumer.setup_cleanroom_request_share_for_laf
.
Esse processo é necessário para modelos definidos pelo consumidor em que o provedor e o consumidor estão em regiões de nuvem diferentes.
Você pode chamar esse procedimento repetidamente para verificar o status da solicitação. Quando o status chegar a FULFILLED, você poderá chamar provider.mount_laf_cleanroom_requests_share
. Pode levar 10 minutos para que o status chegue a FULFILLED.
Argumentos:
cleanroom_name (string) – Nome da clean room para ativar o compartilhamento de solicitações entre nuvens.
consumer_locator (string) – Localizador da conta de consumidor para o qual se deseja ativar o compartilhamento de solicitações entre nuvens.
Retorna: (cadeia de caracteres) mensagem de status da solicitação: CREATED, PENDING, FULFILLED e FAILURE. «FAILURE, listing not found» significa que o consumidor não instalou a sala limpa (ou a desinstalou).
Exemplo:
CALL samooha_by_snowflake_local_db.provider.request_laf_cleanroom_requests(
$cleanroom_name, $consumer_locator);
enable_laf_for_cleanroom (obsoleto)¶
- Esquema:
PROVIDER
Essa função agora está obsoleta e sua funcionalidade é processada por provider.create_or_update_cleanroom_listing
.
Descrição: habilita o preenchimento automático entre nuvens, que permite compartilhar a sala limpa com colaboradores que têm a conta Snowflake em uma região diferente da conta do provedor. O preenchimento automático entre nuvens também é conhecido como preenchimento automático de listagem (LAF).
Por padrão, o preenchimento automático entre nuvens é desativado para novas salas limpas, mesmo que esteja ativado para o ambiente.
Importante
Um administrador Snowflake com a função ACCOUNTADMIN deve habilitar o preenchimento automático entre nuvens em sua conta Snowflake antes para que você possa executar esse procedimento. Saiba mais sobre o preenchimento automático entre nuvens.
Há custos adicionais associados à colaboração com consumidores de outras regiões. Para obter mais informações sobre esses custos, consulte Custos do preenchimento automático entre nuvens.
Argumentos:
cleanroom_name (cadeia de caracteres) – O nome da sala limpa que deve ser compartilhado entre as regiões. O preenchimento automático entre nuvens deve ser ativado para a conta por um administrador antes que as salas limpas individuais possam ser compartilhadas.
Retorna: (cadeia de caracteres) mensagem de sucesso ou falha.
Exemplo:
CALL samooha_by_snowflake_local_db.provider.enable_laf_for_cleanroom($cleanroom_name);
view_ui_registration_request_log – DEPRECATED¶
- Esquema:
PROVIDER
Atenção
Esse comando agora está obsoleto. Não é mais necessário registrar manualmente um modelo de sala limpa para uso na UI de salas limpas.
Descrição: exibe a lista de solicitações geradas pela conta para registrar salas limpas na UI de salas limpas. Cada solicitação tem um ID associado que pode ser usado em conjunto com o procedimento view_ui_registration_log
para visualizar o status das solicitações. As solicitações são compartilhadas com o back-end, onde são processadas, e a sala limpa é adicionada à sala limpa.
Argumentos:
Retorna: (cadeia de caracteres) mensagem de sucesso ou falha.
Exemplo:
CALL samooha_by_snowflake_local_db.provider.view_ui_registration_request_log();
register_table_or_view – obsoleto¶
- Esquema:
LIBRARY
Atenção
Este comando está obsoleto. Em vez disso, 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)
Retorna: (cadeia de caracteres) mensagem de sucesso ou falha.
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);
register_table – obsoleto¶
- Esquema:
LIBRARY
Atenção
Este comando está obsoleto. Em vez disso, use library.register_objects.
Descrição: semelhante ao register_db
, mas opera no nível da tabela. Conceda o privilégio SELECT nesta tabela à função SAMOOHA_APP_ROLE, permitindo que o usuário vincule a tabela à sala limpa.
Se quiser registrar tabelas em um esquema de acesso gerenciado (ou seja, um esquema criado usando o parâmetro WITH MANAGED ACCESS), use library.register_managed_access_table
em vez disso.
Argumentos: table_name (array)
Retorna: (cadeia de caracteres) mensagem de sucesso ou falha.
Exemplo:
CALL samooha_by_snowflake_local_db.library.register_table(['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);
register_managed_access_table – obsoleto¶
- Esquema:
LIBRARY
Atenção
Este comando está obsoleto. Em vez disso, use library.register_objects.
Descrição: semelhante a register_table
, mas registra tabelas em um esquema que foi criado usando 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: (cadeia de caracteres) mensagem de sucesso ou falha.
Exemplo:
CALL samooha_by_snowflake_local_db.library.register_managed_access_table(['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);
register_view – obsoleto¶
- Esquema:
LIBRARY
Atenção
Este comando está obsoleto. Em vez disso, use library.register_objects.
Descrição: semelhante ao register_db
, mas opera em um 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 quiser registrar exibições em um esquema de acesso gerenciado (ou seja, um esquema criado usando o parâmetro WITH MANAGED ACCESS), use library.register_managed_access_view
.
Argumentos: view_name (array)
Retorna: (cadeia de caracteres) mensagem de sucesso ou falha.
Exemplo:
CALL samooha_by_snowflake_local_db.library.register_view(['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);
register_managed_access_view – obsoleto¶
- Esquema:
LIBRARY
Atenção
Este comando está obsoleto. Em vez disso, use library.register_objects.
Descrição: semelhante a register_view
, mas registra exibições em um esquema que foi criado usando 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: (cadeia de caracteres) mensagem de sucesso ou falha.
Exemplo:
CALL samooha_by_snowflake_local_db.library.register_managed_access_view(['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);
unregister_table_or_view – obsoleto¶
- Esquema:
LIBRARY
Atenção
Este comando está obsoleto. Em vez disso, 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)
Retorna: (cadeia de caracteres) mensagem de sucesso ou falha.
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);
unregister_table – obsoleto¶
- Esquema:
LIBRARY
Atenção
Este comando está obsoleto. Em vez disso, use library.unregister_objects.
Descrição: semelhante ao unregister_db
, mas opera no nível da 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 quiser cancelar o registro de tabelas em um esquema de acesso gerenciado (ou seja, um esquema criado usando o parâmetro WITH MANAGED ACCESS), use library.unregister_managed_access_table
.
Argumentos: table_name (array)
Retorna: (cadeia de caracteres) mensagem de sucesso ou falha.
Exemplo:
CALL samooha_by_snowflake_local_db.library.unregister_table(['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);
unregister_managed_access_table – obsoleto¶
- Esquema:
LIBRARY
Atenção
Este comando está obsoleto. Em vez disso, 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 usando o parâmetro WITH MANAGED ACCESS).
Argumentos: table_name (array)
Retorna: (cadeia de caracteres) mensagem de sucesso ou falha.
Exemplo:
CALL samooha_by_snowflake_local_db.library.unregister_managed_access_table(['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);
unregister_view – obsoleto¶
- Esquema:
LIBRARY
Atenção
Este comando está obsoleto. Em vez disso, use library.unregister_objects.
Descrição: semelhante ao unregister_db
, mas opera em um 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 quiser cancelar o registro de exibições em um esquema de acesso gerenciado (ou seja, um esquema criado usando o parâmetro WITH MANAGED ACCESS), use library.unregister_managed_access_view
.
Argumentos: view_name (array)
Retorna: (cadeia de caracteres) mensagem de sucesso ou falha.
Exemplo:
CALL samooha_by_snowflake_local_db.library.unregister_view(['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);
unregister_managed_access_view – obsoleto¶
- Esquema:
LIBRARY
Atenção
Este comando está obsoleto. Em vez disso, 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 usando o parâmetro WITH MANAGED ACCESS).
Argumentos: view_name (array)
Retorna: (cadeia de caracteres) mensagem de sucesso ou falha.
Exemplo:
CALL samooha_by_snowflake_local_db.library.unregister_managed_access_view(['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);
create_cleanroom_listing – obsoleto¶
- Esquema:
PROVIDER
Atenção
Esse comando está obsoleto. Em vez disso, use provider.create_or_update_cleanroom_listing.
Descrição: após a configuração de uma sala limpa, cria uma listagem privada com a sala limpa no Snowflake Marketplace e a compartilha com os colaboradores especificados.
Você identifica o colaborador usando o formato orgname.account_name
de sua URL de conta. O consumidor pode encontrar essa cadeia de caracteres seguindo as instruções em Como encontrar o nome da conta e organização de uma conta.
Nota
Para usar esse procedimento, você precisa ter definido a diretiva de lançamento. Para obter mais informações, consulte provider.set_default_release_directive.
Argumentos: cleanroom_name (cadeia de caracteres), consumer_account_name (cadeia de caracteres)
Retorna: (cadeia de caracteres) mensagem de sucesso ou falha.
Exemplo:
CALL samooha_by_snowflake_local_db.provider.create_cleanroom_listing($cleanroom_name, <consumerorg.consumeracct>);
register_cleanroom_in_ui – DEPRECATED¶
- Esquema:
PROVIDER
Atenção
Esse comando agora está obsoleto. Não é mais necessário registrar manualmente um modelo de sala limpa para uso na UI de salas limpas.
Descrição: registra uma sala limpa para uso do consumidor na UI de salas limpas. A sala limpa é criada e configurada pelo provedor usando as APIs de desenvolvedor. Esse comando registra a sala limpa na UI de salas limpas para que os consumidores instalem, adicionem a tabela e executem análises personalizadas que você adicionou sem precisar usar as APIs de desenvolvedor. Os consumidores trabalham com a sala limpa inteiramente por meio da interface do usuário da UI de salas limpas.
Você pode chamar essa API mais de uma vez para incluir vários modelos personalizados na UI de salas limpas.
Argumentos: cleanroom_name (string), template name (string), consumer_account_locator (string), user_email (string)
Retorna: (cadeia de caracteres) mensagem de sucesso ou falha.
Exemplo:
CALL samooha_by_snowflake_local_db.provider.register_cleanroom_in_ui($cleanroom_name, 'prod_custom_template', <CONSUMER ACCOUNT LOCATOR>, <USER_EMAIL>)