외부 함수 소개

외부 함수 소개 (Introduction to external functions)

이 문서는 Snowflake 외부에서 개발, 유지, 저장, 실행되는 실행 코드를 호출하는 외부 함수(external function)에 대해 설명해요. 외부 함수가 무엇인지, 일반 UDF와 어떤 점이 다른지, 언제 사용하면 좋은지에 대한 개념을 잡는 데 도움을 줍니다.

출처: Snowflake SQL Reference

본문

이 문서는 여러분이 다음을 이해하도록 도와줘요:

  • 외부 함수가 무엇인지
  • 외부 함수가 UDF(사용자 정의 함수, user-defined function)을 구현하는 가장 좋은 방법인지 결정하는 법
  • 외부 함수를 위한 클라우드 플랫폼을 선택하는 법

참고: 중국에서 외부 함수를 사용할 때는 AWS용으로 설명된 문법과 워크플로를 사용하세요.

외부 함수란 무엇인가? (What is an external function?)

외부 함수는 Snowflake 외부에서 실행되는 코드를 호출해요. 원격으로 실행되는 코드를 원격 서비스(remote service)라고 해요. 원격 서비스로 보내는 정보는 보통 프록시 서비스(proxy service)를 통해 중계돼요. Snowflake는 보안 관련 외부 함수 정보를 API 통합(API integration)에 저장해요.

다음 다이어그램은 클라이언트 프로그램에서 Snowflake를 거쳐 원격 서비스로의 기본적인 정보 흐름을 보여줘요. 각 핵심 구성 요소는 아래에서 더 자세히 설명합니다.

외부 함수 (External Function)

외부 함수는 UDF의 한 유형이에요. 다른 UDF와 달리 외부 함수는 자체 코드를 포함하지 않아요. 대신 외부 함수는 Snowflake 외부에 저장되고 실행되는 코드를 호출해요.

Snowflake 내부에서 외부 함수는 원격 서비스를 호출하는 데 Snowflake가 사용하는 정보를 포함하는 데이터베이스 객체로 저장돼요. 이 저장된 정보는 원격 서비스와의 정보를 중계하는 프록시 서비스의 URL을 포함해요. 이 정보는 CREATE EXTERNAL FUNCTION 명령의 일부로 지정됩니다.

외부 함수를 나타내는 데이터베이스 객체는 특정 데이터베이스와 스키마에 생성돼요. 외부 함수는 점 표기법(dot notation)으로 완전히 한정된 이름(fully-qualified name)을 나타내어 호출할 수 있어요. 예를 들어:

select my_database.my_schema.my_external_function(col1) from table1;

원격 서비스 (Remote Service)

원격으로 실행되는 코드를 원격 서비스라고 해요. 원격 서비스는 함수처럼 동작해야 해요. 예를 들어 값을 반환해야 합니다. Snowflake는 스칼라(scalar) 외부 함수를 지원하며, 원격 서비스는 받은 각 행에 대해 정확히 하나의 행을 반환해야 해요.

Snowflake 외부 함수 기능에 의해 호출되려면 원격 서비스는 다음을 충족해야 해요:

  • JSON 입력을 받아 JSON 출력을 반환해야 해요. (Snowflake 호환 HTTP 헤더와 JSON 형식 데이터에 대한 자세한 내용은 원격 서비스 입출력 데이터 형식 문서 참고)
  • HTTPS 엔드포인트를 노출해야 해요.

예를 들어 원격 서비스는 다음과 같이 구현할 수 있어요:

  • AWS Lambda 함수
  • Microsoft Azure Function
  • EC2 인스턴스에서 실행되는 HTTPS 서버(예: Node.js)

프록시 서비스 (Proxy Service)

Snowflake는 원격 서비스를 직접 호출하지 않아요. 대신 Snowflake는 프록시 서비스를 호출하고, 프록시 서비스가 데이터를 원격 서비스로 중계해요. 프록시 서비스는 원격 서비스에 대한 요청을 인증함으로써 보안을 높일 수 있어요. 프록시 서비스는 원격 서비스에 대한 구독 기반 과금(subscription-based billing)을 지원할 수 있어요. 예를 들어 프록시 서비스는 원격 서비스 호출자가 유료 구독자인지 확인할 수 있어요. 프록시 서비스는 또한 원격 서비스의 응답을 Snowflake로 다시 중계해요.

프록시 서비스의 예로는 다음이 있어요:

  • Amazon API Gateway
  • Microsoft Azure API Management service

API 통합 (API Integration)

통합(integration)은 Snowflake와 타사 서비스 사이의 인터페이스를 제공하는 Snowflake 객체예요. API 통합은 프록시 서비스 또는 원격 서비스와 작업하는 데 필요한 보안 정보 같은 정보를 저장해요. API 통합은 CREATE API INTEGRATION 명령으로 만들어집니다.

사용자는 자신만의 원격 서비스를 작성하고 호출할 수도 있고, 타사가 작성한 원격 서비스를 호출할 수도 있어요. 이 원격 서비스들은 AWS Lambda 같은 클라우드 서버리스 컴퓨팅 서비스를 포함한 모든 HTTP 서버 스택으로 작성할 수 있어요.

SQL 문을 실행하는 사용자의 관점에서 외부 함수는 다른 UDF처럼 동작해요. 외부 함수는 다음 규칙을 따릅니다:

  • 외부 함수는 값을 반환해요.
  • 외부 함수는 파라미터를 받을 수 있어요.
  • 외부 함수는 다른 유형의 UDF가 나타날 수 있는 SQL 문의 어느 절에서나 나타날 수 있어요. 예를 들어:
select my_external_function_2(column_1, column_2)
 from table_1;

select col1
 from table_1
 where my_external_function_3(col2)
  • 외부 함수는 더 복잡한 표현식의 일부가 될 수 있어요:
select upper(zipcode_to_city_external_function(zipcode))
 from address_table;
  • 반환된 값은 JSON을 포함하는 VARIANT 같은 복합 값일 수 있어요.
  • 외부 함수는 오버로드(overload)될 수 있어요. 두 개의 다른 함수가 같은 이름을 가질 수 있지만 시그니처(입력 파라미터의 개수나 데이터 타입)는 다를 수 있어요.

외부 함수는 어떻게 동작하나? (How external functions work)

Snowflake는 원격 서비스를 직접 호출하지 않아요. 대신 Snowflake는 클라우드 제공자의 네이티브 HTTPS 프록시 서비스(예: AWS의 API Gateway)를 통해 원격 서비스를 호출해요.

외부 함수를 호출하는 주요 단계는 다음과 같아요:

  • 사용자의 클라이언트 프로그램이 외부 함수를 호출하는 SQL 문을 Snowflake에 전달해요.
  • 쿼리 실행의 일부로 외부 함수를 평가할 때 Snowflake는 외부 함수 정의와 해당 API 통합 정보를 읽어요.
    • 외부 함수 정의의 정보에는 다음이 포함됩니다:
      • 프록시 서비스의 URL
      • 해당 API 통합의 이름
    • API 통합의 정보에는 다음이 포함됩니다:
      • 사용할 프록시 서비스 리소스. 리소스는 해당 서비스의 위치 같은 원격 서비스에 대한 정보를 포함해요.
      • 그 프록시 서비스 리소스의 인증 정보
  • 그런 다음 Snowflake는 다음을 포함하는 HTTP POST 명령을 구성해요:
    • 처리할 데이터. 이 데이터는 JSON 형식이에요.
    • HTTP 헤더 정보. (세부 사항은 CREATE EXTERNAL FUNCTION에 문서화돼 있어요.)
    • API 통합의 인증 정보
  • 그런 다음 Snowflake는 POST 요청을 프록시 서비스로 보내요.
  • 프록시 서비스는 POST를 받아 처리한 뒤 요청을 실제 원격 서비스로 전달해요. 프록시 서비스와 리소스를 원격 서비스를 호출하는 "중계 함수(relay function)"로 느슨하게 생각할 수 있어요.
  • 원격 서비스는 데이터를 처리하고 결과를 반환하며, 그 결과는 체인을 통해 원래 SQL 문으로 다시 전달돼요.
  • 원격 서비스가 비동기 처리를 알리기 위해 HTTP 코드로 응답하면, Snowflake는 원격 서비스에서 결과를 가져오기 위해 하나 이상의 HTTP GET 요청을 보내요. Snowflake는 요청을 계속하라는 응답 코드를 받는 동안 계속 GET 요청을 보내거나, 외부 함수가 타임아웃되거나 오류를 반환할 때까지 계속 보내요.

일반적으로 쿼리가 원격 서비스로 보낼 행이 많을 때 행들은 배치(batch)로 나뉘어요. 배치는 일반적으로 더 많은 병렬 처리와 더 빠른 쿼리를 허용해요. 어떤 경우에는 배치가 원격 서비스의 과부하를 줄여줘요. 원격 서비스는 받은 각 배치에 대해 1개의 행 배치를 반환해요. 스칼라 외부 함수의 경우 반환된 배치의 행 수는 받은 배치의 행 수와 같아요. 각 배치는 고유한 배치 ID(batch ID)를 가지며, 이 ID는 Snowflake에서 원격 서비스로 보내는 각 요청에 포함돼요. 재시도 작업(예: 타임아웃으로 인한)은 일반적으로 배치 수준에서 수행돼요.

외부 함수의 장점 (Advantages of external functions)

외부 함수는 다른 UDF에 비해 다음 장점이 있어요:

  • 원격 서비스 코드는 다른 UDF로는 작성할 수 없는 언어로 작성할 수 있어요. 여기에는 다음이 포함됩니다:
    • Go
    • C#
  • 원격 서비스는 내부 UDF가 접근할 수 없는 함수와 라이브러리를 사용할 수 있어요. 예를 들어 원격 서비스는 머신러닝 스코어링(scoring) 라이브러리 같은 상업적으로 이용 가능한 타사 라이브러리와 연동할 수 있어요.
  • 개발자는 Snowflake와 같은 인터페이스를 사용하도록 작성된 다른 소프트웨어 양쪽에서 호출할 수 있는 원격 서비스를 작성할 수 있어요.

외부 함수의 제한 사항 (Limitations of external functions)

외부 함수에는 다음 제한 사항이 있으며, 대략 생성 시 제한 사항과 실행 시 제한 사항으로 나눌 수 있어요.

생성 시 제한 사항 및 요구 사항 (Creation-time limitations and requirements)

  • 외부 함수가 처음 호출되기 전에 관리자가 구성 작업을 해야 해요. 이 작업은 클라우드 플랫폼(예: AWS 또는 Microsoft Azure), 특히 보안에 대한 지식이 필요해요.
  • Snowflake는 클라우드 HTTP 프록시 서비스(예: Amazon API Gateway)를 통해 원격 서비스를 간접적으로 호출하므로, 외부 함수의 원격 서비스는 프록시 서비스에서 호출 가능해야 해요. 다행히 HTTPS 엔드포인트로 동작할 수 있는 거의 모든 함수는 프록시 서비스를 통해 외부 함수로 접근할 수 있어요. 함수 작성자는 프록시 서비스가 원격 서비스(예: AWS Lambda에서 실행되는 함수)를 호출하도록 프로그래밍해야 해요.
  • 일부 클라우드 플랫폼에는 특정 요구 사항이 있을 수 있어요. 예를 들어 AWS에서 외부 함수는 리전 엔드포인트(regional endpoints) 또는 프라이빗 엔드포인트(private endpoints)를 요구해요. 자세한 내용은 지원 플랫폼(Supported platforms) 문서를 참고하세요. Amazon API Gateway 리전 및 프라이빗 엔드포인트에 대한 자세한 내용은 엔드포인트 유형 선택을 참고하세요.
  • 외부 함수 기능으로는 함수만 작성할 수 있고 저장 프로시저(stored procedures)는 작성할 수 없어요.
  • 외부 함수에 대한 향후 권한 부여(future grants of privileges)는 지원되지 않아요.

실행 시 제한 사항 및 문제 (Execution-time limitations and issues)

  • 원격 서비스가 Snowflake에 불투명(opaque)하기 때문에, 옵티마이저가 동등한 함수에 대해 수행할 수 있는 일부 최적화를 수행하지 못할 수 있어요.
  • 외부 함수는 함수(내장 함수와 내부 UDF 모두)보다 오버헤드가 더 크고 일반적으로 더 느리게 실행돼요.
  • 현재 외부 함수는 스칼라 함수여야 해요. 스칼라 외부 함수는 각 입력 행에 대해 단일 값을 반환해요.
  • 현재 외부 함수는 Secure Data Sharing을 통해 데이터 소비자와 공유할 수 없어요.
  • 배치당 최대 응답 크기는 10MB예요.
  • 외부 함수는 다음 상황에서는 사용할 수 없어요:
    • Secure Data Sharing을 통해 공유되는 데이터베이스 객체(예: 테이블, 뷰, UDF 또는 마스킹 정책)의 일부로 사용. 예를 들어 외부 함수를 사용하는 공유 뷰를 만들 수 없어요. 다음은 지원되지 않습니다:
CREATE VIEW my_shared_view AS SELECT my_external_function(x) ...;
CREATE SHARE things_to_share;
...
GRANT SELECT ON VIEW my_shared_view TO SHARE things_to_share;
...
  • CREATE TABLE 문의 DEFAULT 절에서 사용. 즉, 컬럼의 기본값이 외부 함수를 호출하는 표현식일 수 없어요. DEFAULT 절에 외부 함수를 포함하려 하면 CREATE TABLE 문이 실패해요.
  • COPY 변환(transformation)에서 사용.
  • 외부 함수는 추가적인 보안 문제를 제기할 수 있어요. 예를 들어 타사의 함수를 호출한다면 그 타사가 함수에 전달된 데이터의 사본을 보관할 수 있어요.

외부 함수 사용에 대한 과금 (Billing for external functions usage)

외부 함수를 사용하면 다음과 관련된 일반 비용이 발생해요:

  • Snowflake 웨어하우스 사용량
  • 데이터 전송

또한 원격 서비스 제공자의 요금을 포함한 간접 요금 또는 타사 요금을 지불해야 할 수 있어요. 요금은 벤더마다 다를 수 있어요.

참고: Amazon API Gateway Private Endpoints를 통해 전송되는 데이터는 수신(ingress)과 송신(egress) 모두에 대해 AWS PrivateLink 요금이 발생해요.

지원 플랫폼 (Supported platforms)

외부 함수 호출을 지원하는 플랫폼 (Platforms that support calling an external function)

일반적으로 외부 함수는 Snowflake가 지원하는 모든 클라우드 플랫폼의 Snowflake 계정에서 호출할 수 있어요:

  • Amazon Web Services (AWS)
  • Microsoft Azure
  • Google Cloud Platform (GCP)

예외는 아래에 나열됩니다:

  • AWS API Gateway 프라이빗 엔드포인트를 통해 접근되는 외부 함수는 AWS의 Snowflake VPC(가상 사설 클라우드)와 같은 AWS 리전에서만 접근할 수 있어요. AWS의 프라이빗 엔드포인트에 대한 자세한 내용은 엔드포인트 유형 선택: 리전 엔드포인트 vs. 프라이빗 엔드포인트를 참고하세요.

외부 함수를 호출하는 SQL 문법은 모든 플랫폼에서 동일해요. 이러한 서비스에 대한 접근을 구성하는 SQL 문(CREATE EXTERNAL FUNCTION 및 CREATE API INTEGRATION)은 모든 플랫폼에서 동일해요. 그러나 이 문장 내의 절은 프록시 서비스와 원격 서비스를 호스팅하는 플랫폼에 따라 달라져요.

외부 함수의 원격 서비스 및 프록시 서비스 생성을 지원하는 플랫폼 (Platforms that support creating an external function's remote service and proxy service)

외부 함수는 어떤 플랫폼에서든 호출할 수 있지만, 외부 함수의 원격 서비스와 프록시 서비스는 각각 특정 지원 플랫폼에서 만들어져야 해요. 많은 경우 원격 서비스의 플랫폼과 계정은 프록시 서비스의 플랫폼과 계정과 동일해요. 그러나 그럴 필요는 없어요. 예를 들어 SQL 쿼리가 AWS API Gateway(프록시 서비스)를 통해 Azure Function(원격 서비스)을 호출할 수 있어요. SQL 쿼리 자체는 GCP에서 실행되는 Snowflake 인스턴스에서 실행될 수 있어요.

원격 서비스를 지원하는 플랫폼 (Platforms that support a remote service)

원격 서비스를 호스팅하려면 HTTP 서버 스택이 필요해요. 원격 서비스를 지원할 수 있는 모든 HTTP 서버 스택은 외부 함수와 호환되어야 해요.

원격 서비스를 만들려면 일반적으로 다음이 필요해요:

  • 클라우드 플랫폼 제공자의 계정(예: Azure Function을 만들기 위한 Microsoft Azure 계정). 이 계정은 원격 서비스에 저장 및 컴퓨팅 서비스를 제공해요. 이 계정은 여러분의 Snowflake 계정과 별개예요.

Snowflake는 다음 형태로 원격 서비스를 만들기 위한 지침을 제공해요:

  • AWS Lambda 함수
  • Microsoft Azure 함수
  • Google Cloud Function
프록시 서비스를 지원하는 플랫폼 (Platforms that support a proxy service)

클라우드 플랫폼에 네이티브 HTTP 프록시 서비스 인스턴스가 필요해요.

프록시 서비스를 구성하려면 일반적으로 다음이 필요해요:

  • 클라우드 플랫폼 제공자의 계정(예: AWS를 사용하기 위한 Amazon 계정). 이 계정은 프록시 서비스에 저장 및 컴퓨팅 서비스를 제공해요. 이 계정은 여러분의 Snowflake 계정과 별개예요.
  • 프록시 서비스를 구성하는 데 필요한 권한을 가진 클라우드 플랫폼 역할(role). 이 클라우드 플랫폼 역할은 여러분의 Snowflake 역할과 별개예요.

다음 HTTPS 프록시 서비스가 지원돼요:

  • Amazon API Gateway
  • Microsoft Azure API Management Service
  • Google Cloud API Gateway

아래 섹션들은 플랫폼을 선택하기 전에 사용자가 알아야 할 플랫폼별 정보를 포함해요.

플랫폼별 제한 사항 (Platform-specific restrictions)

AWS:

  • 이 기능은 Amazon API Gateway의 리전 엔드포인트와 프라이빗 엔드포인트만 지원해요. (다양한 유형의 엔드포인트에 대한 설명은 endpoints 문서를 참고하세요.)
  • Snowflake 외부 함수와 API 통합은 AWS 사용자 지정 도메인(custom domains)을 지원하지 않아요. Snowflake에서 Amazon API Gateway에 접근하려면 AWS가 생성한 기본 URL을 사용하세요. 이 URL은 대략 다음과 같아요:
https://api-id.execute-api.region.amazonaws.com/stage

더 알아보기 (Learn more)

  • 고성능 외부 함수 설계 (external-functions-implementation)
  • 원격 서비스 입출력 데이터 형식 (external-functions-data-format)
  • 외부 함수 보안 (external-functions-security)
  • 외부 함수 트랜슬레이터 (external-functions-translators)