Snowflake Data Clean Rooms: Guia de referência da API do provedor¶

view_cleanrooms¶

Esquema:

PROVIDER

Descrição: lista todas as salas limpas existentes criadas por esta conta de provedor.

Argumentos: nenhum

Retorna: (tabela) uma lista de salas limpas criadas por esta conta de provedor. As salas limpas não precisam ser compartilhadas, instaladas ou usadas pelos consumidores. As salas limpas excluídas são eliminadas do banco de dados e não aparecem nesta lista.

Exemplo:

CALL samooha_by_snowflake_local_db.provider.view_cleanrooms();

describe_cleanroom¶

Esquema:

PROVIDER

Descrição: obtenha um resumo das informações sobre uma sala limpa, como modelos, políticas de junção, políticas de coluna e consumidores.

Argumentos:

• cleanroom_name (cadeia de caracteres) – nome da sala limpa sobre a qual obter informações.

Retorna: (cadeia de caracteres) um resumo dos metadados da sala limpa.

Exemplo:

CALL samooha_by_snowflake_local_db.provider.describe_cleanroom($cleanroom_name);

cleanroom_init¶

Esquema:

PROVIDER

Descrição: cria uma sala limpa com o nome especificado em sua conta. Este procedimento pode levar um minuto ou mais para ser executado. A sala limpa não fica visível na UI ou para os colaboradores até que você chame create_or_update_cleanroom_listing.

Argumentos:

• cleanroom_name (cadeia de caracteres) – nome da sala limpa, com no máximo 80 caracteres. Caracteres válidos: [A-Z,a-z,0-9,_] e espaços.

• distribution – (cadeia de caracteres, opcional) Um dos seguintes valores:

  • INTERNAL (padrão) – a sala limpa fica visível apenas para usuários na 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 de uma sala limpa, chame ALTER PACKAGE, conforme mostrado aqui:

    ALTER APPLICATION PACKAGE samooha_cleanroom_<CLEANROOM_ID>
      SET DISTRIBUTION = EXTERNAL;
    

    Copy

Retorna: (string) Mensagem de sucesso.

Exemplo:

-- Create an internal clean room
CALL samooha_by_snowflake_local_db.provider.cleanroom_init($cleanroom_name, 'INTERNAL');

set_default_release_directive¶

Esquema:

PROVIDER

Descrição: especifica a versão e o patch de uma sala limpa carregada pelos colaboradores quando eles iniciam uma nova sessão do navegador na UI de salas limpas ou quando acessam a sala limpa da API. Isso deve ser feito antes que a sala limpa possa ser compartilhada com os consumidores.

O aplicativo de sala limpa cria uma nova versão de uma sala limpa sempre que você faz upload ou altera o código Python. Se você quiser que os usuários recebam a versão mais recente, chame esse procedimento com o número da nova versão. Para ver as versões disponíveis e seus status ou a diretiva de lançamento atual, execute o comando SQL apropriado:

-- See all versions, including failed versions.
SHOW VERSIONS IN APPLICATION PACKAGE SAMOOHA_CLEANROOM_<cleanroom_name>;

-- See current release directive.
SHOW RELEASE DIRECTIVES IN APPLICATION PACKAGE SAMOOHA_CLEANROOM_<cleanroom_name>;

Em que <cleanroom_name> segue este formato.

Todas as salas limpas são criadas com os seguintes números de versão e patch:

• versão: V1_0

• patch: 0

Argumentos:

• cleanroom_name (cadeia de caracteres) – nome da sala limpa.

• version (cadeia de caracteres) – Versão. Deve ser sempre «V1_0».

• patch (cadeia de caracteres) – número do patch carregado pelo consumidor. Ele começa com 0 e você deve incrementá-lo sempre que uma nova versão de sala limpa estiver disponível. É possível ver as versões disponíveis conforme descrito acima.

Retorna: (string) Mensagem de sucesso.

Exemplo:

CALL samooha_by_snowflake_local_db.provider.set_default_release_directive(
  $cleanroom_name,
  'V1_0', '0'
);

drop_cleanroom¶

Esquema:

PROVIDER

Descrição: excluir a sala limpa. Os colaboradores que têm a sala limpa instalada não podem mais acessá-la ou usá-la. A sala limpa não aparece mais na UI de salas limpas na próxima vez que o navegador é atualizado.

Argumentos:

• cleanroom_name (cadeia de caracteres) – nome da sala limpa a ser excluída.

Retorna: (string) Mensagem de sucesso.

Exemplo:

CALL samooha_by_snowflake_local_db.provider.drop_cleanroom($cleanroom_name);

enable_consumer_run_analysis¶

Esquema:

PROVIDER

Descrição: permite que o consumidor execute análises na sala limpa. Este recurso é ativado por padrão em todas as novas salas limpas, portanto, este procedimento só precisa ser executado se você tiver desativado explicitamente a análise de execução do consumidor para uma sala limpa.

Argumentos:

• cleanroom_name (cadeia de caracteres) – nome da sala limpa na qual análises executadas pelo consumidor são permitidas.

• consumer_accounts (matriz de cadeias de caracteres) – localizadores de contas de todos os consumidores para os quais este recurso deve ser ativado. NOTE: esses consumidores já devem ter sido adicionados à sala limpa.

Retorna: (string) Mensagem de sucesso.

Exemplo:

CALL samooha_by_snowflake_local_db.provider.enable_consumer_run_analysis(
  $cleanroom_name,
  ['<CONSUMER_ACCOUNT_LOCATOR_1>']
);

disable_consumer_run_analysis¶

Esquema:

PROVIDER

Descrição: impede que os consumidores especificados executem análises na sala limpa especificada. Por padrão, todos os consumidores têm permissão para executar uma análise em uma sala limpa.

Argumentos:

• cleanroom_name (cadeia de caracteres) – sala limpa onde a análise executada pelo consumidor está sendo desativada.

• consumer_accounts (matriz de cadeias 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: (string) Mensagem de sucesso.

Exemplo:

CALL samooha_by_snowflake_local_db.provider.disable_consumer_run_analysis(
  $cleanroom_name,
  ['<CONSUMER_ACCOUNT_LOCATOR_1>']
);

is_consumer_run_enabled¶

Esquema:

LIBRARY

Descrição: verifica se esta sala limpa permite análises executadas pelo consumidor.

Argumentos:

• cleanroom_name (cadeia de caracteres) – nome da sala limpa a ser verificada.

Retorna: (cadeia de caracteres) se esta sala limpa permite ou não análises executadas pelo consumidor.

Exemplo:

CALL samooha_by_snowflake_local_db.library.is_consumer_run_enabled($cleanroom_name)

create_or_update_cleanroom_listing¶

Esquema:

PROVIDER

Descrição: publica uma nova sala limpa ou atualiza uma sala limpa existente. É necessário chamar este método sempre que fizer alterações em uma sala limpa para garantir que as alterações sejam propagadas aos consumidores.

Ao publicar uma sala limpa pela primeira vez, pode levar até 15 minutos para que ela fique visível na UI de salas limpas.

Se você fizer atualizações em uma sala limpa sem chamar este método posteriormente, não há 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.

Argumentos:

• cleanroom_name (cadeia de caracteres) – nome da sala limpa a ser publicada ou atualizada.

Retorna: (string) Mensagem de sucesso.

Tratamento de erros:

se você receber um erro informando que o «preenchimento automático entre nuvens não está ativado para esta conta», isso significa que um dos consumidores está em outra região de hospedagem na nuvem. Você deve ativar 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
);

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. Este procedimento concede privilégios de USAGE e SELECT no banco de dados para SAMOOHA_APP_ROLE, que é usado 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.

Argumentos:

• db_name (cadeia de caracteres) – Nome do banco de dados a ser registrado.

Retorna: (string) Mensagem de sucesso.

Exemplo:

USE ROLE <role_with_manage_grants>;
CALL samooha_by_snowflake_local_db.provider.register_db('SAMOOHA_SAMPLE_DATABASE');

register_schema¶

Esquema:

LIBRARY

Descrição: semelhante a register_db, mas opera em nível de esquema. É necessário ter o privilégio MANAGE GRANTS no esquema para chamar este procedimento.

Este procedimento concede os privilégios USAGE e SELECT no esquema para SAMOOHA_APP_ROLE, que é usado pelo ambiente de sala limpa para acessar os dados.

Se você 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.

Argumentos:

• schema_name (matriz de cadeias de caracteres) – uma matriz de um ou mais nomes de esquema totalmente qualificados para registro.

Retorna: (string) Mensagem de sucesso.

Exemplo:

USE ROLE <role_with_manage_grants>;
CALL samooha_by_snowflake_local_db.library.register_schema(['SAMOOHA_SAMPLE_DATABASE.DEMO']);

register_managed_access_schema¶

Esquema:

LIBRARY

Descrição: semelhante a register_schema, mas registra um esquema que foi criado usando o parâmetro WITH MANAGED ACCESS. É necessário ter os privilégios MANAGE GRANTS no esquema para chamar este 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.

Argumentos:

• schema_name (matriz de cadeias de caracteres) – uma matriz de um ou mais nomes de esquema totalmente qualificados.

Retorna: (string) Mensagem de sucesso.

Exemplo:

USE ROLE <role_with_manage_grants>;
CALL samooha_by_snowflake_local_db.library.register_managed_access_schema(
  ['SAMOOHA_SAMPLE_DATABASE.DEMO']
);

register_objects¶

Esquema:

LIBRARY

Descrição: concede à sala limpa acesso a tabelas e exibições de todos os tipos, tornando-as disponíveis para serem vinculadas à sala limpa chamando provider.link_datasets. Você pode registrar grupos maiores 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 (matriz) – matriz de nomes de objetos totalmente qualificados. Esses objetos podem então ser conectados à sala limpa.

Retorna: (string) Mensagem de sucesso.

Exemplos

Para registrar uma tabela e uma exibição:

USE ROLE <role_with_manage_grants>;
CALL samooha_by_snowflake_local_db.library.register_objects(
  [
    'SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS',
    'SAMOOHA_SAMPLE_DATABASE.INFORMATION_SCHEMA.FIELDS'
  ]
 );

enable_external_tables_on_account¶

Esquema:

LIBRARY

Descrição: permite que tabelas Iceberg ou externas sejam usadas em todas as salas limpas desta conta. Deve ser chamada por um ACCOUNTADMIN em ambas as contas do provedor e do consumidor para permitir que tabelas Iceberg ou externas sejam vinculadas por qualquer conta. Para limitar essa capacidade a salas limpas específicas desta conta, chame enable_external_tables_for_cleanroom.

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. Em caso de sucesso, ele aciona uma verificação de segurança e também fornece o número do patch que será gerado se a verificação de segurança for bem-sucedida.

Exemplo:

USE ROLE ACCOUNTADMIN;
CALL samooha_by_snowflake_local_db.library.enable_external_tables_on_account();

enable_external_tables_for_cleanroom¶

Esquema:

PROVIDER

Descrição: permite que tabelas Iceberg ou externas sejam vinculadas à sala limpa especificada nesta conta pelo provedor. Para permitir tabelas Iceberg e externas para todas as salas limpas desta conta, chame enable_external_tables_on_account.

Em caso de sucesso, isso gera uma nova versão de patch da sala limpa.

Argumentos:

• cleanroom_name (cadeia de caracteres) – o nome da sala limpa à qual o provedor pode vincular tabelas Iceberg ou externas.

Retorna: (cadeia de caracteres) mensagem de sucesso. Em caso de sucesso, ele aciona uma verificação de segurança e também fornece o número do patch que será gerado se a verificação de segurança for bem-sucedida.

Exemplo:

CALL samooha_by_snowflake_local_db.provider.enable_external_tables_for_cleanroom(
  $cleanroom_name);

unregister_db¶

Esquema:

LIBRARY

Descrição: reverte o procedimento register_db e remove as concessões em nível de banco de dados concedidas à função SAMOOHA_APP_ROLE e ao 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 a ter o registro cancelado.

Retorna: (string) Mensagem de sucesso.

Exemplo:

USE ROLE <role_with_manage_grants>;
CALL samooha_by_snowflake_local_db.library.unregister_db('SAMOOHA_SAMPLE_DATABASE');

unregister_schema¶

Esquema:

LIBRARY

Descrição: cancela o registro de um esquema, o que impede que os usuários vinculem suas tabelas e exibições à sala limpa.

Se você 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 (matriz) – esquemas para cancelar o registro.

Retorna: (string) Mensagem de sucesso.

Exemplo:

USE ROLE <role_with_manage_grants>;
CALL samooha_by_snowflake_local_db.library.unregister_schema(
  ['SAMOOHA_SAMPLE_DATABASE.DEMO']
);

unregister_managed_access_schema¶

Esquema:

LIBRARY

Descrição: semelhante a unregister_schema, mas cancela o registro de um esquema criado usando o parâmetro WITH MANAGED ACCESS.

Argumentos:

• schema_name (matriz) – Esquemas gerenciados para cancelar o registro.

Retorna: (string) Mensagem de sucesso.

Exemplo:

USE ROLE <role_with_manage_grants>;
CALL samooha_by_snowflake_local_db.library.unregister_managed_access_schema(['SAMOOHA_SAMPLE_DATABASE.DEMO']);

unregister_objects¶

Esquema:

LIBRARY

Descrição: revoga o acesso de sala limpa a tabelas e exibições de todos os tipos. Os objetos não estarão mais disponíveis para nenhum usuário em nenhuma sala limpa gerenciada por essa conta.

Argumentos:

• object_names (matriz) – matriz de nomes de objetos totalmente qualificados para os quais o acesso deve ser revogado.

Retorna: (string) Mensagem de sucesso.

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

link_datasets¶

Esquema:

PROVIDER

Descrição: vincula uma tabela ou exibição do Snowflake à sala limpa. O procedimento torna a tabela automaticamente acessível à sala limpa, criando uma exibição segura da tabela dentro da sala limpa, evitando assim a necessidade de fazer uma cópia da tabela. A tabela ainda está vinculada à sua origem, portanto, as atualizações na origem serão refletidas na versão segura dentro da sala limpa.

Todos os itens vinculados aqui devem ser registrados primeiro, no nível do banco de dados, do esquema ou do objeto.

Argumentos:

• cleanroom_name (cadeia de caracteres) – nome da sala limpa com acesso aos objetos.

• tables_list (matriz de cadeias de caracteres) – lista de tabelas ou exibições a serem vinculadas à sala limpa. Os objetos devem ser registrados antes de poderem ser vinculados.

• consumer_list (matriz de cadeias de caracteres, opcional) – se presente, permite que apenas os consumidores listados aqui acessem esses objetos. Se não estiver presente, permite que qualquer pessoa com acesso à sala limpa acesse estes dados.

Retorna: (string) Mensagem de sucesso.

Exemplo:

CALL samooha_by_snowflake_local_db.provider.link_datasets(
  $cleanroom_name,
  [
    'SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS',
    'MYDB.MYSCH.EXPOSURES'
  ]
);

unlink_datasets¶

Esquema:

PROVIDER

Descrição: remove o acesso às tabelas especificadas na sala limpa especificada para todos os usuários. As tabelas especificadas devem ter sido vinculadas pelo provedor.

Argumentos:

• cleanroom_name (cadeia de caracteres) – nome da sala limpa vinculada a esses conjuntos de dados.

• tables_list (matriz) – matriz de nomes de tabelas ou exibições a serem desvinculadas da sala limpa.

Retorna: (string) Mensagem de sucesso.

Exemplo:

CALL samooha_by_snowflake_local_db.provider.unlink_datasets(
  $cleanroom_name,
  [
    'SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS',
    'MYDB.MYSCH.EXPOSURES'
  ]
);

view_provider_datasets¶

Esquema:

PROVIDER

Descrição: exibe todas as tabelas e exibições vinculadas à sala limpa especificada por qualquer provedor nesta conta.

Argumentos:

• cleanroom_name (cadeia de caracteres) – nome da sala limpa.

Retorna: tabela de objetos vinculados à sala limpa especificada, juntamente com o nome da exibição interna da sala limpa para cada objeto.

Exemplo:

CALL samooha_by_snowflake_local_db.provider.view_provider_datasets($cleanroom_name);

restrict_table_options_to_consumers¶

Esquema:

PROVIDER

Descrição: controla se um determinado consumidor pode acessar uma tabela na sala limpa. Esse procedimento é somente substituição, o que significa que ele substitui completamente todos os valores definidos em uma chamada anterior.

Consumidores com acesso concedido por meio de provider.link_datasets, provider.restrict_table_options_to_consumers ou qualquer outro método perderão o acesso a uma tabela se ela não for especificada ao chamar este método.

Argumentos:

• cleanroom_name (cadeia de caracteres) – nome da sala limpa a ser restringida.

• access_details (objeto) – um objeto JSON, em que cada nome de campo é o nome totalmente qualificado de uma tabela ou exibição, e o valor do campo é uma matriz de localizadores de contas de usuários que podem acessar essa tabela ou exibição.

Retorna: (string) Mensagem de sucesso.

Exemplo:

CALL samooha_by_snowflake_local_db.provider.restrict_table_options_to_consumers(
  $cleanroom_name,
  {
    'DB.SCHEMA.TABLE1': ['CONSUMER_1_LOCATOR'],
    'DB.SCHEMA.TABLE2': ['CONSUMER_1_LOCATOR', 'CONSUMER_2_LOCATOR']
  }
);

view_join_policy¶

Esquema:

PROVIDER

Descrição: mostra as políticas de junção atualmente aplicadas à sala limpa.

Argumentos:

• cleanroom_name (cadeia de caracteres) – nome da sala limpa a ser consultada.

Retorna: (tabela) lista de linhas juntáveis em todas as tabelas ou exibições na sala limpa.

Exemplo:

CALL samooha_by_snowflake_local_db.provider.view_join_policy($cleanroom_name);

set_join_policy¶

Esquema:

PROVIDER

Descrição: especifica em quais colunas o consumidor pode se unir ao executar modelos dentro desta sala limpa. Observe que a política é somente substituição, portanto, se o procedimento for chamado novamente, a política de junção definida anteriormente será completamente substituída pela nova.

Argumentos:

• cleanroom_name (cadeia de caracteres) – nome da sala limpa onde a política de associação deve ser aplicada.

• table_and_col_names (matriz de cadeias de caracteres) – nome da coluna totalmente qualificado no formato database_name.schema_name.table_or_view_name:column_name. Observe o uso correto dos sinais de ponto final (.) em comparação a dois-pontos (:)

Retorna: (string) Mensagem de sucesso.

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

view_added_templates¶

Esquema:

PROVIDER

Descrição: exibe os modelos adicionados pelo provedor na sala limpa. Não existe um método para listar todos os modelos em todas as salas limpas para este provedor.

Argumentos:

• cleanroom_name (cadeia de caracteres) – sala limpa a ser consultada.

Retorna: (tabela) – Lista de modelos disponíveis na sala limpa especificada, com detalhes sobre cada modelo.

Exemplo:

CALL samooha_by_snowflake_local_db.provider.view_added_templates($cleanroom_name);

view_template_definition¶

Esquema:

PROVIDER

Descrição: mostra informações sobre um modelo específico. Os consumidores que estiverem consultando um modelo de provedor devem usar consumer.view_template_definition.

Argumentos:

• cleanroom_name (cadeia de caracteres) – nome da sala limpa com este modelo.

• template_name (cadeia de caracteres) – nome do modelo sobre o qual solicitar informações.

Retorna: (cadeia de caracteres) a definição do modelo.

Exemplo:

CALL samooha_by_snowflake_local_db.provider.view_template_definition(
  $cleanroom_name,
  $template_name);

add_templates¶

Esquema:

PROVIDER

Descrição: adiciona uma lista de modelos à sala limpa. Isso não substitui a lista de modelos existente.

Argumentos:

• cleanroom_name (cadeia de caracteres) – nome da sala limpa à qual adicionar modelos.

• template_names (matriz de cadeias 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: (string) Mensagem de sucesso.

Exemplo:

CALL samooha_by_snowflake_local_db.provider.add_templates(
  $cleanroom_name,
  ['my_custom_template']);

clear_template¶

Esquema:

PROVIDER

Descrição: Remove um modelo especificado da sala limpa.

Argumentos:

• cleanroom_name (cadeia de caracteres) – nome da sala limpa.

• template_name (cadeia de caracteres) – nome do modelo a ser removido dessa sala limpa.

Retorna: (string) Mensagem de sucesso.

Exemplo:

CALL samooha_by_snowflake_local_db.provider.clear_template(
  $cleanroom_name,
  'prod_custom_template');

clear_all_templates¶

Esquema:

PROVIDER

Descrição: remove todos os modelos que foram adicionados à sala limpa.

Argumentos:

• cleanroom_name (cadeia de caracteres) – nome da sala limpa da qual remover todos os modelos.

Retorna: (string) Mensagem de sucesso.

Exemplo:

CALL samooha_by_snowflake_local_db.provider.clear_all_templates($cleanroom_name);

set_column_policy¶

Esquema:

PROVIDER

Descrição: define quais colunas nos dados estão disponíveis para um modelo especificado na sala limpa como linhas sem junção. 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 (cadeia de caracteres) – nome da sala limpa.

• analysis_and_table_and_cols – (matriz de cadeias de caracteres) matriz de colunas que podem ser utilizadas por modelos. O formato de cada coluna é: template_name:full_table_name:column_name

Retorna: (string) Mensagem de sucesso.

Exemplo:

CALL samooha_by_snowflake_local_db.provider.set_column_policy($cleanroom_name,
['prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:STATUS',
 'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:AGE_BAND',
 'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:DAYS_ACTIVE']);

 -- Same example, but using a variable name for the template.
CALL samooha_by_snowflake_local_db.provider.set_column_policy($cleanroom_name,
[$template_name || ':SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:STATUS',
 $template_name || ':SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:AGE_BAND',
 $template_name || ':SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:DAYS_ACTIVE']);

view_column_policy¶

Esquema:

PROVIDER

Descrição: lista as políticas de coluna atualmente ativas na sala limpa. Uma política de coluna informa quais colunas da tabela podem ser exibidas em quais modelos.

Argumentos:

• cleanroom_name (cadeia de caracteres)

Retorna: (tabela) quais colunas podem ser usadas em quais modelos.

Exemplo:

CALL samooha_by_snowflake_local_db.provider.view_column_policy($cleanroom_name);

add_custom_sql_template¶

Esquema:

PROVIDER

Descrição: adiciona um modelo JinjaSQL personalizado à sala limpa. Isso permite que o consumidor chame o modelo. 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 utilizado pelo consumidor para ativar os resultados de volta para o 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, para o modelo chamado activation_data_analysis_results, você retornaria 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 esta sala limpa, ela controlará a quantidade de ruído de privacidade diferencial aplicada aos dados retornados por este modelo. Deve ser um número maior que 0. O padrão é 1.0. A tarefa de privacidade diferencial deve estar em execução nesta sala limpa para que este argumento tenha efeito.

• consumer_locators (matriz de cadeias de caracteres, opcional) – uma matriz de um ou mais localizadores de contas. Se estiver presente, esse modelo será adicionado à sala limpa somente para essas contas. Você pode modificar esta 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 (booleano, opcional) – se é TRUE, impede que os consumidores visualizem 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 utilizado para uma análise executada 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 utilizado junto com sensitivity.

Retorna: (string) Mensagem de sucesso.

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
        IDENTIFIER({{ c.consumer_id  }}) = IDENTIFIER({{ provider_id | join_policy }})
    {% if where_clause %}
      WHERE {{ where_clause | sqlsafe | join_and_column_policy }}
    {% endif %};
    $$);

add_ui_form_customizations¶

Esquema:

PROVIDER

Descrição: define um formulário de personalização para um modelo em uma sala limpa quando a sala limpa é executada na UI de salas limpas. Isso é útil quando você permite que os consumidores escolham parâmetros do modelo, como tabelas ou colunas. No mínimo, você deve especificar valores para display_name, description e methodology no argumento template_information.

Recomendamos colocar 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 sala limpa após chamar esta função. Se você não chamar provider.create_or_update_cleanroom_listing após atualizar a UI, os colaboradores não vão enxergar nenhuma atualização.

Argumentos:

• cleanroom_name (cadeia de caracteres) – o nome da sala limpa que contém 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 essa UI se aplica. Este não é o título visível ao usuário, que é especificado usando o campo template_information.display_name.

• template_information (Dicionário) – metainformações sobre o modelo a ser exibido na UI do Clean Rooms. As seguintes propriedades devem ou podem ser definidas:

  • display_name (obrigatório): nome de exibição do modelo na UI do Clean Rooms..

  • 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 utilizado para executar a análise. Este é um objeto com os seguintes campos:

    • warehouse_size: consulte warehouse_size em CREATE WAREHOUSE para obter valores válidos.

    • snowpark_optimized (booleano): se um warehouse otimizado para Snowpark deve ser utilizado para processar a consulta. Para a maioria dos casos de uso de machine learning, a Snowflake recomenda TRUE.

  • render_table_dropdowns (objeto): se deve ou não mostrar as listas suspensas padrão que permitem ao usuário selecionar quais tabelas de provedores ou consumidores usar na consulta. Este é um objeto com os seguintes campos:

    • render_consumer_table_dropdown (booleano) – se TRUE, mostra o seletor padrão da tabela de consumidores. 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, o padrão será TRUE.

    • render_provider_table_dropdown (booleano) – se TRUE, mostra o seletor padrão da tabela de provedores. 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, o padrão será TRUE.

  • activation_template_name (cadeia de caracteres) – nome de um modelo de ativação nesta sala limpa. Use o nome do modelo sem o prefixo cleanroom. Saiba mais sobre modelos de ativação.

  • enabled_activations (cadeia de caracteres) – quais tipos de ativações estão habilitados. Valores possíveis: consumer, provider. Sem padrão; deve ser fornecido se activation_template_name for especificado.

• details (dicionário, opcional) – define campos de entrada configuráveis ​​pelo usuário que passam valores para o 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, o Clean Rooms 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 para este item na UI do formulário.

  • order: ordem baseada em 1 em que esse elemento deve ser exibido 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. Forneça ajuda breve ou exemplos aqui. Se não for fornecido, nada será exibido.

  • type: O tipo do elemento de UI. Se references for especificado para este campo de entrada, omita esta entrada (o tipo é determinado para você). Valores aceitos:

    • any (padrão): campo de entrada de texto normal.

    • boolean: seletor verdadeiro/falso

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

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

    • dropdown: selecione um item em uma lista suspensa

    • date: seletor de datas

  • default: valor padrão deste elemento

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

  • infoMessage: texto informativo exibido ao lado do elemento. Se não fornecido, nenhuma dica de ferramenta será fornecida.

  • size: Tamanho do elemento. Valores aceitos: XS, S, M, L, XL

  • required: Se um valor é obrigatório para o usuário. Especifique 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, em seguida, definir sua própria lista suspensa que contém as tabelas desejadas. Para obter mais informações sobre o uso dessas variáveis ​​especiais ao 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 utilizado, type deve ser multiselect ou dropdown. Os seguintes valores de cadeia de caracteres são aceitos:

    • PROVIDER_TABLES: liste todas as tabelas do provedor na sala limpa. Se especificado, render_table_dropdowns.render_provider_table_dropdown deve ser FALSE.

    • PROVIDER_JOIN_POLICY: liste todas as colunas na política de junção do provedor para a tabela atualmente selecionada no elemento provider_parent_table_field.

    • PROVIDER_COLUMN_POLICY: liste todas as colunas na política de colunas 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 do consumidor na sala limpa. Se especificado, render_table_dropdowns.render_consumer_table_dropdown deve ser FALSE.

    • CONSUMER_COLUMNS: liste todas as colunas na tabela de consumidores especificada por consumer_parent_table_field. Você não deve usar referências de coluna do consumidor em modelos executados pelo provedor, pois o consumidor pode aplicar políticas de junção e coluna a essas colunas; 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 da UI do elemento em que o usuário seleciona uma tabela do provedor; não forneça o nome da tabela aqui. Use somente quando references estiver definido como PROVIDER_COLUMN_POLICY ou PROVIDER_JOIN_POLICY. Para fazer referência ao seletor de tabela do provedor padrão, especifique source_table aqui e defina render_table_dropdowns.render_provider_table_dropdown como TRUE.

  • consumer_parent_table_field: o nome da UI do elemento em que o usuário seleciona uma tabela do consumidor; não forneça o nome da tabela aqui. Use somente quando references estiver definido como CONSUMER_COLUMNS, CONSUMER_JOIN_POLICY ou CONSUMER_COLUMN_POLICY. Para fazer referência ao seletor de tabela de consumidor padrão, especifique my_table aqui e defina render_table_dropdowns.render_provider_table_dropdown como TRUE.

• output_config (Dicionário) – define como exibir os resultados do modelo graficamente na UI do Clean Rooms. 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 este argumento. Campos permitidos:

  • measure_columns: nomes de colunas contendo medidas e dimensões a serem utilizadas no gráfico gerado pela UI do Clean Rooms.

  • 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 correto. Tipos aceitos:

    • TABLE (padrão): formato tabular

    • BAR: gráfico de barras, ideal para comparar diferentes categorias

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

    • PIE: gráfico de pizza, adequado para mostrar proporções ou porcentagens

A tabela a seguir mostra uma matriz de valores permitidos no objeto details para valores que podem entrar em conflito:

Retorna: (string) Mensagem de sucesso.

Exemplo:

-- Specify the display name, description, and warehouse, and hide the default table dropdown lists.
-- Define the following two fields in the UI:
--   A provider table selector that shows all provider tables. Chosen tables can be accessed by the template with the variable 'a_provider_table'
--     (This dropdown list is equivalent to setting ``render_table_dropdowns.render_provider_table_dropdown: True``)
--   A column selector for the tables chosen in 'a_provider_table'. Chosen columns can be accessed by the template with the variable 'a_provider_col'

  CALL samooha_by_snowflake_local_db.provider.add_ui_form_customizations(
      $cleanroom_name,
      'prod_custom_template',
      {
          'display_name': 'Custom Analysis Template',
          'description': 'Use custom template to run a customized analysis.',
          'methodology': 'This custom template dynamically renders a form for you to fill out, which are then used to generate a customized analysis fitting your request.',
          'warehouse_hints': {
              'warehouse_size': 'xsmall',
              'snowpark_optimized': FALSE
          },
          'render_table_dropdowns': {
              'render_consumer_table_dropdown': false,
              'render_provider_table_dropdown': false
          },
          'activation_template_name': 'activation_my_template',
          'enabled_activations': ['consumer', 'provider']
      },
      {
          'a_provider_table': {
              'display_name': 'Provider table',
              'order': 3,
              'description': 'Provider table selection',
              'size': 'S',
              'group': 'Seed Audience Selection',
              'references': ['PROVIDER_TABLES'],
              'type': 'dropdown'
          },
          'a_provider_col': {
              'display_name': 'Provider column',
              'order': 4,
              'description': 'Which col do you want to count on',
              'size': 'S',
              'group': 'Seed Audience Selection',
              'references': ['PROVIDER_COLUMN_POLICY'],
              'provider_parent_table_field': 'a_provider_table',
              'type': 'dropdown'
          }
      },
      {
          'measure_columns': ['col1', 'col2'],
          'default_output_type': 'PIE'
      }
  );

restrict_template_options_to_consumers¶

Esquema:

PROVIDER

Descrição: controla quais usuários podem acessar um determinado modelo em uma determinada sala limpa. Esse procedimento substitui qualquer lista de acesso especificada anteriormente por qualquer outro procedimento para um par de sala limpa/modelo.

Argumentos:

• cleanroom_name (cadeia de caracteres) – o nome da sala limpa.

• access_details (objeto JSON) – o nome de um modelo e os usuários que podem acessá-lo nessa sala limpa. Se um modelo for especificado, somente os usuários listados aqui poderão acessar esse modelo nessa sala limpa. Este é um objeto com um objeto filho por modelo no seguinte formato: '{template_name': ['user1_locator','user2_locator','userN_locator']}

Retorna: (string) Mensagem de sucesso.

Exemplo:

CALL samooha_by_snowflake_local_db.provider.restrict_template_options_to_consumers(
  $cleanroom_name,
  {
      'prod_template_1': ['CONSUMER_1_LOCATOR', 'CONSUMER_2_LOCATOR']
  }
);

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 sala limpa. Isso inclui solicitações pendentes, aprovadas e rejeitadas. Use este procedimento para verificar solicitações pendentes e aprová-las (provider.approve_template_request) ou rejeitá-las (provider.reject_template_request).

Isso falhará até que todos os consumidores com os quais a sala limpa é compartilhada tenham instalado a sala limpa.

Argumentos:

• cleanroom_name (cadeia de caracteres) – visualize as solicitações do consumidor para adicionar um modelo a esta 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 fez 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($cleanroom_name);

list_template_requests¶

Esquema:

PROVIDER

Descrição: lista todas as solicitações de consumidores que desejam adicionar um modelo definido pelo consumidor a uma sala limpa. Isso inclui solicitações pendentes, aprovadas e rejeitadas. Use isso para verificar solicitações pendentes e aprová-las (provider.approve_template_request) ou rejeitá-las (provider.reject_template_request).

Argumentos:

• cleanroom_name (cadeia de caracteres) – visualize as solicitações do consumidor para adicionar um modelo a esta 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 fez 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($cleanroom_name);

approve_template_request¶

Esquema:

PROVIDER

Descrição: aprova uma solicitação para adicionar um modelo à sala limpa.

Argumentos:

• cleanroom_name (cadeia de caracteres) – nome da sala limpa à qual o usuário deseja adicionar o modelo.

• request_id (cadeia de caracteres) – ID da solicitação a ser aprovada. Chame provider.list_template_requests para ver os IDs das solicitações.

Retorna: (string) Mensagem de sucesso.

Exemplo:

CALL samooha_by_snowflake_local_db.provider.approve_template_request(
  $cleanroom_name,
  '815324e5-54f2-4039-b5fb-bb0613846a5b'
);

approve_multiple_template_requests¶

Esquema:

PROVIDER

Descrição: aprova várias solicitações de consumidores para adicionar um modelo a uma clean room. Todas as solicitações devem ser para uma única clean room.

Argumentos:

• cleanroom_name (cadeia de caracteres) – o nome da sala limpa à qual esta solicitação se aplica.

• request_ids (matriz de cadeias de caracteres) – os IDs de todas as solicitações de modelo a serem aprovadas. Para obter o ID de uma solicitação, chame provider.list_template_requests.

Retorna: (string) Mensagem de sucesso.

Exemplo:

CALL samooha_by_snowflake_local_db.provider.approve_multiple_template_requests(
  $cleanroom_name,
  [
    'cfd538e2-3a17-48e3-9773-14275e7d2cc9',
    '2982fb0a-02b7-496b-b1c1-56e6578f5eac'
  ]
);

reject_template_request¶

Esquema:

PROVIDER

Descrição: rejeita uma solicitação para adicionar um modelo a uma sala limpa.

Argumentos:

• cleanroom_name (cadeia de caracteres) – nome da sala limpa à qual o usuário deseja adicionar o modelo.

• request_id (cadeia de caracteres) – ID da solicitação a ser rejeitada. Chame provider.list_template_requests para ver os IDs das solicitações.

• reason_for_rejection (cadeia de caracteres) – motivo da rejeição da solicitação.

Retorna: (string) Mensagem de sucesso.

Exemplo:

CALL samooha_by_snowflake_local_db.provider.reject_template_request(
  $cleanroom_name,
  'cfd538e2-3a17-48e3-9773-14275e7d2cc9',
  'Failed security assessment');

reject_multiple_template_requests¶

Esquema:

PROVIDER

Descrição: rejeita várias solicitações de consumidores para adicionar um modelo a uma clean room. Todas as solicitações devem ser para a mesma clean room.

Argumentos:

• cleanroom_name (cadeia de caracteres) – nome da sala limpa à qual esta solicitação se aplica.

• rejected_templates – (matriz de objetos) uma matriz de objetos com os seguintes campos, um por rejeição:

  • request_id (cadeia de caracteres) – ID da solicitação a ser rejeitada. Para obter o ID de uma solicitação, chame provider.list_template_requests.

  • reason_for_rejection (cadeia de caracteres) – uma descrição em texto livre do motivo da rejeição da solicitação.

Retorna: (string) Mensagem de sucesso.

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

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 por meio da chamada de provider.add_template_chain.

  • cache_results (booleano) – 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: (string) Mensagem de sucesso.

Exemplo:

CALL samooha_by_snowflake_local_db.provider.add_template_chain(
  $cleanroom_name,
  'my_chain',
  [
    {
      'template_name': 'crosswalk',
      'cache_results': True,
      'output_table_name': 'crosswalk',
      'jinja_output_table_param': 'crosswalk_table_name',
      'cache_expiration_hours': 2190
    },
    {
      'template_name': 'transaction_insights',
      'cache_results': False
    }
  ]
);

view_added_template_chains¶

Esquema:

PROVIDER

Descrição: lista as cadeias de modelos na sala limpa especificada.

Argumentos:

• cleanroom_name (cadeia de caracteres) – nome da sala limpa.

Retorna: (tabela) descrição de todas as cadeias de modelos adicionadas a essa sala limpa.

Exemplo:

CALL samooha_by_snowflake_local_db.provider.view_added_template_chains($cleanroom_name);

view_template_chain_definition¶

Esquema:

PROVIDER

Descrição: retorna a definição de uma cadeia de modelos.

Argumentos:

• cleanroom_name (cadeia de caracteres) – nome da sala limpa associada a esta cadeia de modelos.

• template_chain_name (cadeia de caracteres) – nome da cadeia de modelos associada a esta sala limpa.

Retorna: (tabela) Descrição da cadeia de modelos especificada.

Exemplo:

CALL samooha_by_snowflake_local_db.provider.view_template_chain_definition(
  $cleanroom_name,
  'my_chain');

clear_template_chain¶

Esquema:

PROVIDER

Descrição: exclui uma cadeia de modelos especificada de uma sala limpa especificada. A cadeia não é armazenada em nenhum lugar, portanto, se você quiser recriar a cadeia, deverá recriá-la do zero.

Argumentos:

• cleanroom_name (cadeia de caracteres) – a sala limpa à qual esta cadeia de modelos está atribuída.

• template_chain_name (cadeia de caracteres) – a cadeia de modelos a ser removida desta sala limpa.

Retorna: (string) Mensagem de sucesso.

Exemplo:

CALL samooha_by_snowflake_local_db.provider.clear_template_chain($cleanroom_name, 'my_chain');

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 essas 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 registro de solicitações multiprovedor desta sala limpa.

Todas as chamadas feitas para esta sala limpa usando consumer.prepare_multiprovider_flow serão salvas e ficarão visíveis mesmo antes de você chamar enable_multiprovider_computation para esta sala limpa.

Para permitir que um consumidor acesse várias salas limpas em sua conta, especifique uma sala limpa 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 após o início, mas você pode suspender a aprovação automatizada para um determinado usuário (se você a concedeu chamando provider.suspend_multiprovider_tasks) e, em seguida, não aprovar mais solicitações.

Argumentos:

• cleanroom_name (cadeia de caracteres) – nome de uma sala limpa de sua propriedade. Todos os dados nesta sala limpa podem ser compartilhados com salas limpas listadas em approved_other_cleanrooms em solicitações multiprovedor por consumer_account.

• consumer_account (cadeia de caracteres) – localizador de conta de um consumidor que tem permissão para fazer a solicitação e, se aprovado, executar uma consulta em quaisquer tabelas nesta sala limpa, combinadas com dados de quaisquer salas limpas listadas em approved_other_cleanrooms.

• approved_other_cleanrooms (matriz de cadeias de caracteres) – matriz de nomes de salas limpas totalmente qualificados com os quais os dados desta 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, não o localizador da conta, em cada descrição de sala limpa.

Retorna: (string) Mensagem de sucesso.

Exemplo:

CALL samooha_by_snowflake_local_db.provider.enable_multiprovider_computation(
  $cleanroom_name,
  $consumer_account_locator,
  <org_name>.<account_locator>.<cleanroom_name>);

view_multiprovider_requests¶

Esquema:

PROVIDER

Descrição: mostra todas as solicitações de análise multiprovedor de uma determinada conta e sala limpa. Isso inclui solicitações aprovadas e negadas. Os provedores podem usar este procedimento para pesquisar solicitações e 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 sala limpa.

Você deve chamar enable_multiprovider_computation para essa conta de consumidor e sala limpa antes de poder chamar view_multiprovider_requests.

Argumentos:

• cleanroom_name (cadeia de caracteres) – exibe solicitações do consumidor especificado desta sala limpa.

• consumer_account (cadeia de caracteres) – exibe solicitações desse localizador de contas de consumidor da sala limpa especificada.

Retorna: (string) Mensagem de sucesso.

Exemplo:

CALL samooha_by_snowflake_local_db.provider.view_multiprovider_requests(
  $cleanroom_name,
  $consumer_locator);

process_multiprovider_request¶

Esquema:

PROVIDER

Descrição: aprova a execução da consulta multiprovedor 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 provider.enable_multiprovider_computation. O consumidor ainda deve chamar consumer.execute_multiprovider_flow para executar a consulta. Uma solicitação será descartada após quatro horas se não for aprovada.

Por padrão, todas as solicitações multiprovedor devem ser tratadas usando este procedimento. Se você preferir que todas as solicitações deste consumidor nesta sala limpa sejam aprovadas automaticamente, especifique -1 para request_id. Se você quiser que todas as solicitações de todos os consumidores nesta sala limpa sejam aprovadas, chame provider.resume_multiprovider_tasks. Saiba como revogar solicitações aprovadas anteriormente.

Após a avaliação da solicitação, o status da solicitação e da avaliação são gravados na tabela de log desta sala limpa.

Argumentos:

• cleanroom_name (cadeia de caracteres) – o nome da sua sala limpa, que um consumidor está solicitando para incluir em uma análise multiprovedor.

• consumer_account (cadeia de caracteres) – o localizador da conta do consumidor do usuário que está solicitando a análise multiprovedor. Esse localizador deve ter sido aprovado para esta sala limpa e 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. Passe -1 para aprovar todas as solicitações para este consumidor nesta sala limpa.

Retorna: (string) Mensagem de sucesso.

Exemplo:

CALL samooha_by_snowflake_local_db.provider.process_multiprovider_request(
  $cleanroom_name_1,
  $consumer_account_locator,
  $request_id);

suspend_multiprovider_tasks¶

Esquema:

PROVIDER

Descrição: interrompe a revisão e aprovação automatizadas (para consultas qualificadas) em uma consulta multiprovedor na sala limpa especificada. As consultas multiprovedor ainda estão ativadas para a sala limpa, mas cada solicitação agora deve ser explicitamente aprovada pelo provedor por meio da chamada de provider.process_multiprovider_request.

O status padrão para todas as salas limpas é que a aprovação automatizada multiprovedor está desativada. Para ativá-la, chame provider.resume_multiprovider_tasks.

Argumentos:

• cleanroom_name (cadeia de caracteres) – nome da sala limpa.

• consumer_account (cadeia de caracteres) – localizador de conta do consumidor cujas solicitações multiprovedor devem ser suspensas para todos os modelos nesta sala limpa. Solicitações posteriores deste usuário nesta sala limpa serão descartadas.

Retorna: (string) Mensagem de sucesso.

Exemplo:

CALL samooha_by_snowflake_local_db.provider.suspend_multiprovider_tasks(
  $cleanroom_name,
  $consumer_locator);

resume_multiprovider_tasks¶

Esquema:

PROVIDER

Descrição: ativa a revisão e aprovação automatizadas (para consultas qualificadas) de análises multiprovedor para o usuário especificado na sala limpa especificada. Por padrão, a revisão automatizada está desabilitada para uma sala limpa.

Para interromper a aprovação automatizada, chame provider.suspend_multiprovider_tasks.

Argumentos:

• cleanroom_name (cadeia de caracteres) – nome da sala limpa.

• consumer_account (cadeia de caracteres) – localizador de conta do consumidor cujas solicitações multiprovedor nesta sala limpa agora serão enfileiradas.

Retorna: (string) Mensagem de sucesso.

Exemplo:

CALL samooha_by_snowflake_local_db.provider.resume_multiprovider_tasks(
  $cleanroom_name,
  $consumer_locator);

set_activation_policy¶

Esquema:

PROVIDER

Descrição: define quais colunas do provedor podem ser utilizadas em um modelo de ativação. Somente colunas listadas em uma política de ativação podem ser ativadas a partir do conjunto de dados do provedor. A ausência de uma política de ativação impede a ativação de quaisquer dados do provedor.

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 de cadeias de caracteres) – somente as colunas listadas aqui podem ser utilizadas em um modelo de ativação nesta 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: (string) Mensagem de sucesso.

Exemplo:

CALL samooha_by_snowflake_local_db.provider.set_activation_policy('my_cleanroom', [
    'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:HASHED_EMAIL',
    'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:REGION_CODE' ]);

request_provider_activation_consent¶

Esquema:

PROVIDER

Descrição: envia uma solicitação ao consumidor para permitir que o provedor execute um modelo especificado e envie os resultados para a conta Snowflake do provedor. Em segundo plano, ele adiciona um modelo à lista de modelos de ativação de provedor na clean room. Quando um modelo é designado como um modelo de ativação, ele só pode ser usado em solicitações de ativação.

Argumentos:

• cleanroom_name (cadeia de caracteres) – sala limpa que contém o modelo de ativação.

• template_name (cadeia de caracteres) – nome do modelo de ativação para o qual solicitar aprovação. Esse modelo deve ter sido adicionado à sala limpa em uma chamada anterior. O nome do modelo deve começar com «activation».

Retorna: (string) Mensagem de sucesso.

Exemplo:

CALL samooha_by_snowflake_local_db.provider.request_provider_activation_consent(
    $cleanroom_name, 'activation_my_activation_template');

update_activation_warehouse¶

Esquema:

PROVIDER

Descrição: especifique qual tamanho de warehouse deve ser usado ao descriptografar os resultados na tabela de saída em uma ativação de provedor. O warehouse usado para descriptografia é DCR_ACTIVATION_WAREHOUSE. O provedor paga por esse warehouse.

Argumentos:

• size (cadeia de caracteres) – 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');

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. Isso é chamado somente quando você está implementando a ativação do provedor e você (o provedor) não tem a UI da sala limpa instalada. (Não importa se o consumidor tem ou não a UI instalada.)

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

Argumentos:

• frequency_minutes – (inteiro) com que frequência verificar novamente se há novos consumidores nesta sala limpa, 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);

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 desta sala limpa.

Retorna: (tabela): uma lista de solicitações de ativação com informações sobre cada um, incluindo o modelo e o nome do segmento, o status, o localizador da conta do consumidor e qualquer mensagem de erro retornada pela solicitação.

Exemplo:

CALL samooha_by_snowflake_local_db.dcr_health.provider_run_provider_activation_history(
  $cleanroom_name);

view_external_activation_history¶

Esquema:

LIBRARY

Descrição: exibe o histórico de solicitações de ativação na conta atual.

Argumentos: nenhum

Retorna: uma tabela com os detalhes e o status das solicitações de ativação.

Exemplo:

CALL samooha_by_snowflake_local_db.library.view_external_activation_history();

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 ativar análises executadas pelo provedor para modelos específicos na sala limpa. Depois disso, o provedor pode executar uma análise chamando provider.submit_analysis_request.

Learn more about provider-run analyses.

Argumentos:

• cleanroom_name (cadeia de caracteres) – nome da sala limpa que deve permitir a análise executada pelo provedor.

• consumer_accounts (matriz de cadeias de caracteres) – localizadores de todas as contas de consumidores que adicionaram dados a esta sala limpa.

Retorna: (string) Mensagem de sucesso.

Exemplo:

CALL samooha_by_snowflake_local_db.provider.enable_provider_run_analysis(
  $cleanroom_name,
  ['<CONSUMER_ACCOUNT_LOCATOR>']
);

disable_provider_run_analysis¶

Esquema:

PROVIDER

Descrição: impede que o provedor (criador da sala limpa) execute uma análise na sala limpa (está desativado por padrão).

Argumentos:

• cleanroom_name (cadeia de caracteres) – nome da sala limpa onde a análise executada pelo provedor deve ser desativada.

• consumer_account_locator (cadeia de caracteres) – mesma lista de nomes de contas de consumidor passada para provider.enable_provider_run_analysis.

Retorna: (string) Mensagem de sucesso.

Exemplo:

CALL samooha_by_snowflake_local_db.provider.disable_provider_run_analysis(
  $cleanroom_name,
  ['<CONSUMER_ACCOUNT_LOCATOR>']);

is_provider_run_enabled¶

Esquema:

LIBRARY

Descrição: verifica se essa sala limpa permite análises executadas pelo provedor.

Argumentos:

• cleanroom_name (cadeia de caracteres) – nome da sala limpa a ser verificada.

Retorna: (cadeia de caracteres) Se essa sala limpa permite ou não análises executadas pelo provedor.

Exemplo:

CALL samooha_by_snowflake_local_db.library.is_provider_run_enabled($cleanroom_name)

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 anteriormente e is_request_back_share_mounted falhar, é provável que você tenha adicionado este consumidor a esta sala limpa após a última chamada de provider.mount_request_logs_for_all_consumers.

Argumentos:

• cleanroom_name (cadeia de caracteres) – nome da sala limpa a ser verificada.

• consumer_account (cadeia de caracteres) – localizador de contas 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);

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 na chamada para consumer.enable_templates_for_provider_run.

Argumentos:

• cleanroom_name (cadeia de caracteres) – nome da sala limpa.

• template_name (cadeia de caracteres) – nome do modelo que o provedor deseja executar.

• consumer_account (cadeia de caracteres) – localizador de contas do consumidor que aprovará a solicitação de execução do provedor.

Retorna: uma tabela de tamanhos e tipos de warehouse permitidos. As cadeias de caracteres de tipo e tamanho de warehouse aceitas são aquelas utilizadas pelas propriedades WAREHOUSE_TYPE e WAREHOUSE_SIZE no comando CREATE WAREHOUSE.

Exemplo:

CALL samooha_by_snowflake_local_db.PROVIDER.VIEW_WAREHOUSE_SIZES_FOR_TEMPLATE(
  $cleanroom_name,
  $template_name,
  $consumer_account_loc);

submit_analysis_request¶

Esquema:

PROVIDER

Descrição: envia uma análise para ser executada na clean room. Todas as condições a seguir devem ser atendidas antes de chamar esse procedimento:

• O provedor deve ter ativado as análises executadas pelo provedor nesta sala limpa.

• O consumidor deve ter aprovado as análises executadas pelo provedor para o modelo especificado.

• Todas as políticas de join) e column) nos dados do consumidor e no modelo devem ser respeitadas.

O modelo é executado dentro da sala limpa e os resultados são armazenados com segurança dentro da sala limpa. Os resultados são criptografados para que somente o provedor possa vê-los.

Argumentos:

• cleanroom_name (cadeia de caracteres) – nome da sala limpa onde o modelo deve ser executado.

• consumer_account_locator (cadeia de caracteres) – localizador de conta do consumidor nesta sala limpa que permitiu as análises executadas pelo provedor por meio da chamada de consumer.enable_templates_for_provider_run.

• template_name (cadeia de caracteres) – nome do modelo a ser executado.

• provider_tables (matriz) – lista de tabelas de provedores a serem expostas ao modelo. Essa lista preencherá a variável de matriz source_table.

• consumer_tables (matriz) – lista de tabelas de consumidores 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 utilizado no modelo que você criou. Se você quiser usar um tipo e tamanho de warehouse específicos, escolha um tipo e tamanho listados por provider.view_warehouse_sizes_for_template e especifique-os usando os seguintes campos:

  • warehouse_type (cadeia de caracteres) – um tipo de warehouse compatível com o consumidor para análises executadas pelo provedor com o modelo especificado.

  • warehouse_size (cadeia de caracteres) – um tamanho de warehouse compatível com o consumidor para análises executadas pelo provedor com o modelo especificado.

Retorna: (cadeia de caracteres) um ID de solicitação que é usado para verificar o status da solicitação e também para acessar os resultados. Salve esse ID porque você precisará dele para ver os resultados da análise.

Exemplo:

CALL samooha_by_snowflake_local_db.provider.submit_analysis_request(
  $cleanroom_name,
  '<CONSUMER_ACCOUNT>',
  'prod_overlap_analysis',
  ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS'],
  ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS'],
  object_construct(
    'dimensions', ['c.REGION_CODE'],
    'measure_type', ['AVG'],
    'measure_column', ['c.DAYS_ACTIVE'],
    'warehouse_type', 'STANDARD',        -- If this type and size pair were not listed by view_warehouse_sizes_for_template,
    'warehouse_size', 'LARGE'            -- the request will automatically fail.
  )
);

check_analysis_status¶

Esquema:

PROVIDER

Descrição: o provedor chama esse procedimento para verificar o status da solicitação de análise do provedor. Pode haver um atraso significativo antes que você possa começar a ver o status de uma solicitação. Quando uma análise for marcada como concluída, chame provider.get_analysis_result para ver os resultados.

Todos os consumidores na sala limpa devem ter os próprios logs de solicitação montados antes que você possa chamar check_analysis_status. Isso é feito uma vez por consumidor por sala limpa, chamando provider.mount_request_logs_for_all_consumers.

Você pode ver sua lista de solicitações de análise executando este comando SQL, em que cleanroom_name é o nome da sua sala limpa, com espaços substituídos por sublinhados.

SELECT * FROM SAMOOHA_CLEANROOM_<cleanroom_name>.ADMIN.PROVIDER_ANALYSIS_REQUESTS;

Argumentos:

• cleanroom_name (cadeia de caracteres) – nome da sala limpa em que 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 quem a solicitação foi enviada.

Retorna: (cadeia de caracteres) status da solicitação, em que COMPLETED significa que a análise foi concluída com sucesso. 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 o 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.

Erros:

Se você vir o erro «ResultSet está vazio ou não preparado», isso pode indicar que os logs de solicitação não foram montados para pelo menos um consumidor nesta sala limpa. Chame provider.mount_request_logs_for_all_consumers para montar os logs de solicitação para todos os consumidores.

Exemplo:

-- It can take up to 2 minutes for this to pick up the request ID after the initial request
CALL samooha_by_snowflake_local_db.provider.check_analysis_status(
  $cleanroom_name,
  $request_id,
  '<CONSUMER_ACCOUNT>'
);

get_analysis_result¶

Esquema:

PROVIDER

Descrição: obtém os resultados de uma análise executada pelo provedor. Não chame get_analysis_result até que provider.check_analysis_status retorne 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 de 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
);

view_consumers¶

Esquema:

PROVIDER

Descrição: lista os consumidores que têm acesso à sala limpa. Ele não mostra se um consumidor instalou a sala limpa.

Argumentos:

• cleanroom_name (cadeia de caracteres) – a sala limpa de interesse.

Retorna: (tabela) – Lista de contas de consumidores que podem acessar a sala limpa.

Exemplo:

CALL samooha_by_snowflake_local_db.provider.view_consumers($cleanroom_name);

add_consumers¶

Esquema:

PROVIDER

Descrição: concede aos usuários especificados acesso à sala limpa indicada. A sala limpa pode ser acessada tanto pela UI quanto pela API de salas limpas. Isso não substitui as listas de consumidores das chamadas anteriores. O acesso à sala limpa é concedido a um usuário específico, não a uma conta inteira. A conta do consumidor deve estar na mesma região Snowflake que o provedor para poder acessar uma sala limpa. Você pode verificar sua região chamando select current_region();.

Você pode 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, conforme contido em consumer_account_names.

• consumer_account_names (cadeia de caracteres) – uma lista delimitada por vírgulas de IDs de contas de compartilhamento de dados do consumidor para o consumidor no formato org_name.account_name. O 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 (booleano, opcional) – TRUE para impor privacidade diferencial em todas as consultas dos usuários listados nesta sala limpa. Esta é 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 nesta sala limpa para ativar a privacidade diferencial. O padrão é FALSE.

• privacy_settings (cadeia de caracteres, opcional) – se presente, aplica as configurações de privacidade a modelos personalizados quando utilizados ​​por qualquer um dos usuários em consumer_account_names. Esta é 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 enable_differential_privacy_tasks e privacy_settings ao mesmo tempo. A tarefa de privacidade diferencial deve estar em execução nesta sala limpa para ativar a privacidade diferencial. Consulte os campos disponíveis para este objeto.

Retorna: mensagem de sucesso. Observe que o procedimento não valida os localizadores de usuário ou os nomes de conta, portanto, o sucesso indica apenas que os localizadores enviados foram adicionados ao banco de dados dessa sala limpa.

Exemplos:

-- Add consumer without differential privacy.
CALL samooha_by_snowflake_local_db.provider.add_consumers($cleanroom_name,
  'LOCATOR1,LOCATOR2',
  'ORG1.NAME1,ORG2.NAME2');

-- Add consumer and turn on differential privacy for all their queries.
CALL samooha_by_snowflake_local_db.provider.add_consumers($cleanroom_name,
  'LOCATOR1',
  'ORGNAME.ACCOUNTNAME',
  '{
    "null": {
        "threshold_value": 5000,
        "differential": 1,
        "privacy_budget": 10,
        "epsilon": 0.1,
        "noise_mechanism": "Laplace"
    }
  }'
);

remove_consumers¶

Esquema:

PROVIDER

Descrição: remove o acesso da conta a uma determinada sala limpa. Esse método bloqueia o acesso de todos os usuários nas contas fornecidas.

Você pode 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.

Exemplo:

CALL samooha_by_snowflake_local_db.provider.remove_consumers(
  $cleanroom_name,
  'locator1,locator2,locator3'
);

set_cleanroom_ui_accessibility¶

Esquema:

PROVIDER

Descrição: mostra ou oculta a sala limpa na UI de salas limpas para todos os usuários conectados a essa conta de provedor.

Argumentos:

• cleanroom_name (cadeia de caracteres) – o nome da sala limpa.

• visibility_status (cadeia de caracteres) – um dos seguintes valores que diferenciam maiúsculas de minúsculas:

  • HIDDEN: oculta a sala limpa 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: (string) Mensagem de sucesso.

Exemplo:

CALL samooha_by_snowflake_local_db.provider.set_cleanroom_ui_accessibility(
  $cleanroom_name,
  'HIDDEN'
);

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.

Argumentos: nenhum

Retorna: (string) Mensagem de sucesso.

Exemplo:

USE ROLE ACCOUNTADMIN;
CALL samooha_by_snowflake_local_db.library.enable_laf_on_account();

disable_laf_on_account¶

Esquema:

LIBRARY

Descrição: desabilita o preenchimento automático entre nuvens na conta atual. A execução desse procedimento requer a função ACCOUNTADMIN.

Argumentos: nenhum

Retorna: (string) Mensagem de sucesso.

Exemplo:

USE ROLE ACCOUNTADMIN;
CALL samooha_by_snowflake_local_db.library.disable_laf_on_account();

is_laf_enabled_on_account¶

Esquema:

LIBRARY

Descrição: retorna se o preenchimento automático entre nuvens está ativado para essa conta.

Argumentos: nenhum

Retorna: TRUE se o preenchimento automático entre nuvens estiver ativado para essa conta, FALSE caso contrário.

Exemplo:

CALL samooha_by_snowflake_local_db.library.is_laf_enabled_on_account();

set_laf_dcr_refresh_schedule¶

Esquema:

PROVIDER

Descrição: define o intervalo de atualização para 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 você precisar de uma atualização imediata, chame SYSTEM$TRIGGER_LISTING_REFRESH.

Argumentos:

• schedule (Int) – 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);

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.

Se você deseja carregar vários pacotes Python chamáveis ​​em uma sala limpa em um único patch, chame prepare_python_for_cleanroom.

Learn how to upload and use Python code in a clean room.

Esse procedimento aumenta o número do patch de sua sala limpa e aciona uma verificação de segurança. Você deve aguardar que o status da verificação seja APPROVED antes de poder compartilhar a versão mais recente com os colaboradores. Essa etapa não relata erros de sintaxe no código, que são gerados em tempo de execução.

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:

(cleanroom_name String, function_name String, arguments Array, packages Array, rettype String, handler String, code String)

(cleanroom_name String, function_name String, arguments Array, packages Array, imports Array, rettype String, handler String)

Retorna: (cadeia de caracteres) mensagem de sucesso se o upload for bem-sucedido.

Exemplos:

-- Inline UDF

CALL samooha_by_snowflake_local_db.provider.load_python_into_cleanroom(
    $cleanroom_name,
    'assign_group',                      -- Name of the UDF.
    ['data STRING', 'index INTEGER'],    -- Arguments of the UDF, along with their type.
    ['pandas', 'numpy'],                 -- Packages UDF will use.
    'INTEGER',                           -- Return type of UDF.
    'main',                              -- Handler.
    $$
import pandas as pd
import numpy as np

def main(data, index):
    df = pd.DataFrame(data)  # you can do something with df but this is just an example
    return np.random.randint(1, 100)
    $$
);

-- Upload from stage

CALL samooha_by_snowflake_local_db.provider.load_python_into_cleanroom(
    $cleanroom_name,
    'myfunc',                            -- Name of the UDF.
    ['data STRING', 'index INTEGER'],    -- Arguments of the UDF.
    ['numpy', 'pandas'],                 -- Packages UDF will use.
    ['/assign_group.py'],                -- Python file to import from a stage.
    'INTEGER',                           -- Return type of UDF.
    'assign_group.main'                  -- Handler, scoped to file name.
);

prepare_python_for_cleanroom¶

Esquema:

PROVIDER

Descrição: carrega código Python personalizado na sala limpa como parte de um fluxo de upload de código em massa. Chame esse procedimento várias vezes para carregar vários pacotes e, em seguida, chame load_prepared_python_into_cleanroom para acionar o upload para a sala limpa especificada, liberar o pool de código preparado e gerar um novo patch para a sala limpa.

O código carregado pode ser chamado pelo seu modelo Jinja. Para enviar apenas um único pacote Python, você pode chamar load_python_into_cleanroom.

Learn how to upload and use Python code in a clean room.

Você pode passar o código diretamente para esse procedimento usando o parâmetro code ou passar o nome de um arquivo em uma área de preparação que contém o código usando o parâmetro imports.

Argumentos:

• cleanroom_name (cadeia de caracteres) – nome da sala limpa em que 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 delimitados por espaços) – uma matriz de argumentos exigida pela função function_name. Cada elemento é um par 'name  data_type' delimitado por espaços 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 todos os nomes de pacotes Python utilizados ​​pelo código. As salas limpas aceitam nativamente todos os pacotes nesta lista ou a API Snowpark. Se você precisar de um pacote não listado lá, use o Snowpark Container Services em uma sala limpa.

• imports (matriz de cadeias de caracteres) – lista de arquivos de origem Python, ao importar seu código-fonte de uma área de preparação. Cada endereço de arquivo é relativo à área de preparação para a qual você carregou o código, por exemplo: ['/my_func.py']. Encontre a área de preparação da sala limpa chamando provider.get_stage_for_python_files. Se você estiver fornecendo código em linha usando o parâmetro code, forneça uma matriz vazia.

• rettype (cadeia de caracteres) – tipo de dado SQL do valor retornado pela função handler. (Consulte alguns tipos Python e SQL equivalentes. Sinônimos do tipo SQL do Snowflake são aceitos, como STRING para VARCHAR.) Para um UDF, o tipo de retorno é um único tipo SQL. Para um UDTF, o tipo de retorno é uma função TABLE com pares <column name> <SQL column type>. Por exemplo:

  TABLE (item_name STRING, total FLOAT)

• handler (cadeia de caracteres) – a função chamada em seu código quando um modelo chama function_name. Para um UDF, este deve ser o próprio nome da função; para um UDTF, este deve ser o nome da classe que implementa o UDTF.

• code (cadeia de caracteres) – seu código Python como uma cadeia de caracteres. Deve ser um UDF ou UDTF do Python. Se você estiver enviando o código de uma área de preparação, ele deve ser uma cadeia de caracteres vazia.

Retorna: (cadeia de caracteres) resumo da solicitação de upload, incluindo o número do patch antes do código ser adicionado à sala limpa.

Exemplo:

Este exemplo carrega dois procedimentos Python simples em uma sala limpa e aciona apenas uma geração de patch.

CALL samooha_by_snowflake_local_db.provider.prepare_python_for_cleanroom(
    $cleanroom_name,
    'get_next_status',  -- Name of the UDF. Can be different from the handler.
    ['status VARCHAR'], -- Arguments of the UDF, specified as (variable name, SQL type).
    ['numpy'],          -- Packages needed by UDF.
    [],                 -- When providing the code inline, this is an empty array.
    'VARCHAR',          -- Return type of UDF.
    'get_next_status',  -- Handler.
    $$
import numpy as np
def get_next_status(status):
  """Return the next higher status, or a random status
  if no matching status found or at the top of the list."""

  statuses = ['MEMBER', 'SILVER', 'GOLD', 'PLATINUM', 'DIAMOND']
  try:
    return statuses[statuses.index(status.upper()) + 1]
  except:
    return 'NO MATCH'
    $$
);

 CALL samooha_by_snowflake_local_db.provider.prepare_python_for_cleanroom(
    $cleanroom_name,
    'hello_world',  -- Name of the UDF.
    [],
    [],
    [],
    'VARCHAR',
    'hello_world',
    $$
import numpy as np
def hello_world():
  return 'Hello world!'
    $$
);

CALL samooha_by_snowflake_local_db.provider.load_prepared_python_into_cleanroom($cleanroom_name);

load_prepared_python_into_cleanroom¶

Esquema:

PROVIDER

Descrição: pega todo o código preparado usando chamadas anteriores para prepare_python_for_cleanroom, executa uma verificação de segurança no código e, se a verificação for bem-sucedida, faz upload do código para a sala limpa e gera um novo patch para a sala limpa. Para fornecer essa versão da sala limpa aos usuários, atualize a diretiva de lançamento da sala limpa para o número do patch retornado por esse procedimento chamando set_default_release_directive. Independentemente de a chamada ser bem-sucedida ou não, ela libera o conjunto de código Python armazenado em chamadas anteriores para prepare_python_for_cleanroom. Essa etapa não relata erros de sintaxe, que são relatados apenas quando você tenta executar seu código.

Argumentos:

• cleanroom_name (cadeia de caracteres) – nome da sala limpa para onde você deseja fazer upload do código Python.

Retorna: (cadeia de caracteres) se bem-sucedido, retorna o novo número do patch criado. Atualize a diretiva de lançamento da sala limpa para o número do patch retornado por esse procedimento chamando set_default_release_directive.

Exemplo:

CALL samooha_by_snowflake_local_db.provider.load_prepared_python_into_cleanroom($cleanroom_name);

get_stage_for_python_files¶

Esquema:

PROVIDER

Descrição: retorna o caminho da área de preparação para onde os arquivos Python devem ser enviados, caso você planeje usar arquivos de código enviados para uma área de preparação em vez de definições de código em linha para definir código Python personalizado em uma sala limpa. A área de preparação não existe e não pode ser examinada até que os arquivos sejam enviados chamando provider.load_python_into_cleanroom.

Learn how to upload and use Python code in a clean room.

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 enviar os arquivos de código. Use isso para o argumento imports em provider.load_python_into_cleanroom.

Exemplo:

CALL samooha_by_snowflake_local_db.provider.get_stage_for_python_files($cleanroom_name);

view_cleanroom_scan_status¶

Esquema:

PROVIDER

Descrição: informa o status da varredura de ameaças para uma sala limpa com DISTRIBUTION definido como EXTERNAL. A varredura precisa ser marcada como «APPROVED» antes que você possa definir ou alterar a diretiva de lançamento padrão. O status da varredura precisa ser verificado somente com as salas limpas EXTERNAL.

Uma verificação é executada após qualquer ação que gere uma nova versão de patch; mais comumente, isso ocorre após a primeira publicação da sala limpa ou após o upload do Python para a sala limpa. O Snowflake Data Clean Rooms usa a estrutura de verificação de segurança do aplicativo Snowflake nativo.

Argumentos:

• cleanroom_name (cadeia de caracteres) – nome da sala limpa cujo status deve ser verificado.

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 revisão manual pelo 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);

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 para a qual serão montados os logs de solicitação.

Retorna: (tabela) uma tabela de consumidores, com o status de montagem do log de solicitações de cada um. Se um consumidor recebeu acesso a uma sala limpa, mas ainda não a instalou, o status é descrito como pendente e você deve chamar mount_request_logs_for_all_consumers novamente após a instalação.

Exemplo:

CALL samooha_by_snowflake_local_db.provider.mount_request_logs_for_all_consumers($cleanroom_name);

view_request_mount_status_for_all_consumers¶

Esquema:

PROVIDER

Descrição: mostra o status de montagem dos logs de solicitações para todos os consumidores na sala limpa especificada. Somente consumidores que foram incluídos em uma chamada para provider.mount_request_logs_for_all_consumers são exibidos. Os logs de solicitações permitem que as mensagens sejam passadas do consumidor para o provedor.

Argumentos:

• cleanroom_name (cadeia de caracteres) – nome da sala limpa.

Retorna: (tabela): uma tabela de consumidores e o status de montagem do log de solicitações de cada consumidor.

Exemplo:

CALL samooha_by_snowflake_local_db.provider.view_request_mount_status_for_all_consumers($cleanroom_name);

view_request_logs¶

Esquema:

PROVIDER

Descrição: mostra os logs das solicitações enviadas pelos consumidores nesta sala limpa. Somente as solicitações de consumidores que foram incluídos em uma chamada anterior bem-sucedida para mount_request_logs_for_all_consumers são exibidas.

Argumentos:

• cleanroom_name (cadeia de caracteres) – nome da sala limpa para a qual serão revisados ​​os logs de solicitação.

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

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 (cadeia de caracteres) – nome da sala limpa.

• consumer_account_locator (cadeia de caracteres) – 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 diferencial para um ou mais modelos. As configurações são aplicadas a todos os modelos executados pelo consumidor especificado. Consulte os campos disponíveis para esse objeto.

Retorna: mensagem de sucesso.

Exemplo:

-- Enforce differential privacy on queries by this consumer
-- with the settings provided.
CALL samooha_by_snowflake_local_db.provider.set_privacy_settings(
  $cleanroom_name,
  $consumer_locator,
  { 'differential': 1,
    'epsilon': 0.1,
    'privacy_budget': 3 });

is_dp_enabled_on_account¶

Esquema:

PROVIDER

Descrição: descreve se a privacidade diferencial está ou não ativada para essa conta.

Argumentos: nenhum

Retorna: TRUE se a privacidade diferencial estiver ativada para essa conta, FALSE caso contrário.

Exemplo:

CALL samooha_by_snowflake_local_db.provider.is_dp_enabled_on_account();

suspend_account_dp_task¶

Esquema:

PROVIDER

Descrição: desabilita a tarefa que monitora e aplica orçamentos de privacidade diferencial. Isso é utilizado para controlar os custos associados à privacidade diferencial em sua conta. Se a tarefa de privacidade diferencial estiver desativada, o ruído ainda será adicionado às consultas por usuários, modelos ou salas limpas em que a privacidade diferencial for especificada, mas os limites de orçamento não serão aplicados e você não terá os custos da privacidade diferencial. Saiba mais sobre como gerenciar a privacidade diferencial.

Argumentos: nenhum

Retorna: (string) Mensagem de sucesso.

Exemplo:

CALL samooha_by_snowflake_local_db.provider.suspend_account_dp_task();

resume_account_dp_task¶

Esquema:

PROVIDER

Descrição: reinicia o ouvinte da tarefa de privacidade diferencial na conta atual, e os orçamentos de privacidade diferencial serão aplicados. Todos os valores diferenciais de privacidade definidos anteriormente (como sensibilidade ou usuários associados) são mantidos.

Argumentos: nenhum

Retorna: (string) Mensagem de sucesso.

Exemplo:

CALL samooha_by_snowflake_local_db.provider.resume_account_dp_task();

load_service_into_cleanroom¶

Esquema:

PROVIDER

Descrição: cria ou atualiza um serviço de contêiner em uma sala limpa. Chamar esse procedimento atualiza o número do patch da sala limpa; 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 sobre como usar o Snowpark Container Services em uma sala limpa.

Argumentos:

• cleanroom_name (cadeia de caracteres) – nome da sala limpa.

• service_spec (cadeia de caracteres) – uma especificação YAML para o serviço, com raiz no elemento spec.

• service_config (cadeia de caracteres) – uma configuração de formato YAML para o serviço. Há suporte para as seguintes propriedades:

  • default_service_options – uma matriz opcional de valores padrão de nível de serviço. Esses valores podem ser substituídos pelo consumidor que ele cria um serviço. As seguintes propriedades filhas são aceitas:

    • min_instances (inteiro, opcional)

    • max_instances (inteiro, opcional)

    • allow_monitoring (booleano, opcional) – se TRUE, permite que o consumidor veja os logs do serviço. O padrão é FALSE.

  • functions – uma matriz de funções expostas pelo serviço. Cada definição de função mapeia para a definição de função do serviço SPCS. Consulte a documentação para saber os detalhes de cada elemento. As seguintes propriedades filhas são aceitas:

    • name

    • args

    • returns

    • endpoint

    • path

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

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 provider ou consumer apropriada desse procedimento com o mesmo valor.

Argumentos:

• enable (booleano) – TRUE para ativar a tarefa, FALSE para desativá-la.

Retorna: mensagem de sucesso.

Exemplo:

-- Disable the task in this account.
CALL samooha_by_snowflake_local_db.provider.manage_datastats_task_on_account(FALSE);

enable_local_db_auto_upgrades¶

Esquema:

LIBRARY

Descrição: ativa a tarefa que atualiza automaticamente o ambiente do Snowflake Data Clean Rooms quando novos procedimentos ou funcionalidades são lançados (a tarefa é samooha_by_snowflake_local_db.admin.expected_version_task ). Chame este procedimento para automatizar as atualizações em vez de chamar library.apply_patch a cada nova versão.

Embora seja possível reduzir custos desativando essa tarefa, recomendamos deixá-la em execução para garantir que você tenha a versão mais recente do ambiente de salas limpas em seu sistema.

Argumentos: nenhum

Retorna: (string) Mensagem de sucesso.

Exemplo:

CALL samooha_by_snowflake_local_db.library.enable_local_db_auto_upgrades();

disable_local_db_auto_upgrades¶

Esquema:

LIBRARY

Descrição: desabilita a tarefa que atualiza automaticamente o ambiente Snowflake Data Clean Rooms quando novas versões são lançadas. Se você desativar as atualizações automáticas, deverá chamar library.apply_patch a cada nova versão.

Argumentos: nenhum

Retorna: (string) Mensagem de sucesso.

Exemplo:

CALL samooha_by_snowflake_local_db.library.disable_local_db_auto_upgrades();

apply_patch¶

Esquema:

LIBRARY

Descrição: atualiza seu ambiente de salas limpas habilitando novos recursos e correções em seu ambiente. Chame esse procedimento quando uma nova versão do ambiente de salas limpas for lançada. (Isso normalmente 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 patches chamando library.enable_local_db_auto_upgrades. Recomendamos habilitar as atualizações automáticas.

Argumentos: nenhum

Retorna: (string) Mensagem de sucesso.

Exemplo:

CALL samooha_by_snowflake_local_db.library.apply_patch();

patch_cleanroom¶

Esquema:

PROVIDER

Descrição: atualiza a sala limpa especificada para a versão mais recente habilitando novos recursos e correções na sala limpa. Normalmente, você chama esse procedimento somente quando é orientado pelo suporte Snowflake.

O provedor deve chamar library.patch_cleanroom antes que o consumidor chame library.patch_cleanroom. Caso contrário, não haverá patch para ser aplicado.

Argumentos:

• cleanroom_name (cadeia de caracteres): nome da sala limpa à qual o patch será aplicado.

Retorna: (string) Mensagem de sucesso.

Exemplo:

CALL samooha_by_snowflake_local_db.provider.patch_cleanroom($cleanroom_name);

dcr_health.dcr_tasks_health_check¶

Descrição: mostra informações sobre as tarefas de sala limpa em execução ou recém-interrompidas.

Argumentos: nenhum

Retorna: (tabela) informações sobre as tarefas de sala limpa, incluindo o cronograma, o nome e o tamanho do warehouse.

Exemplo:

CALL samooha_by_snowflake_local_db.dcr_health.dcr_tasks_health_check();

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: deixa as solicitações entre nuvens acessíveis para a sala limpa e a conta do consumidor fornecidas. provider.request_laf_cleanroom_requests deve retornar o status FULFILLED antes que você 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 (cadeia de caracteres) – sala limpa que é compartilhada.

• consumer_locator (cadeia de caracteres) – localizador da conta Snowflake do consumidor que fará solicitações entre nuvens nesta sala limpa.

Retorna: (string) Mensagem de sucesso.

Exemplo:

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

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 ativar 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 atingir FULFILLED, você poderá chamar provider.mount_laf_cleanroom_requests_share. Pode levar dez minutos para que o status atinja FULFILLED.

Argumentos:

• cleanroom_name (cadeia de caracteres) – nome da sala limpa para ativar o compartilhamento de solicitações entre nuvens.

• consumer_locator (cadeia de caracteres) – localizador da conta do consumidor para o qual ativar o compartilhamento de solicitações entre nuvens.

Retorna: (cadeia de caracteres) mensagem de status da solicitação: CREATED, PENDING, FULFILLED, FAILURE. “FAILURE, listagem não encontrada” significa que o consumidor não instalou a sala limpa (ou a desinstalou).

Exemplo:

CALL samooha_by_snowflake_local_db.provider.request_laf_cleanroom_requests(
  $cleanroom_name, $consumer_locator);

enable_laf_for_cleanroom (obsoleto)¶

Esquema:

PROVIDER

Essa função agora está obsoleta e sua funcionalidade é processada por provider.create_or_update_cleanroom_listing.

Descrição: ativa o preenchimento automático entre nuvens, que permite compartilhar a sala limpa com colaboradores cuja conta Snowflake esteja 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.

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 compartilhada 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: (string) Mensagem de sucesso.

Exemplo:

CALL samooha_by_snowflake_local_db.provider.enable_laf_for_cleanroom($cleanroom_name);

view_ui_registration_request_log – DEPRECATED¶

Esquema:

PROVIDER

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 utilizado 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: (string) Mensagem de sucesso.

Exemplo:

CALL samooha_by_snowflake_local_db.provider.view_ui_registration_request_log();

register_table_or_view – obsoleto¶

Esquema:

LIBRARY

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: (string) Mensagem de sucesso.

Exemplos

Para registrar uma tabela:

CALL samooha_by_snowflake_local_db.library.register_table_or_view(
    ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS'],
    false,
    false,
    false,
    false);

Para registrar uma tabela Iceberg:

CALL samooha_by_snowflake_local_db.library.register_table_or_view(
        ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS'],
        false,
        true,
        false,
        false);

register_table – obsoleto¶

Esquema:

LIBRARY

Descrição: semelhante a register_db, mas opera em nível de tabela. Conceda o privilégio SELECT nesta tabela à função SAMOOHA_APP_ROLE, permitindo que o usuário vincule a tabela à sala limpa.

Se você quiser registrar tabelas em um esquema de acesso gerenciado (ou seja, um esquema criado usando o parâmetro WITH MANAGED ACCESS), use library.register_managed_access_table.

Argumentos: table_name (array)

Retorna: (string) Mensagem de sucesso.

Exemplo:

CALL samooha_by_snowflake_local_db.library.register_table(['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);

register_managed_access_table – obsoleto¶

Esquema:

LIBRARY

Descrição: semelhante a register_table, mas registra tabelas em um esquema 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: (string) Mensagem de sucesso.

Exemplo:

CALL samooha_by_snowflake_local_db.library.register_managed_access_table(['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);

register_view – obsoleto¶

Esquema:

LIBRARY

Descrição: semelhante a register_db, mas opera em nível de exibição. Uma matriz ou cadeia de caracteres representando o nome da exibição totalmente qualificado pode ser passada, e seleções de concessão para a função SAMOOHA_APP_ROLE são feitas, permitindo que o usuário link a exibição à sala limpa.

Se você deseja 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: (string) Mensagem de sucesso.

Exemplo:

CALL samooha_by_snowflake_local_db.library.register_view(['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);

register_managed_access_view – obsoleto¶

Esquema:

LIBRARY

Descrição: semelhante a register_view, mas registra exibições em um esquema 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: (string) Mensagem de sucesso.

Exemplo:

CALL samooha_by_snowflake_local_db.library.register_managed_access_view(['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);

unregister_table_or_view – obsoleto¶

Esquema:

LIBRARY

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: (string) Mensagem de sucesso.

Exemplos

Para cancelar o registro de uma tabela:

CALL samooha_by_snowflake_local_db.library.unregister_table_or_view(
  ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS'],
  false,
  false,
  false,
  false);

unregister_table – obsoleto¶

Esquema:

LIBRARY

Descrição: semelhante a unregister_db, mas opera em nível de tabela. Uma matriz ou cadeia de caracteres representando o nome da tabela totalmente qualificado pode ser passada para cancelar o registro das tabelas. Os usuários não podem vincular tabelas não registradas a uma sala limpa.

Se você quiser cancelar o registro de tabelas em um esquema de acesso gerenciado (ou seja, um esquema criado usando o parâmetro WITH MANAGED ACCESS), use library.unregister_managed_access_table.

Argumentos: table_name (array)

Retorna: (string) Mensagem de sucesso.

Exemplo:

CALL samooha_by_snowflake_local_db.library.unregister_table(['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);

unregister_managed_access_table – obsoleto¶

Esquema:

LIBRARY

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: (string) Mensagem de sucesso.

Exemplo:

CALL samooha_by_snowflake_local_db.library.unregister_managed_access_table(['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);

unregister_view – obsoleto¶

Esquema:

LIBRARY

Descrição: semelhante a unregister_db, mas opera em nível de exibição. Uma matriz ou cadeia de caracteres representando o nome de exibição totalmente qualificado pode ser passada para cancelar o registro das exibições. Os usuários não podem vincular exibições não registradas a uma sala limpa.

Se você quiser cancelar o registro de exibições em um esquema de acesso gerenciado (ou seja, um esquema criado usando o parâmetro WITH MANAGED ACCESS), use library.unregister_managed_access_view.

Argumentos: view_name (array)

Retorna: (string) Mensagem de sucesso.

Exemplo:

CALL samooha_by_snowflake_local_db.library.unregister_view(['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);

unregister_managed_access_view – obsoleto¶

Esquema:

LIBRARY

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: (string) Mensagem de sucesso.

Exemplo:

CALL samooha_by_snowflake_local_db.library.unregister_managed_access_view(['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);

create_cleanroom_listing – obsoleto¶

Esquema:

PROVIDER

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 do URL da conta dele. 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.

Argumentos: cleanroom_name (cadeia de caracteres), consumer_account_name (cadeia de caracteres)

Retorna: (string) Mensagem de sucesso.

Exemplo:

CALL samooha_by_snowflake_local_db.provider.create_cleanroom_listing($cleanroom_name, <consumerorg.consumeracct>);

register_cleanroom_in_ui – DEPRECATED¶

Esquema:

PROVIDER

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: (string) Mensagem de sucesso.

Exemplo:

CALL samooha_by_snowflake_local_db.provider.register_cleanroom_in_ui($cleanroom_name, 'prod_custom_template', <CONSUMER ACCOUNT LOCATOR>, <USER_EMAIL>)