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

Entry points for uploaded code¶

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

예를 들어 두 개의 숫자 매개 변수를 사용하는 simple_add``인 함수를 업로드한 경우 여기에 표시된 대로 템플릿에서 호출할 수 있습니다. 함수는 항상 ``cleanroom 범위를 사용하여 참조됩니다. 예를 들어, 템플릿은 다음과 같이 ``simple_add``를 호출합니다.

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

SELECT
  cleanroom.simple_add(
    {{ price | sqlsafe | int }}, {{ tax | sqlsafe | int }}
    ) AS TOTAL_ITEM_COST
...

You can upload multiple functions in a single package, and functions within a single package can call each other, but functions can’t call functions within other packages. (They can call the handler functions, though.) For example, if you have a clean room where you upload two packages, each with a handler function and two helper functions:

• Code uploaded by either party (provider or consumer) can be run templates submitted by either party.

• A template can call function A or function B, but not A1, A2, B1, or B2.

• 함수 A는 함수 B를 호출할 수 있으며, 그 반대의 경우도 마찬가지입니다.

• 함수 A는 B1 또는 B2를 호출할 수 없고 함수 B는 A1 또는 A2를 호출할 수 없습니다.

• A1은 A2를 호출할 수 있으며 그 반대의 경우도 마찬가지입니다. A1과 A2는 B를 호출할 수 있습니다. A1과 A2는 B1 또는 B2를 호출할 수 없습니다.

• B1은 B2를 호출할 수 있고 그 반대의 경우도 마찬가지입니다. B1과 B2는 A를 호출할 수 있습니다. B1과 B2는 A1 또는 A2를 호출할 수 없습니다.

사용자 지정 함수 업데이트 또는 삭제하기¶

업로드한 기존 함수 또는 템플릿을 업로드하거나 덮어쓸 수 있지만, 기존 함수 또는 템플릿을 삭제할 수는 없습니다. 함수를 “제거”하는 유일한 방법은 항상 성공 값을 반환하는, 정확히 동일한 이름과 서명을 가진 더미 함수를 생성하는 것입니다.

Uploading a function with the same signature as one that you previously uploaded will overwrite the existing function, where a signature means the case-insensitive function name of an external handler, plus the data types of all its arguments, in the same order. Argument names are not part of the signature. You can’t overwrite a function uploaded by another account.

함수를 업데이트할 때 서명이 일치해야 하므로 기존 함수의 서명을 변경할 수 없습니다. 함수 ``foo(name VARIANT age INTEGER)``를 업로드한 다음, 함수 ``foo(name VARIANT age FLOAT)``를 업로드하면 인자 유형이 다르기 때문에 첫 번째 함수 외에 두 번째 함수가 클린룸에 추가됩니다.

개요¶

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

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

2. The provider uploads a bundle by calling provider.load_python_into_cleanroom. You can either upload your code inline directly within that procedure, or upload a code file to a stage, then provide the stage location to that procedure.

   Although each bundle can include multiple functions, only one handler function is exposed for each upload. To expose multiple functions to templates, upload each handler separately or do a bulk upload (described below).

3. If the clean room is exposed externally, security checks are run before the code is installed in the clean room, and you must call provider.view_cleanroom_scan_status to confirm that security checks have passed before incrementing the default version.

4. After each successful upload, a new patch version of the clean room is generated. You must then increase the default version by calling provider.set_default_release_directive with the new patch number.

5. Create and upload a custom template that calls handlers in your code. The template must call the handler function using the cleanroom scope, that is: cleanroom.my_function(...).

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

   팁

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

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

버전 관리에 대한 중요 참고 사항¶

Every time the provider uploads a function, it increases the clean room patch number (and there is a limit of 99 patch numbers). Therefore, do your best to test and debug your code thoroughly before adding it to the clean room to reduce version updates during development.

You can upload multiple packages at once in a single bulk upload to reduce the number of patches generated. However, bulk uploads can make it more challenging to debug if the upload has a security scan issue, because the file that caused the problem isn’t reported in the error response.

패치 번호를 업데이트하면 클린룸 UI를 사용하는 고객이 변경 사항을 확인하기 위해 페이지를 새로 고쳐야 할 수도 있습니다. API를 사용하는 고객에게는 변경 사항이 즉시 표시되지만, 사용 가능한 리소스에 따라 지연이 발생할 수 있습니다. 클린룸 버전 관리에 대해 자세히 알아보세요.

공급자가 작성한 인라인 함수 업로드¶

provider.load_python_into_cleanroom``의 ``code 매개 변수에서 코드를 인라인으로 업로드할 수 있습니다. 다음은 간단한 함수를 인라인으로 업로드하는 예입니다.

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

호출 템플릿은 ``cleanroom.simple_add``를 호출하여 이 함수를 호출합니다. :ref:`공급자 예제<label-dcr_provider_written_code_examples>`는 인라인 코드를 업로드하는 방법을 보여줍니다.

스테이지에서 공급자 작성 함수 업로드¶

You can upload Python files to a clean room stage and reference the stage when you call provider.load_python_into_cleanroom. Loading code from a stage allows you to develop the code in your local system in an editor, avoid copy/paste errors when loading it inline, and also have better versioning control of your source code. Note that you can upload multiple files in a single procedure call, but only one handler function is exposed for each upload.

``load_python_into_cleanroom``을 호출하면 코드가 스테이지에서 클린룸으로 로드됩니다. 나중에 스테이지의 코드 변경 사항이 클린룸으로 전파되지 않습니다.

스테이지로 UDF를 업로드하려면:

1. .py 파일을 만들고 Snowsight 스테이지에 업로드할 수 있는 위치에 저장합니다.

2. To get the name of the stage for your clean room, call provider.get_stage_for_python_files. You must use the specified stage; you cannot use an arbitrary stage that you create.

3. .py 파일을 클린룸의 스테이지에 업로드합니다. CLI, Snowsight 또는 언어별 드라이버를 사용하는 것을 포함하여 :doc:`이 작업을 수행하는 여러 가지 방법</user-guide/data-load-local-file-system-stage>`이 있습니다.

4. 스테이지 위치, 처리기, 외부 이름, 인자 및 반환 유형을 지정하여 ``provider.load_python_into_cleanroom``을 호출합니다. 이제 클린룸의 템플릿에서 이 함수를 호출할 수 있습니다.

다음 예제 코드는 스테이지에서 클린룸으로 코드를 로드하는 방법을 보여줍니다.

-- 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.

:ref:`공급자 예제<label-dcr_provider_written_code_examples>`는 스테이지에서 코드를 업로드하는 방법을 보여줍니다.

업로드된 코드의 구문 오류 또는 검사 실패 문제 해결하기¶

구문 오류로 인해 실패하는 함수를 업로드하거나 보안 검사에 실패하면 게시할 수 없는 패치가 생성될 수 있습니다. 따라서 업로드하기 전에 코드를 철저히 테스트하여 구문 오류가 없는지 확인해야 합니다.

다음 SQL 명령을 실행하여 패키지 목록과 해당 검토 상태를 볼 수 있으며, 표시된 위치에 클린룸 ID가 제공됩니다.

SHOW VERSIONS IN APPLICATION PACKAGE samooha_cleanroom_cleanroom_id;

보안 검사¶

보안 검사는 공급자가 Python을 클린룸에 업로드하는 경우와 같이 외부 클린룸에서 새 패치 버전을 생성하는 모든 작업 후에 실행됩니다. (이 페이지에 설명된 컨슈머 제출 코드는 보안 검사를 트리거하지 않습니다.) 내부 클린룸은 보안 검사를 실행하지 않지만, 내부 클린룸을 외부 클린룸으로 변경하면 해당 패치에 대한 보안 검사가 트리거됩니다. 클린룸 패치는 패치를 검사할 때까지 외부에 게시할 수 없습니다.

Snowflake Clean Rooms는 :doc:`Snowflake Native App 보안 검사 프레임워크</developer-guide/native-apps/security-run-scan>`를 사용합니다. 보안 검사 오류를 방지하려면 :doc:`네이티브 앱 보안 모범 사례</developer-guide/native-apps/security-app-requirements>`를 따릅니다.

마지막 보안 검사가 완료되기 전에 추가 패치 생성 작업을 수행할 수 있습니다. 그러나 클린룸의 최신 버전을 제공하기 위해 기본 릴리스 지시문 업데이트하기 전에 ``provider.view_cleanroom_scan_status``가 성공으로 표시될 때까지 기다려야 합니다.

Uploading multiple Python functions in a single patch (bulk uploading)¶

If you want to upload multiple Python packages to your clean room, you can call prepare_python_for_cleanroom multiple times, then call load_prepared_python_into_cleanroom once to scan, upload, and generate a single patch for your clean room. The following example demonstrates uploading a UDF and a UDTF using bulk uploading:

---- Add custom inline UDF ----
CALL samooha_by_snowflake_local_db.provider.prepare_python_for_cleanroom(
    $cleanroom_name,
    'get_next_status',  -- Name of the UDF. Can be different from the handler.
    ['status VARCHAR'], -- Arguments of the UDF, specified as (variable name, SQL type).
    ['numpy'],          -- Packages needed by UDF.
    [],                 -- When providing the code inline, this is an empty array.
    'VARCHAR',          -- Return type of UDF.
    'get_next_status',  -- Handler.
    $$
import numpy as np
def get_next_status(status):
  """Return the next higher status, or a random status
  if no matching status found or at the top of the list."""

  statuses = ['MEMBER', 'SILVER', 'GOLD', 'PLATINUM', 'DIAMOND']
  try:
    return statuses[statuses.index(status.upper()) + 1]
  except:
    return 'NO MATCH'
    $$
);

---- Add custom inline UDTF. ----
CALL samooha_by_snowflake_local_db.provider.prepare_python_for_cleanroom(
    $cleanroom_name,
    'get_info',  -- Name of the UDTF. Can be different from the handler.
    ['hashed_email VARCHAR', 'days_active INT', 'status VARCHAR', 'income VARCHAR'],   -- Name/Type arguments of the UDTF.
    ['numpy'],         -- Packages used by UDTF.
    [],                -- When providing the code inline, this is an empty array.
    'TABLE(hashed_email VARCHAR, months_active INT, level VARCHAR)',  -- Return type of UDTF.
    'GetSomeVals',     -- Handler class name.
$$
class GetSomeVals:
  def __init__(self):
    self.month_days = 30

  def process(self, hashed_email, days_active, status, income):
    '''Change days into rough months, and also return whether we
    think the user's membership status is lower, higher, or equal to
    what is expected, based on their income.'''

    months_active = days_active // self.month_days
    brackets = ['0-50K', '50K-100K', '100K-250K', '250K+']
    statuses = ['MEMBER', 'SILVER', 'GOLD', 'PLATINUM']
    if(statuses.index(status) < brackets.index(income)):
      level = 'low'
    elif(statuses.index(status) > brackets.index(income)):
      level = 'high'
    else:
      level = 'equal'

    yield(hashed_email, months_active, level)
$$
);

-- Upload all stored procedures.
-- Note the new patch number returned by this procedure. Keep this number for later use.
CALL samooha_by_snowflake_local_db.provider.load_prepared_python_into_cleanroom($cleanroom_name);

-- Set the release directive specified by the last load_python_into_cleanroom call.
CALL samooha_by_snowflake_local_db.provider.set_default_release_directive($cleanroom_name, 'V1_0', <PATCH_NUMBER>);

공급자가 작성한 코드 예제¶

다음 예제는 공급자가 작성한 UDFs 및 UDTFs를 클린룸에 추가하는 방법을 보여줍니다.

Download the following examples and then upload them as worksheet files in your Snowflake account. You need separate accounts for the provider and consumer, each with the clean rooms API installed. Replace the information as noted in the sample files. See instructions to upload a SQL worksheet into your Snowflake account.

• 공급자 예제 코드

• 컨슈머 예제 코드

• 스테이지에서 파일 로드. 공급자 예제를 실행한 후 이 노트북을 실행하여 스테이지에서 UDF를 로드해 봅니다.

• 단일 패치에서 여러 Python 함수 업로드. 이는 단일 계정 내부 테스트 클린룸입니다. 공급자 역할과 컨슈머 역할 모두에 동일한 계정을 사용할 수 있습니다.

컨슈머가 작성한 코드 예제¶

다음 예제에서는 공급자가 작성한 UDFs를 클린룸에 추가하는 방법을 보여줍니다.

Download the following examples and then upload them as worksheet files in your Snowflake account. You need separate accounts for the provider and consumer, each with the clean rooms API installed. Replace the information as noted in the sample files. See instructions to upload a SQL worksheet into your Snowflake account.

• Consumer-written, consumer-run code: Provider worksheet

• Consumer-written, consumer-run code: Consumer worksheet

• Consumer-written, provider-run code: Provider worksheet

• Consumer-written, provider-run code: Consumer worksheet