Dados de índice do Azure Cosmos DB para Apache Gremlin para consultas no Azure AI Search

Neste artigo, saiba como configurar um indexador que importa conteúdo do Azure Cosmos DB para Apache Gremlin e o torna pesquisável no Azure AI Search.

Este artigo complementa Criar um indexador com informações específicas do Cosmos DB. 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, criar um indexador. A extração de dados ocorre quando você envia a solicitação Criar indexador.

Como a terminologia pode ser confusa, vale a pena observar que a indexação do Azure Cosmos DB e a indexação do Azure AI Search são operações diferentes. A indexação na Pesquisa de IA do Azure cria e carrega um índice de pesquisa no seu serviço de pesquisa.

Pré-requisitos

• Registre-se para a visualização para fornecer feedback sobre o cenário. Você pode acessar o recurso automaticamente após o envio do formulário.

• Uma conta, banco de dados, contêiner e itens do Azure Cosmos DB. Use a mesma região para o Azure AI Search e o Azure Cosmos DB para obter latência mais baixa e evitar cobranças de largura de banda.

• Uma política de indexação automática na coleção do Azure Cosmos DB, definida como Consistente. Esta é a configuração predefinida. A indexação lenta não é recomendada e pode resultar na falta de dados.

• Permissões de leitura. Uma cadeia de conexão de "acesso total" inclui uma chave que concede acesso ao conteúdo, mas se você estiver usando funções do Azure, verifique se a identidade gerenciada do serviço de pesquisa tem permissões de Função de Leitor de Conta do Cosmos DB.

• Um cliente REST para criar a fonte de dados, o índice e o indexador.

Definir a fonte de dados

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

Para esta chamada, especifique uma versão de visualização da API REST para criar uma fonte de dados que se conecte por meio de um Azure Cosmos DB para Apache Gremlin. Você pode usar 2021-04-01-preview ou posterior. Recomendamos a API de visualização mais recente.

1. Crie ou atualize uma fonte de dados para definir sua definição:

    POST https://[service name].search.windows.net/datasources?api-version=2024-05-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. Defina "type" como "cosmosdb" (obrigatório).

3. Defina "credenciais" como uma cadeia de conexão. A próxima seção descreve os formatos suportados.

4. Defina "container" para a coleção. A propriedade "name" é necessária e especifica o ID do gráfico.

   A propriedade "query" é opcional. Por padrão, o indexador do Azure AI Search para Azure Cosmos DB para Apache Gremlin torna cada vértice em seu gráfico um documento no índice. As arestas serão ignoradas. O padrão de consulta é g.V(). Como alternativa, você pode definir a consulta para indexar apenas as bordas. Para indexar as bordas, defina a consulta como g.E().

5. Defina "dataChangeDetectionPolicy" se os dados forem voláteis e você quiser que o indexador pegue apenas os itens novos e atualizados em execuções subsequentes. O progresso incremental será habilitado por padrão usando _ts como coluna de marca d'água alta.

6. Defina "dataDeletionDetectionPolicy" se quiser remover documentos de pesquisa de um índice de pesquisa quando o item de origem for excluído.

Credenciais e cadeias de conexão suportadas

Os indexadores podem se conectar a uma coleção usando as seguintes conexões. Para conexões destinadas ao Azure Cosmos DB para Apache Gremlin, certifique-se de incluir "ApiKind" na cadeia de conexão.

Evite números de porta no URL do ponto de extremidade. Se você incluir o número da porta, a conexão falhará.

Adicionar campos de pesquisa a um índice

Em um índice de pesquisa, adicione campos para aceitar os documentos JSON de origem ou a saída de sua projeção de consulta personalizada. Verifique se o esquema de índice de pesquisa é compatível com o gráfico. Para conteúdo no Azure Cosmos DB, seu esquema de índice de pesquisa deve corresponder aos itens do Azure Cosmos DB em sua fonte de dados.

1. Crie ou atualize um índice para definir campos de pesquisa que armazenarão dados:

    POST https://[service name].search.windows.net/indexes?api-version=2024-05-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. Crie um campo de chave de documento ("chave": true). Para coleções particionadas, a chave de documento padrão é a propriedade do Azure Cosmos DB _rid , para a qual o Azure AI Search renomeia automaticamente porque rid os nomes de campo não podem começar com um caractere de sublinhado. Além disso, os valores do Azure Cosmos DB _rid contêm caracteres que são inválidos nas chaves do Azure AI Search. Por esta razão, os _rid valores são codificados em Base64.

3. Crie campos adicionais para mais conteúdo pesquisável. Consulte Criar um índice para obter detalhes.

Mapeando tipos de dados

Configurar e executar o indexador do Azure Cosmos DB

Depois que o índice e a fonte de dados forem criados, você estará pronto para criar o indexador. A configuração do indexador especifica as entradas, parâmetros e propriedades que controlam os comportamentos de tempo de execução.

1. Crie ou atualize um indexador dando-lhe um nome e fazendo referência à fonte de dados e ao índice de destino:

   POST https://[service name].search.windows.net/indexers?api-version=2024-05-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 mapeamentos de campo se houver diferenças no nome ou tipo de campo ou se precisar de várias versões de um campo de origem no índice de pesquisa.

3. Consulte Criar um indexador para obter mais informações sobre outras propriedades.

Um indexador é executado automaticamente quando é criado. Você pode evitar isso definindo "desativado" como true. Para controlar a execução do indexador, execute um indexador sob demanda ou coloque-o em uma programação.

Verificar o estado do indexador

Para monitorar o status do indexador e o histórico de execução, envie uma solicitação Obter Status do Indexador:

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

A resposta inclui o status e o número de itens processados. Deve ser semelhante ao seguinte exemplo:

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

O histórico de execução contém até 50 das execuções concluídas mais recentemente, que são classificadas na ordem cronológica inversa para que a execução mais recente venha primeiro.

Indexação de documentos novos e alterados

Depois que um indexador tiver preenchido totalmente um índice de pesquisa, talvez você queira que as execuções subsequentes do indexador indexem incrementalmente apenas os documentos novos e alterados em seu banco de dados.

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

Para indexadores do Azure Cosmos DB, a única política com suporte é o HighWaterMarkChangeDetectionPolicy uso da propriedade (carimbo _ts de data/hora) fornecida pelo Azure Cosmos DB.

O exemplo a seguir mostra uma definição de fonte de dados com uma política de deteção de alterações:

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

Indexação de documentos eliminados

Quando os dados do gráfico são excluídos, convém excluir o documento correspondente do índice de pesquisa também. O objetivo de uma política de deteção de exclusão de dados é identificar eficientemente itens de dados excluídos e excluir o documento completo do índice. A política de deteção de exclusão de dados não se destina a excluir informações parciais do documento. Atualmente, a única política suportada é a Soft Delete política (a exclusão é marcada com um sinalizador de algum tipo), que é especificada na definição da fonte de dados da seguinte maneira:

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

O exemplo a seguir cria uma fonte de dados com uma política de exclusão suave:

POST https://[service name].search.windows.net/datasources?api-version=2024-05-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"
    }
}

Mesmo que você habilite a política de deteção de exclusão, não há suporte para a exclusão de campos complexos (Edm.ComplexType) do índice. Esta política requer que a coluna 'ativa' no banco de dados Gremlin seja do tipo inteiro, string ou booleano.

Mapeando dados do gráfico para campos em um índice de pesquisa

O indexador do Azure Cosmos DB para Apache Gremlin mapeará automaticamente algumas partes de dados gráficos:

1. O indexador mapeará _rid para um rid campo no índice, se ele existir, e Base64 codificá-lo.

2. O indexador será mapeado _id para um id campo no índice, se ele existir.

3. Ao consultar seu banco de dados do Azure Cosmos DB usando o Azure Cosmos DB para Apache Gremlin, você pode notar que a saída JSON para cada propriedade tem um id e um value. O indexador mapeará automaticamente as propriedades value em um campo no índice de pesquisa que tenha o mesmo nome da propriedade, se existir. No exemplo a seguir, 450 seria mapeado para um pages campo no índice de pesquisa.

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

Você pode achar que precisa usar Mapeamentos de Campo de Saída para mapear a saída da consulta para os campos no índice. Você provavelmente desejará usar Mapeamentos de Campo de Saída em vez de Mapeamentos de Campo, pois a consulta personalizada provavelmente terá dados complexos.

Por exemplo, digamos que sua consulta produza essa saída:

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

Se quiser mapear o valor do JSON acima para um totalpages campo no índice, você pode adicionar o seguinte mapeamento de campo de saída à sua definição de pages indexador:

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

Observe como o mapeamento de campo de saída começa com /document e não inclui uma referência à chave de propriedades no JSON. Isso ocorre porque o indexador coloca cada documento sob o /document nó ao ingerir os dados do gráfico e o indexador também permite que você faça referência automática ao valor de pages por referência simples, pages em vez de ter que fazer referência ao primeiro objeto na matriz de pages.

Próximos passos

• Para saber mais sobre o Azure Cosmos DB para Apache Gremlin, consulte a Introdução ao Azure Cosmos DB: Azure Cosmos DB para Apache Gremlin.

• Para obter mais informações sobre cenários e preços do Azure AI Search, consulte a página do serviço de Pesquisa no azure.microsoft.com.

• Para saber mais sobre a configuração de rede para indexadores, consulte Acesso do indexador ao conteúdo protegido pelos recursos de segurança de rede do Azure.