Mengindeks data dari Azure Cosmos DB untuk Apache Gremlin untuk kueri di Azure AI Search

  • Artikel

Penting

Pengindeks Azure Cosmos DB for Apache Gremlin saat ini berada dalam pratinjau publik di bawah Ketentuan Penggunaan Tambahan. Saat ini, tidak ada dukungan SDK.

Dalam artikel ini, pelajari cara mengonfigurasi pengindeks yang mengimpor konten dari Azure Cosmos DB untuk Apache Gremlin dan membuatnya dapat dicari di Azure AI Search.

Artikel ini melengkapi Buat pengindeks dengan informasi khusus untuk Cosmos DB. Ini menggunakan REST API untuk menunjukkan alur kerja tiga bagian yang umum untuk semua pengindeks: membuat sumber data, membuat indeks, membuat pengindeks. Ekstraksi data terjadi saat Anda mengirimkan permintaan Buat Pengindeks.

Karena terminologi dapat membingungkan, perlu dicatat bahwa pengindeksan Azure Cosmos DB dan pengindeksan Azure AI Search adalah operasi yang berbeda. Pengindeksan di Azure AI Search membuat dan memuat indeks pencarian di layanan pencarian Anda.

Prasyarat

  • Daftarkan pratinjau untuk memberikan umpan balik skenario. Anda dapat mengakses fitur secara otomatis setelah pengiriman formulir.

  • Akun , database, kontainer, dan item Azure Cosmos DB. Gunakan wilayah yang sama untuk Azure AI Search dan Azure Cosmos DB untuk latensi yang lebih rendah dan untuk menghindari biaya bandwidth.

  • Kebijakan pengindeksan otomatis pada koleksi Azure Cosmos DB, diatur ke Konsisten. Ini adalah konfigurasi default. Pengindeksan malas tidak disarankan dan dapat mengakibatkan data yang hilang.

  • Izin baca. String koneksi "akses penuh" menyertakan kunci yang memberikan akses ke konten, tetapi jika Anda menggunakan peran Azure, pastikan identitas terkelola layanan pencarian memiliki izin Peran Pembaca Akun Cosmos DB.

  • Klien REST untuk membuat sumber data, indeks, dan pengindeks.

Menentukan sumber data

Definisi sumber data menentukan data untuk mengindeks, kredensial, dan kebijakan untuk mengidentifikasi perubahan dalam data. Sumber data didefinisikan sebagai sumber daya independen sehingga dapat digunakan oleh beberapa pengindeks.

Untuk panggilan ini, tentukan pratinjau versi REST API (2020-06-30-Preview atau 2021-04-30-Preview) untuk membuat sumber data yang terhubung melalui Azure Cosmos DB untuk Apache Gremlin.

  1. Buat atau perbarui sumber data untuk mengatur definisinya:

     POST https://[service name].search.windows.net/datasources?api-version=2021-04-30-Preview
 Content-Type: application/json
 api-key: [Search service admin key]
 {
   "name": "[my-cosmosdb-gremlin-ds]",
   "type": "cosmosdb",
   "credentials": {
     "connectionString": "AccountEndpoint=https://[cosmos-account-name].documents.azure.com;AccountKey=[cosmos-account-key];Database=[cosmos-database-name];ApiKind=Gremlin;"
   },
   "container": {
     "name": "[cosmos-db-collection]",
     "query": "g.V()"
   },
   "dataChangeDetectionPolicy": {
     "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
     "highWaterMarkColumnName": "_ts"
   },
   "dataDeletionDetectionPolicy": null,
   "encryptionKey": null,
   "identity": null
 }
 }

  2. Atur "jenis" ke "cosmosdb" (diperlukan).

  3. Atur "kredensial" ke string koneksi. Bagian berikutnya menjelaskan format yang didukung.

  4. Atur "kontainer" ke koleksi. Properti "nama" diperlukan dan menentukan ID grafik.

    Properti "kueri" bersifat opsional. Secara default pengindeks Azure AI Search untuk Azure Cosmos DB untuk Apache Gremlin membuat setiap puncak dalam grafik Anda menjadi dokumen dalam indeks. Tepi akan diabaikan. Default kueri adalah g.V(). Atau, Anda dapat mengatur kueri untuk hanya mengindeks tepi. Untuk mengindeks tepi, atur kueri ke g.E().

  5. Atur "dataChangeDetectionPolicy" jika data volatil dan Anda ingin pengindeks hanya mengambil item baru dan yang diperbarui pada eksekusi berikutnya. Kemajuan inkremental akan diaktifkan secara default menggunakan _ts sebagai kolom tanda air tinggi.

  6. Atur "dataDeletionDetectionPolicy" jika Anda ingin menghapus dokumen pencarian dari indeks pencarian saat item sumber dihapus.

Kredensial dan string koneksi yang didukung

Pengindeks dapat tersambung ke koleksi menggunakan koneksi berikut. Untuk koneksi yang menargetkan Azure Cosmos DB untuk Apache Gremlin, pastikan untuk menyertakan "ApiKind" dalam string koneksi.

Hindari nomor port di URL titik akhir. Jika Anda menyertakan nomor port, koneksi akan gagal.

Akses penuh string koneksi
{ "connectionString" : "AccountEndpoint=https://<Cosmos DB account name>.documents.azure.com;AccountKey=<Cosmos DB auth key>;Database=<Cosmos DB database id>;ApiKind=MongoDb" }
Anda bisa mendapatkan string koneksi dari halaman akun Azure Cosmos DB di portal Azure dengan memilih Kunci di panel navigasi kiri. Pastikan untuk memilih string koneksi lengkap dan bukan hanya kunci.
Identitas terkelola string koneksi
{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.DocumentDB/databaseAccounts/<your cosmos db account name>/;(ApiKind=[api-kind];)" }
String koneksi ini tidak memerlukan kunci akun, tetapi Sebelumnya Anda harus mengonfigurasi layanan pencarian untuk terhubung menggunakan identitas terkelola dan membuat penetapan peran yang memberikan izin Peran Pembaca Akun Cosmos DB. Lihat Menyiapkan koneksi pengindeks ke database Azure Cosmos DB menggunakan identitas terkelola untuk informasi selengkapnya.

Menambahkan bidang pencarian ke indeks

Dalam indeks pencarian, tambahkan bidang untuk menerima dokumen JSON sumber atau output proyeksi kueri kustom Anda. Pastikan bahwa skema indeks pencarian kompatibel dengan grafik Anda. Untuk konten di Azure Cosmos DB, skema indeks pencarian Anda harus sesuai dengan item Azure Cosmos DB di sumber data Anda.

  1. Buat atau perbarui indeks untuk menentukan bidang pencarian yang akan menyimpan data:

     POST https://[service name].search.windows.net/indexes?api-version=2020-06-30-Preview
 Content-Type: application/json
 api-key: [Search service admin key]
 {
    "name": "mysearchindex",
    "fields": [
     {
         "name": "rid",
         "type": "Edm.String",
         "facetable": false,
         "filterable": false,
         "key": true,
         "retrievable": true,
         "searchable": true,
         "sortable": false,
         "analyzer": "standard.lucene",
         "indexAnalyzer": null,
         "searchAnalyzer": null,
         "synonymMaps": [],
         "fields": []
     },{
     }, {
         "name": "label",
         "type": "Edm.String",
         "searchable": true,
         "filterable": false,
         "retrievable": true,
         "sortable": false,
         "facetable": false,
         "key": false,
         "indexAnalyzer": null,
         "searchAnalyzer": null,
         "analyzer": "standard.lucene",
         "synonymMaps": []
    }]
  }

  2. Buat bidang kunci dokumen ("key": true). Untuk koleksi yang dipartisi, kunci dokumen default adalah properti Azure Cosmos DB _rid , yang secara otomatis diganti namanya menjadi rid Azure AI Search karena nama bidang tidak dapat dimulai dengan karakter garis bawah. Selain itu, nilai Azure Cosmos DB _rid berisi karakter yang tidak valid di kunci Azure AI Search. Untuk alasan ini, nilai _rid dikodekan dengan Base64.

  3. Buat bidang tambahan untuk konten yang lebih dapat dicari. Lihat Membuat indeks untuk detailnya.

Jenis data pemetaan

Jenis data JSON Jenis bidang Pencarian Azure AI
Bool Edm.Boolean, Edm.String
Angka yang tampak seperti bilangan bulat Edm.Int32, Edm.Int64, Edm.String
Angka yang tampak seperti titik apung Edm.Double, Edm.String
String Edm.String
Array jenis primitif seperti ["a", "b", "c"] Kumpulan(Edm.String)
String yang tampak seperti tanggal Edm.DateTimeOffset, Edm.String
Objek GeoJSON seperti { "type": "Point", "coordinates": [long, lat] } Edm.GeographyPoint
Objek JSON yang lain T/A

Mengonfigurasi dan menjalankan pengindeks Azure Cosmos DB

Setelah indeks dan sumber data dibuat, Anda siap untuk membuat pengindeks. Konfigurasi pengindeks menentukan input, parameter, dan properti yang mengontrol perilaku run time.

  1. Buat atau perbarui pengindeks dengan memberinya nama dan mereferensikan sumber data dan indeks target:

    POST https://[service name].search.windows.net/indexers?api-version=2020-06-30
Content-Type: application/json
api-key: [search service admin key]
{
    "name" : "[my-cosmosdb-indexer]",
    "dataSourceName" : "[my-cosmosdb-gremlin-ds]",
    "targetIndexName" : "[my-search-index]",
    "disabled": null,
    "schedule": null,
    "parameters": {
        "batchSize": null,
        "maxFailedItems": 0,
        "maxFailedItemsPerBatch": 0,
        "base64EncodeKeys": false,
        "configuration": {}
        },
    "fieldMappings": [],
    "encryptionKey": null
}

  2. Tentukan pemetaan bidang jika ada perbedaan dalam nama atau jenis bidang, atau jika Anda memerlukan beberapa versi bidang sumber dalam indeks pencarian.

  3. Lihat Membuat pengindeks untuk informasi selengkapnya tentang properti lain.

Pengindeks berjalan secara otomatis saat dibuat. Anda dapat mencegahnya dengan mengatur "dinonaktifkan" ke true. Untuk mengontrol eksekusi pengindeks, jalankan pengindeks sesuai permintaan atau letakkan sesuai jadwal.

Periksa status pengindeks

Untuk memantau status pengindeks dan riwayat eksekusi, kirim permintaan Dapatkan Status Pengindeks:

GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2020-06-30
  Content-Type: application/json  
  api-key: [admin key]

Respons mencakup status dan jumlah item yang diproses. Ini akan terlihat mirip dengan contoh berikut:

    {
        "status":"running",
        "lastResult": {
            "status":"success",
            "errorMessage":null,
            "startTime":"2022-02-21T00:23:24.957Z",
            "endTime":"2022-02-21T00:36:47.752Z",
            "errors":[],
            "itemsProcessed":1599501,
            "itemsFailed":0,
            "initialTrackingState":null,
            "finalTrackingState":null
        },
        "executionHistory":
        [
            {
                "status":"success",
                "errorMessage":null,
                "startTime":"2022-02-21T00:23:24.957Z",
                "endTime":"2022-02-21T00:36:47.752Z",
                "errors":[],
                "itemsProcessed":1599501,
                "itemsFailed":0,
                "initialTrackingState":null,
                "finalTrackingState":null
            },
            ... earlier history items
        ]
    }

Riwayat eksekusi berisi hingga 50 eksekusi yang terakhir selesai, yang diurutkan dalam urutan kronologis terbalik sehingga eksekusi terbaru menjadi yang pertama.

Mengindeks dokumen baru dan yang diubah

Setelah pengindeks mengisi indeks pencarian sepenuhnya, Anda mungkin ingin pengindeks berikutnya berjalan untuk mengindeks secara bertahap hanya dokumen baru dan yang diubah dalam database Anda.

Untuk mengaktifkan pengindeksan inkremental, atur properti "dataChangeDetectionPolicy" dalam definisi sumber data Anda. Properti ini memberi tahu pengindeks mekanisme pelacakan perubahan mana yang digunakan pada data Anda.

Untuk pengindeks Azure Cosmos DB, satu-satunya kebijakan yang HighWaterMarkChangeDetectionPolicy didukung adalah menggunakan _ts properti (tanda waktu) yang disediakan oleh Azure Cosmos DB.

Contoh berikut menunjukkan definisi sumber data dengan kebijakan deteksi perubahan:

"dataChangeDetectionPolicy": {
    "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
"  highWaterMarkColumnName": "_ts"
},

Mengindeks dokumen yang telah dihapus

Saat data grafik dihapus, Anda mungkin ingin menghapus dokumen yang sesuai dari indeks pencarian juga. Tujuan dari kebijakan deteksi penghapusan data adalah untuk mengidentifikasi item data yang dihapus secara efisien dan menghapus dokumen lengkap dari indeks. Kebijakan deteksi penghapusan data bukan berarti menghapus sebagian informasi dokumen. Saat ini, satu-satunya kebijakan yang didukung adalah Soft Delete kebijakan (penghapusan ditandai dengan bendera semacam), yang ditentukan dalam definisi sumber data sebagai berikut:

"dataDeletionDetectionPolicy"": {
    "@odata.type" : "#Microsoft.Azure.Search.SoftDeleteColumnDeletionDetectionPolicy",
    "softDeleteColumnName" : "the property that specifies whether a document was deleted",
    "softDeleteMarkerValue" : "the value that identifies a document as deleted"
}

Berikut ini contoh membuat sumber data dengan kebijakan penghapusan sementara:

POST https://[service name].search.windows.net/datasources?api-version=2020-06-30-Preview
Content-Type: application/json
api-key: [Search service admin key]

{
    "name": "[my-cosmosdb-gremlin-ds]",
    "type": "cosmosdb",
    "credentials": {
        "connectionString": "AccountEndpoint=https://[cosmos-account-name].documents.azure.com;AccountKey=[cosmos-account-key];Database=[cosmos-database-name];ApiKind=Gremlin"
    },
    "container": { "name": "[my-cosmos-collection]" },
    "dataChangeDetectionPolicy": {
        "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
        "highWaterMarkColumnName": "`_ts`"
    },
    "dataDeletionDetectionPolicy": {
        "@odata.type": "#Microsoft.Azure.Search.SoftDeleteColumnDeletionDetectionPolicy",
        "softDeleteColumnName": "isDeleted",
        "softDeleteMarkerValue": "true"
    }
}

Bahkan jika Anda mengaktifkan kebijakan deteksi penghapusan, menghapus bidang kompleks (Edm.ComplexType) dari indeks tidak didukung. Kebijakan ini mengharuskan kolom 'aktif' dalam database Gremlin berjenis bilangan bulat, string, atau boolean.

Memetakan data grafik ke bidang dalam indeks pencarian

Pengindeks Azure Cosmos DB for Apache Gremlin akan secara otomatis memetakan beberapa bagian data grafik:

  1. Pengindeks akan memetakan _rid ke rid bidang dalam indeks jika ada, dan Base64 mengodekannya.

  2. Pengindeks akan memetakan _id ke bidang id dalam indeks jika ada.

  3. Saat mengkueri database Azure Cosmos DB Anda menggunakan Azure Cosmos DB untuk Apache Gremlin, Anda mungkin melihat bahwa output JSON untuk setiap properti memiliki id dan value. Pengindeks akan secara otomatis memetakan properti value ke dalam bidang dalam indeks pencarian Anda yang memiliki nama yang sama dengan properti jika ada. Dalam contoh berikut, 450 akan dipetakan ke bidang pages dalam indeks pencarian.

    {
        "id": "Cookbook",
        "label": "book",
        "type": "vertex",
        "properties": {
          "pages": [
            {
              "id": "48cf6285-a145-42c8-a0aa-d39079277b71",
              "value": "450"
            }
          ]
        }
    }

Anda mungkin menemukan bahwa Anda perlu menggunakan Pemetaan Bidang Output untuk memetakan output kueri Anda ke bidang dalam indeks Anda. Anda mungkin ingin menggunakan Pemetaan Bidang Output, bukan Pemetaan Bidang karena kueri kustom kemungkinan akan memiliki data yang kompleks.

Misalnya, kueri Anda menghasilkan output seperti ini:

    [
      {
        "vertex": {
          "id": "Cookbook",
          "label": "book",
          "type": "vertex",
          "properties": {
            "pages": [
              {
                "id": "48cf6085-a211-42d8-a8ea-d38642987a71",
                "value": "450"
              }
            ],
          }
        },
        "written_by": [
          {
            "yearStarted": "2017"
          }
        ]
      }
    ]

Jika Anda ingin memetakan nilai pages pada JSON di atas bidang totalpages dalam indeks, Anda dapat menambahkan Pemetaan Bidang Output berikut ke definisi pengindeks Anda:

    ... // rest of indexer definition 
    "outputFieldMappings": [
        {
          "sourceFieldName": "/document/vertex/pages",
          "targetFieldName": "totalpages"
        }
    ]

Perhatikan cara Pemetaan Bidang Output dimulai /document dan tidak menyertakan referensi ke kunci properti di JSON. Ini karena pengindeks menempatkan setiap dokumen pada simpul /document ketika menyerap data grafik dan pengindeks juga secara otomatis mengizinkan Anda untuk mereferensikan nilai pages dengan referensi sederhana pages daripada harus mereferensikan objek pertama dalam larik pages .

Langkah berikutnya