다음을 통해 공유

대시보드 매개 변수 작업

  • 아티클

이 문서에서는 AI/BI 대시보드에서 매개 변수를 사용하는 방법을 설명합니다. 대신 필드 필터에 대해 알아보려면 필드에 대한 필터를 참조하세요.

AI/BI 대시보드 매개 변수를 사용하면 런타임에 다른 값을 데이터 세트 쿼리로 대체할 수 있습니다. 이렇게 하면 SQL 쿼리에서 데이터를 집계하기 전에 날짜 및 제품 범주와 같은 기준으로 데이터를 필터링하여 보다 효율적인 쿼리 및 정확한 분석을 수행할 수 있습니다. 매개 변수를 필터 위젯과 함께 사용하여 대시보드를 대화형으로 만들거나 시각화 위젯을 사용하여 데이터 세트를 더 쉽게 재사용할 수 있습니다.

대시보드 작성자 또는 편집기가 데이터 세트에 매개 변수를 추가하고 대시보드 캔버스의 하나 이상의 위젯에 연결합니다. 시각화 위젯에 설정된 정적 매개 변수의 경우 값은 작성자 또는 편집기에서 설정합니다. 필터 위젯에 사용되는 매개 변수의 경우 대시보드 뷰어는 런타임에 필터 위젯에서 값을 선택하여 데이터와 상호 작용할 수 있습니다. 이 상호 작용은 연결된 쿼리를 다시 실행하고 필터링된 데이터를 기반으로 시각화를 표시합니다.

매개 변수는 강력한 쿼리를 직접 수정합니다. 데이터 세트 필드 필터는 매개 변수보다 큰 데이터 세트를 사용하여 대시보드 대화형 작업, 더 많은 기능 및 더 나은 성능을 제공할 수도 있습니다. 필터 사용을 참조 하세요.

쿼리 매개 변수 추가

대시보드 데이터 세트에 매개 변수를 추가하려면 초안 대시보드에 대해 적어도 CAN EDIT 권한이 있어야 합니다. 데이터 탭의 데이터 세트 쿼리에 직접 매개 변수를 추가할 수 있습니다.

Gif는 다음 단계의 예를 보여줍니다.

쿼리 매개 변수 추가

  1. 쿼리에서 매개 변수를 배치할 위치에 커서를 놓습니다.

  2. 매개 변수 추가를 선택하여 새 매개 변수를 삽입합니다.

    그러면 기본 이름(parameter)으로 새 매개 변수가 만들어집니다. 기본 이름을 변경하려면 쿼리 편집기에서 바꿉다. 쿼리 편집기에서 이 구문을 입력하여 매개 변수를 추가할 수도 있습니다.

쿼리 매개 변수 편집

매개 변수 편집

  1. 매개 변수 이름 옆에 있는 기어 아이콘 아이콘을 클릭합니다. 매개 변수 세부 정보 대화 상자가 나타나고 다음 구성 옵션이 포함됩니다.

    • 키워드: 쿼리의 매개 변수를 나타내는 키워드입니다. 쿼리의 텍스트를 직접 업데이트해야만 변경할 수 있습니다.

    • 표시 이름: 필터 편집기에서의 이름입니다. 기본적으로 제목은 키워드와 동일합니다.

    • 형식: 지원되는 형식에는 문자열, 날짜, 날짜 및 시간, 숫자가 포함됩니다.

      • 기본 형식은 문자열 형식입니다.
      • 숫자 데이터 형식을 사용하면 10진수와 정수 사이를 지정할 수 있습니다. 기본 숫자 형식은 10진수입니다.

    • 여러 선택 허용: 사용자가 런타임에 여러 매개 변수를 선택할 수 있도록 확인란을 선택합니다.

      참고 항목

      이 옵션을 선택하려면 쿼리를 추가로 변경해야 할 수 있습니다. 여러 선택 허용을 참조 하세요.

  2. UI의 다른 부분을 클릭하여 대화 상자를 닫습니다.

기본 매개 변수 값 설정

쿼리를 실행하려면 매개 변수 이름 아래의 텍스트 필드에 입력하여 매개 변수의 기본값을 선택합니다. 쿼리를 실행하여 매개 변수 값이 적용된 쿼리 결과를 미리 봅니다. 쿼리를 실행하면 기본값도 저장됩니다. 캔버스에서 필터 위젯을 사용하여 이 매개 변수를 설정하는 경우 필터 위젯에 새 기본값을 지정하지 않는 한 기본값이 사용됩니다. 필터 사용을 참조 하세요.

여러 선택 허용

여러 선택을 허용하는 쿼리는 쿼리에 함수를 ARRAY_CONTAINS 포함해야 합니다.

다음 예제에서는 런타임에 쿼리에 삽입할 여러 값을 선택할 수 있는 SQL 쿼리를 보여 줍니다. 절은 WHERE 함수를 ARRAY_CONTAINS 사용합니다. 이 함수는 매개 변수 키워드와 열 이름을 인수로 사용합니다. 쿼리가 실행되면 선택한 매개 변수 값이 포함된 모든 행을 반환합니다.

SELECT
  *
FROM
  samples.tpch.lineitem
WHERE array_contains(:parameter, l_quantity)

기본값을 설정하려면 표시 이름 아래의 텍스트 필드에 입력합니다. 다음 값을 입력하기 전에 현재 값을 선택합니다.

기본값은 편집기에서 설정됩니다. 여러 값이 선택되고 공백으로 구분됩니다.

날짜 범위 매개 변수 적용

매개 변수를 사용하여 범위를 정의하고 해당 범위 내의 결과만 반환할 수 있습니다. 다음 매개 변수 형식 중 하나를 선택하면 지정된 두 개의 매개 변수 .min 와 .max 접미사를 만듭니다.

  • 날짜 범위
  • 날짜 및 시간 범위

다음 예제에서는 이름이 지정된 date_param날짜 범위 매개 변수를 만드는 SQL 쿼리를 보여줍니다.

SELECT * FROM samples.tpch.lineitem
WHERE l_shipdate BETWEEN :date_param.min and :date_param.max

날짜 범위 매개 변수를 만들려면 다음을 수행합니다.

  1. 매개 변수 추가를 클릭합니다.

  2. 매개 변수 이름 옆에 있는 기어 아이콘 아이콘을 클릭합니다. 키워드 및 표시 이름을 입력합니다. 접미사를 포함하거나 .max 접미사를 포함하지 .min 마세요.

  3. 날짜 범위 또는 날짜 및 시간 범위를 형식으로 선택합니다.

  4. WHERE 범위를 정의하는 절을 쿼리에 삽입합니다. 범위를 정의하려면 값과 .max 함께 .min 절을 BETWEEN 사용합니다. 예시:

     WHERE date_col BETWEEN :date_param.min AND :date_param.max

  5. 기본 날짜 값을 입력하고 쿼리를 실행하여 테스트합니다. 달력 아이콘을 사용하여 지난 주 또는 지난 달과 같은 미리 설정된 옵션을 선택합니다.

쿼리 기반 매개 변수

쿼리 기반 매개 변수를 사용하면 작성자는 대시보드에서 데이터를 탐색할 때 뷰어에서 매개 변수를 설정할 때 선택할 수 있는 동적 또는 정적 값 목록을 정의할 수 있습니다. 필드 필터와 매개 변수 필터를 단일 필터 위젯으로 결합하여 정의합니다.

쿼리 기반 매개 변수를 만들기 위해 대시보드 작성자가 다음 단계를 수행합니다.

  1. 결과 집합이 가능한 매개 변수 값 목록으로 제한되는 데이터 세트를 만듭니다.
  2. 매개 변수를 사용하는 데이터 세트 쿼리를 만듭니다.
  3. 필드를 필터링하고 매개 변수를 사용하는 캔버스에서 필터 위젯을 구성합니다.
    • 필드 구성은 적합한 매개 변수 값의 원하는 목록과 함께 필드를 사용하도록 설정해야 합니다.
    • 매개 변수 값을 선택하려면 매개 변수 구성을 설정해야 합니다.

참고 항목

쿼리 기반 매개 변수에 사용되는 데이터 세트가 대시보드의 다른 시각화에도 사용되는 경우 뷰어의 필터 선택은 연결된 모든 쿼리를 수정합니다. 이를 방지하려면 작성자는 대시보드의 다른 시각화에 사용되지 않는 쿼리 기반 매개 변수에 대한 전용 데이터 세트를 만들어야 합니다.

쿼리 기반 매개 변수 및 시각화를 추가하는 방법을 보여 주는 단계별 자습서의 쿼리 기반 매개 변수 사용을 참조하세요.

동적 매개 변수 목록 만들기

뷰어에서 매개 변수 값을 선택하는 데 사용하는 드롭다운을 채우는 동적 데이터 세트를 만들려면 단일 필드를 반환하고 해당 필드의 모든 값을 포함하는 SQL 쿼리를 작성합니다. 해당 필드의 새 값은 매개 변수 선택 영역으로 자동으로 추가됩니다. 예제 SQL 쿼리는 다음과 같습니다.

 SELECT
    DISTINCT c_mktsegment
  FROM
    samples.tpch.customer

정적 매개 변수 목록 만들기

데이터 세트에 하드 코딩하는 값만 포함하는 정적 데이터 세트를 만들 수 있습니다. 쿼리 예는 다음과 같습니다.

SELECT
  *
FROM
  (
    VALUES
      ('MACHINERY'),
      ('BUILDING'),
      ('FURNITURE'),
      ('HOUSEHOLD'),
      ('AUTOMOBILE')
  ) AS data(available_choices)

쿼리 매개 변수 제거거

매개 변수를 제거하려면 쿼리에서 삭제합니다.

정적 위젯 매개 변수

정적 위젯 매개 변수는 시각화 위젯에서 직접 구성되므로 작성자는 동일한 데이터 세트를 공유하는 시각화 위젯을 개별적으로 매개 변수화할 수 있습니다. 이렇게 하면 동일한 데이터 세트가 캔버스에 다른 보기를 표시할 수 있습니다.

이 섹션의 예제는 테이블을 쿼리하는 데이터 세트를 기반으로 합니다 samples.nyctaxi.trips . 제공된 쿼리는 각 여정의 거리를 반환하고 픽업 일을 Weekday 또는 Weekend로 분류합니다. 쿼리 매개 변수는 평일 또는 주말에 픽업이 발생했는지 여부에 따라 결과를 필터링합니다.

쿼리 텍스트는 다음 코드 블록에 제공되지만 이 섹션의 지침은 정적 위젯 매개 변수로 구성된 연결된 시각화를 설정하는 것으로 제한됩니다. 매개 변수를 사용하여 데이터 세트를 설정하는 방법에 대한 지침은 쿼리에 매개 변수 추가를 참조하세요.


  WITH DayType AS (
    SELECT
      CASE
        WHEN DAYOFWEEK(tpep_pickup_datetime) IN (1, 7) THEN 'Weekend'
        ELSE 'Weekday'
      END AS day_type,
      trip_distance
    FROM samples.nyctaxi.trips
  )
  SELECT day_type, trip_distance
  FROM DayType
  WHERE day_type = :day_type_param

시각화에 정적 위젯 매개 변수를 추가하려면 다음을 수행합니다.

  1. 초안 대시보드 캔버스에 시각화 위젯을 추가합니다.

  2. 새 위젯을 선택한 상태에서 구성 패널의 데이터 세트 드롭다운에서 매개 변수가 있는 데이터 세트를 선택합니다.

  3. 필터 표시를 클릭합니다. 매개 변수를 포함하는 데이터 세트의 경우 구성 패널에 매개 변수 섹션이 나타납니다.

    매개 변수를 선택하는 옵션을 보여 주는 시각화 구성 패널

  4. 매개 변수 제목 오른쪽에 있는 더하기 기호를 클릭하고 드롭다운에서 매개 변수를 선택합니다.

  5. 기본적으로 매개 변수 값은 데이터 탭의 쿼리에 설정된 값을 미러링합니다. 데이터 세트를 유지하거나 데이터 세트로 대체할 새 값을 선택할 수 있습니다. 텍스트 필드에서 벗어나 새 매개 변수가 적용된 시각화를 표시합니다.

  6. 대시보드 리뷰

    다음 이미지는 두 개의 시각화 위젯을 보여줍니다. 각각은 정적 위젯 매개 변수를 사용하여 히스토그램으로 구성됩니다. 왼쪽 차트는 평일부터 시작하는 여정의 여정 거리 분포를 보여 주며, 오른쪽 차트는 주말에 동일한 데이터를 표시합니다. 두 시각화 모두 동일한 데이터 세트를 기반으로 합니다.

    설명된 대로 정적 위젯 수준 매개 변수를 사용하도록 구성된 두 개의 히스토그램입니다.

필터 조건을 사용하여 데이터 비교

데이터 부분의 집계를 전체 데이터 집합에 적용된 집계와 비교할 수 있는 필터 조건을 추가할 수 있습니다.

다음 예제에서는 지정된 매개 변수 값 All이(가) 데이터에 나타나지 않는 필터 조건을 포함하도록 이전 쿼리를 확장합니다. 필터 조건의 첫 번째 부분은 이전 예와 동일하게 작동하여 day_type가 Weekday 또는 Weekend인 경우 결과를 필터링합니다. 필터 조건의 두 번째 부분은 매개 변수 자체가 데이터에 표시되지 않는 특정 값(이 경우 All)으로 설정되어 있는지 확인합니다. 데이터 세트 편집기에서 해당 매개 변수의 기본값을 설정하는 경우 Weekday이나 Weekend 값으로 전달되지 않을 때 필터를 효과적으로 무시합니다.


WITH DayType AS (
  SELECT
    CASE
      WHEN DAYOFWEEK(tpep_pickup_datetime) IN (1, 7) THEN 'Weekend'
      ELSE 'Weekday'
    END AS day_type,
    trip_distance
  FROM
    samples.nyctaxi.trips
)
SELECT
  day_type,
  trip_distance
FROM
  DayType
WHERE
  day_type = :day_type_param
  OR :day_type_param = 'All'

이 데이터 세트를 사용하여 day_type_param, All 및 Weekday 각각에 설정된 세 개의 시각화 위젯을 Weekend와(과) 구성할 수 있습니다. 그런 다음 대시보드 뷰어는 일 유형별로 필터링된 각 데이터 세트를 전체 데이터 세트와 비교할 수 있습니다.

다음 GIF는 이 쿼리를 사용하여 만든 데이터 세트에서 세 개의 차트를 빠르게 빌드하는 방법을 보여 줍니다.

  1. 첫 번째 차트는 매개 변수 값이 Weekday로 설정된 Day Type 데이터 세트별 여정 거리를 표시하도록 구성됩니다.
  2. 차트를 복제하여 적용된 모든 구성을 유지 관리합니다.
  3. 주말에 수행된 여정에 대한 데이터를 표시하려면 정적 매개 변수를 주말로 조정합니다.
  4. 새 차트를 복제하여 기존에 적용된 모든 구성을 유지 관리합니다.
  5. 새 차트의 매개 변수를 모두로 설정하여 주말 및 평일 여정의 거리별 총 여정 수를 표시합니다.

앞의 텍스트에 설명된 GIF입니다.

대시보드에 매개 변수 표시

대시보드 캔버스에 필터를 추가하면 뷰어에서 매개 변수 값을 선택하고 수정하여 데이터를 대화형으로 탐색하고 분석할 수 있습니다. 대시보드에 매개 변수를 노출하지 않으면 뷰어는 쿼리에서 설정한 기본 매개 변수 값을 사용하는 쿼리 결과만 볼 수 있습니다.

대시보드에 매개 변수를 추가하려면 다음을 수행합니다.

  1. 필터 아이콘 필터 추가(필드/매개 변수)를 클릭합니다.
  2. 구성 패널에서 매개 변수 옆의 필드 아이콘 추가을 클릭합니다.
  3. 뷰어가 이 위젯에 사용할 매개 변수 이름을 클릭합니다.

필터 위젯 및 정적 매개 변수 작업

매개 변수는 런타임에서 쿼리로 대체되는 고정 값입니다. 대시보드가 업데이트될 때 동일한 매개 변수에 대한 참조가 두 개 이상 다른 값으로 설정되면 시각화 위젯에 충돌하는 값이 있는 매개 변수를 나타내는 오류가 표시됩니다. 여러 필터 위젯이 동일한 매개 변수를 사용하거나 정적 매개 변수가 뷰어 선택을 허용하는 필터 위젯과 충돌할 때 발생할 수 있습니다.

다음 예제와 같은 패턴을 사용하여 동일한 쿼리에서 다른 매개 변수에 대한 대체 값을 설정할 수 있습니다.


CASE WHEN :static_param != 'All' THEN :static_param ELSE :dash_param END

이 예제에서 :static_param는 시각화 위젯과 데이터 세트 편집기 모두에서 'All'로 설정해야 하는 정적 매개 변수를 참조합니다. 매개 변수 :dash_param는 대시보드 캔버스의 필터 위젯에 의해 제어되는 동적 값입니다. 이 문은 정적 매개 변수로 제공된 값을 확인합니다. 설정되지 않은 경우 뷰어에서 선택한 대시보드 매개 변수 값으로 돌아갑니다.

URL에 매개 변수 포함

매개 변수 설정은 URL에 저장되므로 사용자가 미리 설정된 필터 및 매개 변수를 포함하여 대시보드의 상태를 유지 관리하거나 다른 사용자와 공유하여 동일한 필터 및 매개 변수를 일관되게 적용할 수 있도록 책갈피를 설정할 수 있습니다.

대시보드 매개 변수 및 콧수염 쿼리 매개 변수

대시보드 매개 변수는 명명된 매개 변수 표식과 동일한 구문을 사용합니다. 명명된 매개 변수 표식을 참조하세요. 대시보드는 콧수염 스타일 매개 변수를 지원하지 않습니다.

구문 예제

매개 변수의 일반적인 용도로는 JSON 문자열에서 날짜, 숫자, 텍스트, 데이터베이스 개체 및 값을 삽입하는 것이 포함됩니다. 이러한 경우 매개 변수를 사용하는 방법을 보여 주는 예제는 명명된 매개 변수 구문 예제를 참조하세요.

Important

뷰어에서 테이블 또는 카탈로그 이름과 같은 매개 변수 선택을 통해 데이터에 액세스할 수 있게 하면 중요한 정보가 실수로 노출됩니다. 이러한 옵션을 사용하여 대시보드를 게시하는 경우 Azure Databricks는 게시된 대시보드에 자격 증명을 포함하지 않는 것이 좋습니다.