Indexación de datos de Azure Cosmos DB mediante las API SQL y MongoDB

En este artículo se muestra cómo configurar un indizador de Azure Cosmos DB para extraer contenido y que se pueda buscar en Azure Cognitive Search. Este flujo de trabajo crea un índice de Azure Cognitive Search y lo carga con texto existente extraído de Azure Cosmos DB.

Como la terminología puede resultar confusa, merece la pena mencionar que la indexación de Azure Cosmos DB y la indexación de Azure Cognitive Search son operaciones distintas, únicas para cada servicio. Antes de comenzar la indexación de Azure Cognitive Search, la base de datos Azure Cosmos DB ya debe existir y contener datos.

El indizador de Cosmos DB en Azure Cognitive Search puede rastrear elementos de Azure Cosmos DB a los que se ha accedido por medio de los protocolos siguientes.

• Para SQL API, que está disponible con carácter general, puede usar el portal, la API REST, el SDK de .NET u otro SDK de Azure para crear el origen de datos y el indizador.

• Para MongoDB API (versión preliminar) puede usar el portal o la API REST, versión 2020-06-30-Preview para crear el origen de datos y el indexador.

Requisitos previos

Solo las colecciones de Cosmos DB con una directiva de indexación establecida en Coherente son compatibles con Azure Cognitive Search. La indexación de colecciones con una directiva de indexación diferida no se recomienda y puede dar lugar a la pérdida de datos. No se admiten las colecciones con indexación deshabilitada.

Uso del portal

El método más sencillo para indexar elementos de Azure Cosmos DB es usar un asistente en Azure Portal. Mediante el muestre de datos y la lectura de metadatos en el contenedor, el asistente Importar datos de Azure Cognitive Search puede crear un índice predeterminado, asignar campos de origen a campos de índice de destino y cargar el índice en una sola operación. Según el tamaño y la complejidad del origen de datos, puede tener un índice de búsqueda de texto completo y operativo en cuestión de minutos.

Se recomienda usar la misma región o ubicación para Azure Cognitive Search y Azure Cosmos DB a fin de conseguir una menor latencia y evitar cargos por ancho de banda.

Paso 1: preparación de los datos de origen

Debe tener una cuenta de Cosmos DB, una base de datos de Azure Cosmos DB asignada a SQL API o MongoDB API (versión preliminar) y el contenido de la base de datos.

Asegúrese de que la base de datos de Cosmos DB contiene datos. El Asistente para importar datos lee los metadatos y realiza el muestreo de datos para inferir un esquema de índice, pero también carga los datos de Cosmos DB. Si los datos no están presentes, el asistente se detiene con este error "Error al detectar el esquema de índice desde el origen de datos: No se pudo crear un índice prototipo porque el origen de datos 'emptycollection' no devolvió datos".

Paso 2: inicio del asistente para la importación de datos

También puede iniciar el asistente desde la barra de comandos de la página del servicio Azure Cognitive Search, o bien, si se va a conectar a SQL API de Cosmos DB, puede hacer clic en Add Azure Cognitive Search (Agregar Azure Cognitive Search) en la sección Configuración del panel de navegación izquierdo de la cuenta de Cosmos DB.

Paso 3: configuración del origen de datos

En la página origen de datos, el origen debe ser Cosmos DB con las especificaciones siguientes:

• Nombre es el nombre del objeto de origen de datos. Una vez creado, puede elegirlo para otras cargas de trabajo.

• La cuenta de Cosmos DB debe tener uno de los siguientes formatos:

  1. La cadena de conexión principal o secundaria de Cosmos DB, con el siguiente formato: AccountEndpoint=https://<Cosmos DB account name>.documents.azure.com;AccountKey=<Cosmos DB auth key>;.
     • En el caso de las colecciones de MongoDB de las versiones 3.2 y 3.6 use el formato siguiente para la cuenta de Cosmos DB en Azure Portal: AccountEndpoint=https://<Cosmos DB account name>.documents.azure.com;AccountKey=<Cosmos DB auth key>;ApiKind=MongoDb.
  2. Una cadena de conexión de identidad administrada con el siguiente formato que no incluye una clave de cuenta: ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.DocumentDB/databaseAccounts/<your cosmos db account name>/;(ApiKind=[api-kind];). Para usar este formato de cadena de conexión, siga las instrucciones de Configuración de una conexión de indexador a una base de datos de Cosmos DB mediante una identidad administrada.

• Base de datos es una base de datos existente de la cuenta.

• Colección es un contenedor de documentos. Deben existir los documentos para que la importación se realice correctamente.

• Consulta puede estar en blanco si desea ver todos los documentos; en caso contrario, escriba una consulta que seleccione un subconjunto de documentos. Consulta solo está disponible para SQL API.

  

Paso 4: omisión de la página"Enriquecer contenido" del asistente

Agregar habilidades cognitivas (o enriquecimiento) no es un requisito de importación. A menos que tenga una necesidad específica de agregar enriquecimiento con IA a su canalización de indexación, debe omitir este paso.

Para omitir el paso, haga clic en los botones azules en la parte inferior de la página para "Siguiente" y "Omitir".

Paso 5: configuración de los atributos de índice

En la página de Índice, debería mostrarse una lista de campos con un tipo de datos y una serie de casillas de verificación para configurar los atributos del índice. El asistente puede generar una lista de campos basada en metadatos y mediante el muestreo de los datos de origen.

Puede seleccionar atributos de forma masiva si activa la casilla situada en la parte superior de una columna de atributos. Elija Se puede recuperar y Se puede buscar para cada campo que se debe devolver a una aplicación cliente y está sujeto a un proceso de búsqueda de texto completo. Observará que los enteros no permiten búsquedas de texto completo o de texto parcial (los números se evalúan literalmente y suelen ser útiles en filtros).

Revise la descripción de atributos de índice y analizadores de lenguaje para más información.

Dedique un momento a la revisión de las selecciones. Una vez que se ejecuta al asistente, se crean las estructuras de datos físicas y no podrá modificar estos campos sin quitar y volver a crear todos los objetos.

Paso 6: creación de un indexador

Con todas las especificaciones agregadas, el asistente crea tres objetos distintos en el servicio de búsqueda. Un objeto de origen de datos y un objeto de índice se guardan como recursos con nombre en el servicio Azure Cognitive Search. El último paso crea un objeto de indizador. Al asignarle un nombre al indizador, este puede existir como un recurso independiente que se puede programar y administrar independientemente de los objetos de origen de datos y del de índice que se crearon en la misma secuencia del asistente.

Si no está familiarizado con los indexadores, un indexador es un recurso en Azure Cognitive Search que rastrea un origen de datos externo en busca de contenido utilizable en búsquedas. La salida del asistente Importar datos es un indizador que se rastrea el origen de datos de Cosmos DB, extrae el contenido utilizable en búsquedas y lo importa a un índice en Azure Cognitive Search.

En la siguiente captura se muestra la configuración del indexador predeterminado. Puede cambiar a Una vez si desea ejecutar el indexador una vez. Haga clic en Enviar para ejecutar el asistente y crear todos los objetos. La indexación comienza inmediatamente.

Puede supervisar la importación de datos en las páginas del portal. Las notificaciones de progreso indican el estado de la indexación y cuántos documentos se cargan.

Cuando se complete la indización, puede usar el Explorador de búsqueda para consultar el índice.

Uso de API REST

Puede usar la API REST para indexar datos de Azure Cosmos DB, siguiendo un flujo de trabajo de tres partes común a todos los indizadores en Azure Cognitive Search: se crea un origen de datos, se crea un índice y se crea un indizador. En el proceso siguiente, la extracción de datos de Cosmos DB se inicia al enviar la solicitud Crear indexador.

En este artículo ya se ha mencionado que la indexación de Azure Cosmos DB y la indexación de Azure Cognitive Search son operaciones distintas. Para la indexación de Cosmos DB, de forma predeterminada todos los documentos se indexan automáticamente. Si se desactiva la indexación automática, solo se puede acceder a los documentos mediante sus propios vínculos o mediante consultas con el identificador del documento. La indexación de Azure Cognitive Search requiere que se active la indexación automática de Cosmos DB en la colección que Azure Cognitive Search va a indexar.

Paso 1: ensamblado de las entradas de la solicitud

Para cada solicitud, debe proporcionar el nombre del servicio y la clave de administrador de Azure Cognitive Search (en el encabezado POST) y el nombre de cuenta de almacenamiento y la clave para Blob Storage. Puede usar Postman o Visual Studio Code para enviar solicitudes HTTP a Azure Cognitive Search.

Copie los tres valores siguientes para usarlos con la solicitud:

• El nombre del servicio Azure Cognitive Search
• La clave de administrador de Azure Cognitive Search
• Cadena de conexión de Cosmos DB

Encontrará estos valores en el portal:

1. En las páginas del portal de Azure Cognitive Search, copie la URL del servicio de búsqueda desde la página de información general.

2. En el panel de navegación izquierdo, haga clic en Claves y, luego, copie la clave primaria o la secundaria.

3. Cambie a las páginas del portal para la cuenta de almacenamiento de Cosmos. En el panel de navegación de la izquierda, en Configuración, haga clic en Claves. En esta página se proporciona un URI, dos conjuntos de cadenas de conexión y dos conjuntos de claves. En el Bloc de notas, copie una de las cadenas de conexión.

Paso 2: creación de un origen de datos

A origen de datos especifica los datos para indexar, las credenciales y las directivas para identificar cambios en los datos (por ejemplo, los documentos modificados o eliminados dentro de la colección). El origen de datos se define como un recurso independiente para que puedan usarlo múltiples indizadores.

Para crear un origen de datos, formule una solicitud POST:

    POST https://[service name].search.windows.net/datasources?api-version=2020-06-30
    Content-Type: application/json
    api-key: [Search service admin key]

    {
        "name": "mycosmosdbdatasource",
        "type": "cosmosdb",
        "credentials": {
            "connectionString": "AccountEndpoint=https://myCosmosDbEndpoint.documents.azure.com;AccountKey=myCosmosDbAuthKey;Database=myCosmosDbDatabaseId"
        },
        "container": { "name": "myCollection", "query": null },
        "dataChangeDetectionPolicy": {
            "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
            "highWaterMarkColumnName": "_ts"
        }
    }

El cuerpo de la solicitud contiene la definición del origen de datos, que debe incluir los siguientes campos:

Uso de consultas para dar forma a los datos indizados

Puede especificar una consulta de SQL para eliminar el formato de 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

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 Cognitive 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 la cláusula 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 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 Cognitive Search. La consulta devolverá un único valor JSON, mientras que Azure Cognitive Search espera un objeto JSON.

-- The following query returns a single JSON value and isn't supported by Azure Cognitive Search
SELECT DISTINCT VALUE c.name FROM c ORDER BY c.name

Paso 3: creación de un índice de búsqueda de destino

Si aún no tiene un índice de Azure Cognitive Search de destino, créelo. En el ejemplo siguiente se crea un índice con un campo de identificador y de descripción:

    POST https://[service name].search.windows.net/indexes?api-version=2020-06-30
    Content-Type: application/json
    api-key: [Search service admin key]

    {
       "name": "mysearchindex",
       "fields": [{
         "name": "id",
         "type": "Edm.String",
         "key": true,
         "searchable": false
       }, {
         "name": "description",
         "type": "Edm.String",
         "filterable": false,
         "searchable": true,
         "sortable": false,
         "facetable": false,
         "suggestions": true
       }]
     }

Asegúrese de que el esquema del índice de destino es compatible con el de los documentos JSON de origen o el resultado de la proyección de consultas personalizada.

Asignación entre tipos de datos de JSON y de Azure Cognitive Search

Paso 4: configuración y ejecución del indexador

Una vez creados el origen de datos y los índices, ya podrá crear el indizador:

    POST https://[service name].search.windows.net/indexers?api-version=2020-06-30
    Content-Type: application/json
    api-key: [admin key]

    {
      "name" : "mycosmosdbindexer",
      "dataSourceName" : "mycosmosdbdatasource",
      "targetIndexName" : "mysearchindex",
      "schedule" : { "interval" : "PT2H" }
    }

Este indexador se ejecuta cada dos horas (el intervalo de programación se establece en "PT2H"). Para ejecutar un indizador cada 30 minutos, establézcalo en PT30M. El intervalo más breve que se admite es de 5 minutos. La programación es opcional: si se omite, el indizador solo se ejecuta una vez cuando se crea. Sin embargo, puede ejecutarlo a petición en cualquier momento.

Para más información sobre la API Create Indexer, consulte Crear indexador.

Para más información sobre cómo definir las programaciones del indexador, consulte Programación de indexadores para Azure Cognitive Search.

Uso de .NET

El SDK de.NET generalmente disponible tiene plena paridad con la API REST disponible con carácter general. Se recomienda que revise la sección anterior de 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 indizador JSON en código administrado.

• azure.search.documents.indexes.models.searchindexerdatasourceconnection
• azure.search.documents.indexes.models.searchindexerdatasourcetype
• azure.search.documents.indexes.models.searchindex
• azure.search.documents.indexes.models.searchindexer

Indexación de documentos modificados

El fin de una directiva de detección de cambios de datos es identificar de forma eficaz los elementos de datos que han cambiado. Actualmente, la única directiva compatible es HighWaterMarkChangeDetectionPolicy que usa la propiedad _ts (marca de tiempo) que proporciona Azure Cosmos DB, y se especifica de la siguiente forma:

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

Se recomienda encarecidamente usar esta directiva para garantizar un buen rendimiento del indexador.

Si usa una consulta personalizada, asegúrese de que la consulta proyecta la propiedad _ts.

Progreso incremental y consultas personalizadas

El progreso incremental durante la indexación garantiza que si se interrumpe la ejecución del indexador por errores transitorios o por el límite de tiempo de ejecución, dicho indexador puede retomar la ejecución por donde la dejó la próxima vez que se ejecute, en lugar de tener que volver a indexar toda la colección desde el principio. Esto es especialmente importante cuando se indexan colecciones grandes.

Para habilitar el progreso incremental cuando se usa una consulta personalizada, asegúrese de que la consulta ordena los resultados por la columna _ts. Esto permite la creación de puntos de comprobación, que Azure Cognitive 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 Cognitive Search puede no deducir que la consulta se ordene por _ts. Puede indicar a Azure Cognitive Search que los resultados se ordenen mediante el uso de la propiedad de configuración assumeOrderByHighWaterMarkColumn. Para especificar esta sugerencia, cree o actualice el 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 es compatible la directiva Soft Delete (la eliminación se indica con algún tipo de marca), especificada de la siguiente forma:

    {
        "@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 proyecta la propiedad a la que softDeleteColumnName hace referencia.

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
    Content-Type: application/json
    api-key: [Search service admin key]

    {
        "name": "mycosmosdbdatasource",
        "type": "cosmosdb",
        "credentials": {
            "connectionString": "AccountEndpoint=https://myCosmosDbEndpoint.documents.azure.com;AccountKey=myCosmosDbAuthKey;Database=myCosmosDbDatabaseId"
        },
        "container": { "name": "myCosmosDbCollectionId" },
        "dataChangeDetectionPolicy": {
            "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
            "highWaterMarkColumnName": "_ts"
        },
        "dataDeletionDetectionPolicy": {
            "@odata.type": "#Microsoft.Azure.Search.SoftDeleteColumnDeletionDetectionPolicy",
            "softDeleteColumnName": "isDeleted",
            "softDeleteMarkerValue": "true"
        }
    }

Pasos siguientes

Felicidades. En este artículo, aprendió a integrar Azure Cosmos DB con Azure Cognitive Search con un indizador.

• Para más información acerca de Azure Cosmos DB, consulte la página de servicio de Azure Cosmos DB.
• Para obtener más información sobre Azure Cognitive Search, consulte la página del servicio Search.