클린룸에서 사용자 지정 함수 업로드 및 실행¶

개요¶

사용자 지정 Python UDFs 및 UDTFs를 클린룸으로 업로드하고 템플릿에서 실행하여 복잡한 데이터 작업을 수행할 수 있습니다. 이러한 작업으로는 단일 단계 또는 다단계 흐름 중에 쿼리 내에서 머신 러닝 또는 사용자 지정 데이터 조작을 하는 것이 있습니다. Python은 사용자 지정 UDFs에 대해 지원되는 유일한 코딩 언어입니다.

업로드한 코드는 `승인된 Python 패키지 번들<https://repo.anaconda.com/pkgs/snowflake/>`_ 및 :ref:`Snowpark API<label-dcr_snowpark_udf>`에서 패키지를 가져오고 사용할 수 있습니다.

공급자와 컨슈머 모두 사용자 지정 Python 코드를 클린룸에 업로드할 수 있지만, 공급자와 컨슈머의 프로세스는 다릅니다. 업로드된 코드 번들은 각각 서로를 호출하는 여러 함수를 정의할 수 있지만, 하나의 번들은 하나의 처리기 함수만 노출합니다. 이 처리기 함수는 클린룸을 사용하는 모든 사용자가 만들거나 실행하는 템플릿으로 호출할 수 있습니다. 코드가 내부 테이블을 생성하는 경우 :doc:`/user-guide/cleanrooms/multistep-flows`에 설명된 대로 이러한 테이블에 액세스할 수 있습니다.

업로드된 코드는 삭제할 수 없지만 업데이트할 수 있습니다.

이 페이지에서는 공급자 또는 컨슈머 역할로 사용자 지정 Python UDFs 및 UDTFs를 업로드하고 실행하는 방법을 보여줍니다.

공급자 제출 코드¶

공급자가 제출한 함수는 인라인 코드로 업로드하거나 Snowflake 스테이지에서 업로드할 수 있습니다. 두 기술 모두 여기에서 살펴봅니다.

업로드한 코드는 기본적으로 `승인된 Python 패키지 세트<https://repo.anaconda.com/pkgs/snowflake/>`_에서 패키지를 가져와 사용할 수 있습니다. 기본 패키지가 아닌 패키지가 필요한 경우 :ref:`클린룸의 Snowpark Container Services<label-dcr_snowpark_spcs>`를 사용하여 코드를 호스트해야 합니다.

업로드된 코드는 물론 자신의 코드도 볼 수 없으므로, 클린룸에 업로드한 코드의 복사본을 그대로 포함해야 합니다.

다음에서는 공급자가 클린룸에 코드를 추가하는 방법을 개략적으로 살펴봅니다.

1. 공급자는 일반적인 방식으로 클린룸을 만들고 구성합니다.

2. 공급자는 ``provider.load_python_into_cleanroom``을 호출하여 코드를 업로드합니다. 해당 프로시저 내에서 직접 :ref:`코드를 인라인으로 업로드<label-dcr_upload_code_inline>`하거나 :ref:`스테이지에 코드 파일을 업로드<label-dcr_provider_code_from_stage>`한 다음, 해당 프로시저에 스테이지 위치를 제공할 수 있습니다.

   코드에 여러 함수가 포함될 수 있지만, 각 업로드에 대해 하나의 처리기만 노출됩니다. 여러 함수를 템플릿에 노출하려면 ``provider.load_python_into_cleanroom``을 호출하여 각 처리기를 업로드합니다.

3. 코드 업로드에 성공할 때마다 클린룸의 새 패치 버전이 생성됩니다. 그러면 새 패치 번호를 사용하여 ``provider.set_default_release_directive``를 호출함으로써 기본 버전을 증분해야 합니다. 클린룸이 외부에 노출되는 경우 코드를 설치하기 전에 보안 검사가 실행되며, 기본 버전을 증분하기 전에 ``provider.view_cleanroom_scan_status``를 호출하여 보안 검사를 통과했는지 확인해야 합니다.

4. 코드를 호출하는 사용자 지정 템플릿을 만들고 업로드합니다. 템플릿은 cleanroom 범위를 사용하여 처리기 함수를 호출합니다(즉, cleanroom.my_function). 예를 들어, 업로드한 사용자 지정 simple_add 함수를 호출하는 템플릿은 다음과 같을 수 있습니다.

   SELECT cleanroom.simple_add(1, 2), cleanroom.simple_add({{ price | sqlsafe | int }}, {{ tax | sqlsafe | int }})
   

   Copy

5. 컨슈머는 다른 템플릿과 동일한 방식으로 템플릿을 실행합니다.

   팁

   컨슈머가 사용자 지정 코드로 클린룸을 설치할 때 마운트 오류가 발생하는 경우 코드에 구문 오류가 있다는 의미일 수 있습니다.

:ref:`공급자가 작성한 코드 예제 섹션<label-dcr_provider_written_code_examples>`에서 이 흐름을 보여주는 코드 예제를 찾을 수 있습니다.

CALL samooha_by_snowflake_local_db.provider.load_python_into_cleanroom(
$cleanroom_name,
'simple_add',                         -- Name used to call the UDF from a template.
['first INTEGER', 'second INTEGER'],  -- Arguments of the UDF, specified as '<variable_name> <SQL type>' pairs.
['numpy', 'pandas'],                  -- Packages imported by the UDF.
'INTEGER',                            -- SQL return type of UDF.
'add_two',                            -- Handler function in your code called when external name is called.
$$
import numpy as np   # Not used, but you can load supported packages.
import pandas as pd

def add_two(first, second):
    return first + second
$$
);

-- Save the following code as reverser.py:
--import numpy as np
--def main(some_string):
--  '''Return the reverse of a string plus a random number 1-10'''
--  return some_string[::-1] + str(np.random.randint(1,10))

-- Get the stage for your clean room.
CALL samooha_by_snowflake_local_db.provider.get_stage_for_python_files($cleanroom_name);

-- Save the file to the stage. Here is how to do it by using the Snowflake CLI
PUT file://~/reverser.py <STAGE_NAME> overwrite=True auto_compress=False;

-- Load the code from the stage into the clean room.
CALL samooha_by_snowflake_local_db.provider.load_python_into_cleanroom(
    $cleanroom_name,
    'reverse', -- Name used to call the function
    ['some_string  STRING'], -- Arguments and SQL types
    ['numpy'],               -- Any required packages
    ['/reverser.py'],        -- Relative path to file on stage
    'STRING',                -- Return type
    'reverser.main'          -- <FILE_NAME>.<FUNCTION_NAME>
);

-- Uploading code, even from a stage, increases the patch number.
CALL samooha_by_snowflake_local_db.provider.set_default_release_directive(
  $cleanroom_name, 'V1_0', <NEW_PATCH_NUMBER>);

-- Upload a template that calls the function.
CALL samooha_by_snowflake_local_db.provider.add_custom_sql_template(
    $cleanroom_name,
    $udf_template_name,
    $$
    SELECT
      p.status,
      cleanroom.reverse(p.status)
    FROM SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS AS p
    LIMIT 100;
    $$
);

-- Switch to the consumer account and run the template to see the results.

컨슈머가 제출한 코드¶

컨슈머는 UDF 또는 UDTF 코드를 제출하고 사용자 지정 템플릿에서 호출할 수 있습니다. 컨슈머가 업로드한 코드는 사용자 지정 템플릿과 함께 단일 프로시저에 번들로 제공되며, 단일 프로시저 호출을 통해 업로드됩니다. 컨슈머 코드는 해당 템플릿에 직접 연결되어 있으므로, 다른 템플릿에서 호출할 수 없습니다.

컨슈머로서 코드를 업로드하려면 사용자 지정 템플릿 구문 및 :ref:`컨슈머 정의 템플릿을 제출하는 방법<label-dcr_consumer_written_templates>`을 이해해야 합니다.

컨슈머가 업로드한 모든 코드는 공급자가 업로드 권한을 요청할 때 볼 수 있습니다. 공급자 또는 컨슈머가 템플릿을 검사할 때마다 컨슈머 코드도 표시됩니다.

다음은 사용자 지정 컨슈머 코드를 업로드하는 단계의 개요입니다.

1. 공급자가 표준 방식으로 클린룸을 만든 다음, 컨슈머를 초대합니다.

2. 컨슈머가 표준 방식으로 클린룸을 설치하고 구성합니다.

3. 컨슈머가 템플릿을 준비합니다. 이 템플릿은 cleanroom 네임스페이스 내에서 UDF 또는 UDTF를 호출합니다. 예를 들어, 컨슈머 정의 calculate_tax 함수를 호출하려면 다음과 같은 코드 조각이 포함된 간단한 템플릿을 사용하면 됩니다.

   SELECT {{ cleanroom.calculate_tax(p.cost) }} AS Tax FROM my_db.my_sch.sales AS p;
   

   Copy

4. 컨슈머가 Python 코드를 준비합니다. 나중에 추가 이스케이프 처리가 필요하지 않도록 코드에 작은따옴표(' ') 대신 큰따옴표(" ")를 사용하는 것이 좋습니다. 코드는 `선택한 Python 라이브러리 번들<https://repo.anaconda.com/pkgs/snowflake/>`_을 참조할 수 있습니다.

5. 컨슈머는 Python 코드를 ``consumer.generate_python_request_template``에 전달합니다. 이 프로시저는 사용자 지정 JinjaSQL 템플릿에 대한 자리 표시자와 함께 Python 코드를 저장 프로시저로 반환합니다. 이 템플릿에는 ``$$``를 여러 줄 구분 기호로 사용하는 여러 줄 문자열이 있습니다.

6. ``generate_python_request_template``의 출력에서 템플릿 자리 표시자를 사용자의 JinjaSQL 템플릿으로 바꿉니다.

7. 결합된 템플릿에서 ``'``와 같은 작은따옴표를 이스케이프합니다. 작은따옴표가 전체 여러 줄 프로시저 문자열의 가장 바깥쪽 구분 기호로 사용되기 때문입니다. 예:

     BEGIN
   
     CREATE OR REPLACE FUNCTION CLEANROOM.custom_compare(min_status STRING, max_status STRING, this_status STRING)
     RETURNS boolean
     LANGUAGE PYTHON
     RUNTIME_VERSION = 3.10
     PACKAGES = (\'numpy\')
   
     HANDLER = \'custom_compare\'
     AS $$
     import numpy as np
   
     def custom_compare(min_status:str, max_status:str, this_status:str):
       statuses = [\'MEMBER\', \'SILVER\', \'GOLD\', \'PLATINUM\']
       return ((statuses.index(this_status) >= statuses.index(min_status)) &
               (statuses.index(this_status) <= statuses.index(max_status)))
     $$;
   
     -- Custom template
     LET SQL_TEXT varchar := $$
     SELECT
       c.status,
       c.hashed_email
     FROM IDENTIFIER( {{ my_table[0] }} ) as c
     WHERE cleanroom.custom_compare({{ min_status }}, {{ max_status }}, c.status);
     $$;
   
     LET RES resultset := (EXECUTE IMMEDIATE :SQL_TEXT);
     RETURN TABLE(RES);
   
     END;
   

   Copy

8. 결합된 템플릿을 사용하여 consumer.create_template_request``를 호출합니다. ``template_definition 인자에서 저장 프로시저용 코드 주위에 이중 달러 구분 기호($$...$$) 대신 작은따옴표(' ')를 사용합니다. 예:

   CALL samooha_by_snowflake_local_db.consumer.create_template_request(
     $cleanroom_name,
     $template_name,
     '
   BEGIN
   
   -- First, define the Python UDF.
   CREATE OR REPLACE FUNCTION CLEANROOM.custom_compare(min_status STRING, max_status STRING, this_status STRING)
   RETURNS boolean
   LANGUAGE PYTHON
   RUNTIME_VERSION = 3.10
   PACKAGES = (\'numpy\')
   
   HANDLER = \'custom_compare\'
   AS $$
   import numpy as np
   
   def custom_compare(min_status:str, max_status:str, this_status:str):
     statuses = [\'MEMBER\', \'SILVER\', \'GOLD\', \'PLATINUM\']
     return ((statuses.index(this_status) >= statuses.index(min_status)) &
             (statuses.index(this_status) <= statuses.index(max_status)))
       $$;
   
   -- Then define and execute the SQL query.
   LET SQL_TEXT varchar := $$
   SELECT
     c.status,
     c.hashed_email
   FROM IDENTIFIER( {{ my_table[0] }} ) as c
   WHERE cleanroom.custom_compare({{ min_status }}, {{ max_status }}, c.status);
   $$;
   
   -- Execute the query and then return the result.
   LET RES resultset := (EXECUTE IMMEDIATE :SQL_TEXT);
   RETURN TABLE(RES);
   
   END;
   ');
   

   Copy

9. 컨슈머와 공급자가 표준 :ref:`컨슈머 정의 템플릿 흐름<label-dcr_consumer_written_templates>`을 계속 유지합니다.

   1. 공급자가 템플릿 요청을 확인한 다음(provider.list_pending_template_requests), ``approve_template_request``를 호출하여 승인합니다. 공급자는 요청에서 템플릿과 번들 코드를 볼 수 있습니다.

   2. 컨슈머가 요청 상태를 확인하고(consumer.list_template_requests) 상태가 APPROVED인 경우 템플릿을 실행합니다(consumer.run_analysis).