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

בוחרים גרסה של מאמר העזרה:

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

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

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

יצירה של חשבון שירות

כדי לבצע אימות ולהשתמש ב-Secret Manager, צריך חשבון שירות עם Google Cloud ב-AlloyDB Omni. ‫AlloyDB Omni משתמש ב-Secret Manager כדי לאחסן את מפתח ה-API של Elasticsearch.

אם עוד לא יצרתם חשבון שירות ל-AlloyDB Omni, אתם יכולים ליצור אחד לפי השלבים הבאים:

  1. יצירה של חשבון שירות עם Google Cloud. אתם מעניקים לחשבון השירות הזה הרשאות גישה ל-Secret Manager בהגדרת AlloyDB AI.

  2. יוצרים מפתח לחשבון השירות, שומרים אותו בפורמט JSON בקובץ private-key.json ומורידים אותו.

  3. מעתיקים את מפתח חשבון השירות שיצרתם אל KEY_PATH. נתיב המפתח צריך להיות נתיב במארח שלכם שיש לו גישה והוא בבעלות המשתמש שמפעיל את קונטיינר AlloyDB Omni.

איך מאחסנים מפתח API של Elasticsearch ב-Secret Manager

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

צריך לוודא שנתתם לחשבון השירות של AlloyDB Omni הרשאה לקרוא את הסוד. מידע נוסף מופיע במאמר בנושא ניהול הגישה לסודות.

הגדרת AlloyDB AI ל-AlloyDB Omni

כדי להגדיר את AlloyDB AI ל-AlloyDB Omni, אפשר לעיין במאמר בנושא הגדרת AlloyDB AI ל-AlloyDB Omni ולדלג על השלב הראשון.

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

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

  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 Omni ממתין לתגובה מ-Elasticsearch. מגדירים את הערך הזה על סמך המיקומים של מופעי AlloyDB Omni ו-Elasticsearch. ערך ברירת המחדל הוא 10000.

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

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

  3. מגדירים את מיפוי המשתמש של PostgreSQL לשרת Elasticsearch. שימו לב: כדי להשתמש ב-FDW של PostgreSQL, צריך למפות את המשתמשים. ב-AlloyDB Omni, האימות מתבצע באמצעות כותרת ההרשאה של 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 Omni זמינה במאמר בנושא סוגי נתונים נתמכים.

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

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

‫AlloyDB Omni תומך בסוגי הנתונים הבאים של 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 Omni מקבל שאילתות SQL וממיר אותן לשאילתות Elasticsearch API בארכיטקטורת REST. במהלך ההמרה הזו,‏ AlloyDB Omni מנסה להעביר כמה שיותר לוגיקה של שאילתות בלי לשנות את הזהות של השאילתה, כולל LIMIT של שאילתת ה-SQL. עם זאת, יש מקרים שבהם כדאי לציין שלא להעביר למטה שדות מסוימים של Elasticsearch, או מקרים שבהם אי אפשר להעביר למטה את לוגיקת השאילתה. לדוגמה, אי אפשר להעביר למטה את האופרטורים LIKE ואופרטורים אחרים להתאמת טקסט. דוגמאות נוספות למה שאפשר להעביר למטה ולמה שאסור מופיעות במאמר דוגמאות להעברה למטה.

בתרחישים שבהם הערך של LIMIT גבוה מהערך של pagination_num_results, או שבהם הערך של LIMIT לא צוין או שלא ניתן להקטין אותו, AlloyDB Omni משתמש ב-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 היא שפת שאילתות מלאה בסגנון JSON של Elasticsearch, שמומלצת לתרחישי שימוש מתקדמים. בעזרת 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: התרומה של רשומת החיפוש הזו ל-RRF הכולל. לדוגמה, 0.5. אם לא תציינו משקלים, הם יחולקו באופן שווה. מידע נוסף זמין במאמר פרמטרים של פונקציית חיפוש היברידית.

  • ‫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 Omni מנסה להעביר את ההיבטים הבאים של השאילתה ישירות לקריאה ל-API שמתבצעת ל-Elasticsearch:

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

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

סוג השאילתה דוגמה לשאילתה העברת רכיבי שאילתה למטה
שאילתות ללא סינון 
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), ולוודא שלחשבון השירות יש הרשאה secretmanager.secretAccessor.
  • פסק זמן לחיבור: צריך לוודא את כללי הרשת ואת הגדרות חומת האש בין AlloyDB Omni לבין נקודת הקצה של Elasticsearch.

מגבלות

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

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

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

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