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 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 kepada akun layanan ini untuk mengakses Secret Manager di Membuat cluster database dengan AlloyDB AI.

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

  3. Simpan kunci di lokasi permanen pada sistem file Anda. File ini berada di lokasi ini selama masa aktif server AlloyDB Omni Anda.

    Catat lokasinya di sistem file Anda; Anda akan memerlukannya untuk langkah-langkah berikutnya.

  4. Buat secret Kubernetes menggunakan kunci akun layanan.

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 izin untuk membaca secret. Untuk mengetahui informasi selengkapnya, lihat Mengelola akses ke secret.

Membuat cluster database dengan AlloyDB AI

Untuk membuat cluster database dengan AlloyDB AI, lihat Menginstal AlloyDB AI di AlloyDB Omni. Untuk mengakses dan mengkueri data dengan Elasticsearch, Anda tidak perlu menentukan konfigurasi vertexAI*.

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 diperlukan 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 yang diminta, AlloyDB Omni 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 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 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 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 REST API Elasticsearch. Selama konversi ini, AlloyDB Omni mencoba melakukan push-down sebanyak mungkin logika kueri 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 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 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 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 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 menerapkan 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. Contoh, 0.5. Jika Anda tidak memberikan bobot, bobot akan didistribusikan secara merata. Untuk mengetahui informasi selengkapnya, lihat Parameter fungsi penelusuran hybrid.

  • 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

Agar kueri lebih efisien, AlloyDB Omni 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 menunjukkan aspek yang dapat dan tidak dapat didorong ke bawah oleh AlloyDB Omni, 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
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