Indexación de datos de Azure Cosmos DB para Apache Gremlin para consultas en Búsqueda de Azure AI (versión preliminar)

El Azure Cosmos DB para el indexador de Apache Gremlin (versión preliminar) importa contenido de Azure Cosmos DB para Apache Gremlin y hace que se pueda buscar en Búsqueda de Azure AI.

En este artículo se complementa la creación de un indexador 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 al enviar la solicitud Crear indexador.

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

Requisitos previos

• Complete el formulario de registro de vista previa del indexador. El registro se aprueba automáticamente.

• Una cuenta Azure Cosmos DB, base de datos, contenedor y elementos. Use la misma región para Búsqueda de Azure AI y Azure Cosmos DB para reducir la latencia y para evitar cargos de ancho de banda.

• Directiva de indexación automática en la colección Azure Cosmos DB, establecida en Consistente. Esta configuración es la configuración predeterminada. No se recomienda la indexación diferida y podría provocar la ausencia de datos.

• Permisos de lectura. Una cadena de conexión de "acceso completo" incluye una clave que concede acceso al contenido, pero si usa roles de Azure, asegúrese de que la identidad administrada del servicio de búsqueda disponga de permisos de rol de lector de cuentas de Cosmos DB.

• Un cliente REST para crear el origen de datos, el índice y el indexador.

Definición del origen de datos

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

Para esta llamada, especifique una versión preliminar de la API REST para crear un origen de datos que se conecte a través de Azure Cosmos DB para Apache Gremlin. Puede usar la versión 2021-04-01-preview o una posterior. Se recomienda la API REST de versión preliminar más reciente.

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

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

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

4. Establezca "contenedor" en la colección. Se requiere la propiedad "name" y especifica el identificador del grafo.

   La propiedad "query" es opcional. De forma predeterminada, el indizador de Búsqueda de Azure AI para Azure Cosmos DB para Apache Gremlin convierte cada vértice en el gráfico en un documento del índice. Los bordes se omiten. El valor predeterminado de la consulta es g.V(). Como alternativa, puede configurar la consulta para indexar solo las aristas. Para indexar los bordes, configure la consulta en g.E().

5. Establezca "dataChangeDetectionPolicy" si los datos son volátiles y desea que el indexador recoja solo los elementos nuevos y actualizados en ejecuciones posteriores. El progreso incremental está habilitado de forma predeterminada utilizando _ts como columna de marca de nivel máximo.

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

Credenciales admitidas y cadenas de conexión

Los indexadores pueden conectarse a una colección mediante las siguientes conexiones. Para las conexiones que tienen como destino Azure Cosmos DB para Apache Gremlin, asegúrese de incluir "ApiKind" en el 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 produce un error en la conexió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 de índice de búsqueda sea compatible con el grafo. Para el contenido de Azure Cosmos DB, el esquema de índice de búsqueda debe corresponder a los elementos Azure Cosmos DB en el origen de datos.

1. Crear o actualizar un índice para definir campos de búsqueda que almacenan datos:

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

3. Cree campos adicionales para obtener contenido más buscable. Consulte Creación de un índice para obtener más información.

Mapeo de tipos de datos

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

Una vez creado el índice y el origen de datos, está listo para crear el indexador. La configuración del indexador especifica las entradas, los parámetros y las propiedades que controlan los comportamientos de tiempo de ejecución.

1. Cree o actualice un indexador ; para ello, asígnele un nombre y haga referencia al origen de datos y al índice de destino:

   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. Especifique las 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 obtener más información sobre otras propiedades.

Un indexador se ejecuta automáticamente cuando se crea. Para evitarlo, establezca "disabled" en true. Para controlar la ejecución del indexador, ejecute un indexador a petición o colóquelo según una programación.

Comprobación del estado del indexador

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

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

La respuesta incluye el estado y el número de elementos procesados. Debería ser similar al ejemplo siguiente:

    {
        "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 hasta 50 de las ejecuciones completadas más recientemente, que se ordenan en el orden cronológico inverso para que la ejecución más reciente llegue primero.

Indexación de documentos nuevos y modificados

Una vez que un indexador haya rellenado completamente un índice de búsqueda, es posible que desee que el indexador posterior se ejecute para indexar 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.

Para los indexadores de Azure Cosmos DB, la única directiva admitida es la HighWaterMarkChangeDetectionPolicy mediante la propiedad _ts (marca de tiempo) proporcionada por 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 eliminan los datos del grafo, es posible que también desee eliminar 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á pensada para eliminar información parcial del documento. Actualmente, la única directiva admitida es la directiva Soft Delete (la eliminación se indica con algún tipo de marca), que se especifica en la definición del origen de datos de la siguiente manera:

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

Incluso si habilita 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 para Apache Gremlin asigna automáticamente algunos datos de grafos:

1. El indexador asigna _rid a un campo rid del índice, si existe, y lo codifica en Base64.

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

3. Al consultar la base de datos de Azure Cosmos DB mediante Azure Cosmos DB para Apache Gremlin, es posible que observe que la salida JSON de cada propiedad tiene un id y un value. El indexador asigna automáticamente el value de la propiedad a un campo de tu índice de búsqueda que tenga el mismo nombre que la propiedad, si existe. En el ejemplo siguiente, 450 se asigna a un pages campo del índice de búsqueda.

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

Es posible que tenga que usar Output Field Mappings para asignar el resultado de la consulta a los campos de su índice. Probablemente le convenga utilizar Asignaciones de campos de salida en lugar de Asignaciones de campos, ya que es probable que la consulta personalizada contenga 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 desea asignar el valor de pages en el JSON anterior a un campo de totalpages del índice, puede agregar la siguiente Asignación de Campo de Salida a la definición del indexador.

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

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

Pasos siguientes

• Para más información sobre Azure Cosmos DB para Apache Gremlin, consulte la Introducción a Azure Cosmos DB: Azure Cosmos DB para Apache Gremlin.

• Para obtener más información sobre Búsqueda de Azure AI escenarios y precios, consulte la página del servicio Search en azure.microsoft.com.

• Para obtener información sobre la configuración de red de los indexadores, consulte el acceso de Indexer al contenido protegido por las características de seguridad de red de Azure.