쿼리 매개 변수
쿼리 매개 변수를 사용하면 런타임에 값을 쿼리로 대체할 수 있습니다. 이중 중괄호 {{ }} 사이의 모든 문자열은 쿼리 매개 변수로 처리됩니다. 매개 변수 값을 설정하는 결과 창 위에 위젯이 나타납니다. 쿼리 매개변수는 쿼리 필터보다 유연하며 쿼리 필터가 충분하지 않은 경우에만 사용해야 합니다.
쿼리 매개 변수 추가
Cmd + I. 매개 변수가 텍스트 캐럿에 삽입되고 매개 변수 추가 대화 상자가 나타납니다.- 키워드: 쿼리의 매개 변수를 나타내는 키워드입니다.
- 제목: 위젯 위에 표시되는 제목입니다. 기본적으로 제목은 키워드(keyword) 동일합니다.
- 형식: 지원되는 형식은 텍스트, 숫자, 날짜, 날짜 및 시간, 날짜 및 시간(초 포함), 드롭다운 목록 및 쿼리 기반 드롭다운 목록입니다. 기본값은 Text입니다.
- 키워드를 입력하고 선택적으로 제목을 재정의하고 매개 변수 형식을 선택합니다.
- 매개 변수 추가를 클릭합니다.
- 매개 변수 위젯에서 매개 변수 값을 설정합니다.
- 변경 내용 적용을 클릭합니다.
- 저장을 클릭합니다.
또는 이중 중괄호를 {{ }} 입력하고 매개 변수 위젯 근처의 기어 아이콘을 클릭하여 설정을 편집합니다.
다른 매개 변수 값으로 쿼리를 다시 실행하려면 위젯에 값을 입력하고 변경 내용 적용을 클릭합니다.
쿼리 매개 변수 편집
매개 변수를 편집하려면 매개 변수 위젯 옆에 있는 기어 아이콘을 클릭합니다. 쿼리를 소유하지 않은 사용자가 매개 변수를 변경하지 못하도록 하려면 결과만 표시를 클릭합니다. <Keyword> 매개 변수 대화 상자가 나타납니다.
쿼리 매개 변수 제거
쿼리 매개 변수를 제거하려면 쿼리에서 매개 변수를 삭제합니다. 매개 변수 위젯이 사라지고 정적 값을 사용하여 쿼리를 다시 작성할 수 있습니다.
매개 변수 순서 변경
매개 변수가 표시되는 순서를 변경하려면 각 매개 변수를 클릭하여 원하는 위치로 끌 수 있습니다.
쿼리 매개 변수 형식
Text
문자열을 입력으로 받습니다. 백슬래시, 단일 및 큰따옴표는 이스케이프되고 Azure Databricks는 이 매개 변수에 따옴표를 추가합니다. 예를 들어, mr's Li"s 같은 문자열은 'mr\'s Li\"s'로 변환됩니다. 이를 사용하는 예는 다음과 같습니다.
SELECT * FROM users WHERE name={{ text_param }}
숫자
숫자를 입력으로 사용합니다. 이를 사용하는 예는 다음과 같습니다.
SELECT * FROM users WHERE age={{ number_param }}
드롭다운 목록
쿼리를 실행할 때 가능한 매개 변수 값의 범위를 제한하려면 Dropdown List 매개 변수 형식을 사용합니다. 예를 들어 SELECT * FROM users WHERE name='{{ dropdown_param }}'입니다. 매개 변수 설정 패널에서 선택하면 허용되는 값을 입력하는 텍스트 상자가 나타나고 각 값은 새 줄로 구분됩니다. 드롭다운 목록은 텍스트 매개 변수입니다. 드롭다운 목록에서 날짜 또는 날짜 및 시간을 사용하려면 데이터 원본에 필요한 형식으로 입력합니다. 문자열은 이스케이프되지 않습니다. 단일 값 또는 다중 값 드롭다운 중에서 선택할 수 있습니다.
- 단일 값: 매개 변수 주위에 작은따옴표가 필요합니다.
- 다중 값: 여러 값 허용 옵션을 전환합니다. 따옴표 드롭다운에서 매개 변수를 입력된 대로 그대로 둘지(따옴표 없음) 매개 변수를 작은따옴표나 큰따옴표로 래핑할지 선택합니다. 따옴표를 선택하는 경우 매개 변수 주위에 따옴표를 추가할 필요가 없습니다.
쿼리에서 WHERE 키워드(keyword) 사용하도록 IN 절을 변경합니다.
SELECT ...
FROM ...
WHERE field IN ( {{ Multi Select Parameter }} )
매개 변수 다중 선택 위젯을 사용하면 데이터베이스에 여러 값을 전달할 수 있습니다. 따옴표 매개 변수에 대해 큰따옴표 옵션을 선택하면 쿼리에 다음 형식이 반영됩니다.WHERE IN ("value1", "value2", "value3")
쿼리 기반 드롭다운 목록
쿼리 결과를 입력으로 사용합니다. 드롭다운 목록 매개 변수와 동일한 동작을 가집니다. Databricks SQL 드롭다운 목록 쿼리를 저장하여 다른 쿼리의 입력으로 사용해야 합니다.
- 설정 패널의 형식에서 쿼리 기반 드롭다운 목록을 클릭합니다.
- 쿼리 필드를 클릭하고 쿼리를 선택합니다. 대상 쿼리에서 많은 수의 레코드를 반환하면 성능이 저하됩니다.
대상 쿼리가 둘 이상의 열을 반환하는 경우 Databricks SQL은 첫 번째 열을 사용합니다. 대상 쿼리가 name 및 value 열을 반환하는 경우 Databricks SQL은 매개 변수 선택 위젯을 name 열로 채우지만 연결된 value를 사용하여 쿼리를 실행합니다.
예를 들어 다음 쿼리가 테이블의 데이터를 반환한다고 가정합니다.
SELECT user_uuid AS 'value', username AS 'name'
FROM users
| value | name |
|---|---|
| 1001 | John Smith |
| 1002 | 신원 미상 |
| 1003 | Bobby 테이블 |
Azure Databricks가 쿼리를 실행하면 데이터베이스에 전달되는 값은 1001, 1002 또는 1003이 됩니다.
날짜 및 시간
Azure Databricks에는 시간 범위의 매개 변수화를 간소화하는 옵션을 포함하여 날짜 및 타임스탬프 값을 매개 변수화하는 몇 가지 옵션이 있습니다. 다양한 정밀도의 세 가지 옵션 중에서 선택합니다.
| 옵션 | 정밀도 | Type |
|---|---|---|
| 날짜 | 일 | DATE |
| 날짜 및 시간 | 분 | TIMESTAMP |
| 날짜 및 시간(초 포함) | second | TIMESTAMP |
범위 매개 변수 옵션을 선택할 때 .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 }}'
날짜 매개 변수는 달력 선택 인터페이스를 사용하며 기본적으로 현재 날짜 및 시간으로 설정됩니다.
참고 항목
날짜 범위 매개 변수는 DATE 형식의 열에 대해서만 올바른 결과를 반환합니다. TIMESTAMP 열의 경우 날짜 및 시간 범위 옵션 중 하나를 사용합니다.
동적 날짜 및 날짜 범위 값
쿼리에 날짜 또는 날짜 범위 매개 변수를 추가하면 선택 위젯에 파란색 번개 아이콘이 표시됩니다. 이 아이콘을 클릭하면 today, yesterday, this week, last week, last month 또는 last year와 같은 동적 값이 표시됩니다. 이러한 값은 동적으로 업데이트됩니다.
Important
동적 날짜 및 날짜 범위는 예약된 쿼리와 호환되지 않습니다.
대시보드에서 쿼리 매개 변수 사용
필요에 따라 쿼리는 매개 변수 또는 정적 값을 사용할 수 있습니다. 매개 변수가 있는 쿼리를 기반으로 하는 시각화가 대시보드에 추가되면 다음 중 하나를 사용하도록 시각화를 구성할 수 있습니다.
위젯 매개 변수
위젯 매개 변수는 대시보드의 단일 시각화와 관련이 있으며 시각화 패널에 표시되며 지정된 매개 변수 값은 시각화의 기본 쿼리에만 적용됩니다.
대시보드 매개 변수
대시보드 매개 변수는 여러 시각화에 적용할 수 있습니다. 매개 변수가 있는 쿼리를 기반으로 시각화를 대시보드에 추가하면 매개 변수가 기본적으로 대시보드 매개 변수로 추가됩니다. 대시보드 매개 변수는 대시보드에서 하나 이상의 시각화에 대해 구성되고 대시보드의 맨 위에 표시됩니다. 대시보드 매개 변수에 대해 지정된 매개 변수 값은 해당 대시보드 매개 변수를 재사용하는 시각화에 적용됩니다. 대시보드에는 여러 매개 변수가 있을 수 있으며, 각 매개 변수는 다른 시각화가 아닌 일부 시각화에 적용할 수 있습니다.
정적 값
정적 값은 변경 내용에 응답하는 매개 변수 대신 사용됩니다. 고정 값을 사용하면 매개 변수 대신 값을 하드 코딩할 수 있으며 이전에 표시된 대시보드 또는 위젯에서 매개 변수가 "사라집니다".
매개 변수가 있는 쿼리를 포함하는 시각화를 추가할 때 적절한 연필 아이콘을 클릭하여 시각화 쿼리에서 매개 변수의 제목과 원본을 선택할 수 있습니다. 키워드와 기본값도 선택할 수 있습니다. 매개 변수 속성을 참조하세요.
대시보드에 시각화를 추가한 후 대시보드 위젯의 오른쪽 위에 있는 세로 줄임표를 클릭한 다음 위젯 설정 변경을 클릭하여 매개 변수 매핑 인터페이스에 액세스합니다.
매개 변수 속성
제목: 대시보드의 값 선택기 옆에 표시되는 표시 이름입니다. 기본값은 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}}'