대시보드 매개 변수란?

대시보드 매개 변수는 대시보드를 대화형으로 만드는 한 가지 방법으로, 뷰어는 단일 값 선택기와 날짜 선택기를 사용하여 런타임 시 데이터 세트 쿼리에 특정 값을 입력할 수 있습니다. 예를 들어 매개 변수는 SQL 쿼리에서 집계되기 전에 날짜 및 제품 범주와 같은 조건에 따라 데이터를 필터링하여 보다 효율적인 쿼리 및 정확한 분석을 수행할 수 있습니다.

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

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

쿼리에 매개 변수 추가

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

쿼리에 매개 변수를 추가하려면 다음을 수행합니다.

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

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

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

쿼리 매개 변수 편집

매개 변수를 편집하려면 다음을 수행합니다.

1. 매개 변수 이름 옆을 클릭합니다 . 매개 변수 세부 정보 대화 상자가 나타나고 다음 구성 옵션이 포함됩니다.
   • 키워드: 쿼리의 매개 변수를 나타내는 키워드입니다. 쿼리의 텍스트를 직접 업데이트해야만 변경할 수 있습니다.
   • 표시 이름: 필터 편집기에서의 이름입니다. 기본적으로 제목은 키워드(keyword) 동일합니다.
   • 형식: 지원되는 형식에는 문자열, 날짜, 날짜 및 시간, 숫자가 포함됩니다.
     • 기본 형식은 String입니다.
     • 숫자 데이터 형식을 사용하면 10진수와 정수 사이에 지정할 수 있습니다. 기본 숫자 형식은 10진수입니다.
2. UI의 다른 부분을 클릭하여 대화 상자를 닫습니다.

기본 매개 변수 값 설정

매개 변수 이름 아래의 텍스트 필드에 매개 변수를 입력하여 매개 변수의 기본값을 설정할 수 있습니다. 쿼리를 실행하여 매개 변수 값이 적용된 쿼리 결과를 미리 봅니다. 쿼리를 실행하면 기본값도 저장됩니다. 캔버스에서 필터 위젯을 사용하여 이 매개 변수를 설정하면 기본값이 사용됩니다.

쿼리 기반 매개 변수

쿼리 기반 매개 변수를 사용하면 작성자가 대시보드에서 데이터를 탐색할 때 뷰어에서 선택할 수 있는 동적 또는 정적 값 목록을 정의할 수 있습니다. 쿼리 기반 매개 변수를 만들기 위해 대시보드 작성자가 다음 단계를 수행합니다.

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)

필터 유형

단일 값 및 날짜 선택 필터 는 설정 매개 변수를 지원합니다. 날짜 선택기 필터를 사용하여 쿼리 기반 매개 변수를 설정할 때 기본 쿼리 결과에 표시되는 날짜는 검은색으로 표시됩니다. 쿼리 결과에 표시되지 않는 날짜는 회색입니다. 사용자는 기본 쿼리에 포함되지 않더라도 회색 날짜를 선택할 수 있습니다.

쿼리 매개 변수 제거

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

대시보드에 매개 변수 표시

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

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

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

URL에 매개 변수 포함

매개 변수 설정은 URL에 저장되므로 사용자가 미리 설정된 필터 및 매개 변수를 포함하여 대시보드 상태를 기본 확인하거나 동일한 필터 및 매개 변수의 일관된 적용을 위해 다른 사용자와 공유할 수 있습니다.

매개 변수 구문 예제

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

날짜 삽입

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

Important

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

여러 매개 변수 연결

다른 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)

대시보드 매개 변수와 Databricks SQL 쿼리 매개 변수 비교

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