쿼리 매개 변수 작업

이 문서에서는 Azure Databricks SQL 편집기에서 쿼리 매개 변수를 사용하는 방법을 설명합니다.

쿼리 매개 변수를 사용하면 런타임에 변수 값을 삽입하여 쿼리를 보다 동적으로 유연하게 만들 수 있습니다. 쿼리에 특정 값을 하드 코딩하는 대신 데이터를 필터링하거나 사용자 입력에 따라 출력을 수정하는 매개 변수를 정의할 수 있습니다. 이 방법은 쿼리 재사용을 개선하고 SQL 삽입을 방지하여 보안을 강화하며 다양한 데이터 시나리오를 보다 효율적으로 처리할 수 있도록 합니다.

명명된 매개 변수 표식 구문

명명된 매개 변수 표식은 형식화된 자리 표시자 변수입니다. 이 구문을 사용하여 Azure Databricks UI의 다음 부분에서 쿼리를 작성합니다.

• SQL 편집기(신규 및 레거시)
• 노트북
• AI/BI 대시보드 데이터 세트 편집기
• AI/BI 지니 공간

콜론과 같은 :parameter_name매개 변수 이름을 입력하여 SQL 쿼리에 매개 변수를 삽입합니다. 쿼리에 명명된 매개 변수 표식을 포함하면 위젯이 UI에 나타납니다. 위젯을 사용하여 매개 변수 형식 및 이름을 편집할 수 있습니다.

쿼리에 명명된 매개 변수 표식 추가

이 예제에서는 다음 쿼리에 매개 변수 표식을 추가합니다.

SELECT
  trip_distance,
  fare_amount
FROM
  samples.nyctaxi.trips
WHERE
  fare_amount < 5

이 쿼리는 5달러 미만의 요금 금액만 포함하는 데이터 세트를 반환합니다. 다음 단계를 사용하여 하드 코딩된 값(5) 대신 매개 변수를 사용하도록 쿼리를 편집합니다.

1. 쿼리에서 숫자 5를 삭제합니다.
2. 콜론(:) 뒤에 문자열 fare_parameter을(를) 입력합니다. 업데이트된 쿼리의 마지막 줄에 fare_amount < :fare_parameter을(를) 표시합니다.
3. 을 클릭합니다. 매개 변수 위젯 근처의 기어 아이콘입니다. 대화 상자에는 다음 필드가 표시됩니다.
   • 키워드: 쿼리의 매개 변수를 나타내는 키워드입니다. 이 필드를 편집할 수 없습니다. 키워드를 변경하려면 SQL 쿼리에서 표식을 편집합니다.
   • 제목: 위젯 위에 표시되는 제목입니다. 기본적으로 제목은 키워드와 동일합니다.
   • 형식: 지원되는 형식은 텍스트, 숫자, 드롭다운 목록, 날짜, 날짜 및 시간, 날짜 및 시간(초 포함)입니다. 기본값은 Text입니다.
4. 대화 상자에서 형식을 숫자로 변경합니다.
5. 매개 변수 위젯에 숫자를 입력하고 변경 내용 적용을 클릭합니다.
6. 저장 을 클릭하여 쿼리를 저장합니다.

명명된 매개 변수 구문 예제

다음 예제에서는 매개 변수에 대한 몇 가지 일반적인 사용 사례를 보여 줍니다.

날짜 삽입

다음 예제에서는 쿼리 결과를 특정 날짜 이후의 레코드로 제한하는 Date 매개 변수를 포함합니다.

SELECT
  o_orderdate AS Date,
  o_orderpriority AS Priority,
  sum(o_totalprice) AS `Total Price`
FROM
  samples.tpch.orders
WHERE
  o_orderdate > :date_param
GROUP BY
  1,
  2

숫자 삽입

다음 예제에서는 필드가 제공된 매개 변수 값보다 큰 레코드 로 결과를 제한하는 o_total_price 매개 변수를 포함합니다.

SELECT
  o_orderdate AS Date,
  o_orderpriority AS Priority,
  o_totalprice AS Price
FROM
  samples.tpch.orders
WHERE
  o_totalprice > :num_param

필드 이름 삽입

다음 예제에서는 field_param은(는) IDENTIFIER 함수와 함께 런타임에 쿼리에 대한 임계값을 제공하는 데 사용됩니다. 매개 변수 값은 쿼리에 사용된 테이블의 열 이름이어야 합니다.

SELECT
  *
FROM
  samples.tpch.orders
WHERE
  IDENTIFIER(:field_param) < 10000

데이터베이스 개체 삽입

다음 예제에서는 세 개의 매개 변수를 catalogschematable만듭니다.

SELECT
  *
FROM
  IDENTIFIER(:catalog || '.' || :schema || '.' || :table)

IDENTIFIER 절참조하십시오.

여러 매개 변수 연결

다른 SQL 함수에 매개 변수를 포함할 수 있습니다. 이 예제에서는 뷰어가 직원 제목과 숫자 ID를 선택할 수 있습니다. 쿼리는 format_string 함수를 사용하여 두 문자열을 연결하고 일치하는 행을 필터링합니다. format_string 함수참조하세요.

SELECT
  o_orderkey,
  o_clerk
FROM
  samples.tpch.orders
WHERE
  o_clerk LIKE format_string('%s%s', :title, :emp_number)

JSON 문자열로 작업

매개 변수를 사용하여 JSON 문자열에서 특성을 추출할 수 있습니다. 다음 예에서는 from_json 함수를 사용하여 JSON 문자열을 구조체 값으로 변환합니다. a 문자열을 매개 변수(param)의 값으로 대체하면 특성 1이 반환됩니다.

SELECT
  from_json('{"a": 1}', 'map<string, int>') [:param]

간격 만들기

형식은 INTERVAL 시간 범위를 나타내며 시간 기반 산술 및 연산을 수행할 수 있습니다. 다음 예제에서는 CAST 함수를 사용하여 매개 변수를 간격 형식으로 캐스팅합니다. 결과 INTERVAL 값은 쿼리에서 시간 기반 계산 또는 필터링에 사용할 수 있습니다.

전체 세부 정보 및 구문은 형식을 참조 INTERVAL 하세요.

SELECT CAST(:param AS INTERVAL MINUTE)

날짜 범위 추가

다음 예제에서는 날짜 범위 내에서 레코드를 필터링하는 방법을 보여 줍니다. 날짜 매개 변수와 .max 특성을 사용하여 .min 범위를 지정할 수 있습니다. 두 개의 서로 다른 날짜 매개 변수를 사용하여 범위를 지정할 수도 있습니다.

최소 및 최대 특성 사용

1. 매개 변수 이름을 선택합니다. 다음 쿼리와 같이 최소 범위 값에 액세스하고 .max 최대 범위 값에 액세스하는 데 사용합니다.min.

   SELECT * FROM samples.nyctaxi.trips
   WHERE tpep_pickup_datetime
   BETWEEN :date_range.min AND :date_range.max
   

2. 매개 변수 형식을 .로 Date설정합니다.

3. 위젯 유형을범위로 설정합니다.

두 날짜 매개 변수 사용

다음 예제에서는 두 개의 매개 변수 start_date 를 end_date사용하고 날짜 범위를 설정합니다.

SELECT * FROM samples.nyctaxi.trips
WHERE tpep_pickup_datetime
BETWEEN :start_date AND :end_date

일, 월 또는 연도별 롤업 매개 변수화

다음 예제에서는 매개 변수가 있는 세분성 수준에서 택시 여정 데이터를 집계합니다. 이 함수는 DATE_TRUNC 매개 변수 값(예: tpep_pickup_datetime, :date_granularity또는 DAY.)에 MONTH 따라 값을 자립니다YEAR. 잘린 날짜는 절에서 별칭으로 date_rollup 지정되고 사용됩니다 GROUP BY .

SELECT DATE_TRUNC(:date_granularity, tpep_pickup_datetime) AS
  date_rollup,
  COUNT(*) AS total_trips
FROM samples.nyctaxi.trips
GROUP BY date_rollup

단일 쿼리에서 여러 값 사용

다음 예제에서는 함수를 ARRAY_CONTAINS 사용하여 값 목록을 필터링합니다. TRANSFORM및 SPLIT 함수를 사용하면 쉼표로 구분된 여러 값을 문자열 매개 변수로 전달할 수 있습니다.

이 값은 :list_parameter 쉼표로 구분된 값의 목록을 사용합니다. 이 함수는 SPLIT 해당 목록을 구문 분석하여 쉼표로 구분된 값을 배열로 분할합니다. 이 함수는 TRANSFORM 공백을 제거하여 배열의 각 요소를 변환합니다. 이 함수는 ARRAY_CONTAINS 테이블의 값 dropoff_zip 이 trips 로 전달된 값 배열에 list_parameter포함되어 있는지 여부를 확인합니다.

SELECT * FROM samples.nyctaxi.trips WHERE
  array_contains(
    TRANSFORM(SPLIT(:list_parameter, ','), s -> TRIM(s)),
    dropoff_zip
  )

구문 변경 내용

다음 표에서는 매개 변수, 원래 Databricks SQL 콧수염 구문 및 명명된 매개 변수 표식 구문을 사용하는 동일한 구문에 대한 일반적인 사용 사례를 보여 줍니다.

콧수염 매개 변수 구문

SQL 탐색기에서 이중 중괄호 사이의 모든 {{ }} 문자열은 쿼리 매개 변수로 처리됩니다. 매개 변수 값을 설정하는 결과 창 위에 위젯이 나타납니다. Azure Databricks는 일반적으로 명명된 매개 변수 표식을 사용하는 것이 권장되지만 일부 기능은 콧수염 매개 변수 구문을 사용하여만 지원됩니다.

다음 기능에는 콧수염 매개 변수 구문을 사용합니다.

• 레거시 대시보드 필터
• 다중 값 드롭다운 매개변수
• 쿼리 기반 드롭다운 매개 변수

콧수염 매개 변수 추가

1. Cmd + I. 매개 변수가 텍스트 캐럿에 삽입되고 매개 변수 추가 대화 상자가 나타납니다.
   • 키워드: 쿼리의 매개 변수를 나타내는 키워드입니다.
   • 제목: 위젯 위에 표시되는 제목입니다. 기본적으로 제목은 키워드와 동일합니다.
   • 형식: 지원되는 형식은 텍스트, 숫자, 날짜, 날짜 및 시간, 날짜 및 시간(초), 드롭다운 목록 및 쿼리 기반 드롭다운 목록입니다. 기본값은 Text입니다.
2. 키워드를 입력하고, 필요에 따라 제목을 재정의하고, 매개 변수 유형을 선택합니다.
3. 매개 변수 추가를 클릭합니다.
4. 매개 변수 위젯에서 매개 변수 값을 설정합니다.
5. 변경 내용 적용을 클릭합니다.
6. 저장을 클릭합니다.

또는 이중 중괄호 {{ }}을(를) 입력하고 매개 변수 위젯 근처의 기어 아이콘을 클릭하여 설정을 편집할 수도 있습니다.

다른 매개 변수 값으로 쿼리를 다시 실행하려면 위젯에 값을 입력하고 변경 내용 적용을 클릭합니다.

쿼리 매개 변수 편집

매개 변수를 편집하려면 매개 변수 위젯 옆에 있는 기어 아이콘을 클릭합니다. 쿼리를 소유하지 않은 사용자가 매개 변수를 변경하지 못하도록 하려면 결과만 표시를 클릭합니다. <Keyword> 매개 변수 대화 상자가 나타납니다.

쿼리 매개 변수 제거

쿼리 매개 변수를 제거하려면 쿼리에서 매개 변수를 삭제합니다. 매개 변수 위젯이 사라지고 정적 값을 사용하여 쿼리를 다시 작성할 수 있습니다.

매개 변수 순서 변경

매개 변수가 표시되는 순서를 변경하려면 각 매개 변수를 클릭하여 원하는 위치로 끌 수 있습니다.

쿼리 매개 변수 형식

• 문자 메시지
• 숫자
• 드롭다운 목록
• Query-Based 드롭다운 목록
• 날짜 및 시간

문자 메시지

문자열을 입력으로 받습니다. 백슬래시, 작은따옴표 및 큰따옴표는 이스케이프 처리되고 Azure Databricks는 이 매개 변수에 따옴표를 추가합니다. 예를 들어, mr's Li"s 같은 문자열은 'mr\'s Li\"s'로 변환됩니다. 이를 사용하는 예는 다음과 같습니다.

SELECT * FROM users WHERE name={{ text_param }}

number

숫자를 입력으로 사용합니다. 이를 사용하는 예는 다음과 같습니다.

SELECT * FROM users WHERE age={{ number_param }}

드롭다운 목록

쿼리를 실행할 때 가능한 매개 변수 값의 범위를 제한하려면 Dropdown List 매개 변수 형식을 사용합니다. 예를 들어 SELECT * FROM users WHERE name='{{ dropdown_param }}'입니다. 매개 변수 설정 패널에서 선택하면 허용되는 값을 입력하는 텍스트 상자가 나타나고 각 값은 새 줄로 구분됩니다. 드롭다운 목록은 텍스트 매개 변수입니다. 드롭다운 목록에서 날짜 또는 날짜 및 시간을 사용하려면 데이터 원본에 필요한 형식으로 입력합니다. 문자열은 이스케이프되지 않습니다. 단일 값 또는 다중 값 드롭다운 중에서 선택할 수 있습니다.

• 단일 값: 매개 변수를 작은따옴표로 묶어야 합니다.
• 다중 값: 여러 값 허용 옵션을 토글합니다. 따옴표 드롭다운에서 매개 변수를 입력된 대로 그대로 둘지(따옴표 없음) 매개 변수를 작은따옴표나 큰따옴표로 래핑할지 선택합니다. 따옴표를 선택하는 경우 매개 변수 주위에 따옴표를 추가할 필요가 없습니다.

쿼리에서 WHERE 키워드를 사용하도록 IN 절을 변경합니다.

SELECT ...
FROM   ...
WHERE field IN ( {{ Multi Select Parameter }} )

매개 변수 다중 선택 위젯을 사용하면 여러 값을 데이터베이스에 전달할 수 있습니다. 인용부호 매개 변수에 대해 큰따옴표 옵션을 선택하면 쿼리가 다음 형식을 따릅니다.WHERE IN ("value1", "value2", "value3")

Query-Based 드롭다운 목록

쿼리 결과를 입력으로 사용합니다. 드롭다운 목록 매개 변수와 동일한 동작을 가집니다. Databricks SQL 드롭다운 목록 쿼리를 저장하여 다른 쿼리의 입력으로 사용해야 합니다.

1. 설정 패널의 형식 아래에서 쿼리 기반 드롭다운 목록을 클릭합니다.
2. 쿼리 필드를 클릭하고 쿼리를 선택합니다. 대상 쿼리가 많은 수의 레코드를 반환하면 성능이 저하됩니다.

대상 쿼리가 둘 이상의 열을 반환하는 경우 Databricks SQL은 첫 번째 열을 사용합니다. 대상 쿼리가 name 및 value 열을 반환하는 경우, Databricks SQL은 매개 변수 선택 위젯을 name 열로 채우며, 연결된 value을 사용하여 쿼리를 실행합니다.

예를 들어 다음 쿼리가 테이블의 데이터를 반환한다고 가정합니다.

SELECT user_uuid AS 'value', username AS 'name'
FROM users

Azure Databricks가 쿼리를 실행할 때 데이터베이스에 전달되는 값은 1001, 1002 또는 1003입니다.

날짜 및 시간

Azure Databricks에는 시간 범위의 매개 변수화를 간소화하는 옵션을 포함하여 날짜 및 타임스탬프 값을 매개 변수화하는 몇 가지 옵션이 있습니다. 다양한 정밀도의 세 가지 옵션 중에서 선택합니다.

범위 매개 변수 옵션을 선택할 때는 두 개의 매개 변수를 지정하고 .start.end 접미사를 만듭니다. 모든 옵션은 매개 변수를 쿼리에 문자열 리터럴로 전달합니다. Azure Databricks를 사용하려면 날짜 및 시간 값을 작은따옴표(')로 래핑해야 합니다. 예시:

-- Date parameter
SELECT *
FROM usage_logs
WHERE date = '{{ date_param }}'

-- Date and Time Range parameter
SELECT *
FROM usage_logs
WHERE modified_time > '{{ date_range.start }}' and modified_time < '{{ date_range.end }}'

날짜 매개 변수는 달력 선택 인터페이스를 사용하며 기본적으로 현재 날짜 및 시간으로 설정됩니다.

동적 날짜 및 날짜 범위 값

쿼리에 날짜 또는 날짜 범위 매개 변수를 추가하면 선택 위젯에 파란색 번개 아이콘이 표시됩니다. 를 클릭하여 동적 값(예: today, yesterday, this week, last weeklast month또는 last year)을 표시합니다. 이러한 값은 동적으로 업데이트됩니다.

대시보드에서 쿼리 매개 변수 사용

필요에 따라 쿼리는 매개 변수 또는 정적 값을 사용할 수 있습니다. 매개 변수가 있는 쿼리를 기반으로 하는 시각화가 대시보드에 추가되면 다음을 사용하도록 시각화를 구성할 수 있습니다.

• 위젯 매개 변수

  위젯 매개 변수는 대시보드의 단일 시각화와 관련이 있으며 시각화 패널에 표시되며 지정된 매개 변수 값은 시각화의 기본 쿼리에만 적용됩니다.

• 대시보드 매개 변수

  대시보드 매개 변수는 여러 시각화에 적용할 수 있습니다. 매개 변수가 있는 쿼리를 기반으로 시각화를 대시보드에 추가하면 기본적으로 매개 변수가 대시보드 매개 변수로 추가됩니다. 대시보드 매개 변수는 대시보드에서 하나 이상의 시각화에 대해 구성되고 대시보드의 맨 위에 표시됩니다. 대시보드 매개 변수에 대해 지정된 매개 변수 값은 해당 대시보드 매개 변수를 재사용하는 시각화에 적용됩니다. 대시보드에는 여러 매개 변수가 있을 수 있으며, 각 매개 변수는 다른 시각화가 아닌 일부 시각화에 적용할 수 있습니다.

• 고정 값

  정적 값은 변경 내용에 응답하는 매개 변수 대신 사용됩니다. 정적 값을 사용하면 매개 변수 대신 값을 하드 코딩할 수 있습니다. 이전에 표시된 대시보드 또는 위젯에서 매개 변수를 "사라지게" 만듭니다.

매개 변수가 있는 쿼리를 포함하는 시각화를 추가할 때, 적절한 연필 아이콘을 클릭하여 시각화 쿼리에서 매개 변수의 제목과 원본을 선택할 수 있습니다. 키워드와 기본값도 선택할 수 있습니다. 매개 변수 속성을 참조하세요.

대시보드에 시각화를 추가한 후 대시보드 위젯의 오른쪽 상단에 있는 케밥 메뉴를 클릭한 다음 위젯 설정 변경을 클릭하여 매개변수 매핑 인터페이스에 액세스합니다.

매개 변수 속성

• 제목: 대시보드의 값 선택기 옆에 표시되는 표시 이름입니다. 기본값은 Keyword 매개 변수입니다. 편집하려면, 연필 아이콘 을 클릭합니다. 값 선택기가 숨겨져 있으므로 정적 대시보드 매개 변수에 대한 제목이 표시되지 않습니다. 정적 값을값 원본으로 선택하면 제목 필드가 회색으로 표시됩니다.

• 키워드: 기본 쿼리에서 이 매개 변수에 대한 문자열 리터럴입니다. 이는 대시보드가 예상 결과를 반환하지 않는 경우 디버깅에 유용합니다.

• 기본값: 다른 값이 지정되지 않은 경우 사용되는 값입니다. 쿼리 화면에서 이를 변경하려면 원하는 매개 변수 값으로 쿼리를 실행하고 저장 단추를 클릭합니다.

• 값 원본: 매개 변수 값의 원본입니다. 연필 아이콘을 클릭하여 원본을 선택합니다.

  • 새 대시보드 매개 변수: 새 대시보드 수준 매개 변수를 만듭니다. 이렇게 하면 대시보드의 한 위치에서 매개 변수 값을 설정하고 여러 시각화에 매핑할 수 있습니다.
  • 기존 대시보드 매개 변수: 매개 변수를 기존 대시보드 매개 변수에 매핑합니다. 기존 대시보드 매개 변수를 지정해야 합니다.
  • 위젯 매개 변수: 대시보드 위젯 내부에 값 선택기를 표시합니다. 이는 위젯 간에 공유되지 않는 일회성 매개 변수에 유용합니다.
  • 정적 값: 다른 위젯에 사용된 값에 관계없이 위젯에 대한 정적 값을 선택합니다. 정적으로 매핑된 매개 변수 값은 대시보드에서 더 간결한 위치에 값 선택기를 표시하지 않습니다. 이를 통해 특정 매개 변수가 자주 변경되지 않을 것으로 예상되는 경우 대시보드의 사용자 인터페이스를 복잡하게 만들지 않고 쿼리 매개 변수의 유연성을 활용할 수 있습니다.

  

FAQ(질문과 대답)

• 단일 쿼리에서 동일한 매개 변수를 여러 번 재사용할 수 있나요?
• 단일 쿼리에서 여러 매개 변수를 사용할 수 있나요?

단일 쿼리에서 동일한 매개 변수를 여러 번 재사용할 수 있나요?

예. 중괄호에 동일한 식별자를 사용합니다. 이 예에서는 {{org_id}} 매개 변수를 두 번 사용합니다.

SELECT {{org_id}}, count(0)
FROM queries
WHERE org_id = {{org_id}}

단일 쿼리에서 여러 매개 변수를 사용할 수 있나요?

예. 각 매개 변수에 고유한 이름을 사용합니다. 이 예제에서는 두 개의 매개 변수를 {{org_id}}{{start_date}}사용합니다.

SELECT count(0)
FROM queries
WHERE org_id = {{org_id}} AND created_at > '{{start_date}}'