Indexar dados do servidor flexível do Banco de Dados do Azure para MySQL

  • Artigo

Importante

O suporte ao MySQL está em visualização pública de acordo com os Termos de Uso Complementares. Use uma API REST em versão prévia (2020-06-30-preview ou posterior) para indexar seu conteúdo. No momento, não há suporte no portal.

Neste artigo, saiba como configurar um indexador que importa o conteúdo do Banco de Dados do Azure para MySQL e o torna pesquisável no Azure AI Search. As entradas para o indexador são os registros, numa só tabela ou exibição. A saída é um índice de pesquisa com conteúdo pesquisável em campos individuais.

Este artigo complementa Criar um indexador com informações específicas para indexação do servidor flexível do Banco de Dados do Azure para MySQL. Ele usa as APIs REST para demonstrar um fluxo de trabalho de três partes comum a todos os indexadores: criar uma fonte de dados, criar um índice e criar um indexador. A extração de dados ocorre quando você envia a solicitação Criar Indexador.

Quando configurado para incluir a marca-d'água alta e a exclusão reversível, o indexador realiza todas as alterações, uploads e exclusões do seu banco de dados MySQL. Isso reflete essas alterações no índice de pesquisa. A extração de dados ocorre quando você envia a solicitação Criar Indexador.

Pré-requisitos

Limitações de visualização

No momento, o controle de alterações e a detecção de exclusão não estão funcionando se a data ou o carimbo de data/hora é igual em todas as linhas. Essa limitação é um problema conhecido a ser resolvido em uma atualização da versão prévia. Até que esse problema seja resolvido, não adicione um conjunto de habilidades ao indexador do MySQL.

A versão prévia não dá suporte a tipos de geometria e blobs.

Como indicado, não há suporte no portal para a criação do indexador, mas uma fonte de dados e um indexador do MySQL podem ser gerenciados no portal depois de criados. Por exemplo, você pode editar as definições e redefinir, executar ou agendar o indexador.

Definir a fonte de dados

A definição da fonte de dados especifica os dados a serem indexados, as credenciais e as políticas para identificar alterações nos dados. A fonte de dados é definida como um recurso independente para que possa ser usada por vários indexadores.

Criar ou Atualizar Fonte de Dados especifica a definição. Use uma versão prévia da API REST (2020-06-30-Preview ou posterior) ao criar a fonte de dados.

{   
    "name" : "hotel-mysql-ds",
    "description" : "[Description of MySQL data source]",
    "type" : "mysql",
    "credentials" : { 
        "connectionString" : 
            "Server=[MySQLServerName].MySQL.database.azure.com; Port=3306; Database=[DatabaseName]; Uid=[UserName]; Pwd=[Password]; SslMode=Preferred;" 
    },
    "container" : { 
        "name" : "[TableName]" 
    },
    "dataChangeDetectionPolicy" : { 
        "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
        "highWaterMarkColumnName": "[HighWaterMarkColumn]"
    }
}

Pontos principais:

  • Defina type como "mysql" (obrigatório).

  • Defina credentials como uma cadeia de conexão ADO.NET. Você pode encontrar cadeias de conexão no portal do Azure, na página Cadeias de conexão para MySQL.

  • Defina container como o nome da tabela.

  • Defina dataChangeDetectionPolicy se os dados forem voláteis e você quiser que o indexador selecione apenas os itens novos e atualizados nas execuções seguintes.

  • Defina dataDeletionDetectionPolicy se desejar remover documentos de pesquisa de um índice de pesquisa quando o item de origem for excluído.

Crie um índice

Criar ou Atualizar Índice especifica o esquema de índice:

{
    "name" : "hotels-mysql-ix",
    "fields": [
        { "name": "ID", "type": "Edm.String", "key": true, "searchable": false },
        { "name": "HotelName", "type": "Edm.String", "searchable": true, "filterable": false },
        { "name": "Category", "type": "Edm.String", "searchable": false, "filterable": true, "sortable": true  },
        { "name": "City", "type": "Edm.String", "searchable": false, "filterable": true, "sortable": true },
        { "name": "Description", "type": "Edm.String", "searchable": false, "filterable": false, "sortable": false  }     
    ]
}

Se a chave primária na tabela de origem corresponder à chave do documento (nesse caso, "ID"), o indexador importará a chave primária como a chave do documento.

Mapeamento de tipos de dados

A tabela a seguir mapeia o banco de dados MySQL para os equivalentes ao Azure AI Search. Para obter mais informações, confira Tipos de dados com suporte (Azure AI Search).

Observação

A versão prévia não oferece suporte a tipos de geometria e blobs.

Tipos de dados do MySQL Tipos de campo do Azure AI Search
bool, boolean Edm.Boolean, Edm.String
tinyint, smallint, mediumint, int, integer, year Edm.Int32, Edm.Int64, Edm.String
bigint Edm.Int64, Edm.String
float, double, real Edm.Double, Edm.String
date, datetime, timestamp Edm.DateTimeOffset, Edm.String
char, varchar, tinytext, mediumtext, text, longtext, enum, set, time Edm.String
unsigned numerical data, serial, decimal, dec, bit, blob, binary, geometry N/D

Configurar e executar o indexador do MySQL

Uma vez que o índice e a fonte de dados forem criados, será possível criar o indexador. A configuração do indexador especifica as entradas, os parâmetros e as propriedades que controlam os comportamentos de tempo de execução.

Crie ou atualize um indexador dando um nome a ele e referenciando a fonte de dados e o índice de destino:

{
    "name" : "hotels-mysql-idxr",
    "dataSourceName" : "hotels-mysql-ds",
    "targetIndexName" : "hotels-mysql-ix",
    "disabled": null,
    "schedule": null,
    "parameters": {
        "batchSize": null,
        "maxFailedItems": null,
        "maxFailedItemsPerBatch": null,
        "base64EncodeKeys": null,
        "configuration": { }
        },
    "fieldMappings" : [ ],
    "encryptionKey": null
}

Pontos principais:

Checar o status do indexador

Envie uma solicitação Obter Status do Indexador para monitorar a execução do indexador:

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

A resposta inclui o status e o número de itens processados. Ela deve ser parecida com o seguinte exemplo:

{
    "status":"running",
    "lastResult": {
        "status":"success",
        "errorMessage":null,
        "startTime":"2024-02-21T00:23:24.957Z",
        "endTime":"2024-02-21T00:36:47.752Z",
        "errors":[],
        "itemsProcessed":1599501,
        "itemsFailed":0,
        "initialTrackingState":null,
        "finalTrackingState":null
    },
    "executionHistory":
    [
        {
            "status":"success",
            "errorMessage":null,
            "startTime":"2024-02-21T00:23:24.957Z",
            "endTime":"2024-02-21T00:36:47.752Z",
            "errors":[],
            "itemsProcessed":1599501,
            "itemsFailed":0,
            "initialTrackingState":null,
            "finalTrackingState":null
        },
        ... earlier history items
    ]
}

O histórico de execuções contém até 50 execuções mais recentes, classificadas em ordem cronológica inversa, de modo que a execução mais recente apareça em primeiro lugar.

Como indexar linhas novas e alteradas

Depois que um indexador preencher completamente um índice de pesquisa, o ideal será que o indexador seguinte seja executado para indexar de maneira incremental apenas as linhas novas e alteradas no banco de dados.

Para habilitar a indexação incremental, defina a propriedade dataChangeDetectionPolicy na definição da fonte de dados. Essa propriedade informa o indexador de que o mecanismo de controle de alterações é usado nos dados.

Para os indexadores do Banco de Dados do Azure para MySQL, a única política com suporte é o HighWaterMarkChangeDetectionPolicy.

A política de detecção de alteração de um indexador depende da presença de uma coluna de marca d'água alta que captura a versão de linha ou a data e a hora da última atualização de uma linha. Muitas vezes, é uma coluna DATE, DATETIME ou TIMESTAMP com granularidade suficiente para atender aos requisitos de uma coluna de marca d'água alta.

No banco de dados MySQL, a coluna de marca d'água alta precisa atender aos seguintes requisitos:

  • Todas as inserções de dados precisam especificar um valor para a coluna.
  • Todas as atualizações de um item também alteram o valor da coluna.
  • O valor dessa coluna aumenta com cada inserção ou atualização.
  • Consultas com as seguintes cláusulas WHERE e ORDER BY podem ser executadas com eficiência: WHERE [High Water Mark Column] > [Current High Water Mark Value] ORDER BY [High Water Mark Column]

O seguinte exemplo mostra uma definição de fonte de dados com uma política de detecção de alteração:

{
    "name" : "[Data source name]",
    "type" : "mysql",
    "credentials" : { "connectionString" : "[connection string]" },
    "container" : { "name" : "[table or view name]" },
    "dataChangeDetectionPolicy" : {
        "@odata.type" : "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
        "highWaterMarkColumnName" : "[last_updated column name]"
    }
}

Importante

Se você estiver usando uma exibição, precisará definir uma política de marca d'água alta na fonte de dados do indexador.

Se a tabela de origem não tiver um índice na coluna de marca d'água alta, as consultas usadas pelo indexador do MySQL poderão atingir o tempo limite. Em particular, a cláusula ORDER BY [High Water Mark Column] requer que um índice seja executado com eficiência quando a tabela contiver muitas linhas.

Como indexar linhas excluídas

Quando as linhas são excluídas da tabela ou da exibição, normalmente, o ideal também é excluí-las do índice de pesquisa. No entanto, se as linhas forem fisicamente removidas da tabela, um indexador não terá como inferir a presença de registros que não existem mais. A solução é usar a técnica de exclusão reversível para excluir logicamente as linhas sem removê-las da tabela. Adicione uma coluna à sua tabela ou exiba e marque as linhas como excluídas usando essa coluna.

Considerando uma coluna que fornece o estado de exclusão, um indexador pode ser configurado para remover todos os documentos de pesquisa para os quais o estado de exclusão esteja definido como true. A propriedade de configuração que dá suporte a esse comportamento é uma política de detecção de exclusão de dados, que é especificada na definição da fonte de dados da seguinte maneira:

{
    …,
    "dataDeletionDetectionPolicy" : {
        "@odata.type" : "#Microsoft.Azure.Search.SoftDeleteColumnDeletionDetectionPolicy",
        "softDeleteColumnName" : "[a column name]",
        "softDeleteMarkerValue" : "[the value that indicates that a row is deleted]"
    }
}

O softDeleteMarkerValue deve ser uma cadeia de caracteres. Por exemplo, se você tiver uma coluna de inteiros na qual as linhas excluídas são marcadas com o valor 1, use "1". Se você tiver uma coluna BIT na qual as linhas excluídas são marcadas com o valor true booliano, use a cadeia de caracteres literal True ou true, o caso não importa.

Próximas etapas

Agora você pode executar o indexador, monitorar o statusou agendar a execução do indexador. Os seguintes artigos se aplicam aos indexadores que efetuam pull do conteúdo do Azure MySQL: