Usar o Snowflake Collaboration Data Clean Rooms

Este tópico apresenta um guia de alto nível para usar o Collaboration Data Clean Rooms. Ele também inclui detalhes de todas as etapas principais necessárias para criar ou participar de uma colaboração.

Requisitos

  • Você deve ter atualizado para a versão mais recente do Snowflake Data Clean Rooms.

  • Proprietários e provedores de dados devem usar o Snowflake Enterprise Edition. Os executores de análise podem usar a Standard Edition.

  • Você precisa de acesso à API Collaboration Data Clean Rooms para ver ou gerenciar colaborações. Para obter mais informações, consulte Gerenciar o acesso à API Collaboration DCR.

  • Você deve desabilitar as funções secundárias em seu ambiente ao usar a API Collaboration:

    USE SECONDARY ROLES NONE;

Fluxo de trabalho básico de colaboração de sala limpa

Veja a seguir um cenário simples de colaboração de sala limpa:

  1. Opcionalmente, o proprietário da colaboração registra modelos ou ofertas de dados que deseja que apareçam na configuração inicial da colaboração.

  2. O proprietário pode pedir que qualquer colaborador pretendido registre os modelos ou as ofertas de dados que deseja que apareçam na configuração inicial da colaboração. Sendo assim, os colaboradores fornecem os IDs dos recurso dos itens que eles registraram.

  3. O proprietário cria uma colaboração. A colaboração é definida por uma especificação YAML que lista os colaboradores, suas funções e todos os recursos que devem estar presentes na versão inicial da colaboração.

    • Quando uma colaboração é criada, o conjunto de colaboradores e as respectivas funções são fixos: somente colaboradores com uma função na definição da colaboração são convidados a ingressar. Da mesma forma, o conjunto de executores de análise é fixo. No entanto, qualquer colaborador também pode se tornar um provedor de dados vinculando novos dados à colaboração.

    • Se a colaboração incluir usuários em outras regiões de hospedagem na nuvem, eles deverão habilitar o preenchimento automático entre nuvens em suas contas para que possam revisar e ingressar na colaboração.

  4. O proprietário ingressa na colaboração que criou, o que torna a colaboração ativa. A colaboração fica visível e qualquer colaborador na especificação pode ingressar nela.

  5. Os colaboradores revisam e ingressam na colaboração.

  6. Os colaboradores podem adicionar recursos à colaboração, como modelos e, se eles forem provedores de dados, ofertas de dados.

  7. Os executores de análise podem executar todos os modelos atribuídos a eles na colaboração, usando os dados disponíveis para eles na colaboração (e, opcionalmente, os dados locais não compartilhados). O executor de análise arca com o custo da análise. Os modelos podem retornar resultados de consulta na resposta ou ativar resultados para o autor da chamada ou outro colaborador.

As seções a seguir descrevem os detalhes de cada uma dessas etapas.

Criar uma colaboração

Para criar uma colaboração, elabore uma especificação de colaboração que defina todos os colaboradores e suas funções. O proprietário da colaboração pode registrar e vincular outros recursos que deseja disponibilizar na colaboração inicial e incluí-los na especificação da colaboração. Se o proprietário pretende usar recursos de colaboradores, ele também pode solicitar que esses usuários registrem seus recursos e forneçam ao proprietário os IDs dos recursos para incluir na especificação da colaboração.

Depois disso, o proprietário chama INITIALIZE para começar a criar a colaboração. Por padrão, INITIALIZE também adiciona automaticamente o proprietário à colaboração. Este é um processo assíncrono, portanto ele deve chamar GET_STATUS até que o status seja JOINED. Quando o status da colaboração é JOINED, a colaboração está ativa e todos os colaboradores podem ver e ingressar na colaboração.

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.INITIALIZE(
$$
api_version: 2.0.0
spec_type: collaboration
name: my_first_collaboration
owner: alice
collaborator_identifier_aliases:
  alice: example_com.acct_abc
  bob: another_example.acct_xyz
analysis_runners:
  bob:
    data_providers:
      alice:
        data_offerings: []
      bob:
        data_offerings: []
  alice:
    data_providers:
      alice:
        data_offerings: []
      bob:
        data_offerings: []
    templates: []
$$,
'APP_WH'
);
SET collaboration_name = '<collaboration_name>';

-- INITIALIZE automatically joins the owner. Check status until JOINED.
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.GET_STATUS($collaboration_name);

-- Collaboration is visible here when it's joined.
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.VIEW_COLLABORATIONS();

Adicionar recursos a uma colaboração

Qualquer colaborador pode adicionar recursos a uma colaboração ou remover recursos que ele adicionou à colaboração. Há duas etapas para adicionar um recurso a uma colaboração:

  1. O proprietário do recurso cria uma especificação de definição do recurso e a utiliza para registrar o recurso em sua conta. É possível registrar o recurso no registro padrão da sua conta ou usar um registro personalizado.

  2. Um colaborador vincula o recurso a uma colaboração. Depois que o recurso for vinculado, ele poderá ser usado pelos colaboradores designados. Alguns tipos de recursos, como modelos, podem ser vinculados por qualquer colaborador; outros recursos, como ofertas de dados, podem ser vinculados somente por usuários com a função de provedor de dados. Normalmente, os recursos estão disponíveis apenas para colaboradores específicos, conforme definido na especificação da colaboração e por quem compartilhou os recursos.

Os recursos podem ser adicionados a uma colaboração antes ou depois que ela é criada.

Os recursos oferecem suporte a controle de versão; no entanto, criar um novo recurso com uma nova versão não remove a versão anterior da colaboração.

Os recursos são nomeados de forma exclusiva combinando o nome e a versão fornecidos pelo usuário (e o alias, no caso de ofertas de dados).

Você pode adicionar os seguintes recursos a uma colaboração:

Modelos

Trata-se de modelos de sala limpa JinjaSQL que podem ser executados por colaboradores especificados. Qualquer colaborador pode registrar e adicionar um modelo a uma colaboração, desde que todos os colaboradores afetados aprovem a solicitação, conforme descrito nas etapas a seguir. Você apenas pode adicionar ou remover modelos que sua conta tenha registrado.

Para adicionar um modelo a uma colaboração:

  1. Elabore um modelo para a colaboração e incorpore-o a uma especificação de modelo.

  2. Registre o modelo chamando REGISTRY.REGISTER_TEMPLATE. Esse procedimento retorna um ID do modelo.

  3. Vincule o modelo. O processo depende se a colaboração já existe:

    • Para adicionar um modelo antes que a colaboração seja criada, forneça o ID do modelo para o proprietário da colaboração, que o adiciona à especificação da colaboração, definindo quem pode executá-lo.

       alice:
   data_providers:
     bob:
       data_offerings: []
   templates:
   - id: bob_template_v1 # Alice can run this template, seemingly registered by bob.

    • Para adicionar um modelo a uma colaboração existente, você deve solicitar permissão de todos os colaboradores afetados pelo modelo. Siga as etapas a seguir para adicionar um modelo a uma colaboração existente:

      1. Chame REGISTER_TEMPLATE para registrar o modelo em sua conta, o que o torna disponível para adição a colaborações.

      2. Chame ADD_TEMPLATE_REQUEST com o ID do modelo para iniciar o fluxo de aprovação para adicionar o modelo a uma colaboração específica, para usuários designados.

        Todos os colaboradores afetados pelo recurso veem a solicitação ao chamar VIEW_UPDATE_REQUESTS.

      3. Os colaboradores que veem a solicitação com status PENDING devem chamar APPROVE_UPDATE_REQUEST ou REJECT_UPDATE_REQUEST.

        • Se algum colaborador rejeitar a solicitação, a solicitação de atualização será rejeitada.

        • Os colaboradores não podem mais tarde mudar uma aprovação para rejeição, ou vice-versa.

        Quando o status da solicitação é APPROVED, o modelo está disponível para os usuários especificados na solicitação de adição de modelo. Se a solicitação for REJECTED, qualquer motivo fornecido pela parte que a rejeitou ficará visível no relatório de solicitações. Pode haver um pequeno atraso para um modelo ficar disponível depois de ser aprovado por todos os usuários. Chame view_templates se quiser garantir que o modelo esteja disponível para uso.

Dica

Para ver quais modelos você registrou, chame REGISTRY.VIEW_REGISTERED_TEMPLATES.

Criação de modelo para uma colaboração

Os modelos de colaboração são iguais aos modelos de sala limpa, com algumas considerações especiais:

  • Tabelas compartilhadas listadas na colaboração são usadas para preencher a variável source_table do modelo.

  • my_table é usado somente se um executor de análise quiser usar dados locais e não compartilhados. Se você usar a variável my_table em um modelo, esteja ciente de que as tabelas atribuídas a essa variável não serão compartilhadas com a colaboração.

  • As colunas das fontes de dados podem ter novos nomes quando expostas ao modelo ou usuário. Consulte Renomeação da coluna de origem para saber como e quando as colunas de origem são renomeadas. Modelos e argumentos fornecidos pelo usuário (como um nome de coluna de junção) deverão usar o nome final, não o nome original, se a coluna for renomeada.

  • Os modelos de ativação em uma colaboração não precisam ser nomeados activation_template_name. Todos os outros requisitos de modelo de ativação permanecem aplicáveis.

Para obter informações sobre a sintaxe de modelo personalizado no Snowflake Data Clean Rooms, consulte Referência de modelo de sala limpa personalizado.

Ofertas de dados

Uma oferta de dados é um conjunto de uma ou mais exibições de dados compartilhadas com executores de análise específicos em uma colaboração. As ofertas de dados podem ser adicionadas por qualquer provedor de dados listado em uma colaboração. As ofertas de dados são expostas em um formato com escopo, como data offering ID.alias, em que o alias é uma exibição específica na oferta de dados. Você pode compartilhar ofertas de dados com um determinado colaborador somente se estiver listado como provedor de dados para esse executor de análise na especificação da colaboração.

Uma oferta de dados é uma exibição ativa dos dados, não um instantâneo dos dados no momento em que a oferta de dados é criada ou registrada. Todas as políticas do Snowflake aplicadas aos dados de origem ficam ativas na colaboração.

Quando você registra uma oferta de dados, o Snowflake cria uma exibição para cada fonte de dados listada na especificação da oferta de dados. A exibição inclui apenas as colunas listadas na especificação da oferta de dados. Ao vincular uma oferta de dados a uma colaboração, o Snowflake cria uma cópia da exibição, com acesso protegido para qualquer executor de análise que possa acessar essa oferta de dados, de acordo com a especificação da colaboração. Se você mover, renomear ou alterar as permissões de acesso das tabelas subjacentes, a oferta de dados se tornará inutilizável por meio dos links que já foram registrados.

Se você usa o Snowflake Standard Edition, não pode compartilhar ofertas de dados com outros colaboradores, mas pode usar seus próprios dados em uma consulta.

Requisitos:

As ofertas de dados são adicionadas a uma colaboração seguindo estas etapas:

  1. Crie uma especificação da oferta de dados para seus dados.

  2. Registre a oferta de dados chamando REGISTRY.REGISTER_DATA_OFFERING, que retorna um ID da oferta de dados.

    Essa etapa torna a oferta de dados disponível para ser vinculada a qualquer colaboração que você possa acessar. Você pode usar o mesmo ID para compartilhar uma oferta de dados com várias colaborações.

  3. A próxima etapa depende se a colaboração foi ou não criada:

    • Se a colaboração ainda não foi criada, o provedor de dados fornece o ID da oferta de dados ao criador da colaboração para adicionar à definição da colaboração. Quando uma oferta de dados é adicionada à definição da colaboração, a oferta de dados fica visível para qualquer pessoa na colaboração depois que o provedor de dados ingressa na colaboração.

    • Se a colaboração foi criada, o provedor de dados ingressa na colaboração e chama COLLABORATION.LINK_DATA_OFFERING com o ID da oferta de dados, o nome da colaboração e com quem os dados podem ser compartilhados. Pode haver um pequeno atraso para uma oferta de dados ficar disponível para uso depois de ser aprovada por todos os usuários. Chame view_data_offerings se quiser garantir que os dados estejam disponíveis para uso.

    Você pode remover recursos de dados de uma colaboração chamando unlink_data_offering.

Cada oferta de dados representa uma ou mais tabelas ou exibições. As tabelas individuais são acessadas usando a sintaxe collaborator alias.data offering ID.dataset alias, em que o ID da oferta de dados é uma combinação dos valores de nome e versão fornecidos pelo usuário, e o alias é uma única tabela na oferta. Considere o nome, a versão e o alias como um sistema de escopo ao registrar suas ofertas de dados.

Por exemplo, você pode registrar a seguinte oferta de dados de vendas, em que cada tabela é específica a um estado dos US:

api_version: 2.0.0
spec_type: data_offering
version: v0
name: examplecorp_sales_by_state
datasets:
 - alias: AL
   data_object_fqn: mydb.mysch.al_data
 - alias: NY
   data_object_fqn: mydb.mysch.ny_data
 - alias: CA
   data_object_fqn: mydb.mysch.ca_data

O executor de análise faz referência a essas tabelas como data offering id.AL, data offering id.NY ou data offering id.CA.

As ofertas de dados não estarão visíveis em uma colaboração até que o usuário que a registrou ingresse na colaboração.

Dica

Se você não tiver OWNERSHIP dos dados que compartilha, receberá um erro ao tentar ingressar na colaboração ou vincular sua oferta de dados. A mensagem de erro fornece informações sobre um comando SQL que o ACCOUNTADMIN deve executar para conceder acesso aos dados à colaboração. Depois que o ACCOUNTADMIN executar o comando, você poderá ingressar na colaboração. Consulte mais informações.

Ao executar uma consulta, os executores de análise passam as ofertas de dados por ID para o parâmetro source_tables de COLLABORATION.RUN.

Para ver suas ofertas de dados registradas, chame VIEW_REGISTERED_DATA_OFFERINGS.

Aplicar políticas de uso aos seus dados

Há duas maneiras de aplicar uma política de coluna do Snowflake, como uma política de junção ou agregação, aos seus dados compartilhados:

  • Aplique a política aos dados de origem. As políticas aplicadas aos dados de origem são executadas nos conjuntos de dados expostos em uma colaboração. Assegure-se de comunicar sua política ao usuário.

  • Aplique a política à oferta de dados quando usada em consultas de forma livre. Se você permitir consultas de forma livre em suas ofertas de dados, poderá especificar políticas de coluna a serem executadas nas consultas de forma livre a seus dados. Determine as políticas de coluna para consultas de forma livre na especificação da oferta de dados. Essas políticas são aplicadas às políticas existentes do Snowflake em suas tabelas de origem.

Aplicar a política aos dados de origem

As políticas do Snowflake aplicadas aos dados de origem também se aplicam à exibição da oferta de dados na colaboração.

Se você aplicar políticas do Snowflake aos seus dados de origem, certifique-se de informar seus colaboradores sobre elas, para que eles não tentem executar, sem saber, uma consulta que faça junção a uma coluna que não pode ser unida ou que não se agrupe quando deveria. Você pode mencionar políticas do Snowflake no campo description da oferta de dados.

Aplicar a política à oferta de dados (somente para uso de consulta de forma livre)

Você pode aplicar as políticas do Snowflake a consultas de forma livre em seus dados compartilhados sem aplicá-las aos dados de origem. Essas políticas são aplicadas aos seus dados quando acessados por meio de consultas de forma livre, além das políticas do Snowflake aplicadas diretamente à tabela de origem.

Para adicionar políticas SQL de forma livre aos seus dados:

  1. Crie um tipo de política compatível com o Collaboration Data Clean Rooms.

  2. Adicione as seguintes informações à definição das usas ofertas de dados:

    • Defina allowed_analyses: template_and_freeform_sql.

    • Adicione uma seção freeform_sql_policies à definição do conjunto de dados.

    • Adicione as seções de tipo de política apropriadas em freeform_sql_policies, listando as políticas do Snowflake que você criou e a quais colunas de colaboração aplicá-las.

Os colaboradores veem os tipos de política aplicados aos seus dados quando chamam COLLABORATION.VIEW_DATA_OFFERINGS.

Você pode reutilizar uma política em várias colunas de várias tabelas.

Exemplo:

CREATE OR REPLACE AGGREGATION POLICY my_db.public.my_agg_policy AS ()
  RETURNS AGGREGATION_CONSTRAINT ->
    AGGREGATION_CONSTRAINT(MIN_GROUP_SIZE => 5);

Renomeação da coluna de origem

Os nomes das colunas expostos ao modelo ou ao autor da chamada SQL de forma livre são determinados pelos valores category e column_type que descrevem a coluna na definição da oferta de dados. A renomeação da coluna segue esta ordem de avaliação:

  • Se category da coluna é join_custom ou passthrough, o nome original da coluna é exposto.

  • Se category é join_standard, a coluna é renomeada para o valor column_type.

  • Se category é timestamp, a coluna é renomeada para timestamp na oferta de dados.

Por exemplo, se o nome da coluna na tabela de origem é user_email_address, como a coluna é exposta ao modelo ou SQL de forma livre depende da respectiva especificação na definição da oferta de dados:

  • Se a categoria da coluna é join_standard, e column_type está presente:

    ... Snippet from data offering yaml ...
schema_and_template_policies:
     user_email_address:
       category: join_standard
       column_type: hashed_email_sha256

    O valor column_type é usado em consultas e modelos:

    SELECT HASHED_EMAIL_SHA256 FROM source_table[0];

  • Se a categoria da coluna é join_custom:

    ... Snippet from data offering yaml ...
schema_and_template_policies:
     user_email_address:
       category: join_custom
       column_type: hashed_email_sha256

    O nome da coluna de origem é usado em consultas e modelos:

    -- column_type is ignored for join_custom columns.
SELECT user_email_address FROM source_table[0];

Ingressar em uma colaboração

Você deve ingressar em uma colaboração para que todos os recursos que você indicou para contribuir em uma colaboração estejam disponíveis na colaboração, ou para poder executar uma análise na colaboração.

  • O criador é incluído automaticamente ao chamar INITIALIZE (a menos que auto_join_warehouse seja fornecido). Se a junção automática estiver desativada, o criador chama JOIN separadamente.

  • Os não criadores chamam REVIEW e, depois, JOIN.

    Importante

    Se sua conta estiver em uma região de hospedagem na nuvem diferente daquela do proprietário da colaboração:

A ingressão é um processo assíncrono. Chame GET_STATUS para ver quando o status aparece como JOINED.

Execute uma análise

Você pode executar análises executando um modelo na consulta ou uma consulta SQL de forma livre nos dados de colaboração. Você deve ser um executor de análise designado em uma colaboração para poder executar uma análise. A especificação da colaboração determina se você pode executar um modelo, ativar resultados ou fazer consultas SQL de forma livre. Suas capacidades, assim como os dados e os modelos disponíveis para você usar, estão descritos na especificação da colaboração.

O executor de análise arca com o custo da execução de uma análise.

Executar uma análise com base em um modelo

Para executar uma análise com base em um modelo, visualize a lista de modelos que você pode executar, visualize a lista de ofertas de dados que você pode usar e chame COLLABORATION.RUN com seus valores, seja como parâmetros individuais ou como uma especificação da análise no formato YAML:

-- See which data offerings are available.
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.VIEW_DATA_OFFERINGS($collaboration_name);

-- See which templates you can run.
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.VIEW_TEMPLATES($collaboration_name);

-- Pass in the arguments in analysis YAML format.
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.RUN(
  $collaboration_name,
  $$
    api_version: 2.0.0
    spec_type: analysis
    name: My_analysis
    description: Sales results Q2 2025
    template: sales_join_template

    template_configuration:
      view_mappings:
        source_tables:
          -  user1_alias.data_offering_v1.table1
          -  user2_alias.another_data_offering_v1.table_2
      arguments:
         conv_purchase_id: PURCHASE_ID
         conv_purchase_amount: PURCHASE_AMOUNT
         publisher_impression_id: IMPRESSION_ID
         publisher_campaign_name: CAMPAIGN_NAME
         publisher_device_type: DEVICE_TYPE
  $$ );

Habilitar e executar consultas SQL de forma livre nos dados

Um provedor de dados pode permitir que os executores de análise façam consultas SQL em suas ofertas de dados de colaboração. Você deve ser membro de uma colaboração e ter a função de executor de análise com permissão para SQL de forma livre em uma oferta de dados para poder executar consultas SQL de forma livre nesses dados.

Etapas do provedor de dados

Para permitir que os colaboradores consultem um conjunto de dados pela linha de comando, defina allowed_analyses: template_and_freeform_sql na descrição do conjunto de dados. Os usuários que ingressam na colaboração podem executar consultas SQL de forma livre nos conjuntos de dados que eles podem acessar.

O seguinte YAML define um conjunto de dados que permite consultas de forma livre:

api_version: 2.0.0
version: 1
name: my_favorite_dataset
datasets:
  - alias: test_freeform_restricted_agg
    data_object_fqn: samooha_provider_sample_database.audience_overlap.customers
    object_class: custom
    allowed_analyses: template_and_freeform_sql
...

Etapas do executor de análise

  1. Para ver quais conjuntos de dados oferecem suporte a consultas de forma livre, depois de ingressar em uma colaboração, o executor de análise executa COLLABORATION.VIEW_DATA_OFFERINGS. A coluna FREEFORM_SQL_VIEW_NAME nos resultados mostra quais tabelas podem ser acessadas usando SQL de forma livre, e o nome da tabela a ser usado na consulta SQL.

    CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.VIEW_DATA_OFFERINGS($collaboration_name);

    +-------------------------------+------------------------+------------------------------+------------------------------+---------------------------------------+
|   template_view_name          | template_join_columns  | analysis_allowed_columns     | activation_allowed_columns   |      freeform_sql_view_name           |
+-------------------------------+------------------------+------------------------------+------------------------------+---------------------------------------+
| useralias.data_offering_alias |     ip_address         | email, name, age             |             SSN              | alias_name.test_data_offering_v0.customers|
+-------------------------------+------------------------+------------------------------+------------------------------+---------------------------------------+

  2. O colaborador pode consultar a tabela listada na coluna FREEFORM_SQL_VIEW_NAME usando consultas SQL de forma livre:

    SELECT * FROM alias_name.test_data_offering_v0.customers;

Todas as políticas aplicadas à tabela são executadas.

Executar uma análise com seus próprios dados ao usar a Standard Edition

Se você usa a Standard Edition, pode executar uma análise da maneira padrão. No entanto, não é possível adicionar seus dados à descrição da colaboração e compartilhá-los com outros usuários.

Para usar seus próprios dados em uma colaboração como usuário Standard Edition:

  1. Para registrar sua oferta de dados, chame REGISTRY.REGISTER_DATA_OFFERING. Você deve especificar os nomes das colunas.

  2. Chame COLLABORATION.LINK_LOCAL_DATA_OFFERING.

    Somente você pode ver sua oferta ao chamar COLLABORATION.VIEW_DATA_OFFERINGS. Outros colaboradores não verão sua fonte de dados listada.

  3. Use o ID da oferta de dados quando chamar COLLABORATION.RUN, seja no parâmetro local_template_view_names, seja no campo local_view_mappings.my_tables se passar um YAML de análise. local_template_view_names e local_view_mappings.my_tables preenchem o parâmetro my_table no modelo.

O exemplo a seguir mostra como executar um modelo usando a versão de formato YAML do procedimento de execução. Este exemplo inclui o campo my_tables, que é preenchido com a chamada de LINK_LOCAL_DATA_OFFERING.

-- See what data offerings are available. Your own local data will be listed here as well.
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.VIEW_DATA_OFFERINGS($collaboration_name);

-- Pass in the arguments in analysis YAML format.
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.RUN(
  $collaboration_name,
  $$
    api_version: 2.0.0
    spec_type: analysis
    name: my_analysis
    description: Cross-purchase results for Q4 2025
    template: mytemplate_v1

    template_configuration:
      view_mappings:
        source_tables:
          - ADVERTISER1.ADVERTISER_DATA_V1.CUSTOMERS
          - PUBLISHER.ADVERTISER_DATA_V1.CUSTOMERS
      local_view_mappings:
        my_tables:
          - PARTNER.MY_DATA_V1.MY_CUSTOMERS # Populate my_table array with my own table.
      arguments:  # Template arguments, as name: value pairs
         conv_purchase_id: PURCHASE_ID
         conv_purchase_amount: PURCHASE_AMOUNT
         publisher_impression_id: IMPRESSION_ID
         publisher_campaign_name: CAMPAIGN_NAME
         publisher_device_type: DEVICE_TYPE
  $$ );

Ativar os resultados da consulta

Nota

Se você não usa a função SAMOOHA_APP_ROLE, ou seja, você usa uma função gerenciada pelos procedimentos de gerenciamento de acesso, deve ter o privilégio REGISTER DATA OFFERING para ingressar em qualquer colaboração da qual você seja executor de análise e que inclua um campo activation_destinations na especificação da colaboração.

Para ativar os resultados de uma consulta:

  1. Certifique-se de que todas as colunas de ativação tenham as seguintes propriedades definidas na especificação apropriada:

    A especificação da oferta de dados para a tabela com a coluna ativada deve definir activation_allowed: TRUE para essa coluna:

     api_version: 2.0.0
 spec_type: data_offering
 name: 2025_orders
 version: 2025_01_01_v1
 description: Activating Cleveland sales results for 2025

 datasets:
  - alias: customers
    data_object_fqn: db1.schema1.orders
    allowed_analyses: template_only
    object_class: custom
    schema_and_template_policies:
      email:
        category: join_standard
        column_type: hashed_email_sha256
        activation_allowed: TRUE
      purchase_amount:
        category: passthrough
        activation_allowed: TRUE

    Nota

    Qualquer coluna usada no modelo com o filtro activation_policy aplicado deve ter seu valor activation_allowed definido como TRUE na especificação da oferta de dados. O exemplo a seguir mostra um modelo com a política de ativação aplicada a duas colunas fornecidas pelo executor de análise:

    BEGIN
  CREATE OR REPLACE TABLE cleanroom.activation_data_analysis_results AS
    SELECT count(*) AS ITEM_COUNT, c.status, c.age_band
    FROM IDENTIFIER({{ my_table[0] }}) AS c
    JOIN IDENTIFIER({{ source_table[0] }}) AS p
    ON {{ c_join_col | sqlsafe | activation_policy }} = {{ p_join_col | sqlsafe | activation_policy }}
    GROUP BY c.status, c.age_band
    ORDER BY c.age_band;
  RETURN 'analysis_results';
END;

  2. O executor de análise chama RUN para executar a análise.

    • Se ativar para você mesmo, os resultados ficarão disponíveis imediatamente na conta do autor da chamada na tabela consumers_database.ACTIVATION_RESULTS.CONSUMER_DIRECT_ACTIVATION_SUMMARY. Para saber como visualizar os resultados da consulta, veja a última etapa.

    • Se ativar para outro colaborador:

      1. O colaborador chama VIEW_ACTIVATIONS até retornar o status SHARED. A ativação para outra conta pode levar um tempo considerável para grandes conjuntos de resultados, pois os dados devem ser transferidos para a conta do colaborador e descriptografados.

      2. Quando o status da ativação é SHARED, o colaborador chama PROCESS_ACTIVATION para enviar os resultados à conta dele. A resposta a PROCESS_ACTIVATION inclui os nomes de tabelas e segmentos. Isso define o status da ativação como PROCESSED.

  3. Para recuperar os resultados da consulta, execute o seguinte comando SQL, fornecendo o nome da tabela de resultados e, opcionalmente, um nome de segmento para filtrar os resultados:

    SELECT *
  FROM <results_table_name>
    [WHERE segment = <segment_name>];

Sair ou excluir uma colaboração

  • Para sair de uma colaboração, os não proprietários chamam COLLABORATION.LEAVE. Todas as ofertas de dados fornecidas por eles serão removidas da colaboração. Não é possível reingressar em uma colaboração depois que você sai dela.

  • Os proprietários de colaboração não podem sair de uma colaboração. A propriedade não pode ser transferida. Um proprietário de colaboração pode descartar uma colaboração para todos os colaboradores chamando COLLABORATION.TEARDOWN.

Ambos os processos são assíncronos. Você deve chamar GET_STATUS para monitorar o status e chamar LEAVE ou TEARDOWN novamente quando GET_STATUS mostra o status como LOCAL_DROP_PENDING.

Habilitar o preenchimento automático entre nuvens

Se você não estiver na mesma região de host de nuvem que o proprietário da colaboração, será necessário habilitar o preenchimento automático entre nuvens (LAF) em sua conta para você ingressar na colaboração. Se você tentar revisar uma colaboração em outra região de nuvem e o LAF não estiver habilitado em sua conta, ou se não tiver as permissões adequadas, você receberá um erro ao chamar REVIEW na colaboração.

Nota

Quando o preenchimento automático entre nuvens é usado em uma colaboração:

  • Os dados são replicados na conta de cada colaborador que pode acessá-los.

  • Os dados também são replicados na região do proprietário, quer ele possa ou não acessar a oferta de dados. No entanto, a capacidade de acessar os dados é determinada pelas regras de compartilhamento da oferta de dados.

Você pode determinar sua própria região de host de nuvem executando SELECT CURRENT_REGION();.

Para habilitar o preenchimento automático entre nuvens em sua conta:

  1. Um administrador da organização deve habilitar o LAF em sua conta chamando SYSTEM$ENABLE_GLOBAL_DATA_SHARING_FOR_ACCOUNT. Para obter mais informações, consulte Gerenciar privilégios para preenchimento automático.

  2. Para ter os privilégios adequados para revisar ou ingressar em uma colaboração LAF, use SAMOOHA_APP_ROLE ou uma função concedida ao privilégio no nível da conta MANAGE LISTING AUTO FULFILLMENT.

Os colaboradores localizados em uma região de host de nuvem diferente enfrentam um atraso maior nos dados devido à frequência de replicação. A frequência de replicação ainda não é configurável no Collaboration Data Clean Room.

Exemplo: colaboração de duas partes

O exemplo a seguir demonstra uma colaboração de duas partes, em que uma parte (chamada «alice») é criadora da colaboração, provedora de dados para si mesma e para Bob e executora de análise. A outra parte (chamada «bob») é o provedor de dados para si mesmo e para alice e o executor de análise.

O exemplo demonstra as seguintes ações:

  • Criar uma colaboração

  • Registrar modelos e ofertas de dados

  • Adicionar um modelo e uma oferta de dados no momento da criação da colaboração

  • Ingressar em uma colaboração

  • Adicionar modelos e recursos a uma colaboração existente

  • Executar uma análise

Para executar este exemplo, você deve ter duas contas separadas com o Snowflake Data Clean Rooms instalado.

Você pode baixar os arquivos e carregá-los em sua conta Snowflake ou copiar e colar o código de exemplo em planilhas em duas contas separadas usando o Snowsight.

Baixe os arquivos SQL de origem e carregue-os em duas contas separadas que tenham o Snowflake Data Clean Rooms instalado: