تحميل البيانات إلى Postgres: جداول وupsert

ما الذي ستعدّه

في هذا الإجراء تكون Postgres وجهة البيانات، وتحصل في النهاية على ملفات CSV لكل مجال من البيانات إضافة إلى جدول للإجازات الرسمية يدعم التحميل المتكرر. لا تستطيع Postgres جلب HTTP بنفسها، لذا تُنفَّذ الطلبات في الطرفية قبل التحميل إلى قاعدة البيانات. تحتاج إلى curl وjq وpsql. تشترك أوامر الجلب في دالة مساعدة لعنوان API ورأس التفويض؛ ويستخدم مثال قاعدة البيانات جدولًا مرحليًا مؤقتًا قبل الكتابة في جدول الإجازات الرسمية. تحفظ عمليات التصدير الإجازات الرسمية وتواريخ الإصدار وCPI وأسعار السلع وأسعار الصرف واحتمالات مسار السياسة النقدية في ملفات منفصلة، مع اختيار حقول الاستجابة لكل مجال.

اضبط مفتاح API الخاص بك

1. أنشئ مفتاحًا مجانيًا أنشئ مفتاحك المجاني من تسجيل Narwhal. يستخدم Narwhal حسابًا واحدًا ومفتاح API واحدًا للإجازات الرسمية والتقويم الاقتصادي والبيانات الاقتصادية وأسعار السلع الفورية وأسعار الصرف واحتمالات أسواق التنبؤ.
2. احفظ المفتاح في بيئة التشغيل احتفظ بالمفتاح في متغير بيئة اسمه NARWHAL_API_KEY في الطرفية التي تشغّل أوامر الجلب. تقرأ الدالة المساعدة هذا المتغير عند إرسال كل طلب، لذا ينطبق المفتاح نفسه على جميع عمليات تصدير CSV.
3. استخدم الدالة المساعدة المشتركة للطلبات ترسل الأوامر المفتاح في الرأس Authorization: Bearer YOUR_KEY إلى https://api.narwhalapi.com. يشترك REST وMCP في المفتاح نفسه. في إجراء Postgres هذا، استخدم طلبات REST في الدالة المساعدة بالطرفية قبل تحميل الملفات الناتجة عبر psql.

اسحب البيانات بالكود

1. اجلب كل مجال إلى ملف CSV شغّل أوامر الطرفية لطلب كل مجال، واختر حقول الاستجابة باستخدام jq. تستخدم الدالة المساعدة curl -f ليفشل الأمر عند حالة خطأ HTTP. يكتب كل خط معالجة ملف CSV يتبع ترتيب أعمدته ترتيب الحقول في تعبير jq. تصبح الإجازات الرسمية عمودي التاريخ والاسم، ويصبح CPI عمودي الفترة والقيمة. حافظ على هذا الترتيب عند تعريف الجدول المرحلي للملف.
   الخطوة 1، اجلب كل مجال إلى CSV باستخدام curl وjq

   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 وعمود name من النوع text. وللجدول المرحلي ترتيب الأعمدة نفسه في CSV.
   الخطوة 2، حمّل الإجازات الرسمية بجدول مرحلي وupsert

   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 يوميًا لتشغيل السكربت. ضع خطوة الجلب قبل التحميل إلى قاعدة البيانات ليكون ملف CSV متاحًا عندما يقرأه \copy، وأتح NARWHAL_API_KEY للسكربت. ولأن التحميل يستخدم upsert، فإعادة التشغيل آمنة: يُحدَّث اسم تاريخ الإجازة الموجود. وللملفات الأخرى، استخدم مفاتيحها الأساسية الخاصة بدل نسخ مفتاح الإجازات الرسمية كما هو. يستخدم CPI الحقل period؛ وتستخدم أسعار الصرف currency وtimestamp معًا. عند توسيع التحميل المجدول، اجعل ترتيب حقول CSV متوافقًا مع كل جدول مرحلي.

الإجازات الرسمية في Postgres

اطلب الإجازات الرسمية للولايات المتحدة لعام 2026 واقرأ المصفوفة 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 واقرأ releases. هذه هي تواريخ الإصدار. أبقِ at وperiod وtopic وstatus في ملف CSV لتحتوي قاعدة البيانات على وقت الإصدار مع موضوعه وفترته. يتضمن الطلب تاريخي البداية والنهاية في عنوانه، ويذهب الناتج إلى 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

اطلب ملاحظات CPI للولايات المتحدة بدءًا من سبتمبر 2025 واقرأ observations. يكتب المثال كل period وvalue في cpi.csv. استخدم period مفتاحًا أساسيًا للوجهة في هذه السلسلة. تصل القيم سلاسل عشرية، لذا استخدم عمودًا من النوع numeric عند تحميلها إلى Postgres. يحدد عمود period الملاحظة التي يحدّثها upsert.

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

اطلب سعر BRENT الفوري بالدولار الأمريكي (USD) واقرأ 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

اطلب أسعار EUR وIDR مع USD عملةً أساسية واقرأ 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 عند تكرار المفتاح. يستقبل الجدول المرحلي المؤقت الصفوف قبل أن يعالج الإدراج التكرارات. في مثال الإجازات الرسمية، يحدد ترتيب التاريخ والاسم أي اسم يبقى عندما يحتوي ملف واحد على تاريخ مكرر. ثم يتولى upsert التواريخ الموجودة مسبقًا في الوجهة.

كيف أخزّن الأسعار؟

تصل القيم العشرية سلاسل نصية. حوّلها إلى numeric عند تحميل الأسعار إلى Postgres. ملف CSV هو صيغة النقل فقط؛ أما عمود الوجهة فيحدد كيف يُخزَّن السعر في قاعدة البيانات. طبّق خيار العمود العشري نفسه على قيم CPI وأسعار الصرف في عمليات التصدير هذه.