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

בוחרים גרסת תיעוד:

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

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

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

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

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

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

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

  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 לשאילתות API בארכיטקטורת REST של Elasticsearch. במהלך ההמרה, 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 היא שפת השאילתות המלאה של 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) הכולל. לדוגמה, 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. למידע נוסף, ראו סוגי נתונים נתמכים.

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