쿼리 parameters로 작업하기

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

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

명명된 매개 변수 표식 구문

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

• SQL 편집기
• Notebooks
• AI/BI 대시보드 데이터 세트 편집기
• AI/BI Genie 공간(공개 미리 보기)

SQL 쿼리에 Insertparameters을 추가하려면 콜론과 매개 변수 이름(:parameter_name등)을 입력하세요. 쿼리에 명명된 매개 변수 표식을 포함하면 위젯이 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 쿼리에서 표식을 편집합니다.
   • 제목: 위젯 위에 표시되는 제목입니다. 기본적으로 제목은 키워드와 동일합니다.
   • 형식: 지원되는 형식은 텍스트, 숫자, 드롭다운 List, 날짜, 날짜 및 시간, 날짜 및 시간(초 포함)입니다. 기본값은 Text입니다.
4. 대화 상자에서 형식을 숫자로 변경합니다.
5. 매개 변수 위젯에 숫자를 입력하고 변경 내용 적용을 클릭합니다.
6. 저장 을 클릭하여 쿼리를 저장합니다.

명명된 매개 변수 구문 예제

다음 예제에서는 parameters몇 가지 일반적인 사용 사례를 보여 줍니다.

날짜 Insert

다음 예제에서는 쿼리 결과를 특정 날짜 이후의 레코드로 제한하는 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

Insert 숫자

다음 예는 Number 매개 변수를 포함하며, where 결과를 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

필드 이름 Insert

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

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

데이터베이스 개체 Insert

다음 예제에서는 catalog, schema및 table세 가지 parameters만듭니다.

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

IDENTIFIER 절참조하십시오.

여러 parameters을/를 으로 연결하기

다른 SQL 함수에 parameters 포함할 수 있습니다. 이 예제에서는 뷰어가 직원 제목과 숫자 ID를 select 수 있습니다. 쿼리는 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 문자열로 작업

parameters 사용하여 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)

날짜 범위 추가

다음 예제에서는 특정 시간 프레임에서 select 레코드에 매개변수로 설정된 날짜 범위를 추가하는 방법을 보여 줍니다.

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

하나의 쿼리에서 여러 values을 사용

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

:list_parameter 값은 쉼표로 구분된 values를 list로 취합니다. SPLIT 함수는 list을 구문 분석하여, 쉼표로 구분된 values를 배열로 분할합니다. 이 함수는 TRANSFORM 공백을 제거하여 배열의 각 요소를 변환합니다. ARRAY_CONTAINS 함수는 tripstable에서 dropoff_zip 값이 list_parameter로 전달된 values 배열에 포함되어 있는지를 확인합니다.

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

구문 변경 내용

다음 table는 일반적인 사용 사례를 보여 줍니다. 이 사례들은 parameters, 원래 Databricks SQL의 콧수염 구문 및 명명된 매개 변수 표식 구문을 사용하는 동일한 구문을 포함합니다.

수염 매개 변수 구문

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

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

• 레거시 대시보드 필터
• 여러 값 드롭다운 parameters
• 쿼리 기반 드롭다운 parameters

콧수염 매개 변수 추가

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

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

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

쿼리 매개 변수 편집

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

쿼리 매개 변수 Remove

remove 쿼리 매개 변수를 삭제하려면, 해당 매개 변수를 쿼리에서 제거하십시오. 매개 변수 위젯이 사라지고 정적 values사용하여 쿼리를 다시 작성할 수 있습니다.

parameters 순서 변경

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

쿼리 매개 변수 형식

• Text
• 숫자
• 드롭다운 List
• Query-Based 드롭다운 List
• 날짜 및 시간

Text

문자열을 입력으로 받습니다. 백슬래시, 작은따옴표 및 큰따옴표는 이스케이프 처리되고 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 }}

드롭다운 List

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

• 단일 값: 매개 변수를 작은따옴표로 묶어야 합니다.
• 다중 값: 여러 values 옵션을 켜거나 끕니다. 따옴표 드롭다운 메뉴에서 parameters를 입력한 대로 그대로 둘지(따옴표 없음) 또는 parameters을 작은따옴표나 큰따옴표로 감쌀지를 선택합니다. 따옴표를 선택하는 경우 매개변수 주위에 따옴표를 추가할 필요가 없습니다.

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

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

매개변수 다중 선택 위젯은 데이터베이스에 여러 values를 전달하게 해줍니다. select 큰따옴표 옵션을 따옴표 매개 변수에 선택할 경우, 쿼리는 다음 형식을 반영합니다: WHERE IN ("value1", "value2", "value3")

Query-Based 드롭다운 List

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

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

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

예를 들어, 다음 쿼리를 실행하면 table에서 데이터를 반환한다고 가정합니다.

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

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

날짜 및 시간

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

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

-- 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 }}'

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

동적 날짜 및 날짜 범위 values

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

대시보드에서 쿼리 parameters 사용

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

• 위젯 매개 변수

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

• 대시보드 매개 변수

  대시보드 parameters는 여러 시각화에 적용할 수 있습니다. 매개 변수가 있는 쿼리를 기반으로 시각화를 대시보드에 추가하면 기본적으로 매개 변수가 대시보드 매개 변수로 추가됩니다. 대시보드 parameters는 대시보드에서 하나 이상의 시각화에 대해 구성되며, 대시보드의 맨 위에 표시됩니다. 대시보드 매개 변수에 대해 지정된 매개 변수 values 특정 대시보드 매개 변수를 재사용하는 시각화에 적용됩니다. 대시보드에는 여러 parameters가 있을 수 있으며, 각각의 경우 일부 시각화에는 적용될 수 있지만 다른 시각화에는 그렇지 않을 수 있습니다.

• 고정 값

  정적 values는 변화를 반영하는 매개 변수 대신 사용됩니다. 정적 values 매개 변수 대신 값을 하드 코딩할 수 있습니다. 이전에 표시된 where 대시보드 또는 위젯에서 매개 변수를 "사라지게" 만듭니다.

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

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

매개 변수 속성

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

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

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

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

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

  

FAQ(질문과 대답)

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

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

예. 중괄호에 동일한 identifier을 사용하도록 합니다. 이 예에서는 {{org_id}} 매개 변수를 두 번 사용합니다.

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

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

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

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