Pengindeksan data dari Azure Cosmos DB NoSQL untuk keperluan pencarian di Pencarian Azure AI

Nota

Pencarian Azure AI tersedia melalui portal Azure, REST API, dan Azure SDK. Ini juga mendukung Foundry IQ, lapisan pengetahuan terkelola yang mengubah konten perusahaan menjadi pangkalan pengetahuan yang dapat digunakan kembali dan sadar izin untuk agen di portal Microsoft Foundry.

Important

Fitur dan fungsionalitas ini mendukung koneksi ke layanan layanan Microsoft dan pihak ketiga lainnya. Penggunaan layanan ini tunduk pada persyaratan masing-masing dan dapat mengakibatkan pemrosesan data atau penyimpanan di luar batas kepatuhan Azure, serta data yang mengalir ke batas kepatuhan Azure.

Anda bertanggung jawab untuk mengelola apakah data Anda akan mengalir di luar batas kepatuhan dan geografis organisasi Anda dan implikasi terkait, dan bahwa izin, batas, dan persetujuan yang sesuai disediakan.

Anda bertanggung jawab untuk meninjau dan menguji aplikasi yang Anda buat dengan cermat dalam konteks kasus penggunaan spesifik Anda dan membuat semua keputusan dan penyesuaian yang sesuai. Ini termasuk menerapkan mitigasi AI Anda sendiri yang bertanggung jawab, seperti metaprompts, filter konten, atau sistem keamanan lainnya, dan memastikan aplikasi Anda memenuhi standar kualitas, keandalan, keamanan, dan kepercayaan yang sesuai. Untuk informasi selengkapnya, lihat Catatan Transparansi Pencarian Azure AI.

Pengindeks Azure Cosmos DB untuk NoSQL mengimpor konten dari Azure Cosmos DB untuk NoSQL dan membuatnya dapat dicari di Pencarian Azure AI.

Artikel ini melengkapi Buat pengindeks dengan informasi khusus untuk Cosmos DB. Ini menggunakan API portal Azure dan REST 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 Pencarian Azure AI adalah operasi yang berbeda. Pengindeksan di Pencarian Azure AI membuat dan memuat indeks pencarian di layanan pencarian Anda.

Prasyarat

  • Akun , database, kontainer, dan item Azure Cosmos DB. Gunakan wilayah yang sama untuk Pencarian Azure AI 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.

  • Hak akses baca. String koneksi "akses penuh" menyertakan kunci yang memberikan akses ke konten, tetapi jika Anda menggunakan identitas (ID Microsoft Entra), pastikan identitas terkelola layanan pencarian ditetapkan sebagai Peran Pembaca Akun Cosmos DB dan Peran Pembaca Data Bawaan Cosmos DB.

Untuk mengerjakan contoh dalam artikel ini, Anda memerlukan portal Azure atau klien REST. Jika Anda menggunakan portal Azure, pastikan akses ke semua jaringan publik diaktifkan. Pendekatan lain untuk membuat pengindeks Cosmos DB termasuk Azure SDK.

Coba dengan data sampel

Gunakan instruksi ini untuk membuat kontainer dan database di Cosmos DB untuk tujuan pengujian.

  1. Unduh HotelsData_toCosmosDB.json dari GitHub untuk membuat kontainer di Cosmos DB yang berisi subset himpunan data hotel sampel.

  2. Masuk ke portal Azure dan buat akun, database, dan kontainer di Cosmos DB.

  3. Di Cosmos DB, pilih Data Explorer dan, untuk kontainer baru, berikan nilai berikut.

    Harta benda Nilai
    Database Buat baru
    Identifikasi Database hotelsdb
    Bagikan throughput di seluruh kontainer Jangan pilih
    ID Kontainer Hotel
    Kunci partisi /HotelId
    Lalu lintas kontainer (penyesuaian otomatis) Skala otomatis
    Maks RU/dtk Kontainer 1000

  4. Di Data Explorer, perluas hotelsdb dan hotel, lalu pilih Item.

  5. Pilih Unggah Item lalu pilih fileHotelsData_toCosmosDB.json yang Anda unduh dari GitHub.

  6. Klik kanan Item dan pilih Kueri SQL baru. Kueri defaultnya adalah SELECT * FROM c.

  7. Pilih Jalankan kueri untuk menjalankan kueri dan menampilkan hasil. Anda harus memiliki 50 dokumen hotel.

Sekarang setelah Anda memiliki kontainer, Anda dapat menggunakan portal Azure, klien REST, atau Azure SDK untuk mengindeks data Anda.

Bidang Deskripsi menyediakan konten paling verbose. Anda harus menargetkan bidang ini untuk pencarian teks lengkap dan kueri vektor opsional.

Gunakan portal Azure

Anda bisa menggunakan wizard Impor data untuk mengotomatiskan pengindeksan dari tabel atau tampilan database SQL.

  1. Mulai panduan

  2. Pada Sambungkan ke data Anda, pilih atau verifikasi bahwa jenis sumber data adalah Azure Cosmos DB atau akun NoSQL.

    Nama sumber data mengacu pada objek koneksi sumber data di Pencarian Azure AI. Nama sumber data Anda dibuat secara otomatis menggunakan awalan kustom yang Anda tentukan di akhir alur kerja wizard.

  3. Tentukan nama dan koleksi database. Kueri bersifat opsional. Ini berguna jika Anda memiliki data hierarkis dan Anda ingin mengimpor irisan tertentu.

  4. Tentukan metode autentikasi, baik identitas terkelola atau kunci API bawaan. Jika Anda tidak menentukan koneksi identitas terkelola, portal Azure menggunakan kunci.

    Jika Anda mengonfigurasi Pencarian Azure AI untuk menggunakan identitas terkelola, dan Anda membuat penetapan peran di Cosmos DB yang memberikan izin Pembaca Akun Cosmos DB dan Pembaca Data Bawaan Cosmos DB ke identitas, pengindeks Anda dapat terhubung ke Cosmos DB menggunakan ID dan peran Microsoft Entra.

  5. Anda dapat menentukan opsi untuk pelacakan perubahan dan penghapusan.

    Deteksi perubahan didukung secara default melalui _ts bidang (tanda waktu). Jika Anda mengunggah konten menggunakan pendekatan yang dijelaskan di bagian Coba dengan data sampel, koleksi dibuat dengan _ts bidang.

    Deteksi penghapusan mengharuskan Anda memiliki bidang tingkat atas yang sudah ada sebelumnya di dalam kumpulan yang dapat digunakan sebagai penanda penghapusan lunak. Ini harus berupa bidang Boolean (Anda bisa menamainya IsDeleted). Tentukan true sebagai nilai yang dihapus sementara. Dalam indeks pencarian, tambahkan bidang pencarian terkait bernama IsDeleted yang diatur agar dapat diambil dan difilter.

  6. Lanjutkan dengan langkah-langkah yang tersisa untuk menyelesaikan wizard:

Menggunakan REST API

Bagian ini menunjukkan panggilan REST API yang 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 adalah sumber daya independen yang dapat digunakan oleh beberapa pengindeks.

  1. Buat atau perbarui sumber data untuk mengatur definisinya:

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

  2. Atur "jenis" ke "cosmosdb" (diperlukan). Jika Anda menggunakan Search API versi 2017-11-11 yang lebih lama, sintaks untuk "type" adalah "documentdb". Jika tidak, untuk 2019-05-06 dan yang lebih baru, gunakan "cosmosdb".

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

  4. Atur "kontainer" dalam koleksi. Properti "nama" diperlukan dan menentukan ID koleksi database yang akan diindeks. Properti "kueri" bersifat opsional. Gunakan untuk meratakan dokumen JSON arbitrer menjadi skema datar yang dapat diindeks oleh Pencarian Azure AI.

  5. Atur "dataChangeDetectionPolicy" jika data volatil dan Anda ingin pengindeks hanya mengambil item baru dan yang diperbarui pada eksekusi berikutnya.

  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.

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

String koneksi akses penuh
{ "connectionString" : "AccountEndpoint=https://<Cosmos DB account name>.documents.azure.com;AccountKey=<Cosmos DB auth key>;Database=<Cosmos DB database id>" }
Anda bisa mendapatkan string koneksi dari halaman akun Azure Cosmos DB di portal Microsoft Azure dengan memilih Kunci di panel kiri. Pastikan untuk memilih string koneksi lengkap dan bukan hanya kunci.
(Pendekatan modern) String koneksi identitas terkelola untuk akun NoSQL
{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.DocumentDB/databaseAccounts/<your cosmos db account name>/;(ApiKind=[api-kind];)/(IdentityAuthType=AccessToken)" }
Connection string ini, hanya didukung untuk Azure Cosmos DB untuk akun NoSQL, memastikan bahwa layanan pencarian tidak pernah menggunakan kunci akun (bahkan di latar belakang) saat mencoba mengakses data dari Cosmos DB. Pendekatan ini direkomendasikan, karena berfungsi bahkan jika akun NoSQL memiliki kunci akun yang dinonaktifkan. Untuk informasi selengkapnya, lihat Menyiapkan koneksi pengindeks ke database Azure Cosmos DB menggunakan identitas terkelola.
(Pendekatan lama) Koneksi string identitas terkelola
{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.DocumentDB/databaseAccounts/<your cosmos db account name>/;(ApiKind=[api-kind];)/(IdentityAuthType=AccountKey)" }
String koneksi ini tidak memerlukan kunci akun untuk ditetapkan secara langsung, tetapi layanan pencarian menggunakan identitas terkelola untuk mengambil kunci akun di latar belakang. Meskipun pendekatan ini didukung untuk semua jenis akun Cosmos DB, pendekatan ini tidak disarankan untuk jenis akun NoSQL. Connection string seperti itu tidak berfungsi jika kunci akun dinonaktifkan untuk akun Cosmos DB. Jika properti IdentityAuthType dihilangkan, layanan pencarian tetap secara default mengambil kunci akun di latar belakang. Untuk koneksi yang menargetkan API SQL, Anda dapat menghilangkan ApiKind dari string koneksi. Untuk informasi selengkapnya tentang ApiKind dan IdentityAuthType, lihat Menyiapkan koneksi pengindeks ke database Azure Cosmos DB menggunakan identitas terkelola.

Menggunakan kueri untuk membentuk data yang terindeks

Di properti "kueri" di bawah "kontainer", Anda dapat menentukan kueri SQL untuk meratakan properti atau array berlapis, memproyeksikan properti JSON, dan memfilter data yang akan diindeks.

Contoh dokumen:

    {
        "userId": 10001,
        "contact": {
            "firstName": "andy",
            "lastName": "hoh"
        },
        "company": "microsoft",
        "tags": ["azure", "cosmosdb", "search"]
    }

Filter kueri:

SELECT * FROM c WHERE c.company = "microsoft" and c._ts >= @HighWaterMark ORDER BY c._ts

Kueri pendataran:

SELECT c.id, c.userId, c.contact.firstName, c.contact.lastName, c.company, c._ts FROM c WHERE c._ts >= @HighWaterMark ORDER BY c._ts

Kueri proyeksi:

SELECT VALUE { "id":c.id, "Name":c.contact.firstName, "Company":c.company, "_ts":c._ts } FROM c WHERE c._ts >= @HighWaterMark ORDER BY c._ts

Permintaan perentangan array:

SELECT c.id, c.userId, tag, c._ts FROM c JOIN tag IN c.tags WHERE c._ts >= @HighWaterMark ORDER BY c._ts

Kueri yang tidak didukung (DISTINCT dan GROUP BY)

Kueri yang menggunakan kata kunci DISTINCT atau klausa GROUP BY tidak didukung. Pencarian Azure AI bergantung pada penomoran halaman kueri SQL untuk sepenuhnya menghitung hasil kueri. Baik kata kunci DISTINCT maupun klausul GROUP BY tidak kompatibel dengan token kelanjutan yang digunakan untuk membagi halaman hasil.

Contoh kueri yang tidak didukung:

SELECT DISTINCT c.id, c.userId, c._ts FROM c WHERE c._ts >= @HighWaterMark ORDER BY c._ts

SELECT DISTINCT VALUE c.name FROM c ORDER BY c.name

SELECT TOP 4 COUNT(1) AS foodGroupCount, f.foodGroup FROM Food f GROUP BY f.foodGroup

Meskipun Azure Cosmos DB memiliki solusi untuk mendukung paginasi kueri SQL dengan kata kunci DISTINCT menggunakan klausul ORDER BY, itu tidak kompatibel dengan Pencarian Azure AI. Kueri mengembalikan satu nilai JSON, sedangkan Pencarian Azure AI mengharapkan objek JSON.

-- The following query returns a single JSON value and isn't supported by Azure AI Search
SELECT DISTINCT VALUE c.name FROM c ORDER BY c.name

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 data sumber. 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 menyimpan data:

    POST https://[service name].search.windows.net/indexes?api-version=2026-04-01
Content-Type: application/json
api-key: [Search service admin key]
{
    "name": "mysearchindex",
    "fields": [{
        "name": "rid",
        "type": "Edm.String",
        "key": true,
        "searchable": false
    }, 
    {
        "name": "description",
        "type": "Edm.String",
        "filterable": false,
        "searchable": true,
        "sortable": false,
        "facetable": false,
        "suggestions": true
    }
  ]
}

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

  3. Buat lebih banyak bidang 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 tipe primitif seperti ["a", "b", "c"] Kumpulan(Edm.String)
String yang terlihat seperti tanggal Edm.DateTimeOffset, Edm.String
Objek GeoJSON seperti { "type": "Point", "coordinates": [long, lat] } Edm.GeographyPoint
Objek JSON yang lain N/A

Mengonfigurasi dan menjalankan pengindeks Azure Cosmos DB for NoSQL

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=2026-04-01
Content-Type: application/json
api-key: [search service admin key]
{
    "name" : "[my-cosmosdb-indexer]",
    "dataSourceName" : "[my-cosmosdb-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, periksa riwayat eksekusi pengindeks di portal Azure, atau kirim permintaan Get Indexer Status REST API.

  1. Pada halaman layanan pencarian, buka manajemen pencarian>Pengindeks.

  2. Pilih pengindeks untuk mengakses konfigurasi dan riwayat eksekusi.

  3. Pilih pekerjaan pengindeks tertentu untuk melihat detail, peringatan, dan kesalahan.

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.

Pada pengindeks Azure Cosmos DB, satu-satunya kebijakan yang didukung adalah menggunakan 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"
},

Nota

Saat Anda menetapkan null nilai ke bidang di Azure Cosmos DB Anda, pengindeks Pencarian AI tidak dapat membedakan antara null dan nilai bidang yang hilang. Oleh karena itu, jika bidang dalam indeks kosong, bidang tersebut tidak diganti dengan null nilai, bahkan jika modifikasi tersebut dibuat dalam database Anda.

Pengindeksan inkremental dan kueri kustom

Jika Anda menggunakan kueri kustom untuk mengambil dokumen, pastikan kueri mengurutkan hasil menurut _ts kolom. Ini memungkinkan titik pemeriksaan berkala yang digunakan Pencarian Azure AI untuk memberikan kemajuan inkremental dalam kondisi kegagalan.

Dalam beberapa kasus, bahkan jika kueri Anda berisi ORDER BY [collection alias]._ts klausa, Pencarian Azure AI mungkin tidak menyimpulkan bahwa kueri diurutkan oleh _ts. Anda dapat memberi tahu Pencarian Azure AI bahwa hasil diurutkan dengan mengatur assumeOrderByHighWaterMarkColumn properti konfigurasi.

Untuk menentukan petunjuk ini, buat atau perbarui definisi pengindeks Anda sebagai berikut:

{
    ... other indexer definition properties
    "parameters" : {
        "configuration" : { "assumeOrderByHighWaterMarkColumn" : true } }
}

Mengindeks dokumen yang telah dihapus

Saat baris dihapus dari kumpulan, Anda biasanya juga ingin menghapus baris tersebut dari indeks pencarian. Tujuan kebijakan deteksi perubahan data adalah untuk mengidentifikasi item data yang diubah secara efisien. 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"
}

Jika Anda menggunakan kueri kustom, pastikan properti yang direferensikan oleh softDeleteColumnName diproyeksikan oleh kueri.

softDeleteColumnName harus berupa bidang tingkat atas dalam indeks. Menggunakan bidang berlapis dalam jenis data kompleks karena softDeleteColumnName tidak didukung.

Berikut ini contoh membuat sumber data dengan kebijakan penghapusan sementara:

POST https://[service name].search.windows.net/datasources?api-version=2026-04-01
Content-Type: application/json
api-key: [Search service admin key]

{
    "name": "[my-cosmosdb-ds]",
    "type": "cosmosdb",
    "credentials": {
        "connectionString": "AccountEndpoint=https://[cosmos-account-name].documents.azure.com;AccountKey=[cosmos-account-key];Database=[cosmos-database-name]"
    },
    "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"
    }
}

Gunakan .NET

Untuk data yang diakses melalui protokol SQL API, Anda dapat menggunakan .NET SDK untuk mengotomatiskan dengan pengindeks. Sebaiknya tinjau bagian REST API sebelumnya untuk mempelajari konsep, alur kerja, dan persyaratan. Anda kemudian dapat merujuk ke dokumentasi referensi .NET API berikut untuk mengimplementasikan pengindeks JSON dalam kode terkelola:

Langkah selanjutnya

Anda sekarang dapat mengontrol bagaimana Anda menjalankan pengindeks, memantau status, atau menjadwalkan eksekusi pengindeks. Artikel berikut ini berlaku untuk pengindeks yang menarik konten dari Azure Cosmos DB:

  • Terakhir diperbarui pada