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

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

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

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

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>
Copy

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

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

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>']); 
Copy

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>']); 
Copy

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

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

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

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']);
Copy

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']);
Copy

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'
    ]
 );
Copy

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

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

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

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']);
Copy

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']);
Copy

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'
    ]
  );
Copy

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

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'
  ]
);
Copy

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

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

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']);
Copy

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

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

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']);
Copy

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

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 com sensitivity.

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 %};
    $$);
Copy

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 modelo my_table. Se algum elemento definir references=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 modelo source_table. Se algum elemento definir references=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 prefixo cleanroom. 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 se activation_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>]
    }
    
    Copy
    • 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/falso

      • integer: Use as setas para alterar o número

      • multiselect: seleciona vários itens em uma lista suspensa

      • dropdown: seleciona um item em uma lista suspensa

      • date: Seletor de data

    • default: valor padrão deste elemento

    • choices: (matriz de cadeia de caracteres) lista de opções para elementos dropdown e multiselect

    • infoMessage: 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á ser multiselect ou dropdown. 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 elemento provider_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 elemento provider_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 por consumer_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, use CONSUMER_JOIN_POLICY ou CONSUMER_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 elemento consumer_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 campo consumer_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 quando references está definido como PROVIDER_COLUMN_POLICY ou PROVIDER_JOIN_POLICY. Para fazer referência ao seletor de tabelas padrão de provedor, especifique source_table aqui e defina render_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 quando references está definido como CONSUMER_COLUMNS, CONSUMER_JOIN_POLICY ou CONSUMER_COLUMN_POLICY. Para fazer referência ao seletor de tabelas padrão de consumidor, especifique my_table aqui e defina render_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 tabular

      • BAR: gráfico de barras, que é bom para comparar diferentes categorias

      • LINE: gráfico de linhas, que é bom para mostrar tendências ao longo do tempo ou dados contínuos

      • PIE: 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:

type

references

provider_parent_table_field

consumer_parent_table_field

render_provider_table_dropdown

render_consumer_table_dropdown

multiselect ou dropdown

PROVIDER_TABLES

Não permitido

Não permitido

FALSE

TRUE ou FALSE

PROVIDER_JOIN_POLICY

source_table

Não permitido

TRUE

TRUE ou FALSE

PROVIDER_JOIN_POLICY

nome do campo pai

Não permitido

TRUE ou FALSE

TRUE ou FALSE

PROVIDER_COLUMN_POLICY

source_table

Não permitido

TRUE

TRUE ou FALSE

PROVIDER_COLUMN_POLICY

nome do campo pai

Não permitido

TRUE ou FALSE

TRUE ou FALSE

CONSUMER_TABLES

Não permitido

Não permitido

TRUE ou FALSE

FALSE

CONSUMER_COLUMNS

Não permitido

my_table ou nome do campo pai

TRUE ou FALSE

TRUE

CONSUMER_JOIN_POLICY

Não permitido

my_table ou nome do campo pai

TRUE ou FALSE

TRUE

CONSUMER_COLUMN_POLICY

Não permitido

my_table ou nome do campo pai

TRUE ou FALSE

TRUE

PROVIDER_ACTIVATION_POLICY

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'
    }
);
Copy

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']
    }
);
Copy

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

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

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

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']);
Copy

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

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')
  ]);
Copy

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 chamando provider.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) – Quando cache_results = TRUE, especifica o nome da tabela Snowflake onde os resultados do modelo são armazenados.

    • jinja_output_table_param (cadeia de caracteres) – Quando cache_results = TRUE, especifica o nome do parâmetro Jinja que outros modelos devem incluir para aceitar os resultados armazenados em output_table_name.

    • cache_expiration_hours (inteiro) – Quando cache_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
    }
  ]
);
Copy

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

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

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

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 por consumer_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>);
Copy

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

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

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

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

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' ]);
Copy

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

setup_provider_activation_share_mount_task

Esquema:

PROVIDER

Descrição: permite a ativação do provedor quando o provedor não tem a UI de clean room instalada em sua conta.

Chame isso após adicionar consumidores com provider.add_consumers. Ele é chamado somente quando você está implementando a ativação do provedor e você (o provedor) não tem a UI de clean room instalada. (Não importa se o consumidor tem ou não a UI instalada)

Isso inicia um thread para montar de forma assíncrona os compartilhamentos do consumidor necessários para a ativação do provedor. Em vez de montar os compartilhamentos de forma síncrona e bloquear seu código, esse código monta o compartilhamento de forma assíncrona e verifica novamente se há novos colaboradores periodicamente. Você precisa chamar esse procedimento apenas uma vez e pode adicionar outros colaboradores posteriormente sem precisar chamá-lo novamente.

Argumentos:

  • frequency_minutes (inteiro) – Com que frequência verificar novamente se há novos consumidores nessa clean room, a fim de montar compartilhamentos para eles também. Um valor recomendado é 15.

Retorna: (string) uma mensagem de sucesso.

Exemplo:

CALL samooha_by_snowflake_local_db.provider.setup_provider_activation_share_mount_task(15);
Copy

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

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

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>']);
Copy

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>']);
Copy

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

is_request_back_share_mounted

Esquema:

PROVIDER

Descrição: verifica se as mensagens podem ser propagadas do consumidor especificado para o provedor na sala limpa indicada. Se um compartilhamento reverso não foi montado para o consumidor nessa sala limpa, as mensagens, como aprovações de solicitações executadas pelo provedor, não são propagadas do consumidor para o provedor (mas são enfileiradas no lado do consumidor).

Chame provider.mount_request_logs_for_all_consumers para configurar o compartilhamento reverso com esse consumidor. Se você chamou provider.mount_request_logs_for_all_consumers e is_request_back_share_mounted falhar, é provável que tenha adicionado o consumidor a essa sala limpa depois da última chamada de provider.mount_request_logs_for_all_consumers.

Argumentos:

  • cleanroom_name (cadeia de caracteres): nome da sala limpa que será verificada.

  • consumer_account (cadeia de caracteres): localizador da conta do consumidor.

Retorna: SUCCESS se o compartilhamento reverso foi habilitado para o consumidor especificado na sala limpa indicada. Caso contrário, gera um erro.

Exemplo:

CALL samooha_by_snowflake_local_db.library.is_request_back_share_mounted(
  $cleanroom_name,
  $consumer_locator);
Copy

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

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

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, chame provider.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>'
);
Copy

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

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

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 em consumer_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 ambos enable_differential_privacy_tasks e privacy_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"
      }}');
Copy

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

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

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

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

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

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

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

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 namespace cleanroom. 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.

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)
    $$
);
Copy
-- 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.
);
Copy

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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.

mount_laf_cleanroom_requests_share (obsoleto)

Esquema:

PROVIDER

Essa função agora está obsoleta. Em vez dela, chame provider.mount_request_logs_for_all_consumers.

Descrição: torna acessíveis as solicitações entre nuvens para a clean room e a conta de consumidor fornecidas. provider.request_laf_cleanroom_requests deve retornar um status FULFILLED para que o usuário possa chamar esse procedimento.

Esse processo é necessário para modelos definidos pelo consumidor em que o provedor e o consumidor estão em regiões de nuvem diferentes.

Argumentos:

  • cleanroom_name (string) – clean room que é compartilhada.

  • consumer_locator (string) – Localizador de conta Snowflake do consumidor que fará solicitações entre nuvens nesta clean room.

Retorna: (string) Mensagem de sucesso.

Exemplo:

CALL samooha_by_snowflake_local_db.provider.mount_laf_cleanroom_requests_share(
  $cleanroom_name, $consumer_locator);
Copy

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

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

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

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

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

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']);
Copy

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']);
Copy

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']);
Copy

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']);
Copy

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

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']);
Copy

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']);
Copy

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']);
Copy

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']);
Copy

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

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