Compartir vía

Indexación de datos de Azure Cosmos DB for NoSQL para consultas en Búsqueda de Azure AI

  • Artículo

En este artículo se enseñará a configurar un indexador que importa contenido de Azure Cosmos DB for NoSQL 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 Azure Portal y las API de REST para demostrar 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

Para trabajar con los ejemplos de este artículo, necesita Azure Portal o un Cliente REST. Si usa Azure Portal, asegúrese de que el acceso a todas las redes públicas está habilitado. Otros enfoques para crear un indexador de Cosmos DB incluyen SDK de Azure.

Pruebe con datos de ejemplo

Use estas instrucciones para crear un contenedor y una base de datos en Cosmos DB con fines de prueba.

  1. Descargue HotelsData_toCosmosDB.JSON de GitHub para crear un contenedor en Cosmos DB que contenga un subconjunto del conjunto de datos de hoteles de ejemplo.

  2. Inicie sesión en Azure Portal y cree una cuenta, una base de datos y un contenedor en Cosmos DB.

  3. En Cosmos DB, seleccione Explorador de datos para el nuevo contenedor y proporcione los siguientes valores.

    Propiedad Valor
    Base de datos Crear nuevo
    Identificador de base de datos hotelsdb
    Uso compartido del rendimiento entre contenedores No seleccionar
    ID de contenedor hoteles
    Clave de partición /HotelId
    Rendimiento del contenedor (escalado automático) Escalado automático
    Número máximo de RU/s de contenedor 1 000

  4. En Explorador de datos, expanda hotelsdb y *hotels" y seleccione Elementos.

  5. Seleccione Cargar elemento y, a continuación, seleccione el archivo HotelsData_toCosmosDB.JSON que descargó de GitHub.

  6. Haga clic con el botón derecho en Elementos y seleccione Nueva consulta SQL. La consulta predeterminada es SELECT * FROM c.

  7. Seleccione Ejecutar consulta para ejecutar la consulta y ver los resultados. Debería tener 50 documentos del hotel.

Ahora que tiene un contenedor, puede usar Azure Portal, un cliente REST o un SDK de Azure para indexar los datos.

El campo Descripción proporciona el contenido más detallado. Debe dirigirse a este campo para la búsqueda de texto completo y las consultas vectoriales opcionales.

Uso de Azure Portal

Puede usar el Asistente de Importación de datos o el Asistente de Importación y vectorización de datos para automatizar la indexación desde una tabla o vista de base de datos SQL. La configuración del origen de datos es similar para ambos asistentes.

  1. Inicie el asistente.

  2. En Conectarse a los datos, seleccione o compruebe que el tipo de origen de datos sea Azure Cosmos DB o una cuenta NoSQL.

    El nombre del origen de datos hace referencia al objeto de conexión del origen de datos en Búsqueda de Azure AI. Si usa el asistente para vectores, el nombre del origen de datos se genera automáticamente mediante un prefijo personalizado especificado al final del flujo de trabajo del asistente.

  3. Especifique el nombre y la colección de la base de datos. La consulta es opcional. Resulta útil si tiene datos jerárquicos y desea importar un segmento específico.

  4. Especifique un método de autenticación, ya sea una identidad administrada o una clave de API integrada. Si no especifica una conexión de identidad administrada, Azure Portal usa la clave.

    Si configura Búsqueda de Azure AI para que use una identidad administrada y crea una asignación de roles en Cosmos DB que conceda permisos de lector de cuentas de Cosmos DB y lector de datos integrados de Cosmos DB a la identidad, el indexador puede conectarse a Cosmos DB mediante Microsoft Entra ID y roles.

  5. Para el asistente de importación y vectorización de datos, puede especificar opciones para el seguimiento de cambios y eliminaciones.

    La detección de cambios se admite de forma predeterminada a través de un campo _ts (marca de tiempo). Si carga contenido mediante el enfoque descrito en Probar con datos de ejemplo, la colección se crea con un campo _ts.

    La detección de eliminación requiere que tenga un campo de nivel superior preexistente en la colección que se pueda usar como una marca de eliminación temporal. Debe ser un campo booleano (podría asignarle el nombre IsDeleted). Especifique true como valor de eliminación temporal. En el índice de búsqueda, agregue un campo de búsqueda correspondiente denominado IsDeleted establecido en recuperable y filtrable.

  6. Continúe con los pasos restantes para completar el asistente:

Usar las API REST

En esta sección se muestran las llamadas a la API de REST que crean un origen de datos, un índice y un indexador.

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 es un recurso independiente que varios indexadores pueden usar.

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

    POST https://[service name].search.windows.net/datasources?api-version=2024-07-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. Establezca "type" en "cosmosdb" (obligatorio). Si usa una versión de la API de búsqueda anterior a la 2017-11-11, la sintaxis del elemento "type" es "documentdb". De lo contrario, para la versión 2019-05-06 y versiones posteriores, use "cosmosdb".

  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 necesaria y especifica el identificador de la colección de base de datos que se va a indexar. La propiedad "query" es opcional. Utilízala para aplanar un documento JSON arbitrario en un esquema plano que Azure AI Search pueda indexar.

  5. Establezca "dataChangeDetectionPolicy" si los datos son volátiles y desea que el indexador seleccione solo los elementos nuevos y actualizados en ejecuciones posteriores.

  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.

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.

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>" }`
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];)/(IdentityAuthType=[identity-auth-type])" }
Esta cadena de conexión no requiere una clave de cuenta, pero debe tener un servicio de búsqueda que pueda conectarse mediante una identidad administrada. En el caso de las conexiones destinadas a la API de SQL, puede omitir ApiKind de la cadena de conexión. Para obtener más información sobre ApiKind, IdentityAuthType consulta Configurar una conexión de indexador a una base de datos de Azure Cosmos DB mediante una identidad administrada.

Uso de consultas para dar forma a los datos indizados

En la propiedad "query" del elemento "container", puede especificar una consulta SQL para aplanar las propiedades o matrices anidadas y de las propiedades JSON del proyecto, y para filtrar los datos que se van a indexar.

Documento de ejemplo:

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

Consulta de filtro:

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

Consulta sin formato:

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

Consulta de proyección:

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

Consulta sin formato de matriz:

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

Consultas no admitidas (DISTINCT y GROUP BY)

No se admiten las consultas en las que se usan la palabra clave DISTINCT o la cláusula GROUP BY. Azure AI Search se basa en la paginación de consultas SQL para enumerar la totalidad de los resultados de la consulta. Ni la palabra clave DISTINCT ni las cláusulas GROUP BY son compatibles con los tokens de continuación que se usan para paginar los resultados.

Ejemplos de consultas no admitidas:

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

Aunque Azure Cosmos DB tiene una solución alternativa para admitir la paginación de consultas SQL con la palabra clave DISTINCT mediante la cláusula ORDER BY, no es compatible con Azure AI Search. La consulta devuelve un único valor JSON, mientras que Azure AI Search espera un objeto 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

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 sea compatible con los datos de origen. 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. Crear o actualizar un índice para definir campos de búsqueda que almacenan datos:

    POST https://[service name].search.windows.net/indexes?api-version=2024-07-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. 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 más campos para obtener más contenido que se puede buscar. Consulte Creación de un índice en Azure Cognitive Search para más información.

Asignar tipos de datos

Tipos 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 for NoSQL

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=2024-07-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. 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, compruebe el historial de ejecución del indexador en Azure Portal, o envíe una API de RESTObtener estado del indexador

  1. En la página del servicio de búsqueda, abra Administración de búsqueda>indexadores.

  2. Seleccione un indexador para acceder al historial de configuración y ejecución.

  3. Seleccione un trabajo de indexador específico para ver detalles, advertencias y errores.

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

Nota:

Al asignar un valor null a un campo de Azure Cosmos DB, el indexador de AI Search no puede distinguir entre null y un valor de campo que falta. Por lo tanto, si un campo del índice está vacío, no se sustituirá por un valor null, incluso si esa modificación se realizó específicamente en la base de datos.

Indexación incremental y consultas personalizadas

Si usa una consulta personalizada para recuperar documentos, asegúrese de que la consulta ordene los resultados por la columna _ts. Esto permite la creación de puntos de comprobación, que Azure AI Search usa para proporcionar el progreso incremental en presencia de errores.

En algunos casos, incluso si la consulta contiene una cláusula ORDER BY [collection alias]._ts, Azure AI Search podría no deducir que la consulta está ordenada por el _ts. Se puede indicar a Azure AI Search que los resultados están ordenados estableciendo la propiedad de configuración assumeOrderByHighWaterMarkColumn.

Para especificar esta sugerencia, cree o actualice la definición del indexador como se indica a continuación:

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

Indexación de documentos eliminados

Cuando se eliminan filas de la recopilación, lo habitual es que también se deseen eliminar del índice de búsqueda. El fin de una directiva de detección de eliminación de datos es identificar eficazmente los elementos de datos eliminados. 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"
}

Si usa una consulta personalizada, asegúrese de que la consulta proyecte la propiedad a la que hace referencia softDeleteColumnName.

softDeleteColumnName debe ser un campo de nivel superior en el índice. No se admite el uso de campos anidados en tipos de datos complejos, ya que no se admite softDeleteColumnName.

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

Uso de .NET

Para los datos a los que se accede mediante el protocolo de SQL API, puede usar el SDK de .NET para la automatización con indexadores. Se recomienda que revise la secciones anteriores sobre la API REST para obtener información sobre los conceptos, el flujo de trabajo y los requisitos. A continuación, puede consultar la siguiente documentación de referencia de la API de .NET para implementar un indexador JSON en código administrado:

Pasos siguientes

Ahora puede controlar cómo ejecutar el indexador, supervisar el estado o programar la ejecución del indexador. Los siguientes artículos se aplican a los indexadores que extraen contenido de Azure Cosmos DB: