Slate 데이터 질의

Queries 패널은 구성된 데이터 소스에 질의와 요청을 보냅니다. 템플릿 편집과 이벤트, 일정 및 실행 조건을 구분하며 JSON 기반 템플릿의 구문 검사와 요청 미리보기를 제공합니다.

소스가 여러 개인 앱은 검색창 옆 필터 아이콘으로 소스별 질의를 고를 수 있습니다. 소스를 모두 선택하거나 해제할 수 있고 검색어와 함께 사용하여 목록을 좁힙니다.

보안 경계

Foundry Synchronizer의 동기화 테이블은 읽기 전용이며 원본 Foundry 데이터셋에 대한 접근 권한도 적용합니다. 외부 SQL 또는 HTTP JSON 소스는 템플릿 입력이 요청 구조를 바꾸지 않도록 각 소스의 보안 규칙을 적용합니다.

질의의 {{user.firstName}} 같은 사용자 정보 참조는 로그인 시 브라우저에 전달된 값을 신뢰하는 대신 서버에서 값을 얻습니다.

API Gateway

API Gateway 소스는 Foundry API를 호출합니다. 소스에 활성화된 서비스와 엔드포인트만 선택기에 나타납니다.

1. 새 질의를 만들고 Source에서 API Gateway 유형의 소스를 선택합니다.
2. Service에서 서비스, Method에서 엔드포인트를 선택합니다.
3. Show description으로 서비스, 엔드포인트나 매개변수의 설명을 펼칩니다. 기본적으로 접혀 있으며 HTTP 메서드와 경로 및 폐기 예정 경고를 확인할 수 있습니다.

원하는 엔드포인트가 없으면 소스에 활성화되지 않았거나 플랫폼 인스턴스에서 사용할 수 없는 경우입니다. Palantir 담당자에게 제공 여부를 확인합니다.

자주 사용하는 메타데이터

트랜잭션 이력과 데이터 상태 관련 API 중에는 Public preview가 있습니다. 해당 엔드포인트의 preview 매개변수를 true로 설정하지 않으면 ApiFeaturePreviewUsageOnly 오류가 Slate에서 400으로 표시됩니다. 운영 앱에 사용하기 전에 엔드포인트의 릴리스 단계를 확인합니다.

요청 구성

Slate가 선택한 서비스와 메서드로 HTTP 요청을 만듭니다. 경로, 질의 매개변수, 헤더와 본문을 포함하여 엔드포인트가 받는 각 입력이 표시됩니다. 각 Show description에서 자료형을 확인합니다.

입력에는 정적값 또는 위젯, 변수와 함수의 Handlebars 참조를 직접 사용할 수 있습니다. API Gateway는 HTTP JSON과 보안 방식이 다르므로 참조를 jsonStringify로 감쌀 필요가 없습니다. 본문의 Text/JSON 전환으로 문자열 또는 JSON 객체로 보낼지를 정합니다.

Preview rendered query는 현재값으로 참조를 해석한 읽기 전용 요청을 표시합니다. View query template으로 편집 화면으로 돌아갑니다. API Gateway에는 extractor가 없고 전체 응답을 반환하므로 결과에서 필요한 필드를 참조합니다.

Legacy Foundry 동기화 질의

온톨로지나 API Gateway 대신 데이터셋을 Foundry의 Postgres에 동기화하여 SQL로 읽는 Legacy 경로도 지원됩니다. 플랫폼 인스턴스에 dataset sync가 활성화되어 있어야 하며 추가 개발은 예정되어 있지 않습니다. 새 기능에는 온톨로지 경로를 권장합니다.

Dataset sync 패널에서 데이터셋을 추가하고 Sync to Postgres를 엽니다. 테이블 이름을 지정한 뒤 Apply and sync를 선택합니다.

완료되면 같은 패널에 나타나는 SQL 예를 Queries에 사용할 수 있습니다. 이 Foundry 소스에는 SQL 보안 helper를 사용할 필요가 없습니다.

외부 SQL 소스

Foundry 소스를 제외한 SQL 질의의 Handlebars 참조는 SQL 보안 helper 또는 허용된 Handlebars Built-in helper로 감싸야 합니다.

아래는 설명용 스키마와 테이블 이름을 사용한 템플릿입니다.

SELECT column1
FROM {{schema someSchemaName 'allowedSchemaName1' 'allowedSchemaName2'}}.{{table someTableName 'allowedTableName1'}};

SELECT {{column someColumnName}} FROM table1;

별칭을 등록한 뒤 참조할 수 있습니다. 이 예에서 someColumnName은 aliasedColumnName입니다.

SELECT column1 AS {{alias 'aliasedColumnName'}}
FROM table1
ORDER BY {{column someColumnName}};

값은 숫자나 문자열로 전달하며 다른 데이터베이스 자료형이 필요하면 연결 소스의 형 변환 문법을 사용합니다. PostgreSQL의 날짜 변환 예는 다음과 같습니다.

SELECT column1 FROM table1
WHERE column1 > {{param value1}} AND dateColumn1 < {{param value2}}::date;

세부 입력과 오류는 SQL helper를 따릅니다. 편집기는 SQL 명령을 받지만 실제로 가능한 동작은 연결 데이터베이스와 실행 권한에 달려 있습니다. 읽기 전용 Foundry 동기화 소스와 외부 쓰기 소스를 구분합니다.

결과 형식

SELECT name, diameter, period FROM allNamed;

이런 질의의 행은 열마다 배열을 가진 JSON으로 전달됩니다. 다음은 결과 형식을 보이는 데이터 예입니다.

{
  "name": ["Undina", "Hekate"],
  "diameter": [126.42, 88.66],
  "period": [5.68801089633658, 5.42957878301233]
}

문자열과 숫자 변환은 연결 SQL 소스의 함수로 수행할 수 있습니다.

HTTP JSON 소스

HTTP JSON 템플릿의 모든 Handlebars 참조는 jsonStringify로 감쌉니다. 값이 따옴표나 객체 경계를 닫고 다른 요청 속성을 추가하는 것을 막기 위한 규칙입니다. 경로에는 ..를 사용할 수 없습니다.

다음은 Handlebars 치환 전 요청 템플릿입니다. 이 경로와 메서드 및 filter 본문을 받는 데이터 소스가 구성되어 있어야 합니다.

{
  "path": "path/to/api",
  "method": "POST",
  "bodyJson": { "filter": {{jsonStringify w1.text}} },
  "extractors": { "result": "$" },
  "headers": { "Custom_Header": "my custom header value" }
}

문자열 일부에 값을 넣을 때에는 jsonStringify 블록을 사용합니다.

{
  "path": "path/to/api",
  "method": "POST",
  "bodyJson": {
    "filter": {{#jsonStringify}}some text plus {{w1.text}}{{/jsonStringify}}
  },
  "extractors": { "result": "$" },
  "headers": { "Custom_Header": "my custom header value" }
}

요청 필드

다음은 queryParams와 본문을 함께 받는 예제 엔드포인트의 구성입니다. GET 본문은 대상 엔드포인트가 해당 요청 계약을 지원할 때 사용합니다.

{
  "path": "astronomy/_comets",
  "queryParams": {"limit":5,"text":"searchabc"},
  "method": "GET",
  "bodyJson": {
    "fields": ["name","type","date"],
    "query": {"type":"dust"}
  },
  "extractors": {"name":"$.results[*].fields.name"},
  "headers": {"Custom_Header":"my custom header value"}
}

Elasticsearch 예

다음은 request 접두사로 문서를 필터링하고 auth별 건수를 집계하는 HTTP JSON 요청입니다. auth는 해당 인덱스에서 집계할 수 있는 필드여야 합니다. terms의 size 10은 반환할 버킷 수를 최대 10개로 제한합니다.

{
  "path": "geologist/_search",
  "method": "POST",
  "bodyJson": {
    "query": {"prefix":{"request":"/daily/api/permalinks/"}},
    "aggs": {
      "views": {"terms":{"field":"auth","size":10}}
    }
  },
  "extractors": {
    "Users":"$.aggregations.views.buckets[*].key",
    "Views":"$.aggregations.views.buckets[*].doc_count"
  }
}

결과 크기

SQL과 Foundry 질의의 기본 결과 한도는 5,000,000바이트(5 MB)입니다. 넘으면 일부만 반환하지 않고 실패하므로 데이터가 커지면 이전에 성공한 질의도 실패할 수 있습니다.

Test에서 Size of query result exceeded specified maximum size of 뒤에 설정된 바이트 한도가 붙는 오류를 확인할 수 있습니다. 필요한 열만 선택하거나 LIMIT, 필터 또는 집계를 사용하고 필요한 경우 여러 질의로 나눕니다. 더 큰 결과가 필요한 업무는 Palantir Support와 한도를 검토합니다.

Query partial

Queries의 + New Partial로 여러 질의에서 재사용할 SQL 조각을 만듭니다. columnFilter의 내용이 다음과 같다고 가정합니다.

WHERE column={{param w8.selectedValue}}

질의에서 다음처럼 포함합니다.

SELECT * FROM table {{>columnFilter}}

매개변수화한 partial은 입력 이름으로 참조합니다.

WHERE column={{param columnValue}}

SELECT * FROM table {{>columnFilter columnValue=w8.selectedValue}}

일반 형식은 {{>partialName arg1=value1 arg2=value2}}이며 정적값과 Handlebars 참조를 전달할 수 있습니다. partial 안에 다른 partial을 넣는 것도 가능합니다. 편집기에서 이름을 바꾸면 질의 안의 해당 partial 참조도 자동 갱신됩니다.

조건부 질의

Triggers & interactions의 Special constraints에서 실행 조건을 정합니다.

선택한 값을 질의에 쓰는 경우 값이 준비되기 전에 요청하면 오류가 날 수 있습니다. 아래 예는 w_visits_bar.selection.data.[0].xValues가 아직 없는 경우입니다.

참조값이 null인 동안 실행을 막으면 실패할 요청이 연결과 자원을 사용하지 않게 합니다.

탭 안의 위젯처럼 처음에는 보이지 않는 대상은 표시할 때에만 질의하도록 구성할 수도 있습니다. 예제의 질의는 w_tabbed_container.selectedTabId를 사용하고, f_chart_visible은 해당 차트가 보이는지를 Boolean으로 반환하는 함수입니다.

The handlebar input returns true에 {{f_chart_visible}}을 지정합니다.

API Gateway 오류 확인

400, 500 또는 An error occurred 같은 표시만으로 원인을 정하지 않습니다.

1. Preview rendered query에서 실제 매개변수와 빈 참조값을 확인합니다. View query template으로 돌아갈 수 있습니다.
2. Preview의 </>에서 가공 전 JSON 응답을 엽니다.
3. errorName으로 실패 종류를, parameters로 해당 입력이나 리소스를 확인합니다. 지원 요청에는 자신의 응답에 있는 errorInstanceId를 보관합니다.

다음은 가상 RID를 사용한 오류 구조 예입니다.

{
  "errorCode":"NOT_FOUND",
  "errorName":"DatasetNotFound",
  "errorInstanceId":"00813215-0844-4716-be7b-a3fe0fce9e42",
  "parameters":{"datasetRid":"ri.foundry.main.dataset.example"}
}

API 오류의 의미를 확인합니다. 실패한 질의는 health check 대화상자에도 모이며 해당 질의로 바로 이동할 수 있습니다.

원인을 찾지 못하면 참조값을 정적값으로 바꿔 어느 입력에서 차이가 생기는지 분리할 수 있습니다. 실제 값을 확인하는 debugger도 사용할 수 있습니다.

Legacy 항공편 데이터 준비 절차

가능하면 Object Set 패널을 사용합니다. 아래는 dataset sync가 활성화된 Legacy 환경에서 Postgres 동기화를 사용하는 절차입니다. last-mile-flights와 airports 데이터셋이 미리 준비되어 있어야 합니다.

데이터셋 동기화

Dataset sync의 리소스 추가로 데이터셋을 선택합니다. 이전 화면에서는 Variables의 +Add가 이 진입점입니다.

All Files > Getting started data에서 last-mile-flights를 찾거나 검색한 뒤 Select last-mile-flights를 선택합니다.

Sync to Postgres를 펼칩니다.

기본 테이블 이름에는 경로, 대소문자와 공백이 포함될 수 있으므로 SQL에서 큰따옴표로 감싸야 합니다. 별도의 Postgresql table name을 정할 때에는 소문자와 밑줄을 사용하는 snake_case 이름을 권장합니다.

이 예제는 데이터가 작고 접근 패턴이 아직 정해지지 않았으므로 인덱스를 만들지 않습니다. 필요하면 나중에 추가할 수 있습니다. Apply and sync로 시작하고 Check Status로 상태를 확인합니다.

완료 후 제공되는 질의의 형태는 다음과 같습니다. 끝의 숫자와 실제 테이블 이름은 동기화 결과에 따라 다릅니다.

SELECT * FROM "foundry_sync"."Getting Started Data/last-mile-flights-master-9406" LIMIT 10;

자신의 동기화 화면에서 제공한 질의를 보관하고 airports도 같은 방식으로 동기화합니다.

q_allFlights 질의

Queries에서 + New query를 선택하고 Name을 q_allFlights로 지정합니다. Source는 이름 옆 유형이 FOUNDRY인 소스입니다. 이름은 foundry-sync, foundry-postgate 또는 foundry 등으로 다를 수 있습니다. q_ 같은 접두사를 쓰면 큰 앱에서 질의를 구분하기 쉽습니다.

동기화가 제공한 SQL을 입력하고 Test 또는 Windows의 Ctrl+Enter, macOS의 Cmd+Enter로 확인합니다. Preview에서 결과를, </>에서 원시 JSON을 봅니다. 오류가 나면 동기화 여부와 정확한 테이블 경로를 확인하고 Update Query로 저장합니다.

다음 예에서는 실제 동기화 테이블 이름을 String 변수 v_flightTable에 넣어 사용합니다. 변수값에는 schema나 바깥 큰따옴표를 제외한 테이블 이름을 지정합니다. 필요한 열만 고릅니다.

SELECT
    flight_id,
    carrier_code,
    tail_num,
    origin,
    dest,
    dep_ts_utc,
    arr_ts_utc,
    distance,
    actual_elapsed_time
FROM "foundry_sync"."{{v_flightTable}}"
LIMIT 10;

이 직접 참조는 위에서 설명한 FOUNDRY 동기화 소스용입니다. 외부 SQL 소스에는 해당 보안 helper 규칙을 적용합니다.