Foundry 데이터셋용 ODBC와 JDBC
Foundry 드라이버는 BI 및 ETL 클라이언트에서 데이터셋을 탐색하고 읽기 전용 SQL을 실행하는 인터페이스를 제공합니다. 서버 측에서는 Foundry SQL Server가 쿼리를 처리합니다. 두 프로토콜을 모두 지원하는 애플리케이션이라면 설치와 설정이 간단하고 데이터 로딩 성능이 좋은 JDBC가 권장됩니다.
실행 환경
| 드라이버 | 운영체제와 요구 조건 |
|---|---|
| ODBC | Windows 64비트, 관리자 권한, 최신 Microsoft Visual C++ Redistributable |
| JDBC | Windows, macOS, Linux. 기본 Java 지원 범위는 11부터 15까지이며 16 이상에는 아래 추가 옵션 필요 |
ODBC는 현재 Windows만 지원합니다. 배포본에서 해당 설치 프로그램 또는 JAR을 받습니다. Visual C++ 런타임은 Microsoft 배포 안내를 따릅니다.
ODBC 설치와 DSN
- Palantir 서명 ODBC 설치 프로그램을 실행하여 설치합니다.
- Windows Start에서 ODBC를 검색하고 64비트 ODBC Data Sources를 엽니다.
- User DSN 또는 System DSN에서
Add...를 선택합니다. - 드라이버 목록에서 FoundrySqlDriver를 선택합니다.
- Data Source Name에 이 컴퓨터에서 사용할 이름을 지정합니다.
- Server에
https://example.palantirfoundry.com처럼 Foundry 환경의 전체 URL을 지정합니다. - 토큰 인증을 사용할 때는 Foundry Settings에서 생성한 토큰을 Token에 입력합니다. OAuth는 아래의 해당 인증 흐름을 사용합니다.
Test...로 연결을 확인한 뒤 OK로 DSN을 저장합니다.
ODBC 소스를 지원하는 클라이언트에서 이 DSN을 선택합니다. Excel, Power BI와 Microsoft Report Builder가 이 경로를 사용할 수 있습니다. 직접 SQL을 받는 애플리케이션에서는 다음처럼 조회할 수 있습니다. 경로는 가상 예시이며 기본 ODBC 방언의 인용 규칙을 사용합니다.
SELECT * FROM "/Path/To/Dataset" LIMIT 10
일부 클라이언트에서는 쿼리 대신 프로젝트와 데이터셋을 그래픽 탐색기로 선택할 수 있습니다.
JDBC 설치와 연결 문자열
JAR을 애플리케이션이 지정한 JDBC 드라이버 위치에 둡니다. 연결 문자열의 형식은 다음과 같습니다.
jdbc:foundrysql://<FOUNDRY_HOSTNAME>?Password=<TOKEN>
FOUNDRY_HOSTNAME에는 example.palantirfoundry.com 같은 호스트 이름을 넣습니다. JDBC URL 앞에는 jdbc:foundrysql 스킴이 있으므로 이 호스트 자리에 https://를 붙이지 않습니다. TOKEN에는 Foundry 토큰을 넣으며 OAuth 대안도 사용할 수 있습니다. 선택 인자는 &OptionalParam=<VALUE>로 이어 붙입니다.
명시적인 드라이버 클래스가 필요하면 다음 값을 사용합니다.
com.palantir.foundry.sql.jdbc.FoundryJdbcDriver
클라이언트가 SQL을 지원하면 위와 같은 SELECT를 실행하거나 데이터셋 탐색기를 사용할 수 있습니다. 연결 문자열에 자격 증명을 포함했다면 저장소, 공유 문서나 로그에 노출하지 않습니다.
연결 구성 위치
| 프로토콜 | 애플리케이션의 연결 문자열 | 외부 구성 |
|---|---|---|
| ODBC | Driver, BaseUrl, Pwd 등을 세미콜론으로 구분 | Windows ODBC Data Sources의 DSN |
| JDBC | jdbc:foundrysql URL의 쿼리 매개변수 | 드라이버 JAR과 같은 디렉터리의 foundry.ini |
ODBC의 BaseUrl은 전체 Foundry URL입니다.
Driver=FoundrySqlDriver;BaseUrl=https://<FOUNDRY_HOSTNAME>;Pwd=<TOKEN>;Branch=master;Dialect=SPARK
jdbc:foundrysql://<FOUNDRY_HOSTNAME>?Password=<TOKEN>&Branch=master&Dialect=SPARK
위 문자열은 선택 인자로 Branch와 Dialect를 지정한 예시입니다. 꺾쇠 부분을 실제 값으로 바꾸고 조회할 브랜치와 SQL 방언을 맞춥니다. 인앱 자격 증명 입력란을 제공하는 경우 OAuth 클라이언트 ID와 시크릿을 해당 입력란에 지정할 수도 있습니다.
구성 매개변수
| 설정 | 키 | 필수 조건과 동작 |
|---|---|---|
| Foundry URL | ODBC BaseUrl, JDBC는 URL 호스트 부분 | 필수. ODBC 예시는 https://example.palantirfoundry.com |
| 인증 토큰 | ODBC Pwd, JDBC Password | Token 인증 또는 외부 앱에서 얻은 접근 토큰을 전달할 때 사용 |
| 데이터셋 브랜치 | Branch | 생략하면 master |
| 프로젝트/카탈로그 | Catalog | 탐색에 표시할 테이블을 프로젝트 하나로 제한. 예: /MyOrg/MyProject. 일부 앱의 탐색 문제 해결에 사용 |
| 인증 방식 | AuthMethod | Token이 기본값. OauthFlow 또는 ClientCredentials 선택 가능 |
| OAuth 클라이언트 ID | OauthClientId | OauthFlow 또는 ClientCredentials에서 필수. 앱의 username 입력란으로 지정할 수도 있음 |
| OAuth 클라이언트 시크릿 | OauthClientSecret | ClientCredentials에서 필수. 앱의 password 입력란으로 지정할 수도 있음 |
| 프록시 호스트 | ProxyHost | 필요할 때 지정. myproxy.example.com처럼 선행 http 없이 사용. Windows 기본 프록시가 있으면 자동 사용 가능 |
| 프록시 포트 | ProxyPort | ProxyHost를 설정하면 필수 |
| 프록시 사용자 | ProxyUsername | 프록시 인증이 필요할 때 지정. HTTP Basic 인증만 지원 |
| 프록시 암호 | ProxyPassword | ProxyUsername을 지정하면 필수 |
| 프록시 자동 탐지 | EnableProxyAutoDetect | true가 기본값. OS 프록시 자동 사용을 끄는 직접 연결 구성에서는 false 지정. 필요한 프록시 자격 증명은 별도 입력 |
| SSL 신뢰 저장소 | TrustStorePath | 사용자 지정 인증서 체인의 PEM 파일 경로. 기본 OS 신뢰 저장소에 인증서가 없을 때 사용 |
| SQL 방언 | Dialect | ODBC가 기본값. ANSI 또는 SPARK 선택 가능 |
| UTC 시각 | ODBC UtcTimestamps | true이면 UTC, 기본값 false이면 시스템 현지 시간. JDBC에는 적용되지 않음 |
OauthFlow의 자동 로그인은 Windows의 ODBC 데스크톱 흐름에서 지원합니다. 인증 방식을 선택한 뒤 그 흐름의 자격 증명을 제공하며, 브라우저 로그인이나 Client Credentials 흐름에 사용자 생성 토큰을 별도로 필수 입력하는 것으로 해석하지 않습니다.
ODBC의 UtcTimestamps는 로컬 DSN 설정입니다. BI 보고서를 게시한 뒤 서버의 설정이나 시간대가 다르면 결과가 달라질 수 있습니다. JDBC Timestamp는 항상 UTC이며 UtcTimestamps를 지정해도 영향을 받지 않습니다.
자료형 매핑
| Foundry 유형 | ODBC | JDBC |
|---|---|---|
| Array | JSON으로 인코딩한 SQL_WVARCHAR 문자열 | JSON 문자열 |
| Binary | 0x 접두사가 있는 16진 SQL_WVARCHAR 문자열 | byte[] |
| Boolean | SQL_BIT | boolean |
| Byte | SQL_TINYINT | byte |
| Date | SQL_DATE | java.sql.Date |
| Decimal | SQL_DECIMAL | java.math.BigDecimal |
| Double | SQL_DOUBLE | double |
| Float | SQL_DOUBLE | float |
| Integer | SQL_INTEGER | int |
| Long | SQL_BIGINT | long |
| Map | JSON으로 인코딩한 SQL_WVARCHAR 문자열 | JSON 문자열 |
| Short | SQL_SMALLINT | short |
| String | SQL_WVARCHAR | java.lang.String |
| Struct | JSON으로 인코딩한 SQL_WVARCHAR 문자열 | JSON 문자열 |
| Timestamp | SQL_TIMESTAMP. 기본값은 시스템 현지 시간 | UTC의 java.sql.Timestamp |
ODBC 문자열 열의 최대 길이는 StringColumnLength 속성으로 설정할 수 있습니다. Timestamp의 UTC/현지 시간 구분은 위 UtcTimestamps 조건을 따릅니다.
SQL 방언과 인용
Spark 방언이 권장됩니다. 사용하는 연결의 Dialect 설정과 SQL의 인용 문법을 맞춥니다.
| 구분 | SPARK | ANSI 및 ODBC |
|---|---|---|
| 테이블/열 식별자 | 백틱 | 큰따옴표 |
| 문자열 리터럴 | 작은따옴표 또는 큰따옴표 | 작은따옴표 |
| 날짜 리터럴 | DATE 'yyyy-mm-dd' | 같음 |
| 현재 날짜 | CURRENT_DATE | 같음 |
Spark 예시:
SELECT * FROM `/Path/To/Dataset`;
SELECT * FROM `/Path/To/Dataset`
WHERE years < 13 AND category = 'Z';
SELECT *
FROM `/Path/To/Dataset_A` a
JOIN `/Path/To/Dataset_B` b
ON a.id = b.fk_id;
ANSI 및 ODBC 예시:
SELECT * FROM "/Path/To/Dataset";
SELECT * FROM "/Path/To/Dataset"
WHERE years < 13 AND category = 'Z';
SELECT *
FROM "/Path/To/Dataset_A" a
JOIN "/Path/To/Dataset_B" b
ON a.id = b.fk_id;
데이터셋은 경로나 RID로 지정할 수 있습니다. 실제 값은 RID와 Location 확인 절차로 찾습니다. 세부 문법과 함수는 Spark SQL 참조와 ODBC 스칼라 함수에서 확인하되 연결의 방언에 맞추어 사용합니다. 이 드라이버는 읽기 전용입니다.
OAuth 인증
가능하면 사용자 생성 토큰보다 OAuth 흐름을 사용합니다. 사용자 개인의 토큰을 공유하지 않고 연결 구성을 공동으로 사용할 수 있습니다.
Windows ODBC의 개인 사용자
자동 OAuth 로그인은 컴퓨터에 설치한 데스크톱 애플리케이션에서만 지원합니다. 웹 브라우저로 접속하는 애플리케이션의 연결 방식으로 사용하지 않습니다.
관리자는 Foundry에 타사 애플리케이션을 등록합니다.
- 대부분의 경우 Public client를 사용합니다. 필요한 사용 사례에서는 Confidential client도 지원합니다.
- Authorization code grant를 활성화하고 redirect URL을 다음 값으로 설정합니다.
http://127.0.0.1/foundrydriver/oauthredirect
- 애플리케이션이 Registered 및 Enabled 상태인지 확인합니다.
- Client ID를 연결을 구성할 사용자에게 전달합니다.
사용자는 AuthMethod를 OauthFlow로, OauthClientId를 받은 Client ID로 설정합니다. OauthClientId 대신 애플리케이션의 username 입력란에 Client ID를 넣을 수도 있지만 AuthMethod는 여전히 설정해야 합니다. Windows ODBC Administrator의 Test를 선택하면 로그인 창을 열어 확인할 수 있습니다.
클라이언트에서 드라이버를 다음에 사용하면 브라우저에서 Foundry 로그인을 요청합니다. 이후 매번 로그인할 필요는 없지만 때때로 다시 인증을 요청할 수 있습니다.
서비스 사용자
개인 사용자와 무관한 정기 대시보드 새로 고침 같은 작업에는 Client Credentials grant 기반 서비스 사용자를 사용합니다. 장기 유지하는 클라이언트 ID/시크릿 쌍을 관리하며 드라이버가 앱에 연결된 서비스 사용자로 인증합니다.
관리자는 다음을 구성합니다.
- 타사 애플리케이션의 유형을 Confidential client로 선택합니다.
- Client credentials grant를 활성화하고 Client ID와 Client Secret을 안전하게 보관합니다.
- 애플리케이션을 Registered 및 Enabled 상태로 둡니다.
- Client credentials grant 상세 패널의 생성된 서비스 사용자에게 필요한 데이터셋 접근 권한을 부여합니다.
드라이버에는 다음 값을 지정합니다.
AuthMethod=ClientCredentials
OauthClientId=<YOUR_CLIENT_ID>
OauthClientSecret=<YOUR_CLIENT_SECRET>
클라이언트가 자격 증명 입력란을 제공하면 Client ID와 Client Secret을 각각 username과 password로 넣을 수 있습니다. 이 경우에도 AuthMethod는 지정해야 합니다.
애플리케이션이 직접 OAuth를 관리하는 경우
개발자는 앱의 OAuth 클라이언트에서 Foundry 로그인으로 이동시키고, 사용자의 인증 및 승인 응답을 처리하여 접근 토큰을 얻을 수 있습니다. 얻은 토큰을 ODBC의 Pwd 또는 JDBC의 Password에 전달합니다. 공통 인증에서 사용자 승인 흐름과 서비스 사용자 흐름을 구분합니다.
ODBC 로그
드라이버 로그를 설정하려면 관리자 권한이 필요할 수 있습니다.
- My Documents\Foundry Driver logs 같은 로그 폴더를 준비합니다.
- 64비트 ODBC Data Sources를 엽니다.
- System DSN의 FoundrySql 같은 Foundry 드라이버 소스를 선택하고 Configure를 엽니다. 어느 Foundry DSN에서 설정하든 같은 드라이버를 쓰는 모든 소스에 로그 설정을 적용합니다.
- Logging Options에서 로그 수준을 DEBUG로, 경로를 준비한 폴더로 설정합니다.
- OK로 저장하고 클라이언트 애플리케이션을 다시 시작합니다.
- 확인하려는 동작을 수행하고 로그 폴더의 결과를 확인합니다.
지원팀에 전달할 때는 폴더를 ZIP으로 묶을 수 있습니다. 공유 전에 민감한 정보가 포함되어 있는지 확인합니다. 문제 확인이 끝나면 성능을 위해 로그 수준을 OFF로 되돌립니다.
JDBC 로그
Java 애플리케이션의 classpath에서 SLF4J 구현을 찾습니다. org.slf4j.impl.StaticLoggerBinder와 org.slf4j.impl.StaticMDCBinder 구현이 필요하며, 기본 구현으로 slf4j-simple 1.x를 의존성에 추가할 수 있습니다.
로거를 구성하지 않으면 처음 드라이버를 불러올 때 다음 진단 문구가 나타납니다.
SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder".
SLF4J: Defaulting to no-operation (NOP) logger implementation
SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details.
SLF4J: Failed to load class "org.slf4j.impl.StaticMDCBinder".
SLF4J: Defaulting to no-operation MDCAdapter implementation.
SLF4J: See http://www.slf4j.org/codes.html#no_static_mdc_binder for further details.
이 문구는 SLF4J 바인딩이 없음을 나타냅니다. 로그 구현을 연결할 때는 드라이버가 요구하는 1.x 바인딩을 사용합니다.
foundry.ini 우선순위
JDBC JAR과 같은 디렉터리에 foundry.ini를 둡니다. high-priority 속성은 연결 문자열보다 우선하고 low-priority 속성은 연결 문자열보다 낮은 우선순위입니다. 개발 컴퓨터에서 게시한 보고서보다 서버 측 속성을 우선할 때 사용할 수 있습니다.
[high-priority]
proxyHost=myproxy.abc
proxyPort=1234
[low-priority]
branch=production-branch
Java 16 이상
기본 Java 지원 범위의 상한은 15입니다. Java 16 이상에서는 애플리케이션의 JVM에 다음 옵션을 적용합니다.
java --add-opens=java.base/java.nio=org.apache.arrow.memory.core,ALL-UNNAMED -jar your_application.jar
일부 Java 환경은 _JAVA_OPTIONS를 자동 적용합니다. Unix 계열 환경의 예시는 다음과 같습니다.
export _JAVA_OPTIONS="--add-opens=java.base/java.nio=org.apache.arrow.memory.core,ALL-UNNAMED"
연결 실패, 권한 오류와 인증서 체인 문제는 드라이버 문제 해결을 확인합니다. 엔진별 실행 조건은 연결 구조에 설명되어 있습니다.