לפני שמתחילים
לפני שמתחילים, צריך לבצע את הפעולות הבאות:
- התקנת AlloyDB Omni באמצעות כלי התזמור של הקונטיינרים.
- פריסה והפעלה של Elasticsearch בסביבת ייצור.
- יוצרים מפתח API אישי או של משתמש לקריאה בלבד, ש-AlloyDB Omni יוכל להשתמש בו כדי לגשת לאשכול Elasticsearch.
יצירה של חשבון שירות
כדי לאמת את Secret Manager ולהשתמש בו, ב-AlloyDB Omni נדרש חשבון שירות עם Google Cloud . AlloyDB Omni משתמש ב-Secret Manager כדי לאחסן את מפתח ה-API של Elasticsearch.
אם עדיין לא יצרתם חשבון שירות ל-AlloyDB Omni, אתם יכולים ליצור אחד לפי השלבים הבאים:
יוצרים חשבון שירות באמצעותGoogle Cloud. במאמר יצירת אשכול מסדי נתונים באמצעות AlloyDB AI מוסבר איך נותנים לחשבון השירות הזה הרשאות גישה ל-Secret Manager.
יוצרים מפתח לחשבון השירות, שומרים אותו בפורמט JSON בקובץ
private-key.jsonומורידים אותו.מאחסנים את המפתח במיקום קבוע במערכת הקבצים. הוא נמצא במיקום הזה למשך כל חיי השרת של AlloyDB Omni.
שימו לב למיקום שלו במערכת הקבצים, כי תצטרכו אותו בשלבים הבאים.
אחסון מפתח ה-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:
מפעילים את התוסף
external_search_fdw.CREATE EXTENSION external_search_fdw;הגדרת גישה לאשכול 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: סוג האימות שבו משתמשים. אפשר לבחור מבין האפשרויות הבאות:
ApiKey: מפתח API אישי/של משתמש ב-Elasticsearch.
Basic: שם המשתמש והסיסמה ב-Elasticsearch.
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.
מגדירים את מיפוי המשתמשים של PostgreSQL לשרת Elasticsearch. שימו לב ש-FDW של PostgreSQL דורשים את מיפוי המשתמשים הזה כדי לפעול. AlloyDB Omni מבצע אימות באמצעות כותרת ההרשאה של REST.
CREATE USER MAPPING FOR CURRENT_USER SERVER ELASTICSEARCH_SERVER_NAME;מגדירים את הסכימה של נתוני 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
|
|
|
SMALLINT
|
date
|
TIMESTAMPTZ
|
DOUBLE PRECISION
|
|
REAL
|
|
integer
|
INTEGER
|
long
|
BIGINT
|
jsonb
|
|
|
|
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 סטנדרטיות
- שאילתת 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:computingbody:(quantum computing)body:(quantum AND computing)body:"quantum computing"body:"quantum computing" AND qubits:[* TO 105}
שאילתת 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 id, body FROM elasticsearch_table WHERE body = 'foo' LIMIT 10; |
|
| ביטויים של שדה יחיד |
SELECT id, body FROM elasticsearch_table WHERE id > 10 ORDER BY metadata <@> 'body:foo' LIMIT 10; |
|
| ביטויים קבועים |
SELECT id, body FROM elasticsearch_table WHERE id > (1+1) LIMIT 10; |
|
| ביטויים עם פונקציות |
SELECT id, body FROM elasticsearch_table WHERE id > CEIL(3.14) LIMIT 10; |
|
| ביטויים עם כמה שדות |
SELECT id, body FROM elasticsearch_table WHERE dbl_field < flt_field LIMIT 10; |
|
| סינון לפי ציון |
SELECT id, body, (metadata <@> 'body:bar') AS score FROM elasticsearch_table WHERE score > 0.5 ORDER by score desc LIMIT 10; |
|
LIKE ואופרטורים דומים |
SELECT id, body FROM elasticsearch_table WHERE id > 10 AND body LIKE '%foo%' LIMIT 10; |
|
| שאילתות גולמיות |
SELECT id, body FROM elasticsearch_table WHERE id < 10 ORDER BY metadata <@> $${"query": { "match_all": {}}}$$ DESC LIMIT 10; |
|
פתרון בעיות
אם נתקלתם בבעיות באימות או בקישוריות כששלחתם שאילתה לאשכול 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. למידע נוסף, ראו סוגי נתונים נתמכים.