גישה לנתוני Elasticsearch מ-AlloyDB ל-PostgreSQL

כדי לגשת לנתונים שמאוחסנים ב-Elasticsearch ולחפש בהם, אתם יכולים ליצור מעטפת נתונים חיצונית (FDW) וטבלה חיצונית ב-AlloyDB ל-PostgreSQL.

לפני שמתחילים

לפני שמתחילים, צריך לבצע את הפעולות הבאות:

אחסון מפתח ה-API של Elasticsearch ב-Secret Manager

‫AlloyDB שומר וקורא את מפתח ה-API של Elasticsearch מ-Secret Manager. למידע נוסף על השימוש ב-Secret Manager, קראו את המאמר יצירה וגישה לסוד באמצעות Secret Manager.

חשוב לוודא שנתתם לחשבון השירות של AlloyDB הרשאה לקרוא את הסוד. מידע נוסף זמין במאמר יצירה וגישה לסוד באמצעות Secret Manager.

הפעלה והגדרה של התוסף external_search_fdw

כדי להתחיל את השילוב עם Elasticsearch, צריך להפעיל ולהגדיר את התוסף external_search_fdw של AlloyDB:

  1. מפעילים את התוסף external_search_fdw.

    CREATE EXTENSION external_search_fdw;

  2. מגדירים גישה לאשכול Elasticsearch דרך שרת נתונים חיצוני.

    CREATE SERVER ELASTICSEARCH_SERVER_NAME
FOREIGN DATA WRAPPER external_search_fdw
OPTIONS (server 'ELASTICSEARCH_SERVER_HOST_PORT',
         search_provider 'elastic',
         auth_mode 'secret_manager',
         auth_method 'AUTH_METHOD',
         secret_path 'SECRET_PATH',
         max_deadline_ms 'MAX_DEADLINE',
         pagination_num_results 'PAGINATION_NUM_RESULTS',
         pagination_context_timeout_ms 'PAGINATION_CONTEXT_TIMEOUT');

    מחליפים את המשתנים הבאים:

    • ‫ELASTICSEARCH_SERVER_NAME: שם לשרת הנתונים החיצוני. לדוגמה, my-elasticsearch-server.

    • ‫ELASTICSEARCH_SERVER_HOST_PORT: כתובת ה-URL שגלויה לכולם של אשכול Elasticsearch. לדוגמה, https://node1.elastic.test.com:9200.

    • ‫AUTH_METHOD: סוג האימות שבו משתמשים. אפשר לבחור מבין האפשרויות הבאות:

    • ‫SECRET_PATH: הנתיב ב-Secret Manager לפרטי הכניסה לאימות ב-Elasticsearch. לדוגמה, projects/123456789012/secrets/apikey/versions/1. ‫123456789012 מייצג את מזהה הפרויקט ב- Google Cloud .

    • ‫MAX_DEADLINE (אופציונלי): משך הזמן המקסימלי, באלפיות השנייה, ש-AlloyDB ממתין לתגובה מ-Elasticsearch. צריך להגדיר את הערך הזה על סמך המיקומים של המכונות של AlloyDB ו-Elasticsearch. ערך ברירת המחדל הוא 10000.

    • ‫PAGINATION_NUM_RESULTS (אופציונלי): המספר המקסימלי של תוצאות שנשלפות בכל אצווה מ-Elasticsearch. אם מבקשים יותר תוצאות, AlloyDB מאחזר את התוצאות בכמה אצוות בגודל הזה. ערך ברירת המחדל הוא 32.

    • ‫PAGINATION_CONTEXT_TIMEOUT (אופציונלי): משך הזמן, באלפיות השנייה, שבו Elasticsearch שומר על ההקשר של בקשת חלוקת הדפים פעיל. ערך ברירת המחדל הוא 30000.

  3. מגדירים את מיפוי המשתמשים של PostgreSQL לשרת Elasticsearch. שימו לב ש-FDW של PostgreSQL דורשים את מיפוי המשתמשים הזה כדי לפעול. ‫AlloyDB מבצע אימות באמצעות כותרת ההרשאה של REST.

    CREATE USER MAPPING FOR CURRENT_USER
       SERVER ELASTICSEARCH_SERVER_NAME;

  4. מגדירים את הסכימה של נתוני Elasticsearch באמצעות טבלת נתונים חיצונית.

    CREATE FOREIGN TABLE ELASTICSEARCH_FD_TABLE(
    metadata external_search_fdw_schema.OpaqueMetadata,
    ELASTICSEARCH_FIELDS)
       SERVER ELASTICSEARCH_SERVER_NAME
       OPTIONS(remote_table_name 'ELASTICSEARCH_INDEX_NAME');

    מחליפים את המשתנים החדשים הבאים:

    • ‫ELASTICSEARCH_FD_TABLE: שם טבלת הנתונים החיצונית שמייצגת את טבלת Elasticsearch. לדוגמה, my-fd-elasticsearch-table.

    • ‫ELASTICSEARCH_FIELDS: רשימה מופרדת בפסיקים של הגדרות סכימה של שדות Elasticsearch בפורמט הבא: elasticsearch_field_name PG_DATA_TYPE. לדוגמה: elasticsearch_boolean_field_name BOOLEAN, elasticsearch_double_field_name DOUBLE PRECISION. השדות האלה חייבים להתאים לשמות השדות ב-Elasticsearch, אלא אם מוסיפים את האפשרות remote_field_name. לדוגמה, elasticsearch_foo OPTIONS (remote_field_name 'elasticsearch_FOO').

      במאמר סוגי נתונים נתמכים מפורטים סוגי הנתונים של Elasticsearch שאפשר להגדיר ל-AlloyDB.

    • ‫ELASTICSEARCH_INDEX_NAME: השם של האינדקס ב-Elasticsearch. לדוגמה, my-elasticsearch-index.

סוגי נתונים נתמכים

‫AlloyDB תומך בסוגי הנתונים הבאים של Elasticsearch:

סוגי הנתונים סוג PostgreSQL
alias סוג PostgreSQL של השדה שאליו alias מפנה
binary bytea
boolean BOOLEAN

byte,

short

SMALLINT
date TIMESTAMPTZ

double,

scaled_float

DOUBLE PRECISION

float,

half_float

REAL
integer INTEGER
long BIGINT

object,

flattened

jsonb

text,

annotated_text,

keyword,

constant_keyword,

wildcard

TEXT
unsigned_long NUMERIC

שאילתות על נתוני Elasticsearch

‫AlloyDB מקבל שאילתות SQL וממיר אותן לשאילתות API בארכיטקטורת REST של Elasticsearch. במהלך ההמרה, AlloyDB מנסה להעביר כמה שיותר לוגיקה של שאילתות בלי לשנות את זהות השאילתה, כולל LIMIT של שאילתת ה-SQL. עם זאת, יש מקרים שבהם אתם יכולים לציין לא להעביר שדות מסוימים של Elasticsearch, או מקרים שבהם לא ניתן להעביר את הלוגיקה של השאילתה. לדוגמה, אי אפשר להעביר את LIKE ואופרטורים אחרים להתאמת טקסט. בדוגמאות לדחיפה למטה מפורט מה אפשר ומה אי אפשר לדחוף למטה.

במקרים שבהם הערך של LIMIT גבוה מהערך של pagination_num_results, או כשלא צוין ערך ל-LIMIT או שלא ניתן להעביר אותו למטה, AlloyDB משתמש ב-Scroll API, שיכול לצרוך הרבה משאבים.

ה-Scroll API יכול לצרוך הרבה משאבים, ולכן מומלץ לבדוק את השאילתות באמצעות EXPLAIN VERBOSE כדי לראות באילו ממשקי API נעשה שימוש. כדי לשפר את הביצועים, כדאי להגביל את השימוש ב-Scroll API ולהשתמש ב-LIMIT.

כדי לשלוח שאילתות לנתוני Elasticsearch, אתם יכולים להשתמש באפשרויות הבאות:

  • שאילתות SQL סטנדרטיות
  • Query DSL
  • חיפושים משולבים

שאילתות SQL סטנדרטיות

אפשר לכתוב שאילתות SQL סטנדרטיות באמצעות התחביר Lucene של Elasticsearch.

כדי לבצע שאילתת SQL סטנדרטי, אפשר להשתמש בשאילתה לדוגמה הבאה:

SELECT id, body
FROM ELASTICSEARCH_FD_TABLE
WHERE FILTER
ORDER BY metadata <@> 'QUERY';

מחליפים את המשתנים הבאים:

  • ‫ELASTICSEARCH_FD_TABLE: שם טבלת הנתונים החיצונית שמייצגת את טבלת Elasticsearch. לדוגמה, my-fd-elasticsearch-table.

  • ‫FILTER (אופציונלי): מסנן להחלה על שאילתת Elasticsearch. לדוגמה, AND qubits < 105.

  • ‫QUERY: השאילתה שתישלח אל Elasticsearch. ברשימה הבאה מופיעות כמה שאילתות לדוגמה:

    • body:quantum body:computing
    • body:(quantum computing)
    • body:(quantum AND computing)
    • body:"quantum computing"
    • body:"quantum computing" AND qubits:[* TO 105}

Query DSL

‫Query DSL היא שפת השאילתות של Elasticsearch, שכוללת את כל התכונות, בסגנון JSON, ומומלצת לתרחישי שימוש מתקדמים. באמצעות Query DSL אפשר לבצע חיפושים, סינונים וצבירות מורכבים שאי אפשר לבטא בתחביר של שאילתות SQL.

כדי לבצע שאילתות באמצעות Query DSL, אפשר להיעזר בשאילתה לדוגמה הבאה:

SELECT id, body
FROM ELASTICSEARCH_FD_TABLE
ORDER BY
  metadata <@> $${
    "query": {
      "bool": {
        "must": [
          {
            "query_string": {
              "query" : "QUERY"
            }
          }
        ],
        "filter": [
          {
            "range": { 
              "id": { 
                "lt": "10"
              }
            }
          }
        ]
      }
    },
    "sort": [
      {
        "id": {
          "order": "desc"
        }
      }
    ]
  }$$
LIMIT 1;

מחליפים את המשתנים הבאים:

  • ‫ELASTICSEARCH_FD_TABLE: שם טבלת הנתונים החיצונית שמייצגת את טבלת Elasticsearch. לדוגמה, my-fd-elasticsearch-table.

  • ‫QUERY: השאילתה שתישלח אל Elasticsearch. לדוגמה, "elasticsearch_field_name:\"quantum computing\" OR int_field:[* TO 3]".

שימו לב שב-Query DSL, אתם צריכים להפיץ רק את הביטויים query, filter ו-sort.

כדי לבצע חיפוש היברידי בנתונים של Elasticsearch, אפשר להשתמש בחיפוש לדוגמה הבא:

SELECT *
FROM
  ai.hybrid_search(
    ARRAY[
      '{"limit": LIMIT,
        "data_type": "external_search_fdw",
        "weight": WEIGHT,
        "table_name": "ELASTICSEARCH_FD_TABLE",
        "key_column": "DOCUMENT_ID_COLUMN_NAME",
        "query_text_input": QUERY}'::jsonb],
    NULL::TEXT,
    'RRF',
    FALSE)
ORDER BY score DESC;

מחליפים את המשתנים הבאים:

  • ‫LIMIT: מספר התוצאות שיוחזרו. לדוגמה, 3.

  • ‫WEIGHT: התרומה של רשומת החיפוש הזו ל-Reciprocal Rank Fusion‏ (RRF) הכולל.

  • ‫ELASTICSEARCH_FD_TABLE: שם טבלת הנתונים החיצונית שמייצגת את טבלת Elasticsearch. לדוגמה, my-fd-elasticsearch-table.

  • ‫DOCUMENT_ID_COLUMN_NAME: שם העמודה של מזהה המסמך.

  • ‫QUERY: השאילתה שתישלח אל Elasticsearch. לדוגמה, "elasticsearch_field_name:\"quantum computing\"" מחפש את הביטוי "quantum computing" בשדה elasticsearch_field_name. אפשר להשתמש בשאילתה בכל סוגי השאילתות שמוזכרים בקטע סוגי נתונים נתמכים.

מידע נוסף על הפרמטרים שזמינים לחיפושים היברידיים זמין במאמר פרמטרים של פונקציות חיפוש היברידי.

דוגמאות למודעות Pushdown

כדי שהשאילתות יהיו יעילות יותר, AlloyDB מנסה להעביר את ההיבטים הבאים של השאילתה ישירות לקריאה ל-API שבוצעה ל-Elasticsearch:

  • SELECT שדות
  • ‫WHERE מסננים
  • ‫ORDER BY מיונים
  • LIMIT

בטבלה הבאה מופיעות שאילתות לדוגמה שממחישות אילו היבטים AlloyDB יכול או לא יכול להעביר.

סוג השאילתה שאילתה לדוגמה רכיבי השאילתה נדחקו למטה
שאילתות ללא סינון 
SELECT id, body
FROM elasticsearch_table
ORDER BY metadata <@> 'body:foo' DESC
LIMIT 10;
  • SELECT שדות
  • מיון לפי ORDER BY ... DESC
  • LIMIT
התאמה מדויקת לטקסט 
SELECT id, body
FROM elasticsearch_table
WHERE body = 'foo'
LIMIT 10;
  • SELECT שדות
  • מסנן WHERE
  • LIMIT
ביטויים של שדה יחיד 
SELECT id, body
FROM elasticsearch_table
WHERE id > 10
ORDER BY metadata <@> 'body:foo'
LIMIT 10;
  • SELECT שדות
  • מסנן WHERE
ביטויים קבועים 
SELECT id, body
FROM elasticsearch_table
WHERE id > (1+1)
LIMIT 10;
  • SELECT שדות
  • מסנן WHERE
  • LIMIT
ביטויים עם פונקציות 
SELECT id, body
FROM elasticsearch_table
WHERE id > CEIL(3.14)
LIMIT 10;
  • SELECT שדות
ביטויים עם כמה שדות 
SELECT id, body
FROM elasticsearch_table
WHERE dbl_field < flt_field
LIMIT 10;
  • SELECT שדות
סינון לפי ציון 
SELECT id, body, (metadata <@> 'body:bar') AS score
FROM elasticsearch_table
WHERE score > 0.5
ORDER by score desc
LIMIT 10;
  • SELECT שדות
  • מיון לפי ORDER BY ... DESC
‫LIKE ואופרטורים דומים 
SELECT id, body
FROM elasticsearch_table
WHERE id > 10 AND body LIKE '%foo%'
LIMIT 10;
  • SELECT שדות
  • מסנן WHERE id > 10
שאילתות גולמיות 
SELECT id, body
FROM elasticsearch_table
WHERE id < 10
ORDER BY metadata <@> $${"query": { "match_all": {}}}$$ DESC
LIMIT 10;
  • SELECT שדות
  • מיון לפי ORDER BY ... DESC

פתרון בעיות

אם נתקלתם בבעיות באימות או בקישוריות כששלחתם שאילתה לאשכול Elasticsearch, כדאי לבדוק את הסיבות הנפוצות הבאות:

  • שגיאות אימות מסוג HTTP 401 או 403: ודאו שהסוד של Elasticsearch ב-Secret Manager מכיל פרטי כניסה תקינים לאימות של auth_method (ApiKey או Basic), וודאו שלחשבון השירות שמשמש את AlloyDB יש את ההרשאה secretmanager.secretAccessor.
  • זמן קצוב לתפוגה של החיבור: מוודאים שהקישוריות לכתובת IP ציבורית יוצאת מופעלת במכונה הראשית של AlloyDB, ושחומת האש של Elasticsearch מאפשרת חיבורים נכנסים ביציאה שצוינה.

מגבלות

לפני שמחברים את AlloyDB ל-Elasticsearch, חשוב להביא בחשבון את המגבלות הבאות:

  • השילוב של Elasticsearch זמין רק בגרסה הראשית 17 ומעלה של PostgreSQL.

  • ‫AlloyDB קורא נתונים מ-Elasticsearch, אבל לא כותב אליו.

  • אתם אחראים לסנכרן את הנתונים בין AlloyDB ל-Elasticsearch.

  • אין תמיכה בסוגים מיוחדים של Elasticsearch, כמו geo_point. לרשימה המלאה של סוגי הנתונים הנתמכים

המאמרים הבאים