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

O conteúdo a seguir detalha todos as APIs de desenvolvedor fornecidas pelas Snowflake Data Clean Rooms para consumidores. Todas as funções residem dentro do seguinte esquema:

samooha_by_snowflake_local_db.consumer
Copy

Configuração do ambiente

Execute os seguintes comandos para configurar o ambiente Snowflake antes de usar as APIs de desenvolvedor para trabalhar com uma Snowflake Data Clean Room. Se você não tiver a função SAMOOHA_APP_ROLE, entre em contato com o administrador de sua conta.

use role samooha_app_role;
use warehouse app_wh;
Copy

Atribua um nome para a sala limpa que o provedor compartilhou com você:

set cleanroom_name = 'Test Cleanroom 1';
Copy

Instalação da sala limpa

Instale a sala limpa que o provedor compartilhou por meio dos seguintes comandos:

consumidor.install_cleanroom

Descrição: Instala a sala limpa na conta do consumidor com o provedor associado e a sala limpa selecionada.

Argumentos: cleanroom_name (string), provider_account_locator (string)

Retorna: mensagem de sucesso (string)

Exemplo:

call samooha_by_snowflake_local_db.consumer.install_cleanroom($cleanroom_name, '<PROVIDER_ACCOUNT_LOCATOR>');
Copy

consumer.is_enabled

Descrição: Após a instalação da sala limpa, o provedor leva cerca de 1 minuto para concluir a configuração e habilitá-la. Esta função permite ao usuário verificar o status da sala limpa e ver se ela está habilitada ou não. O sinalizador geralmente muda para Verdadeiro cerca de 1 minuto após a instalação da sala limpa.

Argumentos: cleanroom_name (string)

Retorna: está ativado (boolean)

Exemplo:

call samooha_by_snowflake_local_db.consumer.is_enabled($cleanroom_name);
Copy

consumer.uninstall_cleanroom

Descrição: Desinstala a sala limpa na conta do consumidor. Isso remove todos os bancos de dados associados à sala limpa, incluindo o banco de dados da sala limpa compartilhada. Observe que a sala limpa sempre pode ser instalada novamente com consumer.install_cleanroom.

Argumentos: cleanroom_name (string)

Retorna: mensagem de sucesso (string)

Exemplo:

call samooha_by_snowflake_local_db.consumer.uninstall_cleanroom($cleanroom_name);
Copy

Configuração da análise de execução do provedor

library.is_provider_run_enabled

Descrição: Verifica se esta sala limpa tem Provider Run Analysis habilitado. Observação: a aprovação explícita ainda precisa ser dada chamando consumer.enable_templates_for_provider_run (consulte abaixo).

Argumentos: cleanroom_name (string)

Retorna: mensagem ativada (string)

Exemplo:

call samooha_by_snowflake_local_db.library.is_provider_run_enabled($cleanroom_name)
Copy

biblioteca.is_consumer_run_enabled

Descrição: Verifica se esta sala limpa tem Consumer Run Analysis habilitado. Este sinalizador determina se o consumidor da sala limpa (instalador) pode executar análises ou atuar como um colaborador de dados.

Argumentos: cleanroom_name (string)

Retorna: mensagem ativada (string)

Exemplo:

call samooha_by_snowflake_local_db.library.is_consumer_run_enabled($cleanroom_name)
Copy

consumer.enable_templates_for_provider_run

Descrição: Se uma sala limpa tiver Provider Run Analysis habilitado (ou seja, o provedor da sala limpa marcou a sala limpa para permitir que os provedores executem a análise), este procedimento deve ser chamado pelo consumidor para habilitá-lo. Este procedimento é necessário para conceder aprovação explícita, modelo por modelo, aos provedores que desejam executar análises.

O parâmetro booliano final permite que o consumidor habilite a privacidade diferencial para as análises do provedor, se definido como TRUE.

Argumentos:

  • cleanroom_name (string) – Nome da sala limpa.

  • template_names (matriz de cadeias de caracteres) – Uma matriz de um ou mais modelos na sala limpa que deve ser habilitada para análise do provedor

  • enable_differential_privacy(booliano) – Se TRUE, habilite a privacidade diferencial para todos os modelos listados em template_names. A privacidade diferencial pode ser ativada para esses modelos somente se a ela estiver ativada para a própria sala limpa. É possível verificar o status de privacidade diferencial de uma sala limpa chamando consumer.is_dp_enabled.

Retorna: mensagem de sucesso (string)

Exemplo:

call samooha_by_snowflake_local_db.consumer.enable_templates_for_provider_run($cleanroom_name, ['prod_overlap_analysis'], FALSE);
Copy

Registro e cancelamento de registro de dados

Use o comando a seguir para registrar e cancelar o registro de bancos de dados, esquemas e objetos. Tabelas e exibições devem ser registradas antes de poderem ser vinculadas à sala limpa. Se você registrar um banco de dados ou esquema, todos os objetos naquele banco de dados ou esquema serão registrados.

consumer.register_db

Descrição: Ao adicionar um banco de dados à sala limpa, você pode vincular qualquer conjunto de dados do banco de dados. Se não for chamado, as concessões terão que ser feitas para samooha_app_role individualmente.

Argumentos: db_name (string)

Retorna: mensagem de sucesso (string)

Exemplo:

call samooha_by_snowflake_local_db.consumer.register_db('SAMOOHA_SAMPLE_DATABASE');
Copy

library.register_schema

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

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

Argumentos: schema_name (array)

Retorna: mensagem de sucesso (string)

Exemplo:

call samooha_by_snowflake_local_db.library.register_schema(['SAMOOHA_SAMPLE_DATABASE.DEMO']);
Copy

library.register_managed_access_schema

Descrição: semelhante a register_schema, mas registra um esquema que foi criado com o parâmetro WITH MANAGED ACCESS. Uma matriz ou cadeia de caracteres representando o nome do esquema totalmente qualificado pode ser passado, e seleções de concessão para a função SAMOOHA_APP_ROLE são feitas, permitindo que o usuário vincule os objetos no esquema à sala limpa.

Argumentos: schema_name (array)

Retorna: mensagem de sucesso (string)

Exemplo:

call samooha_by_snowflake_local_db.library.register_managed_access_schema(['SAMOOHA_SAMPLE_DATABASE.DEMO']);
Copy

library.register_objects

Descrição: concede à sala limpa acesso a tabelas e exibições de todos os tipos, tornando-as disponíveis para serem vinculadas à sala limpa por meio da chamada de consumer.link_datasets. É possível registrar grupos mais amplos de objetos chamando library.register_schema, library.register_managed_access_schema ou consumer.register_db.

Argumentos:

  • object_names (array) – Matriz de nomes de objeto totalmente qualificados. Esses objetos podem então ser conectados à sala limpa.

Retorna: mensagem de sucesso (string)

Exemplos

Para registrar uma tabela e uma exibição:

call samooha_by_snowflake_local_db.library.register_objects(
    ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS','SAMOOHA_SAMPLE_DATABASE.INFORMATION_SCHEMA.FIELDS']);
Copy

library.register_table_or_view – Obsoleto

Atenção

Esse comando está obsoleto. Use library.register_objects.

Descrição: registra tabelas e exibições de todos os tipos.

Argumentos: object_names (array), is_view (boolean), is_iceberg (boolean), is_external (boolean), is_under_managed_access_schema (boolean)

Saída mensagem de sucesso (string)

Exemplos

Para registrar uma tabela:

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

Para registrar uma tabela Iceberg:

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

library.register_table – Obsoleto

Atenção

Esse comando está obsoleto. Use library.register_objects.

Descrição: Semelhante a register_db, mas opera ao nível de tabela. Uma matriz ou cadeia de caracteres representando o nome da tabela totalmente qualificado pode ser passada, e serão concedidos privilégios de seleção à função SAMOOHA_APP_ROLE são criadas, permitindo que o usuário vincule a tabela à sala limpa.

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

Argumentos: table_name (array)

Retorna: mensagem de sucesso (string)

Exemplo:

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

library.register_managed_access_table – Obsoleto

Atenção

Esse comando está obsoleto. Use library.register_objects.

Descrição: semelhante a register_table, mas registra tabelas que foram criadas com o parâmetro WITH MANAGED ACCESS. Uma matriz ou cadeia de caracteres representando o nome da tabela totalmente qualificado pode ser passada, e serão concedidos privilégios de seleção à função SAMOOHA_APP_ROLE são criadas, permitindo que o usuário vincule a tabela à sala limpa.

Argumentos: table_name (array)

Retorna: mensagem de sucesso (string)

Exemplo:

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

library.register_view – Obsoleto

Atenção

Esse comando está obsoleto. Use library.register_objects.

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

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

Argumentos: view_name (array)

Retorna: mensagem de sucesso (string)

Exemplo:

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

library.register_managed_access_view – Obsoleto

Atenção

Esse comando está obsoleto. Use library.register_objects.

Descrição: semelhante a register_view, mas registra exibições que foram criadas com o parâmetro WITH MANAGED ACCESS. Uma matriz ou cadeia de caracteres representando o nome da exibição totalmente qualificado pode ser passada, e seleções de concessão para a função SAMOOHA_APP_ROLE são feitas, permitindo que o usuário link a exibição à sala limpa.

Argumentos: view_name (array)

Retorna: mensagem de sucesso (string)

Exemplo:

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

library.unregister_db

Descrição: Inverte o procedimento register_db e remove as concessões ao nível de banco de dados concedidas à função SAMOOHA_APP_ROLE e ao aplicativo nativo de Snowflake Data Clean Room. Isso também remove qualquer banco de dados do menu suspenso de UI.

Argumentos: db_name (string)

Retorna: mensagem de sucesso (string)

Exemplo:

call samooha_by_snowflake_local_db.library.unregister_db('SAMOOHA_SAMPLE_DATABASE');
Copy

library.unregister_schema

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

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

Argumentos: schema_name (array)

Retorna: mensagem de sucesso (string)

Exemplo:

call samooha_by_snowflake_local_db.library.unregister_schema(['SAMOOHA_SAMPLE_DATABASE.DEMO']);
Copy

library.unregister_managed_access_schema

Descrição: semelhante a unregister_schema, mas cancela o registro em um esquema que foi criado com o parâmetro WITH MANAGED ACCESS.

Argumentos: schema_name (array)

Retorna: mensagem de sucesso (string)

Exemplo:

call samooha_by_snowflake_local_db.library.unregister_managed_access_schema(['SAMOOHA_SAMPLE_DATABASE.DEMO']);
Copy

library.unregister_objects

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

Argumentos:

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

Retorna: mensagem de sucesso (string)

Exemplos

Para cancelar o registro de uma tabela e de uma exibição:

call samooha_by_snowflake_local_db.library.unregister_objects(
    ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS','SAMOOHA_SAMPLE_DATABASE.INFORMATION_SCHEMA.FIELDS']);
Copy

library.unregister_table_or_view – Obsoleto

Atenção

Esse comando está obsoleto. Use library.unregister_objects.

Descrição: cancela o registro de tabelas e exibições de todos os tipos.

Argumentos: object_names (array), is_view (boolean), is_iceberg (boolean), is_external (boolean), is_under_managed_access_schema (boolean)

Saída mensagem de sucesso (string)

Exemplos

Para cancelar o registro de uma tabela:

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

library.unregister_table – Obsoleto

Atenção

Esse comando está obsoleto. Use library.unregister_objects

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

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

Argumentos: table_name (array)

Retorna: mensagem de sucesso (string)

Exemplo:

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

library.unregister_managed_access_table – Obsoleto

Atenção

Esse comando está obsoleto. Use library.unregister_objects

Descrição: semelhante a unregister_table, mas cancela o registro de tabelas em um esquema de acesso gerenciado (ou seja, um esquema criado com o parâmetro WITH MANAGED ACCESS).

Argumentos: table_name (array)

Retorna: mensagem de sucesso (string)

Exemplo:

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

library.unregister_view – Obsoleto

Atenção

Esse comando está obsoleto. Use library.unregister_objects

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

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

Argumentos: view_name (array)

Retorna: mensagem de sucesso (string)

Exemplo:

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

library.unregister_managed_access_view – Obsoleto

Atenção

Esse comando está obsoleto. Use library.unregister_objects

Descrição: semelhante a unregister_view, mas cancela o registro de exibições em um esquema de acesso gerenciado (ou seja, um esquema criado com o parâmetro WITH MANAGED ACCESS).

Argumentos: view_name (array)

Retorna: mensagem de sucesso (string)

Exemplo:

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

Análise executada pelo provedor

consumer.set_join_policy

Descrição: Especifica em quais colunas o provedor tem permissão para executar uma junção ao executar modelos na sala limpa, quando estiver usando Provider Run Analysis. Observe que a política de coluna é somente substituição, portanto, se a função for chamada novamente, a política de coluna definida anteriormente será completamente substituída pela atual.

Observe que as verificações são realizadas analisando a consulta SQL a ser executada nos dados para quaisquer colunas não autorizadas. Consultas com curingas podem não ser detectadas usando essas verificações, e ainda assim é preciso ter cautela ao projetar o modelo de análise.

Argumentos: cleanroom_name(cadeia de caracteres), table_and_col_names(matriz)

Retorna: mensagem de sucesso (string)

Exemplo:

call samooha_by_snowflake_local_db.consumer.set_join_policy($cleanroom_name, ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:EMAIL', 'SAMOOHA_SAMPLE_DATABASE.DEMO.EXPOSURES:EMAIL']);
Copy

consumer.set_column_policy

Descrição: Define em quais colunas de dados o provedor pode realizar operações. Isso só deve ser chamado depois que o modelo for adicionado. Esta também é uma função de modelo, portanto as entradas precisam estar no formato template_name:full_table_name:column_name. Observe que a política de coluna é somente substituição, portanto, se a função for recuperada, a política de coluna definida anteriormente será completamente substituída pela atual.

A política de coluna não deve ser chamada em colunas de identidade como e-mail. Ela deve ser usada somente em colunas agregadas e agrupadas.

Observe que as verificações são realizadas analisando a consulta SQL a ser executada nos dados para quaisquer colunas não autorizadas. Consultas com curingas podem não ser detectadas usando essas verificações, e ainda assim é preciso ter cautela ao projetar o modelo de análise.

As verificações são realizadas em argumentos SQL Jinja chamados dimensions ou measure_columns. Certifique-se de usar essas tags para habilitar essa verificação.

Argumentos: cleanroom_name(cadeia de caracteres), analysis_and_table_and_columns(matriz)

Retorna: mensagem de sucesso (string)

Exemplo:

call samooha_by_snowflake_local_db.consumer.set_column_policy($cleanroom_name,
['prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:STATUS',
 'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:AGE_BAND',
 'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:DAYS_ACTIVE',
 'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE.DEMO.EXPOSURES:CAMPAIGN']);
Copy

Modelos

Os comandos a seguir permitem que os usuários trabalhem com modelos disponíveis na sala limpa.

consumer.view_template_definition

Descrição: As definições do modelo de sala limpa estão disponíveis para ajudar a determinar quais parâmetros precisam ser passados ao modelo.

Nota

Observe que todos os procedimentos do Samooha são criptografados e não podem ser visualizados por padrão. No entanto, todos os modelos personalizados que você adicionar ficarão visíveis para você.

Argumentos: cleanroom_name (string), template_name (string)

Retorna: a definição do modelo (string)

Exemplo:

call samooha_by_snowflake_local_db.consumer.view_template_definition($cleanroom_name, 'prod_overlap_analysis');
Copy

consumer.get_arguments_from_template

Descrição: Define como os dados devem ser organizados e quais dados são necessários para cada modelo para garantir que a saída seja facilmente digerível.

Argumentos: cleanroom_name (string), template_name (string)

Retorna: lista de argumentos e especificação (tabela)

Exemplo:

call samooha_by_snowflake_local_db.consumer.get_arguments_from_template($cleanroom_name, 'prod_overlap_analysis');
Copy

Encadeamentos de modelos

Os comandos a seguir permitem que os usuários trabalhem com cadeias de modelos disponíveis na sala limpa. Para obter informações gerais sobre o uso de cadeias de modelos, consulte Como usar APIs do desenvolvedor para executar modelos sequencialmente.

consumer.view_added_template_chains

Descrição: exibe as cadeias de modelos atualmente ativas na sala limpa.

Argumentos: cleanroom_name (string)

Retorna: cadeias de modelos adicionadas (tabela)

Exemplo:

call samooha_by_snowflake_local_db.consumer.view_added_template_chains($cleanroom_name);
Copy

consumer.view_template_chain_definition

Descrição: retorna os atributos de uma cadeia de modelos.

Argumentos: cleanroom_name (string), template_chain_name (string)

Retorna: definição da cadeia de modelos (string)

Exemplo:

call samooha_by_snowflake_local_db.consumer.view_template_chain_definition($cleanroom_name, 'insights_chain');
Copy

consumer.get_arguments_from_template_chain

Descrição: retorna os argumentos esperados para todos os modelos na cadeia de modelos.

Argumentos: cleanroom_name (string), template__chain_name (string)

Retorna: lista de argumentos e especificação (tabela)

Exemplo:

call samooha_by_snowflake_local_db.consumer.get_arguments_from_template_chain($cleanroom_name, 'insights_chain');
Copy

Execução de análises

Os comandos a seguir executam uma análise ou ativação específica com base no modelo especificado.

consumer.run_analysis

Descrição: executa uma análise usando um modelo ou cadeia de modelos e retorna a tabela de resultados.

Se a privacidade diferencial estiver ativada, a consulta poderá falhar se você tiver atingido o limite de orçamento para esse modelo.

Argumentos:

  • cleanroom_name (cadeia de caracteres) – Nome da sala limpa que tem o modelo a ser executado.

  • template_name (cadeia de caracteres) – nome do modelo ou da cadeia de modelos a ser executada na sala limpa.

  • consumer_tables (matriz de cadeia de caracteres) – matriz de nomes de tabelas de consumidor totalmente qualificados. Elas são atribuídas à variável de modelo my_table. Essas tabelas já devem estar vinculadas à sala limpa. Veja as tabelas disponíveis chamando consumer.view_consumer_datasets. Por exemplo, se você passar [“mytable1”,”mytable2”,”mytable3”], o modelo poderá acessar esses valores como {{my_table[0]}}, {{my_table[1]}} e {{my_table[2]}}, respectivamente.

  • provider_tables (matriz de cadeia de caracteres) – Matriz de nomes de tabela de provedor totalmente qualificados. Elas são atribuídas à variável de modelo source_table. Essas tabelas já devem estar vinculadas à sala limpa. Veja as tabelas disponíveis chamando consumer.view_provider_datasets. Por exemplo, se você passar [“sourcetable1”,”sourcetable2”,”sourcetable3”], o modelo poderá acessar esses valores como {{source_table[0]}}, {{source_table[1]}} e {{source_table[2]}}, respectivamente.

  • analysis_arguments (objeto) – Um objeto com pares chave-valor passados para o modelo. O modelo pode acessar a variável pelo nome da chave. Se você passar o endereço {'age': 20}, o modelo acessará o valor como {{age}}. Passe um objeto vazio se nenhum valor for necessário. Para ver quais valores são necessários, examine o modelo em questão chamando consumer.view_template_definition. Esse objeto tem um valor reservado opcional:

  • use_cache (booliano, opcional) – Se você deve ou não usar resultados em cache para a mesma consulta. O padrão é TRUE. Defina como FALSE ao testar e editar um modelo para garantir que a consulta seja executada novamente usando a versão mais recente do modelo todas as vezes.

Retorna: (tabela) resultados de consulta.

Exemplo:

call samooha_by_snowflake_local_db.consumer.run_analysis(
  $cleanroom_name,
  'prod_overlap_analysis',
  ['SAMOOHA_SAMPLE_DATABASE.MYDATA.CONVERSIONS'],  -- Consumer tables
  ['SAMOOHA_SAMPLE_DATABASE.DEMO.EXPOSURES'],      -- Provider tables
  object_construct(
    'max_age', 30
  )
);
Copy

Ativação

Para obter mais informações sobre a ativação de resultados, consulte Usando as APIs de desenvolvedor para enviar resultados a uma conta Snowflake para ativação.

consumer.set_activation_policy

Descrição: define quais colunas podem ser usadas nos modelos de ativação. Isso garante que somente as colunas aprovadas pelo consumidor possam ser usadas com o modelo de ativação.

Entrada: cleanroom_name (string), columns (array)

O argumento columns é passado no formato <template_name>:<fully_qualified_table_name>:<column_name>.

Saída: mensagem de sucesso

Exemplo:

call samooha_by_snowflake_local_db.consumer.set_activation_policy('my_cleanroom', [ 
    'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE_NAME.DEMO.CUSTOMERS:HASHED_EMAIL',  
    'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE_NAME.DEMO.CUSTOMERS:REGION_CODE' ]);
Copy

consumer.run_activation

Descrição: executa um modelo que envia os resultados de volta para uma conta Snowflake para ativação.

Argumentos: cleanroom_name (string), segment_name (string), template_name (string), consumer_tables (array), provider_tables (array), activation_arguments (objeto), consumer_direct_activation (boolean), application_id (string)

Se o consumidor estiver enviando os resultados para sua própria conta Snowflake para ativação, defina o argumento consumer_direct_activation como TRUE.

Passe uma cadeia de caracteres vazia como argumento para application_id.

Retorna: mensagem de sucesso

Exemplo:

call samooha_by_snowflake_local_db.consumer.run_activation(
  $cleanroom_name,
  'my_activation_segment',
  'activation_custom_template',
  ['consumer_source_table'], 
  ['provider_source_table'],
  object_construct(                 -- Custom arguments needed for the template
    'dimensions', ['p.CAMPAIGN'],   -- always use p. to refer to fields in provider tables, and c. to refer to fields in consumer tables. Use p2, p3, etc. for more than one provider table and c2, c3, etc. for more than one consumer table.
    'where_clause', 'p.EMAIL=c.EMAIL'
  ));
Copy

Modelos definidos pelo consumidor

As seguintes APIs permitem que você adicione modelos definidos pelo consumidor a uma sala limpa. Para obter mais informações, consulte Como usar a API do desenvolvedor para adicionar modelos definidos pelo consumidor.

consumer.create_template_request

Descrição: envia uma solicitação ao provedor de uma sala limpa solicitando que ele aprove um modelo personalizado para que ele possa ser adicionado à sala limpa.

Argumentos: cleanroom_name (string), template_name (string), template_definition (string)

Retorna: mensagem de sucesso (string)

Exemplo:

  CALL samooha_by_snowflake_local_db.consumer.create_template_request('dcr_cleanroom', 
  'my_analysis', 
  $$
  SELECT 
      identifier({{ dimensions[0] | column_policy }}) 
  FROM 
      identifier({{ my_table[0] }}) c 
    INNER JOIN
      identifier({{ source_table[0] }}) p 
        ON   
          c.identifier({{ consumer_id  }}) = identifier({{ provider_id | join_policy }}) 
        {% if where_clause %} where {{ where_clause | sqlsafe | join_and_column_policy }} {% endif %};
  $$);
Copy

consumer.generate_python_request_template

Descrição: gera um modelo de sala limpa para o consumidor que inclui código Python personalizado. O modelo gerado inclui seu código Python e um espaço reservado para seu modelo JinjaSQL. Passe seu modelo final para consumer.list_template_requests.

Saiba mais sobre modelos definidos pelo consumidor.

Argumentos:

  • function_name (string) – O nome da função Python que o modelo SQL deve chamar para executar a função.

  • arguments (matriz de cadeia de caracteres) – Lista de argumentos para sua função Python, em que cada argumento é um par de cadeia de caracteres delimitado por espaço no formato «<argument_name> <argument_type>». Por exemplo: ['data variant', 'scale integer'].

  • packages (matriz de cadeia de caracteres) – Matriz de nomes de pacote necessários para o seu código Python. Se não houver, especifique uma matriz vazia. Exemplo: ['pandas','numpy'].

  • imports (matriz de cadeias de caracteres) – Quaisquer bibliotecas Python personalizadas necessárias para o código Python. Deve ser uma matriz de zero ou mais endereços de estágio. Exemplo: ['@db.schema.stage/my_python_sproc.py']

  • rettype (string) – O tipo de retorno SQL de sua função. Exemplos: 'integer', 'varchar'.

  • handler (string) – O nome da função principal do manipulador em seu código Python. Normalmente, isso é 'main'.

  • code (string) – Sua implementação de código Python. Se você incluir uma importação e o manipulador designado for definido dentro de uma importação, isso poderá ser uma cadeia de caracteres vazia.

Retorna: modelo Python gerado (string). Substitua o espaço reservado pelo seu código SQL.

Exemplo:

Chame a função auxiliar com um exemplo trivial em Python.

call SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.CONSUMER.GENERATE_PYTHON_REQUEST_TEMPLATE(
  'my_func',                         // SQL should use this name to call your function
  ['data variant', 'index integer'], // Arguments and types for the function
  ['pandas', 'numpy'],               // Standard libraries used
  [],                                // No custom libraries needed.
  'integer',                         // Return type integer
  'main',                            // Standard main handler
// Python implementation as UDF  
  $$
import pandas as pd
import numpy as np

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

Aqui está a resposta à chamada anterior. Insira seu JinjaSQL conforme indicado no espaço reservado e passe-o para consumer.create_template_request.

BEGIN

-- First define the Python UDF
CREATE OR REPLACE FUNCTION CLEANROOM.my_func(data variant, index integer)
RETURNS integer
LANGUAGE PYTHON
RUNTIME_VERSION = 3.10
PACKAGES = ('pandas', 'numpy')

HANDLER = 'main'
AS '
import pandas as pd
import numpy as np

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

-- Then define and execute the SQL query
LET SQL_TEXT varchar := '<INSERT SQL TEMPLATE HERE>';

-- Execute the query and return the result
LET RES resultset := (EXECUTE IMMEDIATE :SQL_TEXT);
RETURN TABLE(RES);

END;
Copy

consumer.list_template_requests

Descrição: lista as solicitações que o consumidor fez para adicionar um modelo a uma sala limpa.

Argumentos: cleanroom_name (string)

Retorna: request_id(cadeia de caracteres), provider_identifier(cadeia de caracteres), template_name(cadeia de caracteres), template_definition(cadeia de caracteres), request_status(cadeia de caracteres), reason(cadeia de caracteres)

Exemplo:

CALL samooha_by_snowflake_local_db.consumer.list_template_requests('dcr_cleanroom');
Copy

Métodos de obtenção de metadados de sala limpa

Os métodos a seguir mostram as propriedades relevantes da sala limpa:

consumer.describe_cleanroom

Descrição: Cria um resumo de texto com todas as informações sobre o que foi adicionado à sala limpa, incluindo modelos, conjuntos de dados, políticas etc.

Argumentos: cleanroom_name(cadeia de caracteres)

Retorna: cadeia de caracteres de descrição extensa da sala limpa (tabela)

Exemplo:

call samooha_by_snowflake_local_db.consumer.describe_cleanroom($cleanroom_name);
Copy

consumer.view_provider_datasets

Descrição: Exibe todos os conjuntos de dados adicionados à sala limpa pelo provedor.

Argumentos: cleanroom_name(cadeia de caracteres)

Retorna: todos os nomes de conjuntos de dados do provedor na sala limpa (tabela)

Exemplo:

call samooha_by_snowflake_local_db.consumer.view_provider_datasets($cleanroom_name);
Copy

consumer.view_join_policy

Descrição: Descreve quais colunas os usuários podem unir com segurança em uma sala limpa, definidas pelo consumidor nos conjuntos de dados do consumidor.

Argumentos: cleanroom_name (string)

Retorna: política de junção (tabela)

Exemplo:

call samooha_by_snowflake_local_db.consumer.view_join_policy($cleanroom_name);
Copy

consumer.view_provider_join_policy

Descrição: Descreve quais colunas os usuários podem unir com segurança em uma sala limpa, definidas pelo provedor nos conjuntos de dados do provedor.

Argumentos: cleanroom_name (string)

Retorna: política de junção (tabela)

Exemplo:

call samooha_by_snowflake_local_db.consumer.view_provider_join_policy($cleanroom_name);
Copy

consumer.view_added_templates

Descrição: Exibe todos os modelos ativos na sala limpa.

Argumentos: cleanroom_name (string)

Retorna: modelos adicionados (tabela)

Exemplo:

call samooha_by_snowflake_local_db.consumer.view_added_templates($cleanroom_name);
Copy

consumer.view_column_policy

Descrição: Exibe todas as políticas de coluna aplicadas à sala limpa pelo consumidor.

Argumentos: cleanroom_name (string)

Retorna: política de coluna (tabela)

Exemplo:

call samooha_by_snowflake_local_db.consumer.view_column_policy($cleanroom_name);
Copy

consumer.view_provider_column_policy

Descrição: Exibe todas as políticas de coluna aplicadas à sala limpa pelo provedor.

Argumentos: cleanroom_name (string)

Retorna: política de coluna (tabela)

Exemplo:

call samooha_by_snowflake_local_db.consumer.view_provider_column_policy($cleanroom_name);
Copy

consumer.view_cleanrooms

Descrição: mostra todas as salas limpas associadas (instaladas) ou que podem ser associadas por essa conta. As salas limpas com falha não são mostradas. Na tabela de resultados:

  • IS_ALREADY_INSTALLED: verdadeiro se você tiver ingressado na sala limpa (guia Ingressado no aplicativo da Web), falso se você tiver sido convidado a participar da sala limpa, mas ainda não tiver ingressado nela (guia Convidado no aplicativo da Web).

    Problema conhecido: – Às vezes, esse método pode não mostrar as salas limpas desinstaladas. Se você sabe que uma sala limpa foi compartilhada com você, mas ela não está aparecendo na lista, chame consumer.describe_cleanroom para ver se essa sala limpa está disponível para ingresso.

Argumentos: nenhum

Retorna: todas as salas limpas existentes ordenadas por data de criação (tabela)

Exemplo:

call samooha_by_snowflake_local_db.consumer.view_cleanrooms();

-- Now filter out invitations that have not been accepted
SELECT cleanroom_name FROM TABLE(RESULT_SCAN(LAST_QUERY_ID())) WHERE is_already_installed = TRUE;
Copy

Privacidade diferencial

Esses comandos controlam a privacidade diferencial na sala limpa. Você também pode especificar a privacidade diferencial no nível do modelo ao chamar consumer.enable_templates_for_provider_run.

Saiba mais sobre como gerenciar a privacidade diferencial.

consumer.is_dp_enabled

Descrição: Verifica se a privacidade diferencial foi habilitada na sala limpa.

Argumentos: cleanroom_name(cadeia de caracteres)

Retorna: se a sala limpa tem DP ativado (boolean)

Exemplo:

call samooha_by_snowflake_local_db.consumer.is_dp_enabled($cleanroom_name);
Copy

consumer.view_remaining_privacy_budget

Descrição: Exibe o orçamento de privacidade restante que pode ser usado para fazer consultas na sala limpa. Uma vez esgotadas, outras chamadas para run_analysis não serão permitidas até que o orçamento seja redefinido. O orçamento é redefinido diariamente.

SELECT cleanroom_name FROM TABLE(RESULT_SCAN(LAST_QUERY_ID())) WHERE is_already_installed = TRUE;

Argumentos: cleanroom_name (string)

Retorna: orçamento de privacidade restante (float)

Exemplo:

call samooha_by_snowflake_local_db.consumer.view_remaining_privacy_budget($cleanroom_name);
Copy

Métodos auxiliares gerais

Use os métodos a seguir para ajudar na funcionalidade geral da sala limpa.

consumer.set_cleanroom_ui_accessibility

Descrição: mostra ou oculta salas limpas no aplicativo da Web para consumidores na conta corrente.

Argumentos:

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

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

    • HIDDEN – Oculta a sala limpa especificada no aplicativo da Web de todos os usuários da conta de consumidor atual. A sala limpa ainda estará acessível por meio de chamadas de API.

    • EDITABLE – Torna a sala limpa visível no aplicativo da Web.

Retorna: mensagem de sucesso (string)

Exemplo:

call samooha_by_snowflake_local_db.consumer.set_cleanroom_ui_accessibility($cleanroom_name, 'HIDDEN');
Copy

library.enable_local_db_auto_upgrades

Descrição: habilita a tarefa, samooha_by_snowflake_local_db.admin.expected_version_task, que atualiza automaticamente o Snowflake Native App para Snowflake Data Clean Rooms conforme novas versões são lançadas.

Argumentos: nenhum

Retorna: mensagem de sucesso (string)

Exemplo:

CALL samooha_by_snowflake_local_db.library.enable_local_db_auto_upgrades();
Copy

library.disable_local_db_auto_upgrades

Descrição: desabilita a tarefa, samooha_by_snowflake_local_db.admin.expected_version_task, que atualiza automaticamente o Snowflake Native App para Snowflake Data Clean Rooms conforme novas versões são lançadas.

Argumentos: nenhum

Retorna: mensagem de sucesso (string)

Exemplo:

CALL samooha_by_snowflake_local_db.library.disable_local_db_auto_upgrades();
Copy