Pesquisa de texto completo no Azure DocumentDB

A pesquisa em texto completo do Azure DocumentDB é um motor de busca orientado por analisadores com pontuação BM25, exposto através de primitivas compatíveis com MongoDB. Classifica os resultados por relevância, tolera erros tipográficos dos utilizadores e combina correspondência de texto com condições estruturadas sem um cluster de pesquisa separado. Analisadores personalizados suportam correspondência de prefixos, identificadores hierárquicos e análise específica da língua.

Ative a pesquisa em texto completo no seu cluster Azure DocumentDB antes de criar índices de pesquisa ou executar $search consultas. Escolha um dos métodos seguintes.

portal do Azure

  1. Inicie sessão no portal Azure e abra o seu cluster Azure DocumentDB.
  2. Em Definições, selecione Funcionalidades.
  3. Selecione Pesquisa de texto completo, que inicialmente tem o seu estado definido como Desligado.
  4. No painel que se abre à direita, reveja as informações da funcionalidade e depois selecione Ativar.

CLI do Azure

Execute o seguinte comando no Bash com o CLI do Azure instalado. Substitua os marcadores de posição do ID do recurso pelos valores do seu cluster. O comando PATCH mantém as funcionalidades de pré-visualização lidas do cluster e inclui FullTextSearch exatamente uma vez.

set -euo pipefail

az login

RESOURCE_ID="/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.DocumentDB/mongoClusters/<cluster-name>"
URL="https://management.azure.com${RESOURCE_ID}?api-version=2024-07-01"

# Review the current provisioning state and preview features.
az rest --method get --url "$URL" \
  --query '{state:properties.provisioningState,features:properties.previewFeatures}' \
  --output json

# Preserve other preview features and add FullTextSearch exactly once.
BODY=$(az rest --method get --url "$URL" \
  --query '{properties: {previewFeatures: [properties.previewFeatures[?@ != `"FullTextSearch"`] || `[]`, [`"FullTextSearch"`]][]}}' \
  --output json)

az rest --method patch --url "$URL" --body "$BODY"

# Check the updated configuration.
az rest --method get --url "$URL" \
  --query '{state:properties.provisioningState,features:properties.previewFeatures}' \
  --output json

Terraform

Para um cluster existente, utilize o fornecedor AzAPI para atualizar properties.previewFeatures sem recriar o cluster. O exemplo seguinte utiliza AzAPI 2.x e lê a lista atual antes de adicionar FullTextSearch.

terraform {
  required_providers {
    azapi = {
      source  = "Azure/azapi"
      version = "~> 2.0"
    }
  }
}

provider "azapi" {}

variable "cluster_resource_id" {
  type        = string
  description = "The resource ID of the existing Azure DocumentDB cluster."
}

data "azapi_resource" "cluster" {
  type        = "Microsoft.DocumentDB/mongoClusters@2024-07-01"
  resource_id = var.cluster_resource_id

  response_export_values = {
    preview_features = "properties.previewFeatures || `[]`"
  }
}

resource "azapi_update_resource" "full_text_search" {
  type        = "Microsoft.DocumentDB/mongoClusters@2024-07-01"
  resource_id = var.cluster_resource_id

  body = {
    properties = {
      previewFeatures = distinct(concat(
        data.azapi_resource.cluster.output.preview_features,
        ["FullTextSearch"]
      ))
    }
  }
}

Defina cluster_resource_id para o ID de recurso do seu cluster. Execute terraform init, reveja terraform plane depois execute terraform apply.

Se outro recurso Terraform gerir o cluster, certifique-se de que não gere também esta propriedade. Para um recurso azurerm_mongo_cluster, adicione preview_features à sua lista lifecycle.ignore_changes quando o AzAPI for proprietário da propriedade. Revise o plano e não avance se este propuser substituir o cluster.

Bicep

Atualize o modelo que gere o seu cluster. Adicione um parâmetro do array contendo todas as outras funcionalidades de pré-visualização que pretende manter:

param otherPreviewFeatures array = []

No objeto properties do seu recurso Microsoft.DocumentDB/mongoClusters existente, defina:

previewFeatures: union(otherPreviewFeatures, [
  'FullTextSearch'
])

Mantenha as restantes propriedades do recurso do cluster inalteradas. Este é um fragmento de propriedade, não um modelo autónomo. O Bicep substitui a lista de funcionalidades de pré-visualização pela lista fornecida; não lê e combina automaticamente as funcionalidades existentes.

Revise a implementação com az deployment group what-if, e depois implemente o seu modelo atualizado com az deployment group create.

Importante

Depois de ativar a pesquisa em texto completo com qualquer método, aguarde 10 minutos antes de criar um índice de pesquisa ou executar uma consulta. Ver FullTextSearch na configuração dos recursos não significa que a ativação tenha terminado.

O que está disponível hoje

Capability Operador ou primitivo
Pesquisa por palavras-chave BM25 $search + text
Pesquisa difusa (tolerante a erros tipográficos) $search + text com fuzzy.maxEdits
Pesquisa por frases e correspondência de proximidade $search + phrase + slop
Pesquisa por prefixo Analisador personalizado com tokenizador edgeGram ou filtro de token
Pesquisa de identificador hierárquico Analisador personalizado com tokenizador pathHierarchy
Análise de texto personalizada Pipelines ordenados de tokenizador e filtro de tokens para normalização, stemming, palavras de parada e processamento de padrões
Análise específica da língua Analisadores e tokenizadores chineses, japoneses, coreanos e tailandeses
Pesquisa multicampo de identificadores Um índice com múltiplas mappings.fields entradas e caminhos de consulta explícitos
Análise alternativa do mesmo campo Mapeamentos com nome multi
Pesquisa estruturada e de texto token, number, date, e boolean mapeamentos com equals, range, exists, in, e compound
Ordenação inline e recuperação top-N $search.sort ordenação em campos escalares mapeados e pushdown a jusante $limit
Recuperação híbrida por palavra-chave + vetor Consultas de palavras‑chave separadas e consultas cosmosSearch combinadas com RRF

Limitações atuais

As seguintes capacidades não são atualmente suportadas:

  • Mapeamentos dinâmicos, conjuntos de tipos dinâmicos, filtros de caracteres, definições de sinónimos e storedSource.
  • compound.minimumShouldMatch e aumentos de pontuação personalizados.
  • Os operadores autocomplete, queryString e near.
  • Os regex operadores e wildcard operadores no interior de $search não são suportados.
  • A fase $searchMeta, a variável $$SEARCH_META, as contagens, as facetas e o realce.
  • Os tipos de mapping objectId, uuid, embeddedDocument, autocomplete e geo.

Utilize os exemplos RRF do lado do cliente ou do pipeline de agregação na pesquisa híbrida para fundir resultados de palavras-chave e vetor. A fase $rankFusion não é atualmente suportada.

Para a referência a nível de serviço, incluindo restrições do ciclo de vida do índice de pesquisa, consulte Limitações de pesquisa em texto integral.

Como funciona a pesquisa de texto completo no Azure DocumentDB

Um índice de pesquisa no Azure DocumentDB é um objeto separado de um índice de documento. Cria-o com o comando createSearchIndexes da base de dados, não com db.<coll>.createIndex({ field: "text" }) e não com createIndexes e um tipo de chave "textSearch". A definição do índice declara quais os campos pesquisáveis, os seus tipos e o pipeline do analisador utilizado no momento da indexação e da consulta.

As consultas são executadas como a primeira etapa de um pipeline de agregação utilizando o $search operador. Por predefinição, o motor devolve documentos ordenados por relevância, o que pode consultar através de { $meta: "searchScore" } numa fase posterior $project. Utilize inline sort para ordenar os resultados por campos escalares indexados em vez disso. Exemplos nesta secção usam a sintaxe MongoDB Shell ao estilo mongosh, mas as mesmas operações funcionam a partir de qualquer driver compatível com MongoDB.

Quatro regras aplicam-se a cada consulta de pesquisa de texto completo do Azure DocumentDB:

  • Direcione um índice pelo nome com index: "<name>" dentro de $search. Se for omitido, a consulta tem como alvo um índice chamado default; não escolhe um índice arbitrário. Cada caminho de consulta deve estar presente no índice selecionado.
  • $search é sempre a primeira etapa de um pipeline de agregação, pelo que o índice de pesquisa estreita o conjunto de candidatos antes de qualquer outro operador ser executado.
  • Não há campo count ou limit no interior de $search. Limite os resultados com uma etapa { $limit: N } downstream.
  • Combine texto e condições estruturadas com compound. Utilize equals, range, exists e in em campos escalares mapeados. Para condições que necessitam de um downstream $match, aplique-o antes da final $limit para que o limite se aplique aos resultados elegíveis.

Definir dynamic: false ou omitir dynamic utiliza mapeamentos estáticos. Cada campo pesquisável deve ser explicitamente declarado sob mappings.fields. A definição dynamic: true faz com que a criação de índice falhe, e mappings.dynamic is not supported in search indexes yet. a criação de índice também falha se mappings.fields estiver em falta ou vazia.

Um único índice de pesquisa pode abranger múltiplos campos de texto, identificadores, numéricos, de data, booleanos e de documentos aninhados.

Mode Melhor para Requer índice de pesquisa Classificado por BM25
$regex Correspondência de padrões com valores de campo sem classificação de relevância. O desempenho depende do padrão e dos índices disponíveis. No No
$search + text Pesquisa padrão por palavras-chave em prosa, descrições, títulos. Yes Yes
$search + text + fuzzy Pesquisa à medida que escreve, catálogo orientado para o utilizador ou pesquisa em registos onde erros tipográficos são comuns. Yes Yes
$search + phrase Nomes de produto com várias palavras, entrada do utilizador entre aspas, cadeias de erro onde a ordem das palavras importa. Yes Yes
Analisador personalizado + text Consultas de prefixo, identificadores hierárquicos, texto normalizado e análise específica da língua. Yes Yes
$search + compound Recuperação de texto com categoria exata, disponibilidade exata, condições numéricas exatas ou de data exatas numa única consulta. Yes As cláusulas de texto contribuem para a relevância
Híbrido (BM25 + vector) Pesquisa em catálogo ou base de conhecimento que combina consultas em linguagem natural com identificadores exatos; Recuperação RAG. Sim (BM25 + vetor) Pontuação combinada

Pesquisa de texto completo e índices de texto

O operador $text e os índices { field: "text" } estão geralmente disponíveis. A pesquisa em texto completo utiliza índices de pesquisa separados e consultas $search e permanece em pré-visualização. Ativar a pré-visualização não altera índices de texto ou consultas $text existentes.

Para avaliar a pesquisa em texto integral em pré-visualização, crie um índice de pesquisa separado e utilize consultas $search. Não precisa de migrar as cargas de trabalho $text existentes para avaliar a pré-visualização.