Mengakses data Elasticsearch dari AlloyDB untuk PostgreSQL

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

Sebelum memulai

Sebelum memulai, pastikan Anda telah menyelesaikan hal berikut:

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 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. Konfigurasikan 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 ditampilkan secara 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 project ID Google Cloud Anda.

    • (Opsional) MAX_DEADLINE: jumlah waktu maksimum, dalam milidetik, yang ditunggu AlloyDB untuk mendapatkan respons dari Elasticsearch. Anda harus menetapkan nilai ini berdasarkan lokasi instance AlloyDB dan Elasticsearch Anda. Nilai defaultnya adalah 10000.

    • (Opsional) PAGINATION_NUM_RESULTS: jumlah hasil maksimum yang diambil per batch dari Elasticsearch. Jika lebih banyak hasil yang 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. Konfigurasikan 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 mewakili 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 Anda

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

Dalam skenario saat LIMIT ditetapkan lebih tinggi dari pagination_num_results atau saat LIMIT tidak ditentukan atau tidak dapat didorong ke bawah, 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 mengkueri data Elasticsearch, Anda memiliki opsi berikut:

  • Kueri SQL standar
  • DSL Kueri
  • Penelusuran campuran

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 mewakili 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 bergaya JSON berfitur lengkap 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 DSL Kueri, 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 mewakili 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 DSL Kueri, 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 Reciprocal Rank Fusion (RRF) secara keseluruhan.

  • ELASTICSEARCH_FD_TABLE: nama tabel data asing yang mewakili 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

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

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

Untuk contoh kueri yang menggambarkan aspek mana yang dapat dan tidak dapat didorong oleh AlloyDB, lihat tabel berikut.

Jenis kueri Contoh kueri Elemen kueri yang 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
Kecocokan 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 mengkueri cluster Elasticsearch, periksa penyebab umum berikut:

  • Error autentikasi HTTP 401 atau 403: Pastikan secret Elasticsearch Anda di Secret Manager berisi kredensial autentikasi yang valid untuk auth_method (ApiKey atau Basic), dan pastikan akun layanan yang digunakan oleh AlloyDB memiliki izin secretmanager.secretAccessor.
  • Waktu tunggu koneksi habis: Pastikan konektivitas IP publik keluar diaktifkan di instance AlloyDB utama Anda dan firewall Elasticsearch Anda mengizinkan koneksi masuk di port yang ditentukan.

Batasan

Sebelum menghubungkan AlloyDB ke Elasticsearch, pahami batasan berikut:

  • Integrasi Elasticsearch hanya tersedia di PostgreSQL versi utama 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.

Langkah berikutnya