Python으로 UDTF 작성하기¶

process 메서드 정의하기¶

SQL 형식에서 변환된 UDTF 인자를 값으로 받는 process 메서드를 정의하여 Snowflake가 UDTF의 테이블 형식 반환 값을 만드는 데 사용할 데이터를 반환합니다.

이 메서드의 서명은 다음과 같은 형식이어야 합니다.

def process(self, *args):

process 메서드는 다음 조건을 충족해야 합니다.

• self 매개 변수가 있어야 합니다.

• UDTF 매개 변수에 해당하는 메서드 매개 변수를 선언해야 합니다.

  메서드 매개 변수 이름이 UDTF 매개 변수 이름과 일치할 필요는 없지만, UDTF 매개 변수가 선언된 것과 같은 순서로 메서드 매개 변수를 선언해야 합니다.

  UDTF 인자 값을 메서드에 전달할 때 Snowflake는 값을 SQL 형식에서 메서드에서 사용하는 Python 형식으로 변환합니다. Snowflake가 SQL 데이터 타입과 Python 데이터 타입 간에 매핑하는 방법에 대한 자세한 내용은 SQL-Python 데이터 타입 매핑 섹션을 참조하십시오.

• 하나 이상의 튜플을 생성(또는 튜플을 포함한 이터러블을 반환)해야 하며, 이때 튜플의 시퀀스는 UDTF 반환 값 열의 시퀀스와 상응합니다.

  튜플 요소는 UDTF 반환 값 열이 선언된 것과 같은 순서로 나타나야 합니다. 자세한 내용은 이 항목의 값 반환하기 섹션을 참조하십시오.

  Snowflake는 값을 Python 형식에서 UDTF 선언에서 요구되는 SQL 형식으로 변환합니다. Snowflake가 SQL 데이터 타입과 Python 데이터 타입 간에 매핑하는 방법에 대한 자세한 내용은 SQL-Python 데이터 타입 매핑 섹션을 참조하십시오.

핸들러 클래스의 메서드에서 예외가 발생하면 처리가 중지됩니다. UDTF를 호출한 쿼리는 오류 메시지와 함께 실패합니다. process 메서드가 None 을 반환하면 처리가 중지됩니다. (process 메서드가 None 을 반환하더라도 end_partition 메서드는 여전히 호출됩니다.)

process 메서드의 예

다음 예제의 코드를 실행하면 세 UDTF 인자(symbol, quantity, price)를 처리하여 두 열(symbol, total)이 있는 단일 행을 반환하는 process 메서드가 있는 StockSale 핸들러 클래스가 표시됩니다. process 메서드 매개 변수는 stock_sale 매개 변수와 동일한 순서로 선언됩니다. process 메서드의 yield 문에 있는 인자는 stock_sale RETURNS TABLE 절에 선언된 열과 같은 순서입니다.

CREATE OR REPLACE FUNCTION stock_sale(symbol VARCHAR, quantity NUMBER, price NUMBER(10,2))
  RETURNS TABLE (symbol VARCHAR, total NUMBER(10,2))
  LANGUAGE PYTHON
  RUNTIME_VERSION = 3.9
  HANDLER = 'StockSale'
AS $$
class StockSale:
    def process(self, symbol, quantity, price):
      cost = quantity * price
      yield (symbol, cost)
$$;

다음 예제의 코드에서는 이전 UDF를 호출하여 stocks_table 테이블의 symbol, quantity 및 price 열의 값을 전달합니다.

SELECT stock_sale.symbol, total
  FROM stocks_table, TABLE(stock_sale(symbol, quantity, price) OVER (PARTITION BY symbol));

값 반환하기¶

출력 행을 반환할 때 yield 또는 return (단, 둘 모두는 아님)을 사용하여 테이블 형식 값이 있는 튜플을 반환할 수 있습니다. 메서드가 None 을 반환하거나 생성하면 현재 행의 처리가 중지됩니다.

• yield 를 사용할 때 각 출력 행에 대해 별도의 yield 문을 실행합니다. 이는 yield 와 함께 수반되는 지연 평가를 통해 보다 효율적으로 처리하고 시간 초과 방지에 도움이 될 수 있으므로 모범 사례입니다.

  튜플의 각 요소는 UDTF가 반환하는 결과에서 열 값이 됩니다. yield 인자의 순서는 CREATE FUNCTION의 RETURNS TABLE 절에서 반환 값에 대해 선언된 열의 순서와 일치해야 합니다.

  다음 예제의 코드는 두 행을 나타내는 값을 반환합니다.

  def process(self, symbol, quantity, price):
    cost = quantity * price
    yield (symbol, cost)
    yield (symbol, cost)
  

  Copy

  yield 인자는 튜플이므로 다음 예제와 같이 튜플의 단일 값을 전달할 때 후행 쉼표를 포함해야 합니다.

  yield (cost,)
  

  Copy

• return 사용 시, 튜플이 있는 이터러블을 반환합니다.

  튜플에서 각각의 값은 UDTF가 반환하는 결과에서 열 값이 됩니다. 튜플에서 열 값의 순서는 CREATE FUNCTION의 RETURNS TABLE 절에서 반환 값에 대해 선언된 열의 순서와 일치해야 합니다.

  다음 예제의 코드는 각각 symbol과 total이라는 두 열이 있는 두 행을 반환합니다.

  def process(self, symbol, quantity, price):
    cost = quantity * price
    return [(symbol, cost), (symbol, cost)]
  

  Copy

행 건너뛰기¶

입력 행을 건너뛰고 그다음 행을 처리하려면(예: 입력 행의 유효성을 검사할 때) process 메서드가 다음 중 하나를 반환하도록 하십시오.

• return 을 사용할 때 행을 건너뛰려면 None, None 을 포함한 목록 또는 빈 목록을 반환하십시오.

• yield 를 사용할 때 행을 건너뛰려면 None 을 반환하십시오.

  yield 를 여러 번 호출하는 경우 Snowflake에서는 None 을 반환하는 호출 이후의 호출은 전부 무시합니다.

다음 예제의 코드는 number 가 양의 정수인 행만 반환합니다. number 가 양수가 아닌 경우 메서드는 현재 행을 건너뛰고 다음 행을 계속 처리하기 위해 None 을 반환합니다.

def process(self, number):
  if number < 1:
    yield None
  else:
    yield (number)

상태 저장 및 상태 비저장 처리¶

파티션 인식 방식으로 행을 처리하거나 단순히 행 단위로 처리하는 핸들러를 구현할 수 있습니다.

• 파티션 인식 처리 에서는 핸들러에 파티션 범위가 지정된 상태를 관리하는 코드가 포함됩니다. 파티션 처리 시작 시에 실행되는 __init__ 메서드와 파티션의 마지막 행을 처리한 후 Snowflake가 호출하는 end_partition 메서드가 포함됩니다. 자세한 내용은 이 항목의 파티션 처리하기 섹션을 참조하십시오.

• 파티션 비인식 처리 에서는 핸들러가 파티션 경계를 무시하고 상태를 저장하지 않고 실행됩니다.

  핸들러가 이와 같이 실행되도록 하려면 __init__ 또는 end_partition 메서드를 포함하지 마십시오.

파티션 처리 마무리하기¶

파티션의 모든 행을 처리한 후 Snowflake가 호출할 핸들러 클래스에서 end_partition 메서드를 선택적으로 구현할 수 있습니다. 이 메서드에서는 파티션의 모든 행이 처리된 후 파티션의 코드를 실행할 수 있습니다. end_partition 메서드는 파티션 범위 지정 계산의 결과 반환과 같은 출력 행을 생성할 수 있습니다. 자세한 내용은 이 항목의 파티션 처리하기 섹션을 참조하십시오.

이 메서드의 서명은 다음과 같은 형식이어야 합니다.

def end_partition(self):

Snowflake는 다음과 같은 end_partition 메서드 구현을 예상합니다.

• 메서드가 정적이지 않아야 합니다.

• 메서드에 self 이외에는 매개 변수가 없을 수도 있습니다.

• 테이블 형식 값 반환의 대체 수단으로, 빈 목록 또는 None 을 생성할 수 있습니다.

파티션 처리의 예¶

다음 예제의 코드를 실행하면 (process 메서드에서) 먼저 매입당 비용을 계산해 매입 금액을 함께 더함으로써 어떤 주식의 매입을 위해 지불한 총비용이 계산됩니다. 이 코드는 end_partition 메서드에서 총계를 반환합니다.

UDTF 호출과 함께 이 처리기를 포함하는 UDTF의 예는 처리기 클래스의 예 섹션을 참조하십시오.

class StockSaleSum:
  def __init__(self):
    self._cost_total = 0
    self._symbol = ""

  def process(self, symbol, quantity, price):
    self._symbol = symbol
    cost = quantity * price
    self._cost_total += cost
    yield (symbol, cost)

  def end_partition(self):
    yield (self._symbol, self._cost_total)

파티션을 처리할 때는 다음 사항을 유념하십시오.

• 사용자의 코드가 UDTF에 대한 호출에 명시적으로 지정되지 않은 파티션을 처리할 수 있습니다. UDTF에 대한 호출에 PARTITION BY 절이 포함되지 않더라도 Snowflake는 데이터를 암시적으로 분할합니다.

• process 메서드는 파티션의 ORDER BY 절에 지정된 순서대로 행 데이터(있는 경우)를 수신합니다.