개방형 SQL 인터페이스

Looker LookML 시맨틱 모델링 레이어를 사용하면 데이터 분석가는 SQL 데이터베이스에서 측정기준, 집계, 계산, 데이터 관계를 정의할 수 있습니다. LookML 모델은 코드 재사용성 및 Git 통합을 제공합니다. 잘 구조화된 LookML 모델을 사용하면 사용자가 직접 셀프서비스 데이터 탐색 및 보고를 수행할 수 있습니다.

LookML 모델은 Looker UI의 Looker Explore 인터페이스, 회사 포털 또는 다른 서드 파티 애플리케이션의 임베디드 시각화, Looker API로 개발된 커스텀 애플리케이션 등 Looker에서 요청된 모든 데이터의 기반입니다. 개방형 SQL 인터페이스는 자바 데이터베이스 연결(JDBC)을 지원하는 모든 타사 애플리케이션에 대한 LookML 모델 액세스를 제공합니다. 애플리케이션은 LookML 모델에 데이터베이스인 것처럼 연결할 수 있으므로, 사용자가 가장 익숙한 도구를 사용하여 LookML 모델에서 데이터 분석가가 수행한 모든 작업을 활용할 수 있습니다.

개방형 SQL 인터페이스가 LookML 프로젝트 요소를 표시하는 방법

개방형 SQL 인터페이스가 LookML 프로젝트의 요소를 어떻게 표시하는지 파악하려면 LookML 프로젝트의 구조를 이해하는 것이 중요합니다.

LookML 프로젝트는 Looker에서 SQL 쿼리를 수행하는 데 사용되는 객체, 데이터베이스 연결, 사용자 인터페이스 요소를 설명하는 파일 모음입니다(자세한 내용은 LookML 용어 및 개념 참조). 다음 LookML 프로젝트 개념은 개방형 SQL 인터페이스와 관련이 있습니다.

  • LookML 모델은 데이터베이스 연결 및 하나 이상의 Explore를 지정합니다. 개방형 SQL 인터페이스는 모델을 데이터베이스 스키마로 표시합니다.
  • Explore는 하나 이상의 뷰와 이러한 뷰 간의 조인 관계를 논리적으로 그룹화한 것입니다. 개방형 SQL 인터페이스에서는 Explore를 데이터베이스 테이블로 표시합니다.
  • 는 필드 집합(측정기준 및 측정 모두)을 정의합니다. 뷰는 일반적으로 데이터베이스의 테이블 또는 파생 테이블을 기반으로 합니다. 뷰에는 기본 데이터베이스 테이블의 열과 최종 사용자에게 필요할 수 있는 커스텀 측정기준 또는 측정값이 포함될 수 있습니다. 개방형 SQL 인터페이스는 뷰 이름과 필드 이름의 조합을 데이터베이스 열 이름으로 표시합니다. 예를 들어 order_items 뷰의 id 측정기준은 개방형 SQL 인터페이스에서 order_items.id라는 데이터베이스 열로 표시됩니다.

Looker Explore는 여러 뷰 간의 조인 관계를 정의할 수 있습니다. 한 뷰에 다른 뷰의 필드와 이름이 동일한 필드가 있을 수 있으므로 열을 참조할 때 개방형 SQL 인터페이스에는 뷰 이름과 필드 이름이 모두 포함됩니다. 따라서 개방형 SQL 인터페이스에 쿼리를 전송할 때는 열 이름을 참조하여 다음 형식을 사용합니다.

`<view_name>.<field_name>`

예를 들어 customer 뷰와 product 뷰를 결합하는 order_items라는 Explore가 있고 이 두 뷰 모두 id 측정기준이 있는 경우 이 두 id 필드를 각각 `customer.id``product.id`라고 합니다. Explore 이름과 함께 정규화된 이름을 사용하려면 두 필드를 `order_items`.`customer.id``order_items`.`product.id`라고 합니다. (데이터베이스 식별자를 참조할 때 백틱을 넣을 위치에 대한 자세한 내용은 데이터베이스 식별자 주변에 백틱 사용을 참조하세요.)

개방형 SQL 인터페이스 설정

개방형 SQL 인터페이스를 사용하려면 다음 단계를 수행합니다.

  1. 요구사항이 충족되는지 확인합니다.
  2. 개방형 SQL 인터페이스 JDBC 드라이버 파일을 다운로드합니다.

다음 섹션은 이러한 단계를 설명합니다.

요구사항

개방형 SQL 인터페이스를 사용하기 위해서는 다음 구성요소가 필요합니다.

개방형 SQL Interface JDBC 드라이버 다운로드

Looker 개방형 SQL 인터페이스 JDBC 드라이버는 avatica-<release_number>-looker.jar라고 합니다. https://github.com/looker-open-source/calcite-avatica/releases의 GitHub에서 최신 버전을 다운로드합니다.

JDBC 드라이버에는 다음 URL 형식이 필요합니다.

jdbc:looker:url=https://Looker instance URL

예를 들면 다음과 같습니다.

jdbc:looker:url=https://myInstance.cloud.looker.com

JDBC 드라이버 클래스는 다음과 같습니다.

org.apache.calcite.avatica.remote.looker.LookerDriver

개방형 SQL 인터페이스에 인증

개방형 SQL 인터페이스는 세 가지 인증 방법을 지원합니다.

OAuth

OAuth를 지원하는 JDBC 클라이언트는 Looker 인스턴스의 OAuth 서버를 사용하도록 구성할 수 있습니다. OAuth 인증을 구성하는 단계는 다음과 같습니다.

  1. Looker 인스턴스가 OAuth 요청을 인식할 수 있도록 API 탐색기 확장을 사용하여 Looker 인스턴스에 JDBC OAuth 클라이언트를 등록합니다. 자세한 내용은 OAuth 클라이언트 애플리케이션 등록을 참조하세요.
  2. OAuth로 Looker에 로그인하여 액세스 토큰을 요청합니다. 예시는 OAuth를 사용한 사용자 로그인 수행을 참조하세요.
  3. 속성 객체를 사용하여 개방형 API 인터페이스에 JDBC 연결을 열 때 OAuth 사용자 인증 정보를 전달합니다.

다음은 DriverManager#getConnection(<String>, <Properties>`)를 사용하는 예입니다.

String access_token = getAccessToken() //uses the Looker OAuth flow to get a token
String URL = "jdbc:looker:url=https://myInstance.cloud.looker.com"
Properties info = new Properties( );
info.put("token", access_token);
Connection conn = DriverManager.getConnection(URL, info);

API 키를 사용하여 액세스 토큰 생성

액세스 토큰을 생성하는 데 표준 OAuth 흐름을 사용하는 대신 Looker API를 사용하여 개방형 SQL 인터페이스 JDBC 드라이버로 전달할 수 있는 액세스 토큰을 생성할 수 있습니다.

  1. 관리자 설정 - 사용자 페이지에 설명된 대로 Looker 사용자에 대한 API 키를 생성합니다.
  2. Looker 인스턴스에 login API 엔드포인트를 사용합니다. 응답에는 Authorization: token <access_token> 형식의 액세스 토큰이 포함됩니다. 다음은 이 요청을 실행하는 데 사용할 수 있는 curl 명령어의 예입니다.

      curl -k -d "client_id=<client_id>&client_secret=<client_secret>" https://<looker_host>/login\
    
  3. 속성 객체에서 응답의 <access_token> 값을 토큰으로 전달하여 개방형 SQL 인터페이스로 JDBC 연결을 열 때 OAuth 사용자 인증 정보를 전달합니다.

API 키

사용자 이름과 비밀번호 대신 API 키를 사용하여 인증할 수도 있습니다. API 키는 OAuth보다 보안 수준이 낮은 것으로 간주되며 개방형 SQL 인터페이스 미리보기 중에만 사용 가능합니다. Looker 인스턴스에 대한 API 키 만들기에 대한 자세한 내용은 API 키를 참조하세요.

Looker API 키의 클라이언트 ID 부분을 사용자 이름으로 사용합니다. 비밀번호는 클라이언트 보안 비밀번호 부분을 사용합니다.

개방형 SQL 인터페이스로 쿼리 실행

개방형 SQL 인터페이스로 쿼리를 실행할 때는 다음 가이드라인을 참고하세요.

  • Open SQL 인터페이스는 GoogleSQL 문법을 준수하는 SQL 쿼리를 허용합니다.
  • 개방형 SQL 인터페이스에는 모델, Explore, 필드 식별자 주변에 백틱(`)이 필요합니다. 추가 정보 및 예시는 데이터베이스 식별자 주변에 백틱 사용을 참조하세요.
  • 개방형 SQL 인터페이스는 대부분의 BigQuery 연산자를 지원합니다.
  • 개뱡형 SQL 인터페이스에서는 특수 함수 AGGREGATE()의 측정값(백틱 포함)을 래핑하여 쿼리에 포함된 LookML 측정을 지정해야 합니다. AGGREGATE()로 LookML 측정 지정 섹션을 참조하세요.

LookML 제한사항

개방형 SQL 인터페이스에 쿼리를 전송할 때는 다음 사항에 유의하세요.

SQL 제한사항

개방형 SQL 인터페이스에 쿼리를 전송할 때는 다음 SQL 제한사항에 유의하세요.

  • 개방형 SQL 인터페이스는 SELECT 쿼리만 지원합니다. 개방형 SQL 인터페이스에서는 UPDATEDELETE 문이나 기타 데이터 정의 언어(DDL), 데이터 조작 언어(DML) 또는 데이터 컨트롤 언어(DCL) 문을 지원하지 않습니다.
  • 개방형 SQL 인터페이스는 JOIN 연산자를 지원하지 않습니다.
    • JOIN 연산자와 함께 동일한 Explore 내에 또는 두 개의 다른 Explore에 걸쳐 조인을 만드는 쿼리를 개방형 SQL 인터페이스로 전송할 수 없습니다.
    • 데이터베이스의 두 테이블 간에 조인을 만들려면 LookML 프로젝트의 모델 파일Explore 정의에 있는 하나 이상의 조인을 만들어 LookML 모델에서 조인을 작성할 수 있습니다.
  • 개방형 SQL 인터페이스는 윈도우 함수 호출을 지원하지 않습니다.
  • 개방형 SQL 인터페이스는 서브 쿼리를 지원하지 않습니다.
  • 개방형 SQL 인터페이스는 시간대 변환을 지원하지 않습니다. LookML 모델의 날짜에는 사용자 설정(사용자 시간대, 애플리케이션 시간대 또는 데이터베이스 시간대 설정)에 정의된 시간대에 DATETIME 유형이 있습니다.
  • 개방형 SQL 인터페이스는 BigQuery 데이터 유형 지역, JSON, 시간을 지원하지 않습니다.

데이터베이스 식별자 주변에 백틱 사용

개방형 SQL 인터페이스로 쿼리를 전송할 때는 스키마, 테이블, 열 식별자 주변에 백틱을 사용하세요. Looker 용어와 함께 백틱을 사용하여 데이터베이스 요소를 지정하는 방법은 다음과 같습니다.

  • 스키마: `<model_name>`
  • 테이블: `<explore_name>`
  • 열: `<view_name>.<field_name>`

다음은 이러한 요소를 사용하는 SELECT 문 형식의 예시입니다.

SELECT `view.field`
  FROM `model`.`explore`
  LIMIT 10;

AGGREGATE()로 LookML 측정 지정

데이터베이스 테이블은 일반적으로 측정기준만 포함하는데, 이는 테이블의 한 행에 대한 단일 속성을 설명하는 데이터입니다. 그러나 LookML 프로젝트는 측정기준 및 측정을 모두 정의할 수 있습니다. 측정SUM, AVG, MIN 또는 MAX과 같이 여러 행에 걸쳐 데이터를 집계하는 것입니다. (다른 유형의 측정도 지원됩니다. 지원되는 LookML 측정 유형의 전체 목록은 측정 유형 페이지를 참조하세요.)

개뱡형 SQL 인터페이스에서는 특수 함수 AGGREGATE()의 측정값(백틱 포함)을 래핑하여 쿼리에 포함된 LookML 측정을 지정해야 합니다. 예를 들어 다음을 사용하여 주문 뷰에서 개수 측정값을 지정합니다.

AGGREGATE(`orders.count`)

측정이 SELECT 절, HAVING 절, ORDER BY 절에 있는지 여부에 관계없이 AGGREGATE() 함수에서 LookML 측정을 래핑해야 합니다.

필드가 LookML 측정인지 확실하지 않으면 DatabaseMetaData.getColumns 메서드를 사용하여 LookML 프로젝트의 메타데이터에 액세스할 수 있습니다. IS_GENERATEDCOLUMN 열은 LookML 측정에 대해 YES를, LookML 측정기준에 대해 NO를 표시합니다. 자세한 내용은 데이터베이스 메타데이터 액세스 섹션을 참조하세요.

다음은 측정기준과 측정을 모두 사용하는 쿼리의 예시입니다. 이 쿼리는 고객 뷰에서 상태도시 측정기준을 검색하고 주문 뷰에서 총 금액 기준을 검색합니다. 두 뷰 모두 전자상거래 모델의 주문 Explore에 조인됩니다. 주문이 10개를 초과하는 도시의 경우 이 쿼리 응답은 주문 금액별로 상위 5개 도시를 보여줍니다.

SELECT `customers.state`, `customers.city`,
  AGGREGATE(`orders.total_amount`)
FROM `ecommerce`.`orders`
GROUP BY `customers.state`, `customers.city`
HAVING AGGREGATE(`orders.count`) > 10
ORDER BY 3 DESC LIMIT 5;

JSON_OBJECT로 필터 전용 필드 및 파라미터 지정

개방형 SQL 인터페이스는 파라미터필터 전용 필드를 지원합니다.

개방형 SQL 인터페이스로 쿼리를 실행할 때는 다음 형식의 JSON_OBJECT 생성자 호출을 포함하여 쿼리에 파라미터 및 필터 전용 필드를 적용할 수 있습니다.

JSON_OBJECT(
    '<view>.<parameter name>', '<parameter value>',
    '<view>.<filter name>', '<Looker filter expression>'
)

JSON 객체에는 0개 이상의 필터 키-값 쌍과 0개 이상의 파라미터 키-값 쌍이 포함될 수 있습니다.

  • JSON_OBJECT 생성자의 키는 필터 전용 필드 또는 파라미터의 이름이어야 합니다.
  • 필터 전용 필드의 경우 각 키의 값이 Looker 문자열 필터 표현식이어야 합니다.
  • 파라미터의 경우 각 키 값은 parameter 정의에 정의된 일반 값이어야 합니다.

개방형 SQL 인터페이스에서 파라미터필터 전용 필드를 사용하는 예시는 다음 섹션을 참조하세요.

매개변수 예시

개방형 SQL 인터페이스에서 parameter를 사용하는 예시는 다음과 같이 customers 뷰에 Looker에서 정의된 파라미터가 있는 경우입니다.

parameter: segment {
  type: string
  allowed_value: {
    label: "Small (less than 500)"
    value: "small_customers"
  }
  allowed_value: {
    label: "Larger (greater than 10,000)"
    value: "large_customers"
  }
  allowed_value: {
    label: "Medium customers (Between 500 and 10,000)"
    value: "medium_customers"
  }
}

이 쿼리를 개방형 SQL 인터페이스에 전송하여 medium_customerssegment 파라미터 값을 쿼리에 적용할 수 있습니다.

SELECT `customers.segment_size`,
  AGGREGATE(`orders.total_amount`)
FROM `ecommerce`.`orders`(JSON_OBJECT(
    'customers.segment', 'medium_customers'
))
GROUP BY `customers.state`, `customers.city`
HAVING AGGREGATE(`orders.count`) > 10
ORDER BY 3 DESC LIMIT 5;

개방형 SQL 인터페이스는 이 파라미터 값을 Looker의 쿼리에 전달하고 Looker는 segment 매개변수를 사용하도록 구성된 Explore의 모든 필드에 medium_customers 값을 적용합니다. Looker에서 파라미터가 작동하는 방법은 parameter 문서를 참조하세요.

필터 전용 필드 예시

filter 필드를 개방형 SQL 인터페이스에 사용할 수 있습니다. 예를 들어 다음과 같이 products 뷰에 Looker에서 정의된 측정기준과 필터 전용 필드가 있는 경우:

filter: brand_select {
  type: string
  }

dimension: brand_comparitor {
  sql:
    CASE
      WHEN {% condition brand_select %} ${products.brand_name} {% endcondition %}
      THEN ${products.brand_name}
      ELSE "All Other Brands"
    END ;;
    }

다음과 같은 쿼리를 전송하여 Open SQL 인터페이스에서 brand_select 필터를 사용할 수 있습니다.

SELECT `products.brand_comparator`, `products.number_of_brands`,
  AGGREGATE(`products.total_revenue`)
FROM `ecommerce`.`orders`(JSON_OBJECT(
    'products.brand_select', '%Santa Cruz%'
))
GROUP BY `products.brand_comparator`
ORDER BY 3 DESC LIMIT 5;

개방형 SQL 인터페이스가 Looker의 쿼리에 Looker 문자열 필터 표현식 %Santa Cruz%를 적용합니다. Looker에서 필터 전용 필드가 작동하는 방법은 filter 문서를 참조하세요.

데이터베이스 메타데이터 액세스

개방형 SQL 인터페이스는 기본 데이터베이스에 대한 정보를 얻는 데 사용되는 표준 JDBC DatabaseMetaData 인터페이스의 하위 집합을 지원합니다. DatabaseMetaData 인터페이스의 다음 메서드를 사용하여 LookML 모델에 대한 정보를 가져올 수 있습니다.

DatabaseMetadata.getSchemas

다음 표에서는 LookML 모델이 DatabaseMetadata.getSchemas 인터페이스 메서드의 응답에서 표준 데이터베이스 구조와 어떻게 관련되는지 설명합니다.

getSchemas 응답 열 설명
TABLE_SCHEM LookML 모델 이름
TABLE_CATALOG (Null)

DatabaseMetadata.getTables

다음 표에서는 LookML 모델이 DatabaseMetaData.getTables 인터페이스 메서드의 응답에서 데이터베이스 구조와 어떻게 관련되는지 설명합니다. 응답에는 Looker-특정 메타데이터뿐만 아니라 표준 JDBC 메타데이터도 포함됩니다.

getTables 응답 열 설명
JDBC 표준 메타데이터
TABLE_CAT (Null)
TABLE_SCHEM LookML 모델 이름
TABLE_NAME LookML Explore 이름
TABLE_TYPE 항상 TABLE_TYPE 값을 반환합니다.
Looker 특정 메타데이터
DESCRIPTION Explore 설명
LABEL Explore 라벨
TAGS Explore 태그

DatabaseMetadata.getColumns

다음 표에서는 LookML 모델이 DatabaseMetaData.getColumns 인터페이스 메서드의 응답에서 데이터베이스 구조와 어떻게 관련되는지 설명합니다. 응답에는 Looker-특정 메타데이터뿐만 아니라 표준 JDBC 메타데이터도 포함됩니다.

getColumns 응답 열 설명
JDBC 표준 메타데이터
TABLE_CAT (Null)
TABLE_SCHEM LookML 모델 이름
TABLE_NAME LookML Explore 이름
COLUMN_NAME `<view_name>.<field_name>` 형식의 LookML 필드 이름입니다. 예를 들면 `orders.amount`입니다.
DATA_TYPE 열의 java.sql.Types 코드입니다. 예를 들어 Looker yesno 필드는 SQL 유형 코드 16(BOOLEAN)입니다.
ORDINAL_POSITION Explore 내에서 필드의 1부터 시작하는 서수입니다(뷰 이름을 기준으로 알파벳순으로 측정기준과 측정을 함께 혼합한 다음 필드 이름).
IS_NULLABLE 항상 YES 값을 반환합니다.
IS_GENERATEDCOLUMN 측정값의 경우 YES, 측정기준의 경우 NO
Looker 특정 메타데이터
DIMENSION_GROUP 필드가 측정기준 그룹의 일부인 경우 측정기준 그룹의 이름입니다. 필드가 측정기준 그룹의 일부가 아닌 경우 이 이름은 null입니다.
DRILL_FIELDS 측정기준 또는 측정값에 설정된 드릴 필드 목록(있는 경우)
FIELD_ALIAS 필드의 별칭(있는 경우)
FIELD_CATEGORY 필드가 dimension 또는 measure인지 여부
FIELD_DESCRIPTION 필드 설명
FIELD_GROUP_VARIANT 필드가 그룹 라벨 아래에 표시되면 FIELD_GROUP_VARIANT는 그룹 라벨 아래에 표시되는 필드의 더 짧은 이름을 지정합니다.
FIELD_LABEL 필드 라벨
FIELD_NAME 측정기준 또는 측정의 이름
HIDDEN 탐색(TRUE)의 필드 선택 도구에서 필드를 숨기는지 또는 탐색의 필드 선택 도구에 표시되는지(FALSE) 여부를 나타냅니다.
LOOKER_TYPE 측정기준 또는 측정의 LookML 필드 유형
REQUIRES_REFRESH_ON_SORT 필드 값을 다시 정렬하려면 SQL 쿼리를 새로고침해야 하는지(TRUE) 또는 SQL 쿼리를 새로고침하지 않고 필드 값을 다시 정렬할 수 있는지 여부(FALSE)
SORTABLE 필드를 정렬할 수 있는지(TRUE) 또는 정렬할 수 없는지(FALSE) 여부
TAGS 필드 태그
USE_STRICT_VALUE_FORMAT 필드가 엄격한 값 형식(TRUE)을 사용하는지 또는 아닌지(FALSE) 여부
VALUE_FORMAT 필드의 값 형식 문자열
VIEW_LABEL 필드의 라벨 뷰
VIEW_NAME LookML 프로젝트에 필드가 정의된 의 이름

Looker UI에서 개방형 SQL 인터페이스 쿼리 식별

Looker 관리자는 Looker UI를 사용하여 개방형 SQL 인터페이스에서 시작된 쿼리를 식별할 수 있습니다.

  • 쿼리 관리 페이지에서 개방형 SQL 인터페이스의 쿼리는 'Sql Interface' 소스 값을 갖습니다. 사용자 값에는 쿼리를 실행한 Looker 사용자의 이름이 표시됩니다. 쿼리의 세부정보 버튼을 클릭하여 쿼리에 대한 추가 정보를 불러올 수 있습니다. 세부정보 대화상자에서 SQL 인터페이스 쿼리를 클릭하면 개방형 SQL 인터페이스에서 Looker로 전송된 SQL 쿼리를 확인할 수 있습니다.
  • 시스템 활동 기록 탐색에서 개방형 SQL 인터페이스의 쿼리는 'sql_interface'의 Source 값을 갖습니다. 사용자 이메일 값에는 쿼리를 실행한 Looker 사용자의 이메일 주소가 표시됩니다. Looker 인스턴스 주소를 다음 URL의 맨 앞에 삽입하여 'sql_interface'에서 필터링된 내역 Explore로 직접 이동할 수 있습니다.

    https://Looker instance URL/explore/system__activity/history?fields=history.source,history.completed_date&f[history.source]=sql_interface
    

서드 파티 종속 항목의 저장소

다음 링크는 Looker JDBC 드라이버에서 사용하는 서드 파티 종속 항목의 Google 호스팅 저장소에 대한 액세스 권한을 제공합니다.

https://third-party-mirror.googlesource.com/looker_sql_interface/+/refs/heads/master/third_party/