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

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

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

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

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

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

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

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

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

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

  3. מאחסנים את המפתח במיקום קבוע במערכת הקבצים. הוא נמצא במיקום הזה למשך כל חיי השרת של AlloyDB Omni.

    חשוב לשים לב למיקום שלו במערכת הקבצים, כי תצטרכו אותו בשלבים הבאים.

  4. יוצרים סוד של Kubernetes באמצעות המפתח של חשבון השירות.

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

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

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

יצירת אשכול של מסדי נתונים באמצעות AlloyDB AI

כדי ליצור אשכול של מסדי נתונים באמצעות AlloyDB AI, קראו את המאמר התקנת AlloyDB AI ב-AlloyDB Omni. כדי לגשת לנתונים ולשלוח שאילתות באמצעות Elasticsearch, לא צריך לציין את ההגדרות של vertexAI*.

הפעלה והגדרה של התוסף 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 .

    • ‫(Optional) 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 היא שפת השאילתות המלאה של 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. אפשר להשתמש בשאילתה בכל סוגי השאילתות שמוזכרים בקטע סוגי נתונים נתמכים.

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

דוגמאות להעברת תנאים למטה

כדי לייעל את השאילתות, 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. למידע נוסף, ראו סוגי נתונים נתמכים.

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