파라미터화된 쿼리 사용 - Amazon Athena
고려 사항 및 제한실행 파라미터를 사용한 쿼리준비된 문을 사용한 쿼리추가적인 리소스

파라미터화된 쿼리 사용

Athena 파라미터화된 쿼리를 사용하여 실행 시 동일한 쿼리를 다른 파라미터 값으로 다시 실행하고 SQL 명령어 삽입 공격을 방지할 수 있습니다. Athena에서 파라미터화된 쿼리는 모든 DML 쿼리나 SQL 준비된 문에서 실행 파라미터 형태를 취할 수 있습니다.

  • 실행 파라미터가 있는 쿼리는 한 단계로 수행할 수 있으며 작업 그룹에 특정되지 않습니다. 파라미터화하려는 값의 아무 DML 쿼리에 물음표를 넣습니다. 쿼리를 실행할 때 실행 파라미터 값을 순차적으로 선언합니다. 파라미터 선언과 파라미터 값 할당은 동일한 쿼리에서 분리된 방식으로 수행할 수 있습니다. 준비된 문과 달리 실행 파라미터를 사용하여 쿼리를 제출할 경우 작업 그룹을 선택할 수 있습니다.

  • 준비된 문에는 두 개의 개별 SQL 문인 PREPARE 및 EXECUTE가 필요합니다. 먼저 PREPARE 문에서 파라미터를 정의합니다. 그런 다음 정의한 파라미터의 값을 제공하는 EXECUTE 문을 실행합니다. 준비된 문은 작업 그룹마다 다르므로 해당 문이 속한 작업 그룹의 컨텍스트 외부에서는 실행할 수 없습니다.

고려 사항 및 제한

  • 파라미터화된 쿼리는 Athena 엔진 버전 2 이상에서만 지원됩니다. Athena 엔진 버전에 대한 자세한 내용은 Athena 엔진 버전 관리 단원을 참조하세요.

  • 현재 파라미터화된 쿼리는 SELECT, INSERT INTO, CTAS, UNLOAD 문에만 지원됩니다.

  • 파라미터화된 쿼리에서 파라미터는 위치 파라미터이며 ?로 표시됩니다. 파라미터에는 쿼리의 순서에 따라 값이 할당됩니다. 명명된 파라미터는 지원되지 않습니다.

  • 현재 ? 파라미터는 WHERE절에만 배치할 수 있습니다. SELECT ? FROM table 등의 구문은 지원되지 않습니다.

  • 물음표 파라미터는 큰 따옴표나 작은 따옴표로 묶을 수 없습니다(즉,'?' 및 "?"의 경우 잘못된 구문임).

  • SQL 실행 파라미터를 문자열로 처리하려면 큰따옴표 대신 작은따옴표로 묶어야 합니다.

  • 필요한 경우 파라미터화된 용어의 값을 입력할 때 CAST 함수를 사용할 수 있습니다. 예를 들어 쿼리에서 파라미터화한 date 유형의 열이 있고 날짜 2014-07-05에 대해 쿼리하려는 경우 파라미터 값으로 CAST('2014-07-05' AS DATE)를 입력하면 결과가 반환됩니다.

  • 준비된 문은 작업 그룹에 특정하며 준비된 문 이름은 작업 그룹 내에서 고유해야 합니다.

  • 준비된 문에 대한 IAM 권한이 필요합니다. 자세한 내용은 준비된 문에 대한 액세스 허용 단원을 참조하십시오.

  • Athena 콘솔에서 실행 파라미터가 있는 쿼리는 최대 25개의 물음표로 제한됩니다.

실행 파라미터를 사용한 쿼리

DML 쿼리에서 물음표 자리표시자를 사용하여 준비된 문을 먼저 만들지 않고도 파라미터화된 쿼리를 만들 수 있습니다. 이러한 쿼리를 실행하려면 Athena 콘솔을 사용하거나 AWS CLI 또는 AWS SDK를 사용하고 execution-parameters 인수에 변수를 선언합니다.

Athena 콘솔에서 실행 파라미터와 함께 쿼리 실행

Athena 콘솔에서 실행 파라미터(물음표)가 있는 파라미터화된 쿼리를 실행하면, 쿼리에 물음표가 나타나는 순서대로 값을 입력하라는 메시지가 표시됩니다.

실행 파라미터가 있는 쿼리를 실행하려면

  1. 다음 예제와 같이 Athena 편집기에서 물음표 자리표시자와 함께 쿼리를 입력합니다.

    SELECT * FROM "my_database"."my_table"
WHERE year = ? and month= ? and day= ?

  2. Run(실행)을 선택합니다.

  3. 파라미터 입력(Enter parameters) 대화 상자에서 쿼리에 포함된 각 물음표의 순서대로 값을 입력합니다.

    쿼리 파라미터 값을 순서대로 입력합니다

  4. 파라미터 입력이 끝나면 실행(Run)을 선택합니다. 입력한 파라미터 값에 대한 쿼리 결과가 편집기에 표시됩니다.

이때 다음 중 한 가지를 수행할 수 있습니다.

  • 동일한 쿼리에 대해 다른 파라미터 값을 입력한 다음 다시 실행(Run again)을 선택합니다.

  • 입력한 모든 값을 한 번에 지우려면 지우기(Clear)를 선택합니다.

  • 쿼리를 직접 편집하려면(예: 물음표 추가 또는 제거) 파라미터 입력(Enter parameters) 대화 상자를 먼저 닫습니다.

  • 나중에 사용할 수 있도록 파라미터화된 쿼리를 저장하려면 저장(Save) 또는 다른 이름으로 저장(Save as)을 선택한 다음 쿼리에 이름을 지정합니다. 저장된 쿼리 사용에 관한 자세한 내용은 저장된 쿼리 사용 단원을 참조하세요.

편의상, 쿼리 편집기에서 동일한 탭을 사용하는 한 파라미터 입력(Enter parameters) 대화 상자에는 쿼리에 대해 이전에 입력한 값이 저장됩니다.

AWS CLI를 사용하여 실행 파라미터로 쿼리 실행

AWS CLI를 사용하여 실행 파라미터로 쿼리를 실행하려면 start-query-execution 명령을 사용하고 query-string 인수에 파라미터화된 쿼리를 제공합니다. 그런 다음 execution-parameters 인수에 실행 파라미터 값을 제공합니다. 다음 예는 이 기법을 보여 줍니다.

aws athena start-query-execution 
--query-string "SELECT * FROM table WHERE x = ? AND y = ?"
--query-execution-context "Database"="default" 
--result-configuration "OutputLocation"="s3://DOC-EXAMPLE-BUCKET;/..."
--execution-parameters "1" "2"

준비된 문을 사용한 쿼리

서로 다른 쿼리 파라미터로 동일한 쿼리를 반복 실행하도록 준비된 문을 사용할 수 있습니다. 준비된 문 에는 실행 시 값이 제공되는 파라미터 자리 표시자가 포함됩니다.

참고

작업 그룹에서 준비된 문의 최대 개수는 1000입니다.

SQL 문

PREPARE, EXECUTE, DEALLOCATE PREPARE SQL 문을 사용하여 Athena 콘솔 쿼리 편집기에서 파라미터화된 쿼리를 실행할 수 있습니다.

  • 일반적으로 리터럴 값을 사용하는 파라미터를 지정하기 위해 PREPARE문에 물음표를 사용합니다.

  • 쿼리를 실행할 때 파라미터를 값으로 바꾸려면 EXECUTE 문에 USING 절을 사용합니다.

  • 작업 그룹의 준비된 문에서 준비된 문을 제거하려면 DEALLOCATE PREPARE 문을 사용합니다.

다음 단원에서는 이러한 문 각각에 대한 추가 정보를 제공합니다.

PREPARE

나중에 실행할 문을 준비합니다. 준비된 문은 사용자가 지정한 이름으로 현재 작업 그룹에 저장됩니다. 이 문은 쿼리가 실행될 때 리터럴을 대신해 대체될 파라미터를 포함할 수 있습니다. 값으로 대체할 파라미터는 물음표로 표시됩니다.

구문
PREPARE statement_name FROM statement

다음 표는 이러한 파라미터에 대해 설명합니다.

파라미터 설명
statement_name 준비되는 문의 이름입니다. 이 이름은 작업 그룹 내에서 고유해야 합니다.
설명 SELECT, CTAS 또는 INSERT INTO 쿼리.
PREPARE 예제

다음 예제는 PREPARE 문의 사용을 보여줍니다. 물음표는 쿼리 실행 시 EXECUTE 문이 제공할 값을 나타냅니다.

PREPARE my_select1 FROM
SELECT * FROM nation
PREPARE my_select2 FROM
SELECT * FROM "my_database"."my_table" WHERE year = ?
PREPARE my_select3 FROM
SELECT order FROM orders WHERE productid = ? and quantity < ?
PREPARE my_insert FROM
INSERT INTO cities_usa (city, state)
SELECT city, state
FROM cities_world
WHERE country = ?
PREPARE my_unload FROM
UNLOAD (SELECT * FROM table1 WHERE productid < ?)
TO 's3://DOC-EXAMPLE-BUCKET/'
WITH (format='PARQUET')

EXECUTE

준비된 문을 실행합니다. 파라미터의 값은 USING 절에서 지정합니다.

구문
EXECUTE statement_name [USING value1 [ ,value2, ... ] ]

statement_name은 준비된 문의 이름입니다. value1 및 value2는 문의 파라미터에 지정될 값입니다.

EXECUTE 예제

다음 예제는 파라미터를 포함하지 않는 준비된 문 my_select1을 실행합니다.

EXECUTE my_select1

다음 예제는 하나의 파라미터를 포함한 준비된 문 my_select2를 실행합니다.

EXECUTE my_select2 USING 2012

다음 예제는 2개의 파라미터를 포함한 준비된 문 my_select3을 실행합니다.

EXECUTE my_select3 USING 346078, 12

다음 예제는 준비된 문 my_insert의 파라미터에 문자열 값을 제공합니다.

EXECUTE my_insert USING 'usa'

다음 예제는 준비된 문 my_unload의 productid 파라미터에 숫자 값을 제공합니다.

EXECUTE my_unload USING 12

DEALLOCATE PREPARE

현재 작업 그룹의 준비된 문 목록에서 지정된 이름을 가진 준비된 문을 제거합니다.

구문
DEALLOCATE PREPARE statement_name

statement_name은 제거할 준비된 문의 이름입니다.

예

다음 예제는 현재 작업 그룹에서 준비된 문 my_select1을 제거합니다.

DEALLOCATE PREPARE my_select1

Athena 콘솔에서 USING 절 없이 준비된 문 실행

쿼리 편집기에서 EXECUTE prepared_statement 구문을 사용하여 기존의 준비된 문을 실행하는 경우, Athena에서는 파라미터 입력(Enter parameters) 대화 상자가 열려 EXECUTE ... USING 문의 USING 절에 일반적으로 입력되는 값을 입력할 수 있습니다.

파라미터 입력(Enter parameters) 대화 상자를 사용하여 준비된 문을 실행하려면

  1. 쿼리 편집기에서 EXECUTE prepared_statement USING value1, value2 ... 구문을 사용하는 대신 EXECUTE prepared_statement 구문을 사용합니다.

  2. Run(실행)을 선택합니다. 파라미터 입력(Enter parameters) 대화 상자가 표시됩니다.

    Athena 콘솔에 준비된 문에 대한 파라미터 값 입력.

  3. 실행 파라미터(Execution parameters) 대화 상자에 순서에 따라 값을 입력합니다. 쿼리의 원래 텍스트가 표시되지 않으므로 각 위치 파라미터의 의미를 기억하거나 준비된 문을 참조할 수 있어야 합니다.

  4. Run(실행)을 선택합니다.

AWS CLI를 사용하여 준비된 문 만들기

AWS CLI를 사용해 준비된 문을 작성하는 데 다음 athena 명령 중 하나를 사용할 수 있습니다.

  • create-prepared-statement 명령을 사용하고 실행 파라미터가 있는 쿼리 문을 제공합니다.

  • start-query-execution 명령을 사용하고 PREPARE 구문을 사용하는 쿼리 문자열을 제공합니다.

create-prepared-statement 사용

create-prepared-statement 명령에서 다음 예제와 같이 query-statement 인수에 쿼리 텍스트를 정의합니다.

aws athena create-prepared-statement 
--statement-name PreparedStatement1 
--query-statement "SELECT * FROM table WHERE x = ?" 
--work-group athena-engine-v2

start-query-execution 및 PREPARE 구문 사용

start-query-execution 명령을 사용합니다. 다음 예제와 같이 query-string 인수에 PREPARE 문을 넣습니다.

aws athena start-query-execution 
--query-string "PREPARE PreparedStatement1 FROM SELECT * FROM table WHERE x = ?" 
--query-execution-context '{"Database": "default"}' 
--result-configuration '{"OutputLocation": "s3://DOC-EXAMPLE-BUCKET/..."}'

AWS CLI를 사용해 준비된 문 실행

AWS CLI를 사용해 준비된 문을 실행하는 데 다음과 같은 메서드 중 하나를 사용하여 파라미터 값을 제공할 수 있습니다.

  • execution-parameters 인수를 사용합니다.

  • query-string 인수에 EXECUTE ... USING SQL 구문을 사용합니다.

execution-parameters 인수 사용

이러한 방식에서는 start-query-execution 명령을 사용하고 query-string 인수에 기존 준비된 문의 이름을 제공합니다. 그런 다음 execution-parameters 인수에 실행 파라미터 값을 제공합니다. 다음 예제는 이 메서드를 보여 줍니다.

aws athena start-query-execution 
--query-string "Execute PreparedStatement1" 
--query-execution-context "Database"="default" 
--result-configuration "OutputLocation"="s3://DOC-EXAMPLE-BUCKET/..."
--execution-parameters "1" "2"

EXECUTE 사용 중... SQL 구문 사용

EXECUTE ... USING구문을 사용하여 기존 준비된 문을 실행하려면, start-query-execution 명령을 사용하고 다음 예제와 같이 query-string 인수에 준비된 명령문의 이름과 파라미터 값을 모두 배치합니다.

aws athena start-query-execution 
--query-string "EXECUTE PreparedStatement1 USING 1"
--query-execution-context '{"Database": "default"}' 
--result-configuration '{"OutputLocation": "s3://DOC-EXAMPLE-BUCKET/..."}'

준비된 문 나열

특정 작업 그룹에 대해 준비된 문을 나열하기 위해 Athena list-prepared-statements AWS CLI 명령 또는 ListPreparedStatements Athena API 작업을 사용할 수 있습니다. --work-group 파라미터가 필요합니다.

aws athena list-prepared-statements --work-group primary

추가적인 리소스

AWS 빅 데이터 블로그에서 다음 관련 게시물을 참조하세요.