Mengakses data Elasticsearch dari AlloyDB Omni

Pilih versi dokumentasi:

Anda dapat mengakses dan menelusuri data yang disimpan di Elasticsearch dengan membuat wrapper data asing (FDW) dan tabel asing di AlloyDB Omni.

Sebelum memulai

Sebelum Anda memulai, selesaikan hal-hal berikut:

Membuat akun layanan

AlloyDB Omni memerlukan akun layanan dengan Google Cloud untuk mengautentikasi dan menggunakan Secret Manager. AlloyDB Omni menggunakan Secret Manager untuk menyimpan kunci API Elasticsearch Anda.

Jika Anda belum membuat akun layanan untuk AlloyDB Omni, buat akun layanan dengan mengikuti langkah-langkah berikut:

  1. Buat akun layanan dengan Google Cloud. Anda memberikan izin akun layanan ini untuk mengakses Secret Manager di Mengonfigurasi AlloyDB AI.

  2. Buat kunci akun layanan dan simpan dalam format JSON ke file private-key.json, lalu download.

  3. Salin kunci akun layanan yang Anda buat ke KEY_PATH. Jalur kunci harus berupa jalur di host Anda yang dapat diakses dan dimiliki oleh pengguna yang menjalankan penampung AlloyDB Omni Anda.

Menyimpan kunci API Elasticsearch di Secret Manager

AlloyDB Omni menyimpan dan membaca kunci API Elasticsearch Anda dari Secret Manager. Untuk mengetahui informasi selengkapnya tentang cara menggunakan Secret Manager, lihat Membuat dan mengakses secret menggunakan Secret Manager.

Pastikan Anda memberi akun layanan AlloyDB Omni Anda izin untuk membaca secret. Untuk mengetahui informasi selengkapnya, lihat Mengelola akses ke secret.

Mengonfigurasi AlloyDB AI untuk AlloyDB Omni

Untuk mengonfigurasi AI AlloyDB untuk AlloyDB Omni, lihat Mengonfigurasi AI AlloyDB untuk AlloyDB Omni dan lewati langkah pertama.

Mengaktifkan dan mengonfigurasi ekstensi external_search_fdw

Untuk memulai integrasi dengan Elasticsearch, selesaikan petunjuk berikut untuk mengaktifkan dan mengonfigurasi ekstensi AlloyDB Omni external_search_fdw:

  1. Aktifkan ekstensi external_search_fdw.

    CREATE EXTENSION external_search_fdw;

  2. Konfigurasi akses ke cluster Elasticsearch Anda melalui server data asing.

    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');

    Ganti variabel berikut:

    • ELASTICSEARCH_SERVER_NAME: nama untuk server data asing Anda. Contoh, my-elasticsearch-server.

    • ELASTICSEARCH_SERVER_HOST_PORT: URL yang menghadap publik untuk cluster Elasticsearch Anda. Contoh, https://node1.elastic.test.com:9200.

    • AUTH_METHOD: jenis autentikasi yang akan digunakan. Anda dapat memilih salah satu opsi berikut:

    • SECRET_PATH: Jalur Secret Manager ke kredensial autentikasi Elasticsearch Anda. Contoh, projects/123456789012/secrets/apikey/versions/1. 123456789012 mewakili ID project Google Cloud Anda.

    • (Opsional) MAX_DEADLINE: jumlah waktu maksimum, dalam milidetik, yang digunakan AlloyDB Omni untuk menunggu respons dari Elasticsearch. Tetapkan nilai ini berdasarkan lokasi instance AlloyDB Omni dan Elasticsearch Anda. Nilai defaultnya adalah 10000.

    • (Opsional) PAGINATION_NUM_RESULTS: jumlah maksimum hasil yang diambil per batch dari Elasticsearch. Jika lebih banyak hasil diminta, AlloyDB Omni akan mengambil hasil dalam beberapa batch berukuran ini. Nilai defaultnya adalah 32.

    • (Opsional) PAGINATION_CONTEXT_TIMEOUT: jumlah waktu, dalam milidetik, saat Elasticsearch menjaga konteks permintaan penomoran halaman tetap aktif. Nilai defaultnya adalah 30000.

  3. Tentukan pemetaan pengguna PostgreSQL untuk server Elasticsearch. Perhatikan bahwa FDW PostgreSQL memerlukan pemetaan pengguna ini agar dapat berfungsi. AlloyDB Omni melakukan autentikasi menggunakan header otorisasi REST.

    CREATE USER MAPPING FOR CURRENT_USER
       SERVER ELASTICSEARCH_SERVER_NAME;

  4. Konfigurasi skema untuk data Elasticsearch Anda melalui tabel data eksternal.

    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');

    Ganti variabel baru berikut:

    • ELASTICSEARCH_FD_TABLE: nama tabel data asing yang merepresentasikan tabel Elasticsearch Anda. Contoh, my-fd-elasticsearch-table.

    • ELASTICSEARCH_FIELDS: daftar definisi skema kolom Elasticsearch yang dipisahkan koma dalam format berikut: elasticsearch_field_name PG_DATA_TYPE. Contohnya, elasticsearch_boolean_field_name BOOLEAN, elasticsearch_double_field_name DOUBLE PRECISION. Kolom ini harus cocok dengan nama kolom di Elasticsearch, kecuali jika opsi remote_field_name ditambahkan. Contoh, elasticsearch_foo OPTIONS (remote_field_name 'elasticsearch_FOO').

      Untuk mengetahui daftar jenis data Elasticsearch yang dapat ditentukan untuk AlloyDB Omni, lihat Jenis data yang didukung.

    • ELASTICSEARCH_INDEX_NAME: nama indeks Elasticsearch Anda. Contoh, my-elasticsearch-index.

Jenis data yang didukung

AlloyDB Omni mendukung jenis data Elasticsearch berikut:

Jenis data Jenis PostgreSQL
alias Jenis PostgreSQL untuk kolom yang dirujuk oleh 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

Membuat kueri data Elasticsearch

AlloyDB Omni mengambil kueri SQL dan mengonversinya menjadi kueri Elasticsearch REST API. Selama konversi ini, AlloyDB Omni mencoba mendorong logika kueri sebanyak mungkin tanpa mengubah identitas kueri, termasuk LIMIT kueri SQL. Namun, ada kasus saat Anda mungkin menentukan untuk tidak mendorong ke bawah kolom Elasticsearch tertentu atau saat logika kueri tidak dapat didorong ke bawah. Misalnya, LIKE dan operator pencocokan teks lainnya tidak dapat diturunkan. Untuk contoh selengkapnya tentang apa yang dapat dan tidak dapat didorong ke bawah, lihat Contoh pushdown.

Dalam skenario saat LIMIT ditetapkan lebih tinggi daripada pagination_num_results atau saat LIMIT tidak ditentukan atau tidak dapat diturunkan, AlloyDB Omni menggunakan Scroll API, yang dapat menggunakan banyak resource.

Karena Scroll API dapat menggunakan banyak resource, sebaiknya periksa kueri Anda menggunakan EXPLAIN VERBOSE untuk melihat API mana yang digunakan. Membatasi penggunaan Scroll API dan menggunakan LIMIT akan meningkatkan performa.

Untuk membuat kueri data Elasticsearch, Anda memiliki opsi berikut:

  • Kueri SQL standar
  • DSL Kueri
  • Penelusuran hybrid

Kueri SQL standar

Kueri SQL standar dapat ditulis menggunakan sintaksis Lucene Elasticsearch.

Untuk menjalankan kueri SQL standar, lihat contoh kueri berikut:

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

Ganti variabel berikut:

  • ELASTICSEARCH_FD_TABLE: nama tabel data asing yang merepresentasikan tabel Elasticsearch Anda. Contoh, my-fd-elasticsearch-table.

  • (Opsional) FILTER: filter yang akan diterapkan ke kueri Elasticsearch Anda. Contoh, AND qubits < 105.

  • QUERY: kueri yang akan dikirim ke Elasticsearch. Untuk beberapa contoh kueri, lihat daftar berikut:

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

DSL Kueri

Query DSL adalah bahasa kueri gaya JSON yang kaya fitur dari Elasticsearch yang direkomendasikan untuk kasus penggunaan lanjutan. DSL kueri memungkinkan Anda melakukan penelusuran, pemfilteran, dan agregasi kompleks yang tidak dapat dinyatakan dalam sintaksis kueri SQL.

Untuk menjalankan kueri menggunakan Query DSL, lihat contoh kueri berikut:

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;

Ganti variabel berikut:

  • ELASTICSEARCH_FD_TABLE: nama tabel data asing yang merepresentasikan tabel Elasticsearch Anda. Contoh, my-fd-elasticsearch-table.

  • QUERY: kueri yang akan dikirim ke Elasticsearch. Contoh, "elasticsearch_field_name:\"quantum computing\" OR int_field:[* TO 3]".

Perhatikan bahwa untuk Query DSL, Anda hanya diharapkan untuk menyebarkan ekspresi query, filter, dan sort.

Untuk melakukan penelusuran hybrid pada data Elasticsearch Anda, lihat contoh penelusuran berikut:

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;

Ganti variabel berikut:

  • LIMIT: jumlah hasil yang akan ditampilkan. Contoh, 3.

  • WEIGHT: kontribusi entri penelusuran ini terhadap keseluruhan Reciprocal Rank Fusion (RRF). Contoh, 0.5. Jika Anda tidak memberikan bobot, bobot akan didistribusikan secara merata. Untuk mengetahui informasi selengkapnya, lihat Parameter fungsi penelusuran hibrida.

  • ELASTICSEARCH_FD_TABLE: nama tabel data asing yang merepresentasikan tabel Elasticsearch Anda. Contoh, my-fd-elasticsearch-table.

  • DOCUMENT_ID_COLUMN_NAME: nama kolom ID dokumen.

  • QUERY: kueri yang akan dikirim ke Elasticsearch. Misalnya, "elasticsearch_field_name:\"quantum computing\"" menelusuri frasa "quantum computing" di kolom elasticsearch_field_name. Semua jenis kueri yang disebutkan dalam Jenis data yang didukung dapat digunakan dalam kueri Anda.

Untuk mengetahui informasi selengkapnya tentang parameter yang tersedia untuk penelusuran hybrid, lihat Parameter fungsi penelusuran hybrid.

Contoh pushdown

Untuk membuat kueri lebih efisien, AlloyDB Omni mencoba mendorong aspek kueri berikut langsung ke panggilan API yang dilakukan ke Elasticsearch:

  • SELECT kolom
  • Filter WHERE
  • ORDER BY jenis
  • LIMIT

Untuk contoh kueri yang menunjukkan aspek yang dapat dan tidak dapat didorong ke bawah oleh AlloyDB Omni, lihat tabel berikut.

Jenis kueri Contoh kueri Elemen kueri didorong ke bawah
Kueri yang tidak difilter 
SELECT id, body
FROM elasticsearch_table
ORDER BY metadata <@> 'body:foo' DESC
LIMIT 10;
  • SELECT kolom
  • ORDER BY ... DESC pengurutan
  • LIMIT
Pencocokan teks persis 
SELECT id, body
FROM elasticsearch_table
WHERE body = 'foo'
LIMIT 10;
  • SELECT kolom
  • Filter WHERE
  • LIMIT
Ekspresi kolom tunggal 
SELECT id, body
FROM elasticsearch_table
WHERE id > 10
ORDER BY metadata <@> 'body:foo'
LIMIT 10;
  • SELECT kolom
  • Filter WHERE
Ekspresi konstanta 
SELECT id, body
FROM elasticsearch_table
WHERE id > (1+1)
LIMIT 10;
  • SELECT kolom
  • Filter WHERE
  • LIMIT
Ekspresi dengan fungsi 
SELECT id, body
FROM elasticsearch_table
WHERE id > CEIL(3.14)
LIMIT 10;
  • SELECT kolom
Ekspresi multi-kolom 
SELECT id, body
FROM elasticsearch_table
WHERE dbl_field < flt_field
LIMIT 10;
  • SELECT kolom
Pemfilteran skor 
SELECT id, body, (metadata <@> 'body:bar') AS score
FROM elasticsearch_table
WHERE score > 0.5
ORDER by score desc
LIMIT 10;
  • SELECT kolom
  • ORDER BY ... DESC pengurutan
LIKE dan operator serupa 
SELECT id, body
FROM elasticsearch_table
WHERE id > 10 AND body LIKE '%foo%'
LIMIT 10;
  • SELECT kolom
  • Filter WHERE id > 10
Kueri mentah 
SELECT id, body
FROM elasticsearch_table
WHERE id < 10
ORDER BY metadata <@> $${"query": { "match_all": {}}}$$ DESC
LIMIT 10;
  • SELECT kolom
  • ORDER BY ... DESC pengurutan

Pemecahan masalah

Jika Anda mengalami masalah autentikasi atau konektivitas saat membuat kueri cluster Elasticsearch, periksa hal berikut:

  • Error autentikasi HTTP 401 atau 403: verifikasi bahwa secret Elasticsearch Anda di Secret Manager berisi kredensial autentikasi yang valid untuk auth_method (ApiKey atau Basic) Anda, dan verifikasi bahwa akun layanan Anda memiliki izin secretmanager.secretAccessor.
  • Waktu tunggu koneksi habis: verifikasi aturan jaringan dan konfigurasi firewall antara AlloyDB Omni dan endpoint Elasticsearch Anda.

Batasan

  • AlloyDB Omni membaca, tetapi tidak menulis ke, data Elasticsearch.

  • Anda bertanggung jawab untuk menyinkronkan data antara AlloyDB Omni dan Elasticsearch.

  • Jenis Elasticsearch khusus, seperti geo_point tidak didukung. Untuk mengetahui informasi selengkapnya, lihat Jenis data yang didukung.

Langkah berikutnya