Narwhal API 데이터 DB 저장: Postgres에 적재하기

설정할 내용

이 워크플로에서 Postgres는 데이터를 저장하는 대상이며, 결과로 데이터 영역별 CSV 파일과 반복 적재를 지원하는 공휴일 테이블이 만들어집니다. Postgres는 HTTP를 직접 가져올 수 없으므로, 요청은 데이터베이스에 적재하기 전에 셸에서 실행합니다. curl, jq, psql이 필요합니다. 가져오기 명령은 API URL과 인증 헤더를 공유 도우미로 묶어 쓰고, 데이터베이스 예제는 공휴일 테이블에 쓰기 전에 임시 스테이징 테이블을 사용합니다. 내보내기는 공휴일, 발표일, CPI, 원자재 가격, 환율, 정책 금리 경로 확률을 별도의 파일로 나누고, 영역마다 응답 필드를 골라 담습니다.

API 키 설정

1. 무료 키 만들기 Narwhal 가입에서 무료 키를 만드세요. Narwhal은 공휴일, 경제 캘린더, 경제 데이터, 원자재 현물 가격, 환율, 예측시장 확률 전체에 계정 하나와 API 키 하나를 사용합니다.
2. 환경 변수에 키 저장하기 가져오기 명령을 실행하는 셸에서는 키를 NARWHAL_API_KEY라는 환경 변수에 보관하세요. 도우미는 요청을 보낼 때마다 이 변수를 읽으므로, 모든 CSV 내보내기에 같은 키가 적용됩니다.
3. 공유 요청 도우미 사용하기 명령은 Authorization: Bearer YOUR_KEY 헤더로 키를 https://api.narwhalapi.com에 보냅니다. REST와 MCP는 키를 공유합니다. 이 Postgres 워크플로에서는 결과 파일을 psql로 적재하기 전에 셸 도우미에서 REST 요청을 사용하세요.

코드로 데이터 가져오기

1. 각 영역을 CSV로 가져오기 셸 명령을 실행해 영역별로 요청하고 jq로 응답 필드를 고릅니다. 도우미는 curl -f를 사용하므로 HTTP 오류 상태에서 실패합니다. 각 파이프라인은 CSV 파일을 쓰며, 열 순서는 jq 식의 필드 순서를 따릅니다. 공휴일은 날짜와 이름 열이 되고, CPI는 기간과 값 열이 됩니다. 파일의 스테이징 테이블을 정의할 때는 이 순서를 유지하세요.
   1단계, curl과 jq로 각 영역을 CSV로 가져오기

   get() {
     curl -sf -H "Authorization: Bearer $NARWHAL_API_KEY" \
       "https://api.narwhalapi.com$1"
   }
   
   get /v1/calendars/holidays/USA/2026 \
     | jq -r '.holidays[] | [.date, .name] | @csv' \
     > holidays.csv
   get \
     "/v1/economics/calendar?countries=USA&start_date=2026-11-01&end_date=2026-11-30&limit=100" \
     | jq -r '.releases[] | [.at, .period, .topic, .status] | @csv' > releases.csv
   get "/v1/economics/USA/cpi/observations?start=2025-09" \
     | jq -r '.observations[] | [.period, .value] | @csv' \
     > cpi.csv
   get /v1/commodities/spot/BRENT/USD | jq -r '[(now | todate), .price] | @csv' > brent.csv
   get "/v1/fx/rates/USD?currencies=EUR,IDR" \
     | jq -r '.rates[] | [.currency, .rate, .timestamp] | @csv' \
     > fx.csv
   get /v1/predictions/policy-paths/federal-reserve \
     | jq -r '.meetings[] | [.resolves_at, .p_cut, .p_hold, .p_hike] | @csv' \
     > fed.csv

2. 스테이징 테이블로 공휴일 적재하기 psql이 holidays.csv를 읽을 수 있는 곳에서 적재 명령을 실행하세요. 필요하면 대상 테이블을 만들고, CSV를 임시 테이블에 복사한 뒤, 스테이징된 행을 삽입합니다. DISTINCT ON은 한 번의 적재 안에서 중복된 날짜를 제거합니다. 대상에 이미 있는 날짜는 ON CONFLICT가 이름을 업데이트합니다. 다른 CSV 파일도 필드에 맞는 테이블과 기본 키로 같은 적재 패턴을 쓸 수 있습니다. 공휴일 대상 테이블에는 date 타입의 date 열과 text 타입의 name 열이 있습니다. 스테이징 테이블의 열 순서는 CSV와 같습니다.
   2단계, 스테이징 테이블과 업서트로 공휴일 적재하기

   psql <<'SQL'
   CREATE TABLE IF NOT EXISTS holidays (date date PRIMARY KEY, name text);
   CREATE TEMP TABLE staging (date date, name text);
   \copy staging FROM 'holidays.csv' WITH (FORMAT csv)
   INSERT INTO holidays
     SELECT DISTINCT ON (date) date, name FROM staging ORDER BY date, name
     ON CONFLICT (date) DO UPDATE SET name = EXCLUDED.name;
   SQL

일정에 맞춰 실행하기

매일 실행하는 cron 줄로 스크립트를 실행하세요. \copy가 읽을 때 CSV가 준비되도록 가져오기 단계를 데이터베이스 적재보다 앞에 두고, 스크립트에서 NARWHAL_API_KEY를 쓸 수 있게 하세요. 적재가 업서트이므로 다시 실행해도 안전합니다. 이미 있는 공휴일 날짜는 이름이 업데이트됩니다. 다른 파일에는 공휴일의 키를 그대로 복사하지 말고 각자의 기본 키를 사용하세요. CPI는 period를, 환율은 currency와 timestamp를 함께 사용합니다. 예약 적재를 확장할 때는 CSV 필드 순서를 각 스테이징 테이블과 맞추세요.

Postgres의 공휴일

2026년 USA 공휴일을 요청하고 holidays 배열을 읽습니다. 각 항목에는 date와 name이 있으며, 이것이 holidays.csv의 열이 됩니다. 이 파일은 스테이징 테이블 예제에서 사용합니다. 대상 테이블은 공휴일 날짜를 기본 키로 쓰고, 다시 적재하면 해당 날짜의 이름이 업데이트됩니다.

get() {
  curl -sf -H "Authorization: Bearer $NARWHAL_API_KEY" \
    "https://api.narwhalapi.com$1"
}

get /v1/calendars/holidays/USA/2026 \
  | jq -r '.holidays[] | [.date, .name] | @csv' > holidays.csv

Postgres의 발표일

2026년 11월 USA 경제 캘린더를 요청하고 releases를 읽습니다. 이것이 발표일입니다. 데이터베이스에서 발표 시각이 주제 및 기간과 함께 보이도록 CSV에는 at, period, topic, status를 남기세요. 요청 URL에는 시작일과 종료일이 들어가며, 출력은 releases.csv로 저장됩니다.

get() {
  curl -sf -H "Authorization: Bearer $NARWHAL_API_KEY" \
    "https://api.narwhalapi.com$1"
}

get \
  "/v1/economics/calendar?countries=USA&start_date=2026-11-01&end_date=2026-11-30&limit=100" \
  | jq -r '.releases[] | [.at, .period, .topic, .status] | @csv' > releases.csv

Postgres의 경제 데이터

2025년 9월부터의 USA CPI 관측값을 요청하고 observations를 읽습니다. 예제는 각 period와 value를 cpi.csv에 씁니다. 이 시계열에서는 period를 대상 테이블의 기본 키로 사용하세요. 값은 십진수 문자열로 오므로 Postgres에 적재할 때는 numeric 열을 사용하세요. 업서트가 업데이트할 관측값은 period 열로 식별합니다.

get() {
  curl -sf -H "Authorization: Bearer $NARWHAL_API_KEY" \
    "https://api.narwhalapi.com$1"
}

get "/v1/economics/USA/cpi/observations?start=2025-09" \
  | jq -r '.observations[] | [.period, .value] | @csv' > cpi.csv

Postgres의 원자재 현물 가격

USD 기준 BRENT 현물 가격을 요청하고 price를 읽습니다. CSV 식은 jq로 타임스탬프를 추가해 brent.csv에서 가격 앞에 놓으며, 이 타임스탬프는 식에서 만든 값입니다. 가격은 numeric 열에 저장하세요. 현물 코드에는 예를 들어 XAU, XAG, XPT, XPD, XCU, BRENT, WTI가 있습니다.

get() {
  curl -sf -H "Authorization: Bearer $NARWHAL_API_KEY" \
    "https://api.narwhalapi.com$1"
}

get /v1/commodities/spot/BRENT/USD \
  | jq -r '[(now | todate), .price] | @csv' > brent.csv

Postgres의 환율

USD를 기준 통화로 EUR와 IDR 환율을 요청하고 rates를 읽습니다. CSV에는 currency, rate, timestamp가 이 순서로 들어갑니다. 대상 테이블에서는 currency와 timestamp를 함께 기본 키로 쓰고, 십진수 환율은 numeric 열에 저장하세요. 결과로 만들어진 fx.csv는 별도의 스테이징 테이블로 적재합니다.

get() {
  curl -sf -H "Authorization: Bearer $NARWHAL_API_KEY" \
    "https://api.narwhalapi.com$1"
}

get "/v1/fx/rates/USD?currencies=EUR,IDR" \
  | jq -r '.rates[] | [.currency, .rate, .timestamp] | @csv' > fx.csv

Postgres의 예측시장 확률

Federal Reserve 정책 금리 경로를 요청하고 meetings를 읽습니다. CSV의 각 행에는 회의별 resolves_at, p_cut, p_hold, p_hike가 들어갑니다. 출력은 fed.csv로 저장됩니다. 이 적재를 예측시장 확률 테이블에 맞게 바꿀 때는 스테이징 열을 같은 순서로 정의하고 십진수 값에는 numeric을 사용하세요.

get() {
  curl -sf -H "Authorization: Bearer $NARWHAL_API_KEY" \
    "https://api.narwhalapi.com$1"
}

get /v1/predictions/policy-paths/federal-reserve \
  | jq -r '.meetings[] | [.resolves_at, .p_cut, .p_hold, .p_hike] | @csv' > fed.csv

공휴일 테이블로 바로 복사하면 왜 실패할 수 있나요?

\copy는 키가 중복되면 실패합니다. 임시 스테이징 테이블은 삽입에서 중복을 처리하기 전에 행을 받아 줍니다. 공휴일 예제에서 한 파일에 같은 날짜가 반복되면 날짜와 이름의 정렬 순서가 어떤 이름이 남을지 결정합니다. 그다음 업서트가 대상에 이미 있는 날짜를 처리합니다.

가격은 어떻게 저장하나요?

십진수는 문자열로 옵니다. 가격을 Postgres에 적재할 때 numeric으로 캐스팅하세요. CSV는 전달 형식일 뿐이며, 가격이 데이터베이스에 어떻게 저장되는지는 대상 열이 결정합니다. 이 내보내기의 CPI 값과 환율에도 같은 십진수 열 방식을 적용하세요.