Mengakses data Elasticsearch dari AlloyDB untuk PostgreSQL

Pratinjau — Elasticsearch FDW

Fitur ini tunduk pada "Persyaratan Penawaran Pra-GA" di bagian Persyaratan Layanan Umum dari Persyaratan Khusus Layanan. Fitur pra-GA tersedia "sebagaimana adanya" dan mungkin memiliki dukungan terbatas. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

Akses dan telusuri data yang disimpan di Elasticsearch dengan membuat wrapper data asing (FDW) dan tabel asing di AlloyDB untuk PostgreSQL.

Batasan

Sebelum menghubungkan AlloyDB ke Elasticsearch, ketahui batasan berikut:

• Integrasi Elasticsearch hanya tersedia di versi utama PostgreSQL 17 dan yang lebih baru.

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

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

• Jenis Elasticsearch khusus, seperti geo_point tidak didukung. Untuk mengetahui daftar lengkap jenis data yang didukung, lihat Jenis data yang didukung.

Sebelum memulai

Sebelum memulai, pastikan Anda telah menyelesaikan hal berikut:

• Membuat cluster.

• Aktifkan konektivitas keluar di instance AlloyDB utama Anda.

• Deploy dan jalankan Elasticsearch dalam produksi.

• Buat kunci API Pribadi/Pengguna hanya baca yang dapat digunakan AlloyDB untuk mengakses cluster Elasticsearch Anda.

Menyimpan kunci API Elasticsearch di Secret Manager

AlloyDB 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 Anda izin untuk membaca secret. Untuk mengetahui informasi selengkapnya, lihat Membuat dan mengakses secret menggunakan Secret Manager.

Mengaktifkan dan mengonfigurasi ekstensi external_search_fdw

Untuk memulai integrasi dengan Elasticsearch, selesaikan petunjuk berikut untuk mengaktifkan dan mengonfigurasi ekstensi AlloyDB 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:

     • ApiKey: Elasticsearch Personal/User API key.

     • Basic: Nama pengguna dan sandi Elasticsearch.

   • 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 untuk menunggu respons dari Elasticsearch. Anda harus menetapkan nilai ini berdasarkan lokasi instance AlloyDB 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 akan mengambil hasil dalam beberapa batch dengan ukuran 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 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 asing.

   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, lihat Jenis data yang didukung.

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

Jenis data yang didukung

AlloyDB 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 mengambil kueri SQL dan mengonversinya menjadi kueri Elasticsearch REST API. Selama konversi ini, AlloyDB mencoba menurunkan sebanyak mungkin logika kueri 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 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.

Penelusuran hybrid

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).

• 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 mencoba mendorong aspek kueri berikut langsung ke panggilan API yang dilakukan ke Elasticsearch:

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

Untuk contoh kueri yang menggambarkan aspek yang dapat dan tidak dapat didorong ke bawah oleh AlloyDB, 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

Catatan: Elasticsearch adalah merek dagang Elastic NV dan tidak berafiliasi dengan Google LLC.