Indexación de datos desde Azure Cosmos DB for Apache Gremlin para consultas en Azure AI Search

  • Artículo

Importante

El indexador de Azure Cosmos DB for Apache Gremlin se encuentra actualmente en versión preliminar pública en los Términos de uso complementarios. Actualmente, no hay compatibilidad con el SDK.

En este artículo se enseña a configurar un indexador que importa contenido desde Azure Cosmos DB for Apache Gremlin y hace que se pueda buscar en Azure AI Search.

Este artículo complementa al artículo Creación de indexadores con información específica de Cosmos DB. Usa las API REST para mostrar un flujo de trabajo de tres partes común a todos los indexadores: crear un origen de datos, crear un índice y crear un indexador. La extracción de datos se produce cuando se envía la solicitud para crear un indexador.

Dado que la terminología puede ser confusa, merece la pena tener en cuenta que la indexación de Azure Cosmos DB y la indexación de Azure AI Search son operaciones diferentes. La indexación en Azure AI Search crea y carga un índice de búsqueda en el servicio de búsqueda.

Requisitos previos

Definición del origen de datos

La definición del origen de datos especifica los datos que se indexan, las credenciales y las directivas para identificar los cambios en los datos. Un origen de datos se define como un recurso independiente de forma que puedan usarlo varios indexadores.

Para esta llamada, especifica una versión preliminar de la API de REST (2020-06-30-Preview o 2021-04-30-Preview) para crear un origen de datos que se conecte mediante Azure Cosmos DB for Apache Gremlin.

  1. Cree o actualice un origen de datos para establecer su definición:

     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. Establezca "type" en "cosmosdb" (obligatorio).

  3. Establezca "credentials" en una cadena de conexión. En la sección siguiente se describen los formatos admitidos.

  4. Establezca "container" en la colección. La propiedad "name" es obligatoria y especifica el identificador del gráfico.

    La propiedad "query" es opcional. De forma predeterminada, el indexador de Azure AI Search para Azure Cosmos DB for Apache Gremlin hace que cada vértice del grafo sea un documento en el índice. Los bordes se omitirán. El valor predeterminado de la consulta es g.V(). Como alternativa, puede establecer la consulta para indexar solo los bordes. Para indexar los bordes, establezca la consulta en g.E().

  5. Establezca "dataChangeDetectionPolicy" si los datos son volátiles y desea que el indexador seleccione solo los elementos nuevos y actualizados en ejecuciones posteriores. El progreso incremental se habilitará de forma predeterminada usando _ts como columna de límite superior.

  6. Establezca "dataDeletionDetectionPolicy" si desea quitar documentos de búsqueda de un índice de búsqueda cuando se elimine el elemento de origen.

Credenciales y cadenas de conexión admitidas

Los indexadores pueden conectarse a una colección mediante las siguientes conexiones. Para las conexiones que tienen Azure Cosmos DB for Apache Gremlin como destino, asegúrese de incluir "ApiKind" en la cadena de conexión.

Evite los números de puerto en la dirección URL del punto de conexión. Si incluye el número de puerto, se producirá un error en la conexión.

Cadena de conexión de acceso completo
{ "connectionString" : "AccountEndpoint=https://<Cosmos DB account name>.documents.azure.com;AccountKey=<Cosmos DB auth key>;Database=<Cosmos DB database id>;ApiKind=MongoDb" }
Para obtener la cadena de conexión de la página de la cuenta de Azure Cosmos DB en Azure Portal, seleccione Claves en el panel de navegación izquierdo. Asegúrese de seleccionar una cadena de conexión completa y no solo una clave.
Cadena de conexión de identidad administrada
{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.DocumentDB/databaseAccounts/<your cosmos db account name>/;(ApiKind=[api-kind];)" }
Esta cadena de conexión no requiere una clave de cuenta, pero debe haber configurado previamente un servicio de búsqueda para conectarse mediante una identidad administrada y haber creado una asignación de roles que conceda permisos de rol de lector de la cuenta de Cosmos DB. Consulte Configuración de una conexión de indexador a una base de datos de Azure Cosmos DB mediante una identidad administrada para más información.

Adición de campos de búsqueda a un índice

En un índice de búsqueda, agregue campos para aceptar los documentos JSON de origen o la salida de la proyección de consulta personalizada. Asegúrese de que el esquema del índice de búsqueda es compatible con el gráfico. En el caso del contenido de Azure Cosmos DB, el esquema del índice de búsqueda se debe corresponder con los elementos de Azure Cosmos DB del origen de datos.

  1. Cree o actualice un índice para definir campos de búsqueda que almacenarán los datos:

     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. Cree un campo de clave de documento ("key": true). En el caso de las colecciones con particiones, la clave de documento predeterminada es la propiedad _rid de Azure Cosmos DB, a la que Azure AI Search cambia el nombre automáticamente a rid, porque los nombres de los campos no pueden comenzar por un carácter de guion bajo. Además, los valores _rid de Azure Cosmos DB contienen caracteres que no son válidos en las claves de Azure AI Search. Por este motivo, la _rid valores están codificados con Base64.

  3. Cree campos adicionales para obtener más contenido que se puede buscar. Consulte Creación de un índice en Azure Cognitive Search para más información.

Asignación de tipos de datos

Tipo de datos JSON Tipos de campos de Azure AI Search
Booleano Edm.Boolean, Edm.String
Números que parecen enteros Edm.Int32, Edm.Int64, Edm.String
Números que parecen puntos flotantes Edm.Double, Edm.String
String Edm.String
Matrices de tipos primitivos, como ["a", "b", "c"] Collection(Edm.String)
Cadenas que parecen fechas Edm.DateTimeOffset, Edm.String
Objetos GeoJSON, como { "type": "Point", "coordinates": [long, lat] } Edm.GeographyPoint
Otros objetos JSON N/D

Configuración y ejecución del indexador de Azure Cosmos DB

Una vez creados el índice y el origen de datos, ya podrá crear el indexador. La configuración del indexador especifica las entradas, los parámetros y las propiedades que controlan los comportamientos en tiempo de ejecución.

  1. Cree o actualice un indexador asignándole un nombre y haciendo referencia al origen de datos y al índice de destino:

    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. Especifique asignaciones de campos si hay diferencias en el nombre o el tipo de campo, o si necesita varias versiones de un campo de origen en el índice de búsqueda.

  3. Consulte Creación de un indexador para más información sobre otras propiedades.

Un indexador se ejecuta automáticamente cuando se crea. Puede evitarlo estableciendo el valor de "disabled" en true. Para controlar la ejecución del indexador, ejecute un indexador a petición o prográmelo.

Comprobación del estado del indexador

Para supervisar el estado del indexador y el historial de ejecución, envíe una solicitud para Obtener el estado del indexador:

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

La respuesta incluye el estado y el número de elementos procesados. Debe tener un aspecto similar al siguiente ejemplo:

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

El historial de ejecución contiene como máximo las 50 ejecuciones completadas más recientemente en orden cronológico inverso (la ejecución más reciente aparece en primer lugar).

Indexación de documentos nuevos y modificados

Una vez que un indexador ha rellenado por completo un índice de búsqueda, es posible que quiera que las ejecuciones posteriores del indexador indexen incrementalmente solo los documentos nuevos y modificados de la base de datos.

Para habilitar la indexación incremental, establezca la propiedad "dataChangeDetectionPolicy" en la definición del origen de datos. Esta propiedad indica al indexador qué mecanismo de seguimiento de cambios se usa en los datos.

En el caso de los indexadores de Azure Cosmos DB, la única directiva compatible es HighWaterMarkChangeDetectionPolicy con la propiedad _ts (marca de tiempo) que proporciona Azure Cosmos DB.

En el ejemplo siguiente se muestra una definición de origen de datos con una directiva de detección de cambios:

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

Indexación de documentos eliminados

Cuando se eliminen los datos del grafo, es posible que quiera eliminar también su documento correspondiente del índice de búsqueda. El propósito de una directiva de detección de eliminación de datos es identificar eficazmente los elementos de datos eliminados y eliminar el documento completo del índice. La directiva de detección de eliminación de datos no está diseñada para eliminar información parcial del documento. Actualmente, solo se admite la directiva Soft Delete (la eliminación se indica con algún tipo de marca), especificada de la siguiente forma en el origen de datos:

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

En el ejemplo siguiente se crea un origen de datos con una directiva de eliminación temporal:

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

Aunque habilite la directiva de detección de eliminación, no se admite la eliminación de campos complejos (Edm.ComplexType) del índice. Esta directiva requiere que la columna "activa" de la base de datos de Gremlin sea de tipo entero, cadena o booleano.

Asignación de datos de grafos a campos de un índice de búsqueda

El indexador de Azure Cosmos DB for Apache Gremlin asignará automáticamente un par de fragmentos de datos del grafo:

  1. El indexador asignará _rid a un campo rid del índice si existe y Base64 lo codificará.

  2. El indexador asignará _id a un campo id del índice si existe.

  3. Al consultar la base de datos de Azure Cosmos DB mediante Azure Cosmos DB for Apache Gremlin, es posible que observe que la salida JSON de cada propiedad tiene un campo id y un campo value. El indizador asignará automáticamente las propiedades value al campo del índice de búsqueda que tenga el mismo nombre que la propiedad, en caso de que exista. En el ejemplo siguiente, 450 se asignaría a un campo pages del índice de búsqueda.

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

Es posible que necesite usar asignaciones de campos de salida para asignar la salida de la consulta a los campos del índice. Es probable que quiera usar asignaciones de campos de salida en lugar de asignaciones de campos, ya que es existe la posibilidad de que la consulta personalizada tenga datos complejos.

Por ejemplo, supongamos que la consulta genera esta salida:

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

Si quiere asignar el valor de pages del archivo JSON anterior a un campo totalpages del índice, puede agregar la siguiente asignación de campos de salida a la definición del indexador:

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

Observe que la asignación de campos de salida comienza con /document y no incluye una referencia a la clave de propiedades en el archivo JSON. Esto se debe a que el indexador coloca cada documento en el nodo /document al ingerir los datos del grafo y también le permite hacer referencia automáticamente al valor de pages con una referencia simple a pages en lugar de tener que hacer referencia al primer objeto de la matriz de pages.

Pasos siguientes