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

grant_run_on_cleanrooms_to_role¶

Esquema:

CONSUMER

Descrição: concede à função especificada permissão para executar um subconjunto de procedimentos nas clean rooms especificadas. As clean rooms devem ser instaladas nesta conta, e não criadas por esta conta. (Ou seja, apenas clean rooms para as quais você é um consumidor)

Para conceder uso limitado às suas salas limpas, conceda aos usuários a função especificada em vez de SAMOOHA_APP_ROLE. Para obter mais informações sobre acesso à função, consulte Conceda acesso limitado à API.

Os procedimentos a seguir podem ser executados usando uma função especificada aqui:

• consumer.view_added_templates

• consumer.view_added_template_chains

• consumer.get_arguments_from_template

• consumer.view_column_policy

• consumer.view_consumer_datasets

• consumer.view_join_policy

• consumer.view_provider_column_policy

• consumer.view_provider_datasets

• consumer.view_provider_join_policy

• consumer.view_remaining_privacy_budget

• consumer.run_analysis

• consumer.view_provider_activation_policy

• consumer.view_activation_policy

• consumer.run_activation

Argumentos:

• cleanroom_names (cadeia de caracteres): nomes de todas as salas limpas às quais será concedido acesso limitado para a função especificada.

• run_role_name (string) – Nome de uma função que tem permissões limitadas nas clean rooms especificadas. Você deve criar a função antes de chamar esse procedimento.

Retorna: (cadeia de caracteres): mensagem de sucesso.

Exemplo:

CREATE ROLE MARKETING_ANALYST_ROLE;
CALL samooha_by_snowflake_local_db.consumer.grant_run_on_cleanrooms_to_role(
  ['overlap_cleanroom', 'market_share_cleanroom'],
  'MARKETING_ANALYST_ROLE'
);

revoke_run_on_cleanrooms_from_role¶

Esquema:

CONSUMER

Descrição: revoga permissões das funções especificadas nas salas limpas indicadas. Se o usuário tiver acesso a uma função não revogada, ou tiver a SAMOOHA_APP_ROLE, ele ainda poderá executar procedimentos de sala limpa nas salas limpas especificadas.

Argumentos:

• cleanroom_names (cadeia de caracteres): nomes de uma ou mais salas limpas nesta conta.

• run_role_name (string) – Nome da função que não deve mais ter permissões limitadas nas clean rooms especificadas nessa conta.

Retorna: (cadeia de caracteres): mensagem de sucesso.

Exemplo:

CALL samooha_by_snowflake_local_db.consumer.revoke_run_on_cleanrooms_from_role(
  ['overlap_cleanroom', 'market_share_cleanroom'],
  'TEMP_USERS_ROLE'
);

install_cleanroom¶

Esquema:

CONSUMER

Descrição: instala (une) a sala limpa criada pelo provedor especificado. Chamar esse procedimento várias vezes limpa a sala limpa existente a cada vez. Se você interromper uma segunda instalação antes que ela seja concluída, a sala limpa será corrompida, e você precisará concluir esse procedimento para torná-la utilizável.

Argumentos:

• cleanroom_name (cadeia de caracteres): nome da sala limpa para instalação.

• provider_account_locator (string) – Localizador da conta de provedor que criou essa clean room.

Retorna: (string) Mensagem de sucesso.

Tratamento de erros:

Se você receber um erro informando que o «preenchimento automático entre nuvens não está habilitado para esta conta», isso significa que o provedor está em outra região de hospedagem na nuvem. Você deve habilitar o preenchimento automático entre nuvens, conforme descrito em Gerenciando o preenchimento automático entre nuvens em Snowflake Data Clean Rooms.

Exemplo:

CALL samooha_by_snowflake_local_db.consumer.install_cleanroom(
  $cleanroom_name,
  $provider_locator);

is_enabled¶

Esquema:

CONSUMER

Descrição: pode haver um pequeno atraso após a instalação da sala limpa até ela ficar pronta para uso. Você poderá chamar esse procedimento para confirmar se a sala limpa está ou não pronta para uso após a instalação.

Argumentos:

• cleanroom_name (cadeia de caracteres): nome da sala limpa da qual verificar o status.

Retorna: (booliano) se a sala limpa especificada está ou não instalada e pronta para uso.

Exemplo:

CALL samooha_by_snowflake_local_db.consumer.is_enabled($cleanroom_name);

uninstall_cleanroom¶

Esquema:

CONSUMER

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. A sala limpa sempre pode ser instalada novamente ao chamar consumer.install_cleanroom.

Argumentos:

• cleanroom_name (cadeia de caracteres): nome da sala limpa para desinstalação.

Retorna: (string) Mensagem de sucesso.

Exemplo:

CALL samooha_by_snowflake_local_db.consumer.uninstall_cleanroom($cleanroom_name);

enable_laf_on_account¶

Esquema:

LIBRARY

Descrição: ativa o preenchimento automático entre nuvens na conta atual. 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. 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_for_cleanroom¶

Esquema:

CONSUMER

Descrição: descreve se o preenchimento automático entre nuvens foi ou não ativado para essa clean room. O preenchimento automático entre nuvens deve ser configurado por um administrador de conta.

Argumentos:

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

Devoluções: se o preenchimento automático entre nuvens foi ou não ativado para essa clean room.

Exemplo:

CALL samooha_by_snowflake_local_db.consumer.is_laf_enabled_for_cleanroom($cleanroom_name);

request_laf_cleanroom¶

Esquema:

CONSUMER

Descrição: configura os pré-requisitos para instalar uma sala limpa criada em outra região de nuvem. Haverá falha se consumer.install_cleanroom for chamado antes de chamar esse procedimento falha. Esse procedimento retorna o status atual cada vez que você o chama. Chame-o periodicamente até que o status seja FULFILLED; depois chame consumer.install_cleanroom. Pode levar até 10 minutos para que o status seja FULFILLED.

Argumentos:

• cleanroom_name (cadeia de caracteres): o nome da sala limpa que será instalada entre regiões.

• provider_locator (string) – localizador da conta de provedor que criou essa clean room.

Retorna: (string) mensagem de status da solicitação. Continue chamando até que o status seja FULFILLED.

Exemplo:

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.consumer.request_laf_cleanroom(
  $cleanroom_name,$provider_locator);

setup_cleanroom_request_share_for_laf¶

Esquema:

CONSUMER

Descrição: permite o compartilhamento de solicitações entre nuvens com um provedor específico para uma clean room específica. Isso é necessário para que as clean rooms entre regiões tenham funcionalidade completa, incluindo logs de solicitações, solicitações de modelos de consumidores e análises executadas pelo provedor.

Argumentos:

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

• provider_account_name (string) – Identificador de conta de compartilhamento de dados do provedor.

Retorna: (string) Mensagem de sucesso.

Exemplo:

CALL samooha_by_snowflake_local_db.consumer.setup_cleanroom_request_share_for_laf(
      $cleanroom_name, $provider_account_name);

setup_activation_share_to_laf_consumer¶

Esquema:

CONSUMER

Descrição: permite a ativação do provedor entre um provedor e um consumidor em diferentes regiões de nuvem.

Argumentos:

• provider_account – Um ou mais identificadores de conta de compartilhamento de dados <label-account_name_data_sharing> de provedores delimitados por vírgula {ref}.

Retorna: (string) Mensagem de sucesso.

Exemplo:

CALL samooha_by_snowflake_local_db.consumer.setup_activation_share_to_laf_consumer(
  'org1.locator1,org2.locator2');

is_provider_run_enabled¶

Esquema:

LIBRARY

Descrição: verifica se esta sala limpa permite análises executadas pelo provedor. O consumidor ainda deve conceder permissão explícita chamando consumer.enable_templates_for_provider_run antes que os provedores possam executar uma análise nesta sala limpa.

Argumentos:

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

Retorna: (cadeia de caracteres) descrição se a sala limpa oferece ou não suporte a análises executadas pelo provedor.

Exemplo:

CALL samooha_by_snowflake_local_db.library.is_provider_run_enabled($cleanroom_name)

approve_template¶

Esquema:

CONSUMER

Descrição: aprova um único modelo para análise executada pelo provedor em uma determinada sala limpa. O provedor da sala limpa normalmente se comunica com você de antemão para solicitar permissão para executar um modelo específico em uma sala limpa. Certifique-se de definir as políticas de junção e de coluna em um modelo antes de aprová-lo para análise executada pelo provedor:

• Uma sala limpa sem política de junção de consumidor significa que o provedor pode unir todas as colunas de consumidor.

• Uma sala limpa sem política de coluna de consumidor significa que o provedor pode projetar todas as colunas de consumidor.

• Uma sala limpa com política de coluna de consumidor que não inclui este modelo aprovado significa que o provedor não pode projetar nenhuma coluna de consumidor ao usar este 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 que o provedor pode executar, na sala limpa especificada.

Retorna: (string) Mensagem de sucesso.

Exemplo:

CALL samooha_by_snowflake_local_db.consumer.approve_template(
  $cleanroom_name,
  $template_name);

set_provider_run_configuration¶

Esquema:

CONSUMER

Descrição: aplica configurações a um modelo que controlam como um provedor pode executar um modelo especificado na sala limpa. Se o consumidor não fornecer uma configuração para um modelo, os valores padrão serão aplicados. Um provedor não pode executar um modelo até que um consumidor o aprove para análises executadas pelo provedor chamando consumer.approve_template.

Argumentos:

• cleanroom_name (cadeia de caracteres): nome da sala limpa. Se o modelo não estiver presente nesta sala limpa, o procedimento vai gerar um erro. O modelo ainda não precisa ser aprovado para análise executada pelo provedor, mas o provedor não poderá executar o modelo até que o consumidor o aprove.

• template_configuration (objeto): um objeto que determina limites sobre como um provedor pode executar um modelo específico nesta sala limpa. As análises executadas pelo provedor são feitas na conta do consumidor e faturadas para o consumidor, de modo que ele possa definir limitações sobre quais warehouses podem ser usados para um determinado modelo. O objeto de configuração tem este formato:

  {
    <template_name>: {
      "warehouse_type": <warehouse_type>,
      "warehouse_size": <warehouse_size>
    }
  }
  

  Copy

  Você deve fornecer todos os seguintes valores:

  • template_name: a chave do objeto é o nome do modelo. A configuração é aplicada a este modelo. O modelo deve estar presente na sala limpa.

  • warehouse_type (cadeia de caracteres): qual tipo de warehouse o provedor pode usar para executar este modelo Valores permitidos:

    • ALL: (padrão) permita qualquer tipo de warehouse.

    • STANDARD: permita apenas um warehouse padrão.

    • SNOWPARK-OPTIMIZED: permita apenas um warehouse otimizado para Snowpark. XLARGE ou X-LARGE é tem suporte.

    • ALL: (padrão) qualquer tamanho de warehouse permitido.

    • Qualquer tamanho definido para WAREHOUSE_SIZE ou seus sinônimos (por exemplo, XLARGE ou X-LARGE) tem suporte.

Retorna: (string) Mensagem de sucesso.

Exemplo:

CALL samooha_by_snowflake_local_db.consumer.set_provider_run_configuration(
  $cleanroom_name,
  {
    "some_template": {
      "warehouse_type": "STANDARD",
      "warehouse_size": ["MEDIUM", "LARGE"]
    }
  }
);

enable_templates_for_provider_run¶

Esquema:

CONSUMER

Descrição: concede permissão ao provedor para executar uma análise na sala limpa solicitada. Esse procedimento é chamado depois que o provedor chama provider.enable_provider_run_analysis para permitir a análise executada pelo provedor em uma sala limpa. consumer.enable_templates_for_provider_run concede ao provedor permissão para executar os modelos especificados na sala limpa indicada quantas vezes ele quiser.

Os provedores executam modelos habilitados na conta do consumidor, e isso é cobrado do consumidor. Se quiser limitar o tipo ou os tamanhos de warehouse permitidos para um provedor ao executar um determinado modelo, chame set_provider_run_configuration.

Argumentos:

• cleanroom_name (cadeia de caracteres): o nome da sala limpa em que o provedor pode executar análises.

• template_names (matriz de cadeia de caracteres) – Uma matriz de nomes de um ou mais modelos na clean room que o provedor pode executar.

• enable_differential_privacy (booliano) – Se TRUE, habilita 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. Você pode personalizar as configurações de privacidade chamando consumer.set_privacy_settings. Saiba mais.

• template_configuration (objeto, opcional): um objeto opcional para especificar configurações adicionais para cada modelo em template_names. Esse objeto contém pares chave-valor, em que a chave é o nome do modelo (de template_names) e o valor é um objeto que define limitações sobre como o provedor pode usar esse modelo. Se você não fornecer uma configuração de modelo, «ALL» será o padrão para todas as propriedades de todos os modelos em template_names. Se você fornecer uma configuração de modelo, deverá fornecer uma configuração para cada modelo listado em template_names e definir todas as propriedades para a configuração desse modelo. Você também pode definir os valores permitidos para um modelo chamando consumer.set_provider_run_configuration.

  Há suporte para as seguintes propriedades:

  • warehouse_type (cadeia de caracteres): um tipo de warehouse permitido que o provedor pode usar com este modelo. Valores permitidos:

    • ALL: permita qualquer tipo de warehouse.

    • STANDARD: permita apenas um warehouse padrão.

    • SNOWPARK-OPTIMIZED: permita apenas warehouse otimizado para Snowpark.

  • warehouse_size (matriz de cadeias de caracteres): um ou mais tamanhos de warehouse permitidos que podem ser usados com este tipo e modelo de warehouse. Os valores permitidos são aqueles definidos para WAREHOUSE_SIZE ou seus sinônimos (por exemplo, XLARGE ou X-LARGE). Especifique «ALL» para permitir qualquer tamanho de warehouse.

Retorna: (string) Mensagem de sucesso.

Exemplos:

-- Simple example
CALL samooha_by_snowflake_local_db.consumer.enable_templates_for_provider_run(
  $cleanroom_name,
  ['prod_overlap_analysis'],
  FALSE);

-- Specify what types of warehouse the provider can use to run these templates.
CALL samooha_by_snowflake_local_db.CONSUMER.enable_templates_for_provider_run(
  $cleanroom_name,
  ['template1', 'template2', 'template3'],
  TRUE,
  {
    'template1': {'warehouse_type': 'ALL', 'warehouse_size': ['MEDIUM', 'LARGE']},
    'template2': {'warehouse_type': 'SNOWPARK-OPTIMIZED', 'warehouse_size': ['MEDIUM', 'XLARGE']},
    'template3': {'warehouse_type': 'STANDARD', 'warehouse_size': ['MEDIUM', 'XLARGE']}
  });

prepare_multiprovider_flow¶

Esquema:

CONSUMER

Descrição: envia uma solicitação para executar uma consulta multiprovedor aos provedores das salas limpas especificadas. Esse procedimento não executa de fato a solicitação, ele apenas pede ao provedor permissão para executar essa solicitação no futuro chamando consumer.execute_multiprovider_flow.

Se um provedor conceder a aprovação, o consumidor poderá executar a consulta chamando consumer.execute_multiprovider_flow quantas vezes quiser (dependendo das configurações de privacidade diferencial definidas). Para executar novamente uma consulta já aprovada depois de chamar prepare_multiprovider_flow com novos valores, o consumidor deve chamar prepare_multiprovider_flow com a consulta anterior exata, mas não precisa esperar a aprovação do provedor para executar consumer.execute_multiprovider_flow.

A solicitação é válida por quatro horas; depois disso, a solicitação será retirada da fila.

Argumentos:

• cleanroom_names (cadeia de caracteres): matriz de nomes de salas limpas na conta do consumidor. Essas salas limpas devem ser instaladas.

• template_name (cadeia de caracteres): nome do modelo a ser executado em cada uma das salas limpas listadas em cleanroom_names. Ele pode ser um modelo fornecido pelo Snowflake adicionado pelo provedor da sala limpa ou um modelo personalizado que você já enviou para a sala limpa chamando consumer.create_template_request. Em ambos os casos, o modelo já deve estar presente em uma sala limpa para que a solicitação seja enviada ao provedor da sala limpa.

• arguments (objeto) – Um objeto com os seguintes campos, usado para preencher o modelo:

  • source_table (matriz de cadeias de caracteres): uma matriz de nomes de tabelas que são usados para preencher a matriz source_table disponível ao modelo. A sintaxe para cada nome da tabela é cleanroom_name.db.schema.table. Cada provedor vê apenas as próprias tabelas de sala limpa listadas na solicitação.

  • my_table (matriz de cadeias de caracteres): uma matriz de nomes de tabelas dos próprios dados que são usados para preencher a matriz my_table disponível ao modelo. Use a mesma sintaxe passada para o argumento consumer_tables de consumer.run_analysis.

  • Qualquer outra variável de modelo: passe os valores necessários para o modelo como pares chave-valor.

Retorna: (string) ID de solicitação para passar para consumer.execute_multiprovider_flow.

Exemplo:

CALL samooha_by_snowflake_local_db.consumer.prepare_multiprovider_flow(
    [$cleanroom_name_1, $cleanroom_name_2],
    'prod_aggregate_data',
    object_construct(
        'source_table', [
            CONCAT($cleanroom_name_1, '.SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS'),
            CONCAT($cleanroom_name_2, '.SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS')
        ],
        'my_table', ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']),
        'hem_col', ['p1.HASHED_EMAIL', 'p2.HASHED_EMAIL'],
        'dimensions', ['p1.STATUS', 'p2.STATUS'],
        'consumer_join_col', 'HASHED_EMAIL'
    )
);

execute_multiprovider_flow¶

Esquema:

CONSUMER

Descrição: executa a consulta mais recente enviada pelo consumidor para consumer.prepare_multiprovider_flow. O procedimento executa a consulta em cada clean room especificada onde a consulta foi aprovada pelo provedor e retorna a união de todos os resultados de consulta. A execução desse procedimento é a única maneira de saber se um provedor aprovou uma consulta.

Argumentos:

• cleanroom_names (cadeia de caracteres): matriz de nomes de salas limpas em que a consulta preparada deve ser executada. Essa matriz deve corresponder à lista completa de salas limpas na solicitação de consulta.

• request_id (cadeia de caracteres, opcional) – ID de solicitação retornado por prepare_multiprovider_flow.

Retorna: (tabela) união dos resultados de todas as clean rooms aprovadas. Se um provedor nunca tiver aprovado uma consulta desse consumidor, a consulta falhará. No entanto, se um provedor tiver aprovado uma consulta diferente desse consumidor, mas não a consulta mais recente, o procedimento retornará um conjunto de resultados vazio.

Exemplo:

CALL samooha_by_snowflake_local_db.consumer.execute_multiprovider_flow(
  [$cleanroom1, $cleanroom2],
  $request_id);

register_db¶

Esquema:

CONSUMER

Descrição: registre um banco de dados em uma conta para poder vincular objetos desse banco de dados a uma sala limpa nessa conta. Para um controle mais detalhado, você pode chamar register_schema, register_managed_access_schema ou, em vez dele, register_object. Os objetos adicionados ao banco de dados após o registro podem não ser vinculáveis. Nesse caso, você deve registrar novamente o banco de dados (ou registrar o próprio objeto).

Você deve ter os privilégios MANAGE GRANTS no banco de dados para executar esse procedimento.

Argumentos:

• db_name (cadeia de caracteres): nome do banco de dados a ser registrado nesta conta.

Retorna: (string) Mensagem de sucesso.

Exemplo:

USE ROLE <ROLE_WITH_MANAGE GRANTS>;
CALL samooha_by_snowflake_local_db.consumer.register_db('SAMOOHA_SAMPLE_DATABASE');

register_schema¶

Esquema:

LIBRARY

Descrição: registre um esquema em uma conta para poder vincular objetos desse esquema a uma sala limpa nessa conta. Para um controle mais detalhado, você pode chamar register_object no lugar. Os objetos adicionados ao esquema após o registro podem não ser vinculáveis. Nesse caso, você deve registrar novamente o esquema (ou registrar o próprio objeto).

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_names (matriz de cadeias de caracteres): matriz de esquemas totalmente qualificados a serem registrados.

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: registre um esquema de acesso gerenciado em uma conta para poder vincular objetos desse esquema a uma sala limpa nessa conta. Para um controle mais detalhado, você pode chamar register_object no lugar. Os objetos adicionados ao esquema após o registro podem não ser vinculáveis. Nesse caso, você deve registrar novamente o esquema (ou registrar o próprio objeto).

Argumentos:

• schema_names (matriz de cadeias de caracteres): matriz de esquemas gerenciados totalmente qualificados a serem registrados.

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 ao chamar consumer.link_datasets. Você pode registrar grupos mais amplos de objetos chamando library.register_schema, library.register_managed_access_schema ou consumer.register_db. Você deve ter os privilégios MANAGE GRANTS no banco de dados para executar esse procedimento.

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: habilita o uso de tabelas Iceberg ou externas em todas as clean rooms dessa conta. Deve ser chamado por um ACCOUNTADMIN em ambas as contas, provedor e consumidor, para permitir que tabelas Iceberg ou externas sejam vinculadas por ambas as contas. Para limitar essa capacidade às clean rooms específicas nessa conta, chame enable_external_tables_for_cleanroom em vez disso.

Argumentos: nenhum

Retorna: (string) Mensagem de sucesso.

Exemplo:

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

enable_external_tables_for_cleanroom¶

Esquema:

CONSUMER

Descrição: permite que o consumidor vincule tabelas Iceberg ou externas na clean room especificada nesta conta. Para permitir tabelas Iceberg e externas para todas as clean rooms dessa conta, chame enable_external_tables_on_account em vez disso.

Argumentos:

• cleanroom_name (cadeia de caracteres): o nome da sala limpa na qual o provedor pode vincular tabelas Iceberg ou tabelas 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 é gerado quando a verificação de segurança é bem-sucedida.

Exemplo:

CALL samooha_by_snowflake_local_db.provider.enable_external_tables_for_cleanroom(
    $cleanroom_name);

unregister_db¶

Esquema:

LIBRARY

Descrição: remove as concessões no nível do banco de dados concedidas à função SAMOOHA_APP_ROLE e ao aplicativo nativo Snowflake Data Clean Room. Os dados nesse banco de dados vinculados a uma sala limpa não estarão mais acessíveis nesta conta. Você deve ter os privilégios MANAGE GRANTS no banco de dados para executar esse procedimento.

Argumentos:

• db_name (cadeia de caracteres): nome do banco de dados para cancelar o registro.

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 ou mais esquemas, o que impede que os usuários vinculem suas tabelas e exibições à sala limpa.

Se quiser cancelar o registro de um esquema de acesso gerenciado (ou seja, um esquema criado com o parâmetro WITH MANAGED ACCESS), use library.unregister_managed_access_schema no lugar. Você deve ter os privilégios MANAGE GRANTS no banco de dados para executar esse procedimento.

Argumentos:

• schema_names (matriz de cadeias de caracteres): nomes de esquemas totalmente qualificados 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.PUBLIC', 'MY_DB.MY_SCH']);

unregister_managed_access_schema¶

Esquema:

LIBRARY

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

Argumentos:

• schema_names (matriz de cadeias de caracteres): nomes de esquemas totalmente qualificados para cancelar o registro.

Retorna: (string) Mensagem de sucesso.

Exemplo:

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

unregister_objects¶

Esquema:

LIBRARY

Descrição: revoga o acesso da 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 dos quais revogar o acesso.

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','MY_DB.MY_SCH.MY_VIEW']);

link_datasets¶

Esquema:

CONSUMER

Descrição: vincule uma tabela ou visualização à sala limpa, dando aos modelos dessa sala limpa acesso à tabela, de acordo com as políticas de junção e coluna que você especificar.

Argumentos:

• cleanroom_name (cadeia de caracteres): nome da sala limpa à qual os dados serão vinculados.

• full_tables (matriz de cadeias de caracteres): lista de nomes de tabelas ou exibições totalmente qualificados a serem expostos na sala limpa. Esses objetos devem primeiro ser registrados (disponibilizados ao ambiente de sala limpa) com o método de registro adequado.

Retorna: (string) Mensagem de sucesso.

Exemplo:

CALL samooha_by_snowflake_local_db.consumer.link_datasets(
  $cleanroom_name,
  ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS', 'MY_DB.MY_SCH.EXPOSURES']);

unlink_datasets¶

Esquema:

CONSUMER

Descrição: remove o acesso às tabelas ou exibições especificadas na sala limpa indicada para todos os usuários. Ele funciona somente para dados que você vinculou à sala limpa.

Argumentos:

• cleanroom_name (cadeia de caracteres): nome da sala limpa da qual remover o acesso.

• tables_list (matriz de cadeias de caracteres): lista de nomes de tabelas ou exibições totalmente qualificados para os quais o acesso deve ser bloqueado.

Retorna: (string) Mensagem de sucesso.

Exemplo:

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

view_consumer_datasets¶

Esquema:

CONSUMER

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

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.consumer.view_consumer_datasets($cleanroom_name);

set_join_policy¶

Esquema:

CONSUMER

Descrição: especifica em quais colunas o provedor tem permissão para unir ao executar modelos na sala limpa e ao usar uma análise executada pelo provedor. A política de coluna é somente substituição, portanto, se a função for chamada novamente, a política de coluna já definida será completamente substituída pela atual. Se você não especificar uma política de junção para seus dados, todas as colunas poderão ser unidas.

As consultas com curingas podem desconsiderar alguma política de junção, portanto, tenha cuidado ao criar seu modelo de análise.

Argumentos:

• cleanroom_name (cadeia de caracteres): nome da sala limpa em que a política de junção deve ser aplicada.

• table_col_names (matriz de cadeia de caracteres): nomes totalmente qualificados de colunas que podem ser unidas, no formato nome do banco de dados.nome do esquema:nome da coluna

Retorna: (string) Mensagem de sucesso.

Exemplo:

CALL samooha_by_snowflake_local_db.consumer.set_join_policy(
  $cleanroom_name,
  ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:HASHED_EMAIL', 'MYDB.MYSCH.EXPOSURES:HASHED_EMAIL']);

view_join_policy¶

Esquema:

CONSUMER

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 (cadeia de caracteres)

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

Exemplo:

CALL samooha_by_snowflake_local_db.consumer.view_join_policy($cleanroom_name);

view_provider_join_policy¶

Esquema:

CONSUMER

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 (cadeia de caracteres)

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

Exemplo:

CALL samooha_by_snowflake_local_db.consumer.view_provider_join_policy($cleanroom_name);

set_column_policy¶

Esquema:

CONSUMER

Descrição: define em quais colunas os dados do consumidor podem ser projetados. A política de coluna é aplicada a um modelo em uma sala limpa. A política de coluna é somente substituição, portanto, se a função for chamada novamente, a política de coluna já definida será completamente substituída pela atual. Se você não especificar uma política de coluna, todas as colunas poderão ser projetadas.

Não defina uma política de coluna em colunas de identidade ou sigilosas, como e-mail, pois geralmente você não quer que esse tipo de dados seja projetado.

As consultas com curingas podem não ser detectadas ao usar essas verificações, portanto, você deve ter cuidado ao criar o modelo de análise.

Argumentos:

• cleanroom_name (cadeia de caracteres): nome da sala limpa à qual a política de coluna é aplicada.

• analysis_table_cols (matriz de cadeia de caracteres): nomes totalmente qualificados de colunas que podem ser projetadas, no formato nome do banco de dados.nome do esquema:nome da coluna

Retorna: (string) Mensagem de sucesso.

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

view_column_policy¶

Esquema:

CONSUMER

Descrição: mostra todas as políticas de coluna do consumidor na sala limpa especificada. Para ver as políticas de coluna definidas pelo provedor, chame consumer.view_provider_column_policy.

Argumentos:

• cleanroom_name (cadeia de caracteres): nome da sala limpa a ser descrita.

Retorna: (tabela) informações sobre todas as políticas de coluna do consumidor na sala limpa.

Exemplo:

CALL samooha_by_snowflake_local_db.consumer.view_column_policy($cleanroom_name);

view_provider_column_policy¶

Esquema:

CONSUMER

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

Argumentos:

• cleanroom_name (cadeia de caracteres)

Retorna: política de coluna (tabela)

Exemplo:

CALL samooha_by_snowflake_local_db.consumer.view_provider_column_policy($cleanroom_name);

view_template_definition¶

Esquema:

CONSUMER

Descrição: visualize o JinjaSQL bruto do modelo especificado. Se um modelo foi oculto aplicando o argumento is_obfuscated, você não pode ver o código-fonte do modelo.

Argumentos:

• cleanroom_name (cadeia de caracteres): nome da sala limpa que armazena o modelo.

• template_name (cadeia de caracteres): nome do modelo que será visualizado.

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

Exemplo:

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

get_arguments_from_template¶

Esquema:

CONSUMER

Descrição: obtenha uma lista dos argumentos usados pelo modelo. Você pode passar os valores desses argumentos para o modelo ao chamar consumer.run_analysis.

Argumentos:

• cleanroom_name (cadeia de caracteres): nome da sala limpa que tem o modelo.

• template_name (cadeia de caracteres): nome do modelo para o qual retornar os argumentos.

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

Exemplo:

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

view_added_template_chains¶

Esquema:

CONSUMER

Descrição: lista todas as cadeias de modelos definidas em uma determinada sala limpa.

Argumentos:

• cleanroom_name (cadeia de caracteres): nome da sala limpa para a qual listar as cadeias de modelos.

Retorna: (tabela) informações sobre as cadeias de modelos na sala limpa especificada.

Exemplo:

CALL samooha_by_snowflake_local_db.consumer.view_added_template_chains(
  $cleanroom_name);

view_template_chain_definition¶

Esquema:

CONSUMER

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

Argumentos:

• cleanroom_name (cadeia de caracteres): nome da sala limpa com a cadeia de modelos a ser descrita.

• template_chain_name (cadeia de caracteres): nome da cadeia de modelos a ser descrita.

Retorna: (cadeia de caracteres) a definição da cadeia de modelos especificada.

Exemplo:

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

run_analysis¶

Esquema:

CONSUMER

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

Argumentos:

• cleanroom_name (cadeia de caracteres): nome da sala limpa na qual a análise será executada.

• template_name (cadeia de caracteres): nome do modelo ou da cadeia de modelos a ser executado na sala limpa. Esse modelo deve ter sido adicionado à sala limpa pelo provedor ou consumidor.

• consumer_tables (matriz de cadeias 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.

• provider_tables (matriz de cadeias de caracteres): matriz de nomes de tabelas de provedor totalmente qualificados. Elas são designadas à variável de modelo source_table. Essas tabelas devem ter sido vinculadas à sala limpa. Veja as tabelas disponíveis chamando consumer.view_provider_datasets.

• 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 {'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. Examine o modelo para determinar se você precisa qualificar totalmente os nomes de colunas utilizados. Se o alias da tabela for p ou c no modelo, use os alias de tabela p e c em letras minúsculas para os nomes de colunas.

  Esse objeto tem um valor reservado opcional:

  • epsilon (float, opcional) – especifica o valor de epsilon para privacidade diferencial, se a privacidade diferencial estiver ativada para essa sala limpa. O padrão é 0.1.

• use_cache (booliano, opcional) – Se você deve ou não usar resultados em cache para a mesma consulta. O padrão é FALSE.

Retorna: (tabela) resultados de consulta.

Exemplo:

CALL samooha_by_snowflake_local_db.consumer.run_analysis(
  $cleanroom_name,
  'prod_overlap_analysis',
  ['DB1.MYDATA.CONVERSIONS'],  -- Consumer tables
  ['MYDB.MYSCH.EXPOSURES'],    -- Provider tables
  object_construct(
    'max_age', 30
  )
);

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

set_activation_policy¶

Esquema:

CONSUMER

Descrição: define quais colunas podem ser usadas em um modelo de ativação. Isso garante que somente as colunas aprovadas pelo consumidor possam ser usadas com o modelo de ativação. Se você não definir uma política de ativação, nenhuma coluna dos dados poderá ser ativada. A definição de uma política de ativação substitui qualquer política de ativação existente em sua conta.

Argumentos:

• cleanroom_name (cadeia de caracteres): nome da sala limpa na qual a política de ativação será definida.

• columns (matriz): nome das colunas dos seus próprios dados que podem ser ativadas, no formato nome do modelo:nome do banco de dados.nome do esquema.nome da tabela:nome_da_coluna.

Retorna: (string) Mensagem de sucesso.

Exemplo:

CALL samooha_by_snowflake_local_db.consumer.set_activation_policy(
  $cleanroom_name,
  [
    'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE_NAME.DEMO.CUSTOMERS:HASHED_EMAIL',
    'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE_NAME.DEMO.CUSTOMERS:REGION_CODE' ]);

approve_provider_activation_consent¶

Esquema:

CONSUMER

Descrição: aprova a solicitação do provedor para permitir a ativação dele, que é a capacidade de enviar resultados para a conta Snowflake do provedor.

Argumentos:

• cleanroom_name (cadeia de caracteres): nome da sala limpa em que o provedor está solicitando a execução de um modelo.

• activation_template_name (cadeia de caracteres): nome do modelo de ativação que o provedor quer executar.

Retorna: (cadeia de caracteres) mensagem de sucesso. Esse procedimento falhará se o provedor não tiver chamado provider.request_provider_activation_consent nesta sala limpa com o modelo especificado.

Exemplo:

CALL samooha_by_snowflake_local_db.consumer.approve_provider_activation_consent(
  $cleanroom_name,
  'activation_my_template');

run_activation¶

Esquema:

CONSUMER

Descrição: executa um modelo que envia os resultados de volta para a conta Snowflake do consumidor ou provedor. O argumento consumer_direct_activation determina se esta é uma ativação de consumidor ou provedor.

Argumentos:

• cleanroom_name (cadeia de caracteres): nome da sala limpa em que a ativação será executada.

• sgment_name (cadeia de caracteres): cadeia de caracteres arbitrária usada para rotular as linhas geradas por esta execução de ativação. Cada execução de ativação adiciona novas linhas a uma tabela de resultados existente. Forneça uma cadeia de caracteres exclusiva neste campo cada vez que chamar esse procedimento para poder filtrar os resultados a uma execução específica.

• template_name (string) – Nome do modelo de ativação a ser chamado.

• consumer_tables (matriz de cadeias de caracteres): matriz de nomes de tabelas de consumidor totalmente qualificados a serem passados para o modelo.

• provider_tables (matriz de cadeias de caracteres): matriz de nomes de tabelas de provedor totalmente qualificados a serem passados para o modelo.

• activation_arguments (objeto) – Conjunto de valores-chave de argumentos a serem passados para o modelo.

• consumer_direct_activation (booliano, opcional): TRUE para enviar os resultados de volta à conta do consumidor, FALSE para enviar os resultados ao provedor. O padrão é FALSE.

Retorna: (string) Mensagem de sucesso.

Exemplo:

-- Run a consumer activation, as specified by the final TRUE argument.
SET segment_name = 'my_activation_segment';
CALL samooha_by_snowflake_local_db.consumer.run_activation(
  $cleanroom_name,
  $segment_name,
  $template_name,
  ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS'],
  ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS'],
  object_construct(
    'c_join_col', 'c.hashed_email',
    'p_join_col', 'p.hashed_email'
  ),
  TRUE);

dcr_health.provider_run_provider_activation_history¶

Descrição: retorna um histórico de solicitações de ativação do provedor para a sala limpa especificada. As solicitações de ativação do provedor iniciadas pelo provedor e pelo consumidor são mostradas. Esse procedimento fornece informações extras para ajudar na depuração de problemas com a ativação do provedor.

Argumentos:

• cleanroom_name (cadeia de caracteres): nome da sala limpa na qual a ativação foi solicitada. Você deve ser um provedor ou consumidor nessa sala limpa.

Retorna: (tabela): uma lista de solicitações de ativação com informações sobre cada 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);

create_template_request¶

Esquema:

CONSUMER

Descrição: envia uma solicitação ao provedor de uma sala limpa, solicitando que ele aprove um modelo personalizado para que possa ser adicionado à sala limpa. Consulte Modelos personalizados escritos pelo consumidor.

Argumentos:

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

• template_name (cadeia de caracteres): nome do modelo que será adicionado. Devem ser todas letras minúsculas, números, espaços ou sublinhados. Os nomes dos modelos de ativação devem começar com «activation».

• template_definition (cadeia de caracteres): o modelo JinjaSQL. Conheça a sintaxe do modelo.

Retorna: (string) Mensagem de sucesso.

Exemplo:

CALL samooha_by_snowflake_local_db.consumer.create_template_request(
  $cleanroom_name,
  $template_name,
  $$
  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 %};
  $$);

get_sql_jinja¶

Esquema:

CONSUMER

Descrição: avalia um modelo JinjaSQL para uma instrução SQL. Esse procedimento é usado ao desenvolver modelos personalizados, para ver como o modelo será renderizado após o processamento com um determinado conjunto de parâmetros.

Esse procedimento pode processar apenas instruções JinjaSQL padrão; ele não pode processar extensões de sala limpa para JinjaSQL, como join_policy ou column_policy.

Argumentos:

• template_string (cadeia de caracteres): o código JinjaSQL que será processado. Há suporte apenas para o JinjaSQL padrão.

• arguments (objeto): um objeto em que os nomes dos campos correspondem às variáveis usadas no modelo.

Retorna: (string) a instrução SQL gerada pelo modelo enviado com os valores de variáveis fornecidos.

Exemplo:

CALL samooha_by_snowflake_local_db.consumer.get_sql_jinja(
$$
SELECT COUNT(*), IDENTIFIER({{ group_by_col }})
  FROM IDENTIFIER({{ my_table | sqlsafe }})
  INNER JOIN IDENTIFIER({{ source_table | sqlsafe }})
  ON IDENTIFIER({{ consumer_join_col }}) = IDENTIFIER({{ provider_join_col }})
  GROUP BY IDENTIFIER({{ group_by_col }});
$$,
object_construct(
'group_by_col', 'city',
'consumer_join_col', 'hashed_email',
'provider_join_col', 'hashed_email',
'my_table', 'mydb.mysch.t1',
'source_table', 'mydb.mysch.t2'));

Resposta:

SELECT COUNT(*), IDENTIFIER('city')
  FROM IDENTIFIER(mydb.mysch.t1)
  INNER JOIN IDENTIFIER(mydb.mysch.t2)
  ON IDENTIFIER('hashed_email') = IDENTIFIER('hashed_email')
  GROUP BY IDENTIFIER('city');

generate_python_request_template¶

Esquema:

CONSUMER

Descrição: gera um modelo de sala limpa do 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 o modelo final para consumer.create_template_request.

Para obter mais informações sobre modelos definidos pelo consumidor, consulte Modelos personalizados escritos pelo consumidor.

Argumentos:

• function_name (cadeia de caracteres): o nome da função que é usado por um modelo para chamar a sua função.

• arguments (matriz de pares de cadeias de caracteres): uma matriz de argumentos exigidos pela função function_name. Cada elemento é um par delimitado por espaço que fornece 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): matriz de nomes de pacotes necessários para seu código Python. Se não houver, especifique uma matriz vazia. Consulte a lista completa de pacotes compatíveis.. Exemplo: ['pandas','numpy'].

• imports: [Sem suporte: não usar]

• rettype (cadeia de caracteres): o tipo de retorno SQL no Snowflake da função. Exemplos: INTEGER, VARCHAR.

• handler (cadeia de caracteres): o nome da função principal do manipulador no código Python. Normalmente, isso é 'main'.

• code (cadeia de caracteres): a implementação de código Python. Se você incluir uma importação e o manipulador designado for definido em uma importação, a cadeia de caracteres poderá ficar vazia.

Retorna: (cadeia de caracteres) retorna a UDF Python com um espaço reservado para o seu modelo JinjaSQL. Você deve inserir um caractere de escape nas marcas aninhadas $$ ou de aspas simples (”) aninhadas corretamente antes de passar a cadeia de caracteres do modelo para consumer.create_template_request. Leia Código enviado pelo consumidor.

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.
  [],                                -- Reserved.
  'INTEGER',                         -- SQL return type.
  'main',                            -- Standard 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)
    $$
);

O exemplo a seguir mostra o código gerado. Substitua <INSERT SQL TEMPLATE HERE> pelo código JinjaSQL do seu modelo.

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 run the SQL query
LET SQL_TEXT varchar := $$<INSERT SQL TEMPLATE HERE>$$;

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

END;  

list_template_requests¶

Esquema:

CONSUMER

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

Argumentos:

• cleanroom_name (cadeia de caracteres): a sala limpa para as quais listar as solicitações de modelo.

Retorna: uma tabela com as seguintes colunas:

• request_id: ID da solicitação, gerado pelo sistema de salas limpas.

• provider_identifier: localizador da conta do provedor.

• template_name: nome do modelo que o consumidor especificou na solicitação.

• template_definition: código-fonte do modelo que o consumidor solicitou que fosse adicionado à sala limpa.

• request_status: status da solicitação: PENDING, APPROVED ou REJECTED.

• reason: se o status da solicitação é REJECTED, o provedor deve informar o motivo da rejeição aqui.

Exemplo:

CALL samooha_by_snowflake_local_db.consumer.list_template_requests($cleanroom_name);

describe_cleanroom¶

Esquema:

CONSUMER

Descrição: apresenta um resumo das principais informações sobre a sala limpa especificada, incluindo modelos, conjuntos de dados e políticas. Se um modelo foi oculto aplicando o argumento is_obfuscated, é necessário usar o Snowflake Enterprise Edition ou superior para ver o nome do modelo.

Argumentos:

• cleanroom_name (cadeia de caracteres): nome da sala limpa a ser descrita.

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

Exemplo:

CALL samooha_by_snowflake_local_db.consumer.describe_cleanroom($cleanroom_name);

view_provider_datasets¶

Esquema:

CONSUMER

Descrição: lista todos os conjuntos de dados que o provedor adicionou à sala limpa.

Argumentos:

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

Retorna: (tabela) uma tabela dos conjuntos de dados adicionados pelo provedor. Use o nome da tabela retornado aqui em suas consultas.

Exemplo:

CALL samooha_by_snowflake_local_db.consumer.view_provider_datasets($cleanroom_name);

view_added_templates¶

Esquema:

CONSUMER

Descrição: lista todos os modelos na sala limpa. Se um modelo foi oculto aplicando o argumento is_obfuscated, é necessário usar o Snowflake Enterprise Edition ou superior para visualizar o modelo.

Argumentos:

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

Retorna: uma lista dos modelos nesta sala limpa e o código-fonte de cada um (exceto quando o provedor oculta o modelo).

Exemplo:

CALL samooha_by_snowflake_local_db.consumer.view_added_templates($cleanroom_name);

is_consumer_run_enabled¶

Esquema:

LIBRARY

Descrição: verifica se a análise executada pelo consumidor está habilitada na sala limpa especificada. Essa função está habilitada por padrão, mas um provedor de sala limpa pode desabilitá-la.

Argumentos:

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

Retorna: (cadeia de caracteres) se a 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);

view_cleanrooms¶

Esquema:

CONSUMER

Descrição: lista todas as salas limpas unidas (instaladas) ou que podem ser unidas por esta conta. Para ver apenas as salas limpas instaladas, execute consumer.view_installed_cleanrooms. Para ver as salas limpas criadas por esta conta, chame provider.view_cleanrooms.

Argumentos: nenhum

Retorna: (tabela) Todas as clean rooms instaladas ou convidadas para essa conta.

Exemplo:

CALL samooha_by_snowflake_local_db.consumer.view_cleanrooms();

view_installed_cleanrooms¶

Esquema:

CONSUMER

Descrição: lista todas as salas limpas instaladas (unidas) nesta conta. Para ver as salas limpas unidas e não unidas, chame consumer.view_cleanrooms. Para ver todas as salas limpas criadas por esta conta, chame provider.view_cleanrooms.

Argumentos: nenhum

Retorna: (tabela) as clean rooms instaladas nessa conta.

Exemplo:

CALL samooha_by_snowflake_local_db.consumer.view_installed_cleanrooms();

is_dp_enabled¶

Esquema:

CONSUMER

Descrição: verifica se a privacidade diferencial está habilitada na sala limpa. A sala limpa deve estar instalada para verificar esse valor.

Argumentos:

• cleanroom_name (cadeia de caracteres)

Retorna: (booliano) se a privacidade diferencial está ou não habilitada na sala limpa.

Exemplo:

CALL samooha_by_snowflake_local_db.consumer.is_dp_enabled($cleanroom_name);

view_remaining_privacy_budget¶

Esquema:

CONSUMER

Descrição: exibe o orçamento de privacidade restante que pode ser usado para fazer consultas na sala limpa. Quando o orçamento for atingido, outras chamadas para run_analysis não serão permitidas até que ele seja redefinido. O orçamento é redefinido diariamente.

Argumentos:

• cleanroom_name (cadeia de caracteres) nome da sala limpa. A sala limpa deve estar instalada para a execução deste procedimento.

Retorna: (valor flutuante) o orçamento de privacidade restante.

Exemplo:

CALL samooha_by_snowflake_local_db.consumer.view_remaining_privacy_budget($cleanroom_name);

set_privacy_settings¶

Esquema:

CONSUMER

Descrição: define as configurações de privacidade para as análises executadas pelo provedor (incluindo ativação) que usam modelos personalizados. Substitui todos os valores já definidos. Cada vez que você chama esse método, ele apaga todas as configurações anteriores.

Argumentos:

• cleanroom_name (cadeia de caracteres): nome da sala limpa à qual estas configurações devem ser aplicadas.

• privacy_settings (string) – Um objeto do tipo cadeia de caracteres JSON que especifica as configurações de privacidade quando os modelos personalizados são executados por um provedor. Aqui está a sintaxe do objeto:

  '{
    "null" : <template_config>
  }'
  

  Copy

  template_config é um objeto com configurações diferenciadas de privacidade e agregação. Consulte Configurações de privacidade disponíveis para ver quais campos você pode fornecer nesse objeto.

Exemplo:

-- Apply differential privacy for provider-run analysis using all custom templates.
CALL samooha_by_snowflake_local_db.consumer.set_privacy_settings(
  $cleanroom_name,
  PARSE_JSON('{
    "null":{ "differential": 1, "epsilon": 0.1, "privacy_budget": 3 }
    }')
  );

Retorna: (string) Mensagem de sucesso.

start_or_update_service¶

Esquema:

CONSUMER

Descrição: cria e inicia a versão mais recente do Snowpark Container Services definida pelo provedor nesta sala limpa. Sempre que o provedor chamar provider.load_service_into_cleanroom para criar ou atualizar um contêiner, o consumidor deverá chamar consumer.start_or_update_service para atualizar o serviço.

O consumidor deve definir e iniciar o pool antes de chamar esse procedimento.

Argumentos:

• cleanroom_name (cadeia de caracteres): nome da sala limpa na qual o contêiner deve ser carregado.

• compute_pool_name (cadeia de caracteres): o nome de um pool de computação definido pelo consumidor nesta sala limpa. O pool já deve ter sido criado, e a sala limpa deve ter privilégios de acesso ao pool.

• service_options (objeto, opcional) – Um objeto que especifica parâmetros para esse serviço. As seguintes propriedades são compatíveis:

  • query_warehouse: (cadeia de caracteres, opcional) nome do warehouse que será usado neste serviço. Não precisa ser o mesmo warehouse que executa a sala limpa.

  • min_instances – (Inteiro, opcional) número mínimo de instâncias a serem usadas para esse serviço.

  • max_instances – (Inteiro, opcional) número mínimo de instâncias a serem usadas para esse serviço.

Retorna: (tabela) resultados do carregamento, se bem-sucedido. Gera um erro se não for bem-sucedido.

Exemplo:

CALL samooha_by_snowflake_local_db.consumer.start_or_update_service(
    $cleanroom_name,
    'dcr_lal_pool',
    object_construct(
        'query_warehouse', 'app_wh',
        'min_instances', '1',
        'max_instances', '1'
));

set_cleanroom_ui_accessibility¶

Esquema:

CONSUMER

Descrição: mostra ou oculta salas limpas na UI de salas limpas para consumidores na conta atual.

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 na UI de salas limpas de todos os usuários da conta de consumidor atual. Ainda é possível acessar a sala limpa por meio de 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.consumer.set_cleanroom_ui_accessibility(
  $cleanroom_name,
  'HIDDEN');

manage_datastats_task_on_account¶

Esquema:

CONSUMER

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.

Argumentos:

• enable (booliano): TRUE para habilitar ou FALSE para desabilitar a tarefa.

Retorna: (string) Mensagem de sucesso.

Exemplo:

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

enable_local_db_auto_upgrades¶

Esquema:

LIBRARY

Descrição: habilita a tarefa que atualiza automaticamente o ambiente Snowflake Data Clean Rooms quando há lançamento de novos procedimentos ou funcionalidades (a tarefa é samooha_by_snowflake_local_db.admin.expected_version_task). Chame esse procedimento para automatizar as atualizações, em vez de chamar library.apply_patch a cada novo lançamento.

Você pode desabilitar essa tarefa para reduzir os custos, mas recomendamos deixá-la em execução para garantir que tenha a versão mais recente do ambiente de salas limpas em seu sistema.

Argumentos: nenhum

Retorna: (cadeia de caracteres) mensagem de sucesso ou falha.

Exemplo:

CALL samooha_by_snowflake_local_db.library.enable_local_db_auto_upgrades();

disable_local_db_auto_upgrades¶

Esquema:

LIBRARY

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

Argumentos: nenhum

Retorna: (cadeia de caracteres) mensagem de sucesso ou falha.

Exemplo:

CALL samooha_by_snowflake_local_db.library.disable_local_db_auto_upgrades();

apply_patch¶

Esquema:

LIBRARY

Descrição: atualiza seu ambiente de salas limpas habilitando novos recursos e correções em seu ambiente. Chame esse procedimento quando uma nova versão do ambiente de salas limpas for lançada. (Em geral, isso ocorre semanalmente. Consulte as entradas de salas limpas em Atualizações recentes de recursos.) Esse procedimento atualiza SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.

Você pode automatizar as atualizações de patch chamando library.enable_local_db_auto_upgrades. Recomendamos habilitar as atualizações automáticas.

Argumentos: nenhum

Retorna: (string) Mensagem de sucesso.

Exemplo:

CALL samooha_by_snowflake_local_db.library.apply_patch();

patch_cleanroom¶

Esquema:

CONSUMER

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.consumer.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();

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 no nível da 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: (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 as tabelas 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: (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 no nível da 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: (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 as exibições 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: (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 das 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 (cadeia de caracteres): 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 no nível da tabela. Uma matriz ou cadeia de caracteres representando o nome da tabela totalmente qualificado pode ser passada para cancelar o registro das tabelas. Os usuários não podem vincular tabelas com registro cancelado 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: (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 das tabelas em um esquema de acesso gerenciado (ou seja, um esquema criado com 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 no nível da 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 com registro cancelado 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: (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 das 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: (string) Mensagem de sucesso.

Exemplo:

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