Azure Yapay Zeka Arama'daki sorgular için Apache Gremlin için Azure Cosmos DB'den dizin verileri

  • Makale

Önemli

Apache Gremlin için Azure Cosmos DB dizin oluşturucu şu anda Ek Kullanım Koşulları altında genel önizleme aşamasındadır. Şu anda SDK desteği yoktur.

Bu makalede Apache Gremlin için Azure Cosmos DB'den içerik içeri aktaran ve Azure AI Search'te aranabilir hale getiren bir dizin oluşturucu yapılandırmayı öğrenin.

Bu makale , Cosmos DB'ye özgü bilgilerle dizin oluşturucu oluşturma makalesini tamamlar. Rest API'lerini kullanarak tüm dizin oluşturucular için ortak olan üç parçalı bir iş akışını gösterir: veri kaynağı oluşturma, dizin oluşturma, dizin oluşturucu oluşturma. Dizin Oluşturucu Oluştur isteğini gönderdiğinizde veri ayıklama gerçekleşir.

Terminoloji kafa karıştırıcı olabileceği için Azure Cosmos DB dizin oluşturma ve Azure AI Search dizin oluşturma işlemlerinin farklı işlemler olduğunu belirtmek gerekir. Azure AI Search'te dizin oluşturma, arama hizmetinizde bir arama dizini oluşturur ve yükler.

Önkoşullar

Veri kaynağını tanımlama

Veri kaynağı tanımı, verilerdeki değişiklikleri tanımlamak için dizine eklenecek verileri, kimlik bilgilerini ve ilkeleri belirtir. Veri kaynağı, birden çok dizin oluşturucu tarafından kullanılabilmesi için bağımsız bir kaynak olarak tanımlanır.

Bu çağrı için, Apache Gremlin için Azure Cosmos DB aracılığıyla bağlanan bir veri kaynağı oluşturmak için önizleme REST API sürümünü (2020-06-30-Preview veya 2021-04-30-Preview) belirtin.

  1. Tanımını ayarlamak için bir veri kaynağı oluşturun veya güncelleştirin:

     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. "type" değerini (gerekli) olarak "cosmosdb" ayarlayın.

  3. "Kimlik bilgilerini" bir bağlantı dizesi olarak ayarlayın. Sonraki bölümde desteklenen biçimler açıklanmaktadır.

  4. "kapsayıcı" öğesini koleksiyon olarak ayarlayın. "name" özelliği gereklidir ve grafiğin kimliğini belirtir.

    "query" özelliği isteğe bağlıdır. Apache Gremlin için Azure Cosmos DB için Azure AI Search dizin oluşturucusu varsayılan olarak grafiğinizdeki her köşeyi dizindeki bir belge haline getirir. Kenarlar yoksayılır. Sorgu varsayılanıdır g.V(). Alternatif olarak, sorguyu yalnızca kenarları dizine almak için ayarlayabilirsiniz. Kenarları dizine almak için sorguyu olarak g.E()ayarlayın.

  5. Veriler geçiciyse ve dizin oluşturucunun sonraki çalıştırmalarda yalnızca yeni ve güncelleştirilmiş öğeleri almasını istiyorsanız "dataChangeDetectionPolicy" değerini ayarlayın. Artımlı ilerleme, yüksek su işareti sütunu olarak kullanılarak _ts varsayılan olarak etkinleştirilir.

  6. Kaynak öğe silindiğinde arama belgelerini bir arama dizininden kaldırmak istiyorsanız "dataDeletionDetectionPolicy" değerini ayarlayın.

Desteklenen kimlik bilgileri ve bağlantı dizesi

Dizin oluşturucular aşağıdaki bağlantıları kullanarak bir koleksiyona bağlanabilir. Apache Gremlin için Azure Cosmos DB'yi hedefleyen bağlantılar için bağlantı dizesi "ApiKind" eklemeyi unutmayın.

Uç nokta URL'sinde bağlantı noktası numaralarından kaçının. Bağlantı noktası numarasını eklerseniz bağlantı başarısız olur.

Tam erişim bağlantı dizesi
{ "connectionString" : "AccountEndpoint=https://<Cosmos DB account name>.documents.azure.com;AccountKey=<Cosmos DB auth key>;Database=<Cosmos DB database id>;ApiKind=MongoDb" }
Sol gezinti bölmesinde Anahtarlar'ı seçerek Azure portalındaki Azure Cosmos DB hesap sayfasından bağlantı dizesi alabilirsiniz. Yalnızca bir anahtar değil tam bir bağlantı dizesi seçtiğinizden emin olun.
Yönetilen kimlik bağlantı dizesi
{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.DocumentDB/databaseAccounts/<your cosmos db account name>/;(ApiKind=[api-kind];)" }
Bu bağlantı dizesi bir hesap anahtarı gerektirmez, ancak daha önce bir arama hizmetini yönetilen kimlik kullanarak bağlanacak şekilde yapılandırmış ve Cosmos DB Hesap Okuyucusu Rolü izinleri veren bir rol ataması oluşturmuş olmanız gerekir. Daha fazla bilgi için bkz . Yönetilen kimlik kullanarak Azure Cosmos DB veritabanına dizin oluşturucu bağlantısı kurma.

Dizine arama alanları ekleme

Arama dizininde, kaynak JSON belgelerini veya özel sorgu projeksiyonunuzun çıkışını kabul etmek için alanlar ekleyin. Arama dizini şemasının grafiğinizle uyumlu olduğundan emin olun. Azure Cosmos DB'deki içerik için arama dizini şemanız veri kaynağınızdaki Azure Cosmos DB öğelerine karşılık gelir.

  1. Verileri depolayacak arama alanlarını tanımlamak için bir dizin oluşturun veya güncelleştirin:

     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. Belge anahtarı alanı oluşturma ("anahtar": true). Bölümlenmiş koleksiyonlar için varsayılan belge anahtarı Azure rid Cosmos DB _rid özelliğidir ve alan adları alt çizgi karakteriyle başlayamaz. Ayrıca Azure Cosmos DB _rid değerleri, Azure AI Arama anahtarlarında geçersiz karakterler içerir. Bu nedenle değerler _rid Base64 ile kodlanmıştır.

  3. Daha fazla aranabilir içerik için ek alanlar oluşturun. Ayrıntılar için bkz . Dizin oluşturma.

Eşleme veri türleri

JSON veri türü Azure AI Search alan türleri
Boole Edm.Boolean, Edm.String
Tamsayı gibi görünen sayılar Edm.Int32, Edm.Int64, Edm.String
Kayan noktalar gibi görünen sayılar Edm.Double, Edm.String
String Edm.String
["a", "b", "c"] gibi ilkel tür dizileri Collection(Edm.String)
Tarih gibi görünen dizeler Edm.DateTimeOffset, Edm.String
{ "type": "Point", "coordinates": [long, lat] } gibi GeoJSON nesneleri Edm.GeographyPoint
Diğer JSON nesneleri Yok

Azure Cosmos DB dizin oluşturucusunu yapılandırma ve çalıştırma

Dizin ve veri kaynağı oluşturulduktan sonra dizin oluşturucuyu oluşturmaya hazır olursunuz. Dizin oluşturucu yapılandırması, çalışma zamanı davranışlarını denetleen girişleri, parametreleri ve özellikleri belirtir.

  1. Dizin oluşturucuya bir ad verip veri kaynağına ve hedef dizine başvurarak dizin oluşturucu oluşturun veya güncelleştirin:

    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. Alan adında veya türünde farklılıklar varsa veya arama dizininde bir kaynak alanın birden çok sürümüne ihtiyacınız varsa alan eşlemelerini belirtin.

  3. Diğer özellikler hakkında daha fazla bilgi için bkz . Dizin oluşturucu oluşturma.

Dizin oluşturucu oluşturulduğunda otomatik olarak çalışır. "Devre dışı" ayarını true olarak ayarlayarak bunu önleyebilirsiniz. Dizin oluşturucu yürütmesini denetlemek için isteğe bağlı olarak bir dizin oluşturucu çalıştırın veya zamanlamaya yerleştirin.

Dizin oluşturucu durumunu denetleme

Dizin oluşturucu durumunu ve yürütme geçmişini izlemek için Dizin Oluşturucu Durumunu Al isteği gönderin:

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

Yanıt, durumu ve işlenen öğe sayısını içerir. Aşağıdaki örneğe benzer görünmelidir:

    {
        "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
        ]
    }

Yürütme geçmişi, en son tamamlanan yürütmelerin en son 50'sini içerir ve en son yürütme önce gelecek şekilde ters kronolojik sırada sıralanır.

Yeni ve değiştirilmiş belgelerin dizinini oluşturma

Dizin oluşturucu bir arama dizinini tam olarak doldurduktan sonra, sonraki dizin oluşturucu çalıştırmalarının veritabanınızdaki yalnızca yeni ve değiştirilmiş belgeleri artımlı olarak dizinlemesini isteyebilirsiniz.

Artımlı dizin oluşturmayı etkinleştirmek için veri kaynağı tanımınızda "dataChangeDetectionPolicy" özelliğini ayarlayın. Bu özellik, dizin oluşturucuya verilerinizde hangi değişiklik izleme mekanizmasının kullanıldığını bildirir.

Azure Cosmos DB dizin oluşturucuları için desteklenen tek ilke, Azure Cosmos DB tarafından sağlanan kullanım (zaman damgası) özelliğidir HighWaterMarkChangeDetectionPolicy_ts .

Aşağıdaki örnekte, değişiklik algılama ilkesine sahip bir veri kaynağı tanımı gösterilmektedir:

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

Silinen belgelerin dizinini oluşturma

Grafik verileri silindiğinde, ilgili belgeyi arama dizininden de silmek isteyebilirsiniz. Veri silme algılama ilkesinin amacı, silinen veri öğelerini verimli bir şekilde tanımlamak ve belgenin tamamını dizinden silmektir. Veri silme algılama ilkesi, kısmi belge bilgilerini silmek için tasarlanmamıştır. Şu anda desteklenen tek ilke Soft Delete , veri kaynağı tanımında aşağıdaki gibi belirtilen ilkedir (silme işlemi bir tür bayrakla işaretlenir):

"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"
}

Aşağıdaki örnek geçici silme ilkesine sahip bir veri kaynağı oluşturur:

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"
    }
}

Silme algılama ilkesini etkinleştirseniz bile, karmaşık (Edm.ComplexType) alanların dizinden silinmesi desteklenmez. Bu ilke, Gremlin veritabanındaki 'etkin' sütunun tamsayı, dize veya boole türünde olmasını gerektirir.

Grafik verilerini arama dizinindeki alanlarla eşleme

Apache Gremlin için Azure Cosmos DB dizin oluşturucu, birkaç grafik verisini otomatik olarak eşler:

  1. Dizin oluşturucu, varsa dizindeki bir rid alanla eşlenir _rid ve Base64 bunu kodlar.

  2. Dizin oluşturucu, varsa dizindeki bir id alanla eşlenir_id.

  3. Apache Gremlin için Azure Cosmos DB kullanarak Azure Cosmos DB veritabanınızı sorgularken, her özellik için JSON çıkışının bir id ve valueolduğunu fark edebilirsiniz. Dizin oluşturucu, özellikleri value arama dizininizde varsa özelliğiyle aynı ada sahip bir alana otomatik olarak eşler. Aşağıdaki örnekte 450, arama dizinindeki bir pages alana eşlenir.

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

Sorgu çıkışınızı dizininizdeki alanlarla eşlemek için Çıkış Alanı Eşlemeleri'ni kullanmanız gerektiğini fark edebilirsiniz. Özel sorguda büyük olasılıkla karmaşık veriler olacağından Alan Eşlemeleri yerine Çıkış Alanı Eşlemeleri'ni kullanmak istersiniz.

Örneğin, sorgunuzun şu çıkışı ürettiğini düşünelim:

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

Yukarıdaki JSON değerini dizininizdeki bir alanla eşlemek pages isterseniz, dizin oluşturucu tanımınıza aşağıdaki Çıkış Alanı Eşlemesi'ni ekleyebilirsiniz:totalpages

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

Çıkış Alanı Eşlemesi'nin ile başladığına /document ve JSON'daki özellikler anahtarına başvuru içermediğini fark edin. Bunun nedeni, dizin oluşturucunun grafik verilerini alırken her belgeyi düğümün /document altına yerleştirdiği ve dizin oluşturucunun da dizinindeki ilk nesneye başvurmak yerine basit başvuru yaparak pages değerine pages otomatik olarak başvurmanıza olanak sağlamasıdırpages.

Sonraki adımlar