Az Apache Gremlin Azure Cosmos DB adatainak indexelése a Azure AI Keresés lekérdezéseihez (előzetes verzió)

Az Azure Cosmos DB for Apache Gremlin indexelője (előzetes verzió) importálja az Azure Cosmos DB for Apache Gremlin tartalmát, és kereshetővé teszi azt az Azure AI Keresésben.

Ez a cikk kiegészíti a Cosmos DB-hez kapcsolódó információkat tartalmazó indexelő létrehozását . A REST API-k segítségével egy háromrészes munkafolyamatot mutat be, amely az összes indexelőre jellemző: adatforrás létrehozása, index létrehozása, indexelő létrehozása. Az adatkinyerés az Indexelő létrehozása kérés elküldésekor történik.

Mivel a terminológia zavaró lehet, érdemes megjegyezni, hogy Azure Cosmos DB indexelés és Azure AI Keresés indexelés különböző műveletek. Az Azure AI Keresés-ben való indexelés létrehoz és betölt egy keresési indexet a keresési szolgáltatásra.

Előfeltételek

• Töltse ki az indexelő előzetes regisztrációs űrlapot. A regisztráció automatikusan jóváhagyásra kerül.

• Egy Azure Cosmos DB fiók, adatbázis, tároló és elem. Használja ugyanazt a régiót Azure AI Keresés és Azure Cosmos DB is az alacsonyabb késés és a sávszélesség-díjak elkerülése érdekében.

• Egy automatikus indexelési szabályzat a Azure Cosmos DB gyűjteményben, Konzisztens értékre állítva. Ez a beállítás az alapértelmezett konfiguráció. A lusta indexelés nem ajánlott, és előfordulhat, hogy hiányoznak az adatok.

• Olvasási engedélyek. A teljes hozzáférést biztosító kapcsolati karakterlánc tartalmazza azt a kulcsot, amely hozzáférést biztosít a tartalomhoz, de ha Azure szerepköröket használ, győződjön meg arról, hogy a search szolgáltatás felügyelt identitása rendelkezik a szükséges engedélyekkel a Cosmos DB fiókolvasó szerepkörhöz.

• EGY REST-ügyfél, amely létrehozza az adatforrást, az indexet és az indexelőt.

Az adatforrás meghatározása

Az adatforrás definíciója meghatározza az indexelendő adatokat, valamint a hitelesítő adatokat és a szabályzatokat az adatok változásainak azonosításához. Egy adatforrás független erőforrásként van definiálva, így több indexelő is használhatja.

Ehhez a híváshoz adjon meg egy előzetes REST API-verziót, amely létrehoz egy adatforrást, amely az Apache Gremlin Azure Cosmos DB keresztül csatlakozik. Használhatja 2021-04-01-preview vagy később is használhatja. Javasoljuk, hogy a legújabb előzetes VERZIÓJÚ REST API-t használja.

1. Adatforrás létrehozása vagy frissítése a definíció beállításához:

    POST https://[service name].search.windows.net/datasources?api-version=2026-08-01-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. Állítsa be a "cosmosdb" "type" (típus) értéket (kötelező).

3. Állítsa be a "hitelesítő adatokat" egy kapcsolati karakterlánc beállításával. A következő szakasz a támogatott formátumokat ismerteti.

4. Adja hozzá a "tárolót" a gyűjteményhez. A "name" tulajdonság megadása kötelező, és megadja a gráf azonosítóját.

   A "lekérdezés" tulajdonság megadása nem kötelező. Alapértelmezés szerint az Apache Gremlinhez készült Azure Cosmos DB Azure AI Keresés indexelője a gráf minden csúcsát az index dokumentumává teszi. A rendszer figyelmen kívül hagyja az éleket. A lekérdezés alapértelmezett értéke .g.V() Másik lehetőségként beállíthatja, hogy a lekérdezés csak a széleket indexelje. Az élek indexeléséhez állítsa a lekérdezést a következőre g.E(): .

5. Állítsa be a "dataChangeDetectionPolicy" értéket , ha az adatok változékonyak, és azt szeretné, hogy az indexelő csak az új és frissített elemeket vegye fel a későbbi futtatások során. A növekményes feldolgozás alapértelmezés szerint engedélyezve van, és a(z) _ts van használatban high water mark oszlopként.

6. Állítsa be a "dataDeletionDetectionPolicy" értéket , ha el szeretné távolítani a keresési dokumentumokat a keresési indexből a forráselem törlésekor.

Támogatott hitelesítő adatok és kapcsolati karakterláncok

Az indexelők az alábbi kapcsolatokkal csatlakozhatnak egy gyűjteményhez. Az Azure Cosmos DB for Apache Gremlin-t célzó kapcsolatok esetében ügyeljen arra, hogy az "ApiKind" szerepeljen a kapcsolati karakterláncban.

Kerülje a portszámokat a végpont URL-címében. Ha a portszámot is tartalmazza, a kapcsolat meghiúsul.

Keresési mezők hozzáadása indexhez

A keresési indexben adjon hozzá mezőket a forrás JSON-dokumentumok vagy az egyéni lekérdezésvetítés kimenetének elfogadásához. Győződjön meg arról, hogy a keresési index sémája kompatibilis a gráfjával. A Azure Cosmos DB tartalmai esetében a keresési index sémájának meg kell felelnie az adatforrás Azure Cosmos DB elemeinek.

1. Hozzon létre vagy frissítsen egy indexet az adatokat tároló keresési mezők definiálásához:

    POST https://[service name].search.windows.net/indexes?api-version=2026-08-01-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. Hozzon létre egy dokumentumkulcsmezőt ("key": true). Particionált gyűjtemények esetén az alapértelmezett dokumentumkulcs az Azure Cosmos DB _rid tulajdonság, amelyet az Azure AI Keresés automatikusan átnevez rid-re, mert a mezőnevek nem kezdődhetnek aláhúzásjellel. A Azure Cosmos DB _rid értékek Azure AI Keresés kulcsokban érvénytelen karaktereket is tartalmaznak. Ezért az _rid értékek Base64 kódolásúak.

3. További mezők létrehozása több kereshető tartalomhoz. Részletekért lásd : Index létrehozása .

Adattípusok leképezése

A Azure Cosmos DB indexelő konfigurálása és futtatása

Az index és az adatforrás létrehozása után készen áll az indexelő létrehozására. Az indexelő konfigurációja meghatározza a futási idő viselkedését vezérlő bemeneteket, paramétereket és tulajdonságokat.

1. Hozzon létre vagy frissítsen egy indexelőt úgy, hogy megad neki egy nevet, és hivatkozik az adatforrásra és a célindexre:

   POST https://[service name].search.windows.net/indexers?api-version=2026-08-01-preview
   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. Mezőleképezéseket adhat meg , ha a mezőnév vagy a típus eltérést mutat, vagy ha egy forrásmező több verziójára van szüksége a keresési indexben.

3. További információt az egyéb tulajdonságokról az Indexelő létrehozása című témakörben talál.

Az indexelő automatikusan fut a létrehozásakor. Ezt úgy akadályozhatja meg, hogy a "letiltva" értéket igaz értékre állítja. Az indexelő futtatásának szabályozása érdekében futtasson egy indexelőt folyamatosan, vagy ütemezze azt.

Indexelő állapotának ellenőrzése

Az indexelőzmények állapotának és végrehajtási előzményeinek figyeléséhez küldjön egy indexelőzmény-lekéréses kérést :

GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2026-08-01-preview
  Content-Type: application/json  
  api-key: [admin key]

A válasz tartalmazza az állapotot és a feldolgozott elemek számát. A következő példához hasonlóan kell kinéznie:

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

A végrehajtási előzmények legfeljebb 50 legutóbbi végrehajtást tartalmaznak, amelyek fordított időrendi sorrendben vannak rendezve, hogy a legújabb végrehajtás legyen az első.

Új és módosított dokumentumok indexelése

Miután egy indexelő kitöltött egy keresési indexet, érdemes lehet, hogy a későbbi indexelők növekményesen indexeljenek csak az adatbázis új és módosított dokumentumait.

A növekményes indexelés engedélyezéséhez állítsa be a "dataChangeDetectionPolicy" tulajdonságot az adatforrás definíciójában. Ez a tulajdonság tájékoztatja az indexelőt, hogy melyik változáskövetési mechanizmust használja az adatokon.

Az Azure Cosmos DB indexelők esetében az egyetlen támogatott szabályzat az Azure Cosmos DB által biztosított HighWaterMarkChangeDetectionPolicy (időbélyeg) tulajdonság használata.

Az alábbi példa egy változásészlelési szabályzattal rendelkező adatforrásdefiníciót mutat be:

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

Törölt dokumentumok indexelése

A gráfadatok törlésekor érdemes lehet törölni a megfelelő dokumentumot a keresési indexből is. Az adattörlési észlelési szabályzat célja a törölt adatelemek hatékony azonosítása és a teljes dokumentum törlése az indexből. Az adattörlési észlelési szabályzat nem a részleges dokumentuminformációk törlését jelenti. Jelenleg az egyetlen támogatott szabályzat a Soft Delete szabályzat (a törlés valamilyen jelölővel van megjelölve), amely az adatforrás definíciójában az alábbiak szerint van megadva:

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

Az alábbi példa egy helyreállítható törlési szabályzattal rendelkező adatforrást hoz létre:

POST https://[service name].search.windows.net/datasources?api-version=2026-08-01-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"
    }
}

Még ha engedélyezi is a törlésészlelési szabályzatot, az összetett (Edm.ComplexType) mezők törlése az indexből nem támogatott. Ez a szabályzat megköveteli, hogy a Gremlin-adatbázis "aktív" oszlopa egész szám, sztring vagy logikai típusú legyen.

Gráfadatok leképezése keresési index mezőihez

Az Apache Gremlinhez készült Azure Cosmos DB-indexelő automatikusan leképezi a gráfadatok közül néhányat:

1. Az indexelő a(z) _rid elemet az index egy rid mezőjére képezi le, ha létezik, majd Base64-kódolással kódolja.

2. Az indexelő a _id elemet az index egy id mezőjére képezi le, ha az létezik.

3. Amikor a Azure Cosmos DB-adatbázist az Apache Gremlin Azure Cosmos DB használatával kérdezi le, észreveheti, hogy az egyes tulajdonságok JSON-kimenete rendelkezik egy id és egy value. Az indexelő automatikusan leképozza a tulajdonságot value a keresési index egy olyan mezőjébe, amelynek neve megegyezik a tulajdonság nevével, ha létezik. Az alábbi példában a 450 a keresési index egy pages mezőjére van leképezve.

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

Előfordulhat, hogy a lekérdezés kimenetének az index mezőivel való összerendeléséhez a kimeneti mezőleképezéseket kell használnia. Valószínűleg a kimeneti mezőleképezéseket szeretné használni mezőleképezések helyett, mivel az egyéni lekérdezés valószínűleg összetett adatokkal rendelkezik.

Tegyük fel például, hogy a lekérdezés a következő kimenetet hozza létre:

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

Ha le szeretné képezni a fenti JSON értékét pages az index egy totalpages mezőjére, a következő kimeneti mezőleképezést veheti fel az indexelő definíciójához:

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

Figyelje meg, hogyan kezdődik /document a kimeneti mezőleképezés, és nem tartalmaz hivatkozást a JSON tulajdonságkulcsára. Ennek az az oka, hogy az indexelő minden dokumentumot a /document csomópont alá helyez a gráfadatok betöltésekor, és az indexelő automatikusan lehetővé teszi, hogy egyszerű hivatkozással pages hivatkozzon az értékre pages ahelyett, hogy a tömb első objektumára pageskellene hivatkoznia.

Következő lépések

• Az Apache Gremlinhez készült Azure Cosmos DB-ről további információkhoz lásd: Bevezetés az Azure Cosmos DB-be: Azure Cosmos DB az Apache Gremlinhez.

• A Azure AI Keresés forgatókönyvekről és díjszabásról a azure.microsoft.com Search szolgáltatás oldalán talál további információt>.

• Ha többet szeretne megtudni az indexelők hálózat konfigurációjáról, lásd a Indexer hozzáférése Azure hálózati biztonsági funkciókkal védett tartalmakhoz.