Foundry 데이터셋을 위한 ODBC & JDBC 드라이버

전체보기

Foundry 데이터셋을 위한 ODBC 및 JDBC 드라이버는 BI 도구와 ETL 도구와 같은 클라이언트 애플리케이션에서 데이터셋에 접근하기 위한 읽기 전용 SQL 기반 인터페이스를 제공합니다. 사용자는 Foundry에서 프로젝트와 데이터셋을 탐색하고 SQL 쿼리를 실행하여 테이블 데이터에 접근할 수 있습니다. 이 드라이버들은 서버 측에서 SQL 쿼리를 처리하고 실행하는 데 Foundry SQL Server를 활용합니다.

JDBC 또는 ODBC?

클라이언트 애플리케이션에서 두 프로토콜을 모두 지원하는 경우에는 JDBC를 ODBC보다 권장합니다. JDBC 드라이버는 설치하고 설정하는 것이 더 쉽고, 데이터 로딩 성능이 더 우수합니다.

Foundry SQL Server

이 드라이버들은 Foundry 데이터셋에 대한 SQL 쿼리를 처리하고 실행하는 데 Foundry SQL Server를 의존합니다. Foundry SQL Server 아키텍처 문서를 검토하여 아키텍처에 대해 더 알아보고 쿼리 성능을 향상시키는 방법을 알아보세요.

시스템 요구사항

ODBC

JDBC

설정 가이드

ODBC

1부. ODBC 드라이버 설치하기

Downloads: ODBC Driver에 있는 안내에 따라 ODBC 드라이버 설치 프로그램을 실행합니다.

2부. 데이터 소스 이름(DSN) 설정하기

드라이버를 클라이언트 애플리케이션 내에서 사용하려면, 먼저 Foundry 환경에 대한 데이터 소스 이름(DSN)을 설정해야 합니다:

1. 시작 메뉴에서 ODBC를 검색하고 ODBC 데이터 소스 도구를 열어주세요. 64비트 버전을 선택하세요.
2. 사용자 DSN 또는 시스템 DSN 탭에서 추가... 를 클릭합니다.
3. 드라이버 목록에서 FoundrySqlDriver를 선택합니다.
4. 다음 필수 파라미터를 입력합니다:
   1. 데이터 소스 이름: 당신의 기기에 대한 데이터 소스 이름입니다.
   2. 서버: Foundry 환경의 URL입니다; 예를 들어 https://<SUBDOMAIN>.palantirfoundry.com.
   3. 토큰: Foundry 내부의 설정 페이지에서 생성된 보안 토큰입니다. 토큰을 얻는 방법에 대한 설명은 사용자 생성 토큰 문서를 참고해주세요. 추가 인증 옵션에 대해서는 OAuth를 사용하여 인증하기 가이드를 참고하세요.
5. 테스트... 를 클릭하여 성공적인 연결을 확인한 후, 확인을 클릭하여 DSN 설정을 저장합니다.

연결 URL을 구성하는 방법과 추가 설정 파라미터에 대한 정보는 설정 파라미터를 참고하세요.

3부. 클라이언트 애플리케이션 내에서 DSN 설정하기

DSN을 생성한 이후에는 ODBC 소스를 지원하는 클라이언트 애플리케이션에서 참조할 수 있습니다. ODBC 소스에 대한 클라이언트 애플리케이션 문서를 참조하세요. 아래에는 Foundry와 함께 주로 사용되는 애플리케이션들에 대한 설정 가이드가 있습니다:

• Excel
• Power BI
• Microsoft Report Builder

(선택사항) 4부: SQL 쿼리 실행하기

클라이언트 애플리케이션이 지원하는 경우, Foundry 데이터셋에서 행을 반환하는 SQL 쿼리를 테스트해보세요:

-- 데이터셋의 경로에서 처음 10개 데이터를 선택합니다.
SELECT * FROM "/Path/To/Dataset" LIMIT 10

클라이언트 애플리케이션을 통해 프로젝트를 탐색하고 데이터셋을 선택하여 데이터에 접근할 수도 있습니다.

JDBC

Part 1: JDBC 드라이버 설치하기

다운로드: JDBC 드라이버 페이지에서 JDBC 드라이버 (.jar 파일)를 다운로드합니다. 다운로드한 후, 파일을 클라이언트 애플리케이션의 JDBC 연결을 설정하는 관련 문서에서 지정한 적절한 파일 위치에 놓습니다.

Part 2: JDBC 연결 문자열 구성하기

JDBC 연결 문자열 형식은 다음과 같습니다:

jdbc:foundrysql://<FOUNDRY_HOSTNAME>?Password=<TOKEN>
// jdbc:foundrysql://<FOUNDRY_호스트네임>?Password=<토큰>

• FOUNDRY_HOSTNAME은 Foundry 환경의 호스트 이름입니다(예: subdomain.palantirfoundry.com).
• TOKEN은 Foundry 내 설정 페이지에서 생성된 보안 토큰입니다. 토큰을 얻는 방법은 사용자 생성 토큰 문서를 참고하세요. 추가 인증 옵션은 OAuth를 사용하여 인증하기 가이드를 검토하세요.

선택적인 파라미터는 &OptionalParam=<VALUE>를 연결 문자열에 추가하여 지정할 수 있습니다. 사용 가능한 모든 파라미터의 전체 목록은 설정 파라미터를 참조하세요.

JDBC 클라이언트가 드라이버 클래스를 명시적으로 지정해야 하는 경우, com.palantir.foundry.sql.jdbc.FoundryJdbcDriver를 지정하세요.

(선택사항) 파트 3: SQL 쿼리 실행

클라이언트 애플리케이션이 지원하는 경우, Foundry 데이터셋에서 행을 반환하는 SQL 쿼리를 테스트하세요:

-- 데이터셋 경로에서 처음 10개 데이터를 선택합니다.
SELECT * FROM "/Path/To/Dataset" LIMIT 10

클라이언트 애플리케이션은 프로젝트를 탐색하고 데이터셋을 선택하여 데이터에 액세스할 수도 있습니다.

출처

설정 파라미터

ODBC 및 JDBC에서 사용 가능한 설정 파라미터는 동일합니다. 각 드라이버는 클라이언트 애플리케이션 내의 연결 문자열을 사용하거나 클라이언트 애플리케이션 외부에서 구성하는 두 가지 방법으로 구성할 수 있습니다.

파라미터 출처

유형 처리

다음 표는 Foundry 유형이 ODBC 및 JDBC 유형에 어떻게 매핑되는지 보여줍니다.

SQL 방언

다음 표는 사용 가능한 SQL 방언의 일부 SQL 구문 및 기능을 설명합니다( Configuration parameters의 Dialect 파라미터 참조).

사용 가이드

SQL을 사용하여 Foundry 데이터셋 쿼리하기

데이터셋은 SQL 쿼리에서 경로 또는 RID로 참조할 수 있습니다. SQL 구문은 연결에 설정된 방언에 따라 다릅니다( Configuration parameters 참조).

SPARK 방언

-- 기본 SELECT
SELECT * FROM `/Path/To/Dataset`
-- '/Path/To/Dataset'에서 모든 행을 선택합니다.

-- WHERE 절을 사용한 필터링
SELECT * FROM `/Path/To/Dataset`
WHERE years < 13 AND category = 'Z';
-- '/Path/To/Dataset'에서 years가 13보다 작고, category가 'Z'인 모든 행을 선택합니다.

-- JOIN 사용
SELECT * 
FROM `/Path/To/Dataset_A` a
JOIN `/Path/To/Dataset_B` b
    ON a.id = b.fk_id;
-- 'Dataset_A'와 'Dataset_B'를 id와 fk_id를 기준으로 결합합니다. 
-- 이 때, 'Dataset_A'는 a로, 'Dataset_B'는 b로 별명을 지정합니다.

ODBC & ANSI 방언

-- 기본 SELECT
SELECT * FROM "/Path/To/Dataset";

-- WHERE 절을 사용한 필터링
SELECT * FROM "/Path/To/Dataset"
WHERE years < 13 AND category = 'Z'; -- 13년 미만이고 카테고리가 'Z'인 데이터만 선택

-- JOIN 사용
SELECT * 
FROM "/Path/To/Dataset_A" a -- a라는 별칭으로 Dataset_A 선택
JOIN "/Path/To/Dataset_B" b -- b라는 별칭으로 Dataset_B 선택
    ON a.id = b.fk_id; -- a의 id와 b의 fk_id가 같은 데이터끼리 결합

데이터셋 식별자 사용에 대한 안내를 참조하여 데이터셋 식별자를 사용하는 방법을 자세히 알아보십시오.

OAuth를 통한 인증 사용하기

단일 Foundry 계정에 연결된 인증 토큰을 수동으로 생성하는 대신, ODBC & JDBC 드라이버는 추가적인 인증 옵션을 제공하는 OAuth 2.0 플로우를 지원합니다:

• 개별 사용자: 드라이버가 브라우저에서 로그인 프롬프트를 열어 Foundry에 인증합니다.
• 서비스 사용자: 드라이버가 Foundry에 등록된 서드파티 애플리케이션에 연결된 서비스 사용자로 Foundry에 연결합니다.
• 외부 애플리케이션 (개발자를 위한): 서드파티 애플리케이션은 Foundry의 OAuth 시스템과 통합하여 사용자를 대신해서 토큰을 가져옵니다.

가능한 경우, 이들 OAuth 기반 옵션을 토큰 생성보다 선호하는 것이 좋습니다. 이는 보안이 더 강화되고, 개별 사용자의 토큰을 공유하지 않고도 임베디드 연결 문자열의 공유 사용을 허용하기 때문입니다.

개별 사용자 (ODBC는 윈도우에서만 가능)

ODBC 드라이버는 윈도우에서 실행될 때 자동 OAuth 로그인 및 인증 플로우를 지원합니다. 아래 단계를 따라 이 플로우를 설정하십시오:

1. (Foundry 관리자에 의해 완료됨) Foundry에 서드파티 애플리케이션을 등록하고, 다음의 설정 옵션을 지정합니다:
   1. Client type: 대부분의 경우 Public client를 권장합니다; Confidential client는 유즈케이스가 필요할 경우 지원됩니다.
   2. Authorization grant types: Authorization code grant을 활성화하고 리다이렉트 URL을 http://127.0.0.1/foundrydriver/oauthredirect로 설정합니다.
   3. 애플리케이션이 Registered 및 Enabled인지 확인합니다.
   4. 애플리케이션 세부 정보 화면에서 애플리케이션의 Client ID를 복사하고 ODBC 연결을 설정하는 사용자와 공유합니다.
2. Foundry 관리자로부터 Client ID를 받은 후, 다음의 ODBC 연결 파라미터를 설정합니다:
   1. AuthMethod = OauthFlow
   2. OauthClientId = <YOUR_CLIENT_ID>
3. (선택사항) 윈도우 ODBC 관리자 앱에서 이러한 설정을 구성하는 경우, Test 옵션을 선택하여 로그인 프롬프트를 실행하고 로그인이 작동하는지 확인할 수 있습니다.

다음에 클라이언트 애플리케이션에서 드라이버를 사용할 때, 브라우저에서 Foundry에 로그인하라는 프롬프트가 나타납니다. 그 이후에는 드라이버를 사용할 때마다 로그인할 필요는 없지만, 가끔 다시 프롬프트를 받을 수 있습니다.

서비스 사용자

개별 사용자와 관련되지 않은 워크플로(예: 대시보드의 데이터를 일정에 따라 새로 고침)의 경우, OAuth Client Credentials grant 유형을 가진 서드파티 애플리케이션을 활용한 OAuth 기반 서비스 사용자를 권장합니다. 드라이버는 수동으로 생성된 서비스 계정과 생성된 토큰보다 관리하기 쉬운 장기적인 클라이언트 ID/비밀번호 쌍으로 Foundry에 인증합니다.

서비스 사용자를 위한 OAuth 설정을 위해 아래의 단계를 따르십시오:

1. (Foundry 관리자에 의해 완료됨) Foundry에 서드파티 애플리케이션을 등록합니다:
   1. Client type: Confidential client를 선택합니다.
   2. Authorization grant types: Client credentials grant를 활성화하고, Client ID 와 Client Secret 쌍을 안전한 위치에 저장하십시오.
   3. 애플리케이션이 Registered 및 Enabled인지 확인합니다.
   4. 생성된 서비스 사용자가 ODBC 또는 JDBC 드라이버를 통해 접근될 모든 데이터셋에 접근 권한이 부여되었는지 확인합니다. 애플리케이션에 대해 생성된 서비스 사용자는 Client credentials grant 세부 정보 패널에 나열됩니다.
2. 드라이버를 설정할 때 다음의 구성 파라미터를 설정합니다:
   1. AuthMethod = ClientCredentials
   2. OauthClientId = <YOUR_CLIENT_ID>
   3. OauthClientSecret = <YOUR_CLIENT_SECRET>

드라이버는 이제 OAuth 앱의 서비스 사용자로 Foundry에 연결합니다.

외부 애플리케이션 (개발자를 위한)

애플리케이션 개발자는 ODBC와 JDBC 드라이버를 자체 OAuth 클라이언트를 관리하는 애플리케이션에 통합하여 서드파티 애플리케이션과 함께 OAuth 로그인 플로우를 관리할 수 있습니다. 이 옵션은 로그인 플로우의 전체 제어를 허용하며, 사용자를 Foundry 인증으로 리다이렉트하고 사용자가 인증 및 인가를 완료한 후의 인증 응답을 처리하는 것을 포함합니다. Foundry 사용자를 대신해 액세스 토큰을 가져오기 위한 Foundry를 위한 OAuth2 클라이언트 작성 문서를 참조하십시오.

애플리케이션이 사용자 대신 액세스 토큰을 획득하면, 이 토큰은 표준 비밀번호 속성을 통해 드라이버에 전달될 수 있습니다:

• ODBC Pwd / JDBC Password = <ACCESS_TOKEN_OBTAINED_FROM_TOKEN_ENDPOINT>

ODBC 드라이버에서 로깅 활성화

문제 해결을 위해 드라이버 로깅을 활성화해야 하는 경우 아래의 단계를 따르십시오. 이 단계들은 관리자 권한이 필요할 수 있습니다.

1. 로그를 저장할 폴더를 생성하십시오, 예를 들어 My Documents\Foundry Driver logs.
2. 윈도우 ODBC Data Sources 도구를 엽니다. 이는 윈도우 검색 창에서 "ODBC"를 검색하여 찾을 수 있습니다. 64비트 버전을 선택하십시오.
3. System DSN 탭을 엽니다. FoundrySql 소스를 선택하고, 그다음 Configure를 선택합니다. Foundry 데이터 소스 중 어느 것을 선택하든 상관없습니다, 로깅 설정은 Foundry 드라이버를 사용하는 모든 데이터 소스에 적용됩니다.
4. 설정 창에서 Logging Options를 선택합니다.
5. 로그 레벨을 DEBUG로 설정합니다. 로그 경로를 앞서 생성한 폴더로 설정합니다.
6. OK를 선택하여 설정을 저장합니다.

클라이언트 애플리케이션을 재시작하고 문제 해결하고자 하는 작업을 수행합니다. 로그는 선택한 폴더에 나타나야 합니다. Palantir이나 다른 지원 팀의 지원이 필요한 경우, 이 폴더를 압축 파일로 압축하여 공유할 수 있습니다.

문제 해결이 완료된 후에는 ODBC Data Sources 도구로 돌아가서 로그 레벨을 OFF로 설정하여 로깅을 비활성화하십시오. 이 단계는 성능 향상을 위해 권장됩니다.

JDBC 드라이버에서 로깅 활성화

JDBC 드라이버는 Java 애플리케이션에서 제공하는 어떠한 SLF4J 로거도 발견할 수 있습니다. 구체적으로, 애플리케이션은 org.slf4j.impl.StaticLoggerBinder 및 org.slf4j.impl.StaticMDCBinder 클래스의 구현체를 제공해야 합니다. 프로젝트 의존성으로 slf4j-simple (버전 1.X)을 추가함으로써 기본 구현을 사용할 수 있습니다.

SLF4J 로거를 구성하지 않았다면, 드라이버가 처음 로드될 때 다음 메시지가 출력됩니다:

SLF4J: "org.slf4j.impl.StaticLoggerBinder" 클래스를 로드하지 못했습니다. // SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder".
SLF4J: 기본적으로 작업 없음 (NOP) 로거 구현으로 설정됩니다. // SLF4J: Defaulting to no-operation (NOP) logger implementation
SLF4J: 추가 정보는 http://www.slf4j.org/codes.html#StaticLoggerBinder 에서 확인하세요. // SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details.
SLF4J: "org.slf4j.impl.StaticMDCBinder" 클래스를 로드하지 못했습니다. // SLF4J: Failed to load class "org.slf4j.impl.StaticMDCBinder".
SLF4J: 기본적으로 작업 없음 MDCAdapter 구현으로 설정됩니다. // SLF4J: Defaulting to no-operation MDCAdapter implementation.
SLF4J: 추가 정보는 http://www.slf4j.org/codes.html#no_static_mdc_binder 에서 확인하세요. // SLF4J: See http://www.slf4j.org/codes.html#no_static_mdc_binder for further details.

foundry.ini 설정 파일을 사용하여 JDBC 드라이버 구성하기

JDBC 드라이버는 연결 문자열을 사용하는 것 외에도 설정 파일을 통해 구성할 수 있습니다. 이를 위해 JDBC .jar 파일이 위치한 동일한 디렉터리에 foundry.ini라는 파일을 생성합니다.

.ini 파일은 low-priority와 high-priority 두 섹션으로 나뉩니다. low-priority 섹션에서 지정한 속성은 연결 문자열 속성보다 우선순위가 낮습니다. 즉, 같은 속성이 low-priority 섹션과 연결 문자열에 지정된 경우 연결 값이 사용됩니다. 반대로 high-priority 섹션에서 지정한 속성은 연결 속성보다 우선순위가 높습니다. 이는 개발 기계에서 서버로 보고서가 게시되는 상황에서 서버 속성이 개발 속성보다 우선해야 하는 경우에 유용할 수 있습니다.

예시 foundry.ini 파일:

[high-priority]
# 프록시 호스트
proxyHost=myproxy.abc
# 프록시 포트
proxyPort=1234

[low-priority]
# 브랜치
branch=production-branch

Java 16 이상에서 JDBC 드라이버 사용하기

JDBC 드라이버는 기본적으로 Java 15까지의 최대 버젼을 지원합니다. Java 16 이상의 버전과 함께 드라이버를 사용하려면 애플리케이션 내에서 --add-opens Java 런타임 옵션을 java.base/java.nio=ALL-UNNAMED로 설정하세요.

예시: Java 명령어

Copied!
1
2
// java --add-opens 옵션을 사용하여 java.base/java.nio 모듈을 ALL-UNNAMED 모듈에 열고, 애플리케이션 JAR 파일을 실행합니다.
java --add-opens=java.base/java.nio=ALL-UNNAMED -jar your_application.jar

예시: 환경 변수

일부 경우에는 _JAVA_OPTIONS 환경 변수에서 옵션을 지정하는 것이 더 편리합니다. 이 변수는 일부 Java 환경에서 자동으로 감지 및 적용됩니다. Unix 기반 시스템에서는 export 명령을 사용하여 이를 설정할 수 있습니다:

# 자바 옵션을 설정하여 java.nio 패키지를 모든 이름없는 모듈에 열기 설정
export _JAVA_OPTIONS="--add-opens=java.base/java.nio=ALL-UNNAMED"