Uso das clean rooms com o Snowpark¶

Projeto geral de fluxos de uso complexos¶

Embora você possa gerar seus dados e exibi-los chamando um único modelo, em muitos casos é melhor separar as etapas de geração de dados das etapas de exibição de resultados. Dessa forma, o consumidor pode visualizar os resultados várias vezes sem acionar um novo cálculo a cada vez, ou visualizar dados de vários pontos do processo. Para dividir o fluxo em vários estágios acessíveis ao usuário, crie modelos separados para acionar a geração ou o processamento de dados e para visualizar os resultados armazenados. Leia mais sobre como projetar fluxos de uso complexos.

Pré-requisitos¶

• As clean rooms que executam as UDFs Snowpark devem ser executadas na API de clean rooms; elas não podem ser executadas nas UI de clean rooms.

• Você deve entender os seguintes tópicos:

  • Os princípios básicos da criação de uma clean room em código.

  • A Snowpark Python API.

  • Como fazer upload das UDFs Python em uma clean room.

  • Como criar modelos personalizados.

  • Leia sobre como projetar fluxos de várias etapas para entender o funcionamento das tabelas internas.

Uso da Snowpark API em uma clean room¶

Usar a Snowpark API no código Python de sua clean room é o mesmo que carregar e executar qualquer outra UDF Python, exceto pelo fato de que você precisa vincular a biblioteca snowflake-snowpark-python.

Crie UDFs, UDTFs e procedimentos executando SQL e usando session.sql no esquema cleanroom em vez de usar os decoradores do Snowpark. Por exemplo:

session.sql("CREATE OR REPLACE FUNCTION cleanroom.udf(...")

Copy

Etapas básicas¶

Aqui estão as etapas básicas para usar a Snowpark API por meio de uma UDF ou UDTF em sua clean room:

Provedor

1. Crie a clean room, defina a diretiva de lançamento padrão e vincule seus dados da maneira padrão.

2. Como você provavelmente tem um caso de uso muito específico projetado para o seu código, provavelmente não precisará adicionar políticas de junção ou coluna à clean room, embora possa fazê-lo.

3. Carregue o código do manipulador personalizado do Snowpark na clean room chamando provider.load_python_into_cleanroom. O código deve carregar o pacote snowflake-snowpark-python, no mínimo, além de quaisquer outros pacotes de que você precise. As UDFs podem processar e retornar dados linha por linha, mas os casos de uso do Snowpark normalmente geram uma tabela de saída que é lida chamando um modelo de resultados separado.

4. Atualize a diretiva de lançamento padrão (porque as adições de código geram uma nova versão de patch).

5. Crie e carregue um modelo personalizado para executar seu código do Snowpark. A única maneira de executar uma UDF é acioná-la a partir de um modelo que chama a UDF. Alguns detalhes sobre o modelo de chamada de UDF:

   • Ele deve chamar a função usando o alias e os parâmetros que você especificou em provider.load_python_into_cleanroom. O modelo deve usar o namespace cleanroom para chamar o alias de sua função.

   • Se a UDF gravar os resultados em uma tabela na clean room e o nome da tabela for diferente para cada execução, o modelo de geração de resultados deverá retornar o nome da tabela de resultados e o modelo de resultados deverá receber o nome da tabela como argumento do usuário.

6. Carregue um modelo SQL personalizado para acessar a tabela de resultados gerada por sua UDF Snowpark, se você tiver gerado uma tabela de resultados intermediária. Use o nome da tabela de resultados codificado ou permita que o usuário passe o nome da tabela gerado pelo seu código e retornado pelo modelo de geração de resultados.

7. Adicione colaboradores e publique a clean room da maneira padrão.

Consumidor

O consumidor instala a clean room e executa a análise da maneira padrão. Se a geração de dados e a leitura de resultados forem divididas em modelos separados, o consumidor precisará chamar cada modelo em sequência.

Exemplo de código¶

O código de exemplo a seguir demonstra como fazer upload e executar uma regressão linear de “alcance na contagem de impressões” para estimar o coeficiente angular.

1. O consumidor primeiro executa o modelo prod_calculate_regression que executa uma UDF de provedor para gerar resultados. A UDF de provedor executa as seguintes ações:

   1. Pré-processar dados de impressões. Um SQL dinâmico é criado para unir os dados de impressões do provedor aos dados do consumidor, calcular a contagem distinta de impressões e de alcance por data e armazenar os resultados em uma tabela intermediária dentro da clean room. Se o consumidor não fornecer uma tabela, o código será executado em toda a tabela de impressões do provedor.

   2. Carregar a tabela intermediária. A tabela intermediária é carregada no procedimento Snowpark como um pandas DataFrame.

   3. Realizar a regressão. A regressão é calculada usando a biblioteca statsmodels e retorna os resultados como um pandas DataFrame.

   4. Gravar resultados em uma tabela interna da clean room. Os resultados são gravados em uma tabela de resultados dentro da clean room, e o sufixo de ID do nome da tabela é retornado ao consumidor. Como o procedimento Snowpark está sendo executado dentro da clean room, ele tem uma capacidade limitada de ativar os dados na conta de consumidor. Em vez disso, para manter os resultados mais seguros, eles são gravados em uma tabela dentro da clean room, e o consumidor executa outro modelo para ler os dados dos resultados.

   5. Eliminar as tabelas intermediárias. As tabelas intermediárias criadas durante o cálculo dentro da clean room que não são mais necessárias são descartadas antes do término do procedimento do Snowpark.

   6. Retornar nome da tabela de resultados. O nome retornado ao consumidor deve ser especificado ao executar o modelo para obter os resultados, pois os resultados de todas as execuções anteriores são mantidos.

2. O consumidor então executa o modelo get_results, passando o sufixo da tabela de resultados retornado pelo primeiro modelo para ver os resultados.

Para executar os exemplos abaixo, você precisa de duas contas na mesma região de hospedagem na Web (a menos que tenha implementado o preenchimento automático entre nuvens): uma conta para o provedor e outra para o consumidor.

O código de exemplo deve ser executado em uma planilha do Snowflake sem nenhuma configuração adicional do Snowpark. Se for executado em outro ambiente, talvez seja necessário instalar e configurar a Snowpark Python API.

• Exemplo de notebook do provedor

• Exemplo de notebook do consumidor

Mais informações¶

• Criação de funções definidas pelo usuário (UDFs) para DataFrames em Python.

• Snowpark API

• Guia do desenvolvedor de Snowpark para Python

Pré-requisitos¶

Você precisará entender os tópicos a seguir para poder usar o Snowpark Container Services em uma clean room:

• Como criar uma clean room em código.

• A Snowpark Python API se estiver usando essa API.

• Como criar modelos personalizados.

• Leia sobre como projetar fluxos de uso complexos para entender como dividir o processamento de dados e a exposição dos resultados em etapas separadas.

Etapas básicas¶

Provedor

1. Crie a especificação do serviço, o código e os pontos de extremidade que lidam com as solicitações de processamento.

2. Crie um repositório de imagens e conceda acesso a SAMOOHA_APP_ROLE a esse repositório.

3. Capture o URL de repositório para a próxima etapa.

4. Crie e carregue a imagem no URL de repositório.

5. Crie a clean room, vincule dados, adicione políticas de associação e adicione consumidores da maneira padrão.

6. Defina os modelos que chamam os pontos de serviço e carregue-os em sua clean room. As funções de serviço são criadas e chamadas no namespace service_functions (diferentemente de UDFs, que são criadas e chamadas no namespace cleanroom).

   -- Template to call an SPCS function named train.
   SELECT service_functions.train(
         {{ source_table[0] }},
         {{ provider_join_col }},
         {{ my_table[0] }},
         {{ consumer_join_col }},
         {{ dimensions | sqlsafe }},
   

   Copy

7. Faça o upload dos detalhes de seu serviço para a clean room chamando provider.load_service_into_cleanroom. Isso define o URL da imagem e os pontos de extremidade

   ) AS train_result;

8. Faça o upload dos detalhes de seu serviço para a clean room chamando provider.load_service_into_cleanroom. Isso define o URL da imagem, os pontos de extremidade e outras opções de serviço. Os nomes dos pontos de extremidade definidos aqui devem corresponder à especificação do serviço e são os nomes que o modelo usa para chamar as funções.

   CALL samooha_by_snowflake_local_db.provider.load_service_into_cleanroom(
   $cleanroom_name,
   $$
   spec:
     containers:
     - name: lal
       image: /dcr_spcs/repos/lal_example/lal_service_image:latest
       env:
         SERVER_PORT: 8000
     endpoints:
     - name: lalendpoint
       port: 8000
       public: false
   $$,
   $$
   functions:
     - name: train
       args: PROVIDER_TABLE VARCHAR, PROVIDER_JOIN_COL VARCHAR, CONSUMER_TABLE VARCHAR, CONSUMER_JOIN_COL VARCHAR, DIMENSIONS ARRAY, FILTER VARCHAR
       returns: VARCHAR
       endpoint: lalendpoint
       path: /train
   $$);
   

   Copy

9. Defina a diretiva de lançamento padrão para sua clean room. Sempre que você faz upload ou modifica o serviço, ele cria uma nova versão de patch.

10. Publique sua clean room.

11. Ao fazer qualquer alteração na imagem, nas funções ou no código, você e o consumidor devem atualizar suas instâncias.

Criação do pool de computação¶

Dependendo de quem deve ser o proprietário e configurar o pool, o provedor pode criar o pool de computação dentro da clean room, ou o consumidor pode criar o pool de computação fora da clean room.

Se o pool de computação for criado fora da clean room, você deverá conceder os privilégios adequados à clean room para acessar o pool e criar o serviço, conforme mostrado aqui:

-- Grant access to a warehouse to run queries. Needed only if the service queries Snowflake accounts.
USE ROLE ACCOUNTADMIN;
GRANT USAGE ON WAREHOUSE APP_WH TO APPLICATION SAMOOHA_CLEANROOM_APP_<CLEANROOM_NAME>;

-- Grant SAMOOHA_APP_ROLE privileges to create compute pools and create services
GRANT CREATE COMPUTE POOL ON ACCOUNT TO ROLE SAMOOHA_APP_ROLE WITH GRANT OPTION;
GRANT BIND SERVICE ENDPOINT ON ACCOUNT TO ROLE SAMOOHA_APP_ROLE WITH GRANT OPTION;


USE ROLE SAMOOHA_APP_ROLE;
-- Create the compute pool
CREATE COMPUTE POOL DCR_LAL_POOL
  FOR APPLICATION SAMOOHA_CLEANROOM_APP_<CLEANROOM_NAME>
  min_nodes = 1 max_nodes = 1
  instance_family = highmem_x64_l
  auto_resume = true;

-- Grant the clean room the privileges to access a pool running outside the clean room.
-- Grant the clean room access to the compute pool
GRANT USAGE ON COMPUTE POOL DCR_LAL_POOL TO APPLICATION SAMOOHA_CLEANROOM_<CLEANROOM_NAME>;

-- Allow the clean room to create the service
GRANT BIND SERVICE ENDPOINT ON ACCOUNT TO APPLICATION SAMOOHA_CLEANROOM_APP_<CLEANROOM_NAME>;

Atualização do código de serviço ou da configuração¶

Se o provedor atualizar a imagem, a especificação do serviço, os nomes dos pontos de extremidade ou o código-fonte, o provedor e o consumidor deverão executar as seguintes etapas.

1. Provedor:

1. Atualize a imagem ou o código-fonte conforme necessário.

2. Chame provider.load_service_into_cleanroom, que retorna um novo número de patch.

3. Chame provider.set_default_release_directive e informe o novo número do patch.

2. Consumidor:

• Chame consumer.start_or_update_service.

Monitoramento de serviço¶

Por padrão, os consumidores podem monitorar seus serviços. Esse comportamento pode ser alterado usando o valor allow_monitoring no argumento service_config de provider.load_service_into_cleanroom.

Se o monitoramento do consumidor estiver ativado, o consumidor poderá acessar os logs de monitoramento de um determinado serviço de clean room (no formato SAMOOHA_CLEANROOM_APP_SPCS_cleanroom_name.services.service), ID de serviço, e contêiner, conforme mostrado aqui:

SELECT VALUE AS log_line
  FROM TABLE(
    SPLIT_TO_TABLE(SYSTEM$GET_SERVICE_LOGS(
        'SAMOOHA_CLEANROOM_APP_SPCS_Lookalike_Demo.services.service', 0, 'lal'), '\n')
  );

O consumidor também pode ver o estado de seu serviço usando o comando DESCRIBE SERVICE, conforme mostrado aqui:

-- See the state of the service.
DESCRIBE SERVICE SAMOOHA_CLEANROOM_APP_SPCS_Lookalike_Demo.services.service;

Você pode ver os pontos de extremidade do servidor executando SHOW ENDPOINTS IN SERVICE SAMOOHA_CLEANROOM_APP_clean_room_name.services.service;. Por exemplo:

SHOW ENDPOINTS IN SERVICE SAMOOHA_CLEANROOM_APP_SPCS_Lookalike_Demo.services.service;

Exemplo de código¶

Os notebooks e o arquivo zip a seguir demonstram como usar o Snowflake Container Services em uma clean room. Você precisa de duas contas com clean rooms instaladas: uma para o provedor e outra para o consumidor. Eles devem estar na mesma região de hospedagem na nuvem. Use os arquivos de configuração compactados para definir o serviço.

• Exemplo de notebook do provedor

• Exemplo de notebook do consumidor

• Arquivos de especificação e configuração do serviço