OpenSearch:Processamento de busca

O sistema oferece uma sintaxe de busca abrangente para atender aos requisitos de diversos cenários.

/v3/openapi/apps/$app_name/search?fetch_fields=name&query=config=format:fulljson&&query=name:'zhangsan'&&sort=id

• $app_name: Nome da aplicação. As edições Premium e Standard suportam múltiplas aplicações. Especifique o nome da aplicação para acessar um service ativo.

• A URL acima omite cabeçalhos de requisição, codificação e outros fatores.

• A URL anterior omite o endereço do host para acesso à aplicação.

• Para definições, uso e exemplos dos parâmetros de consulta na URL acima, consulte a seção Parâmetros de consulta abaixo.

HTTP

GET

JSON

Para detalhes sobre como concatenar parâmetros de consulta, consulte o documento v3 API signature mechanism.

Uso dos parâmetros de consulta

• query: O parâmetro de consulta combina várias cláusulas para atender a diversos requisitos de busca. As cláusulas dentro do parâmetro query são conectadas por &&.

• fetch_fields: O tamanho dos dados de texto retornados impacta significativamente o desempenho. Recupere apenas os campos necessários. Se este parâmetro for configurado no SDK ou na API, ele sobrescreve a configuração correspondente no console.

• qp: Caso seja configurado no SDK ou na API, este parâmetro substitui a configuração equivalente no console.

Nota: Visualize os efeitos e resultados do qp na página de teste de busca no console. A API e os SDKs não expõem essas informações atualmente.

• disable: Utilize este parâmetro para desativar recursos de parâmetros como qp, summary, first_rank, second_rank e re_search.

  Descrição do recurso

  • Controla a desativação de determinados recursos durante uma consulta.

  • Permite desativar funcionalidades como análise de consulta, destaque, ordenação aproximada e refinada, além de nova busca.

  Formato do parâmetro:

  disable=function[;function]
  function=function_name[:function_param]

  • Exemplos:

    • Para desativar a análise de consulta, defina disable=qp.

    • Para desativar o recurso spell_check na análise de consulta, defina disable=qp:spell_check.

    • Para desativar a nova busca, defina disable=re_search.

• first_rank_name: Quando configurado no SDK ou na API, sobrescreve a configuração correspondente no console.

• second_rank_name: Substitui a configuração equivalente no console quando definido via SDK ou API.

• user_id:

  • Ao definir este parâmetro em uma requisição de busca, codifique o valor de user_id em URL.

• raw_query:

  Descrição do recurso

  • Recomenda-se definir este parâmetro com a consulta original inserida pelo usuário final.

  Formato do parâmetro:

  raw_query=content

  • content: A consulta de busca original.

• re_search:

  Descrição do recurso

  • Defina a política de nova busca. Atualmente, suporta apenas políticas baseadas no limiar de total de acertos.

  Formato do parâmetro:

  re_search=strategy:threshold,params:total_hits#${COUNT}

  • COUNT: Limite superior para total_hits que dispara uma nova busca. O sistema executa uma nova busca se total_hits for menor que COUNT.

  • Exemplo:

    • re_search=url_encode(strategy:threshold,params:total_hits#6)

• biz:

  Descrição do recurso

  • Descreve informações de negócio associadas à requisição, como o tipo de negócio de origem.

    Formato do parâmetro:

    biz=type:$TYPE

  • type: Tipo de tráfego. Defina o valor conforme necessário. Posteriormente, utilize esse valor para distinguir diferentes fontes de tráfego em relatórios.

  • Exemplo:

    • biz=type:home_page

• vector_threshold:

• Descrição do recurso

  • Controla o limiar de pontuação vetorial para recuperação de documentos em uma busca vetorial. Apenas documentos com pontuação vetorial inferior a este valor são retornados.

• Formato do parâmetro:

  vector_threshold=14.0

  • O valor é um número de ponto flutuante.

  • Parâmetro opcional. Se não for definido, o sistema utiliza um limiar interno.

• summary:

  • Os parâmetros summary_element_prefix e summary_element_postfix devem ser definidos simultaneamente.

  • O parâmetro summary_element e o par (summary_element_prefix, summary_element_postfix) afetam-se mutuamente. Uma configuração posterior sobrescreve a anterior.

  • Atualmente, não é possível configurar resumo e destaque separadamente.

  • Se configurado no SDK ou na API, substitui a configuração correspondente no console.

Parâmetro	Tipo	Obrigatório	Valores válidos	Valor padrão	Descrição
summary_field	string	Sim			Campo a ser resumido.
summary_element	string	Não		em	Tag de destaque representada por uma tag HTML sem os sinais de maior e menor.
summary_ellipsis	string	Não		...	Reticências ao final do resumo.
summary_snipped	int	Não		1	Quantidade de trechos de resumo a selecionar.
summary_len	string	Não			Comprimento do trecho de resumo a exibir.
summary_element_prefix	string	Não			Prefixo para destaque. Deve ser uma tag HTML completa, como <em>.
summary_element_postfix	string	Não			Sufixo para destaque. Deve ser uma tag HTML completa, como </em>.

Resultado retornado

Parâmetro	Tipo	Descrição
status	string	Resultado da execução. OK indica sucesso. FAIL indica falha. Em caso de falha na requisição, solucione o problema com base no código de erro retornado.
request_id	string	ID do registro de consulta. Usado principalmente para solução de problemas.
result	JSON	Resultado efetivo. Inclui informações como tempo de consulta (searchtime), número total de resultados do mecanismo (total), quantidade de resultados retornados para a requisição atual (num), máximo de resultados retornáveis para a consulta (viewtotal), resultados da consulta (items) e resultados estatísticos (facet).
errors	list	Código e mensagem de erro. message representa a mensagem de erro. Para o significado de code, consulte o documento Error codes.

• searchtime: Tempo, em segundos, consumido pelo mecanismo para processar a requisição.

• Diferenças entre total, viewtotal e num: total é a quantidade de resultados correspondentes no mecanismo para uma consulta, ignorando a config clause. Pode sofrer otimização quando há muitos resultados. Por questões de desempenho e relevância, o mecanismo retorna no máximo viewtotal resultados. Para paginação, start+hit must be menor que viewtotal. Geralmente, usa-se total para exibição. num é a quantidade real de entradas retornadas nesta requisição, sujeita a start e hit na config clause, sem exceder hit.

• compute_cost: Array contendo um único elemento map. index_name é o ID da aplicação e value é a quantidade de Logic Compute Units (LCUs) consumidas pela consulta.

• items: Contém os dados recuperados. O parâmetro fields armazena o conteúdo dos resultados de busca.

• variableValue: Representa parâmetros personalizados retornados, como um valor de distância. O nó variableValue aparece apenas quando config clause tem format definido como xml ou fulljson. O formato json não o exibe por padrão.

• sortExprValues: Pontuação de ordenação do documento correspondente.

• facet: Armazena as informações retornadas pela cláusula Aggregate.

• Tipo de campo array: Se um campo array for retornado nos formatos json ou fulljson, os dados serão separados por \t. No formato xml, a separação ocorre por espaços.

Exemplo de busca

Resposta JSON

{
 "result": {
  "searchtime": 0.009554,
  "total": 1,
  "compute_cost": [
   {
    "index_name": "110247758",
    "value": 0.304
   }
  ],
  "num": 1,
  "viewtotal": 1,
  "items": [
   {
    "variableValue": {

    },
    "sortExprValues": [
     "10000"
    ],
    "property": {

    },
    "attribute": {

    },
    "fields": {
     "size": "XL",
     "discount_price": "9.9",
     "pid": "950",
     "range_age": "18\t25",
     "detail": "2021 spring and autumn lightweight casual zip-up jacket with a lapel for young men",
     "index_name": "110247758"
    }
   }
  ],
  "facet": []
 },
 "ops_request_misc": "%7B%22request%5Fid%22%3A%22162642700916781929257960%22%2C%22scm%22%3A%2220140713.110229359..%22%7D",
 "tracer": "",
 "request_id": "162642700916781929257960",
 "errors": [],
 "status": "OK"
}

Resposta de erro

{
 "result": {
  "searchtime": 0.003999,
  "total": 0,
  "compute_cost": [
   {
    "index_name": "110247758",
    "value": 0.232
   }
  ],
  "num": 0,
  "viewtotal": 0,
  "items": [],
  "facet": []
 },
 "ops_request_misc": "%7B%22request%5Fid%22%3A%22162642716516781913069826%22%2C%22scm%22%3A%2220140713.110229359..%22%7D",
 "tracer": "",
 "request_id": "162642716516781913069826",
 "errors": [
  {
   "code": 6127,
   "message": "Attribute not exist."
  }
 ],
 "status": "FAIL"
}

• Nota: status=FAIL significa que ocorreram erros e nenhum resultado foi retornado. Erros e resultados podem ser retornados simultaneamente; nesse caso, status será OK. Por exemplo, resultados ainda podem ser retornados para erros como 1000 server error (tempo limite de busca) ou 2112 (um índice usado na ordenação refinada não foi especificado).

Varredura com scroll

Uma busca tradicional visa recuperar os resultados mais relevantes no menor tempo possível, limitando a quantidade de resultados. Por exemplo, esse método recupera no máximo 5.000 documentos. Em alguns cenários, talvez seja necessário obter mais resultados para análise. Use a API de scroll para recuperar um volume maior de dados.

Cláusulas suportadas

• query clause.

• config clause. O parâmetro start é inválido nesta cláusula.

• filter clause.

• sort clause. Esta cláusula suporta apenas ordenação por um único campo do tipo int e é restrita à API v3 e SDKs.

URL

Consulta inicial

/v3/openapi/apps/$app_name/search?search_type=scan&scroll=1m&query_parameters

Consultas subsequentes

/v3/openapi/apps/$app_name/search?scroll_id=$scroll_id&scroll=1m&query_parameters

• $app_name: Nome da aplicação.

• A URL anterior omite o endereço do host para acesso à aplicação.

• As URLs de requisição de scroll acima omitem cabeçalhos de requisição, conteúdo dos parâmetros de consulta, codificação e outros fatores. Para uma URL completa de requisição de scroll, veja o exemplo abaixo.

• O método scroll possui funcionalidade limitada e não suporta a maioria dos recursos. Para mais informações sobre limitações específicas, consulte as notas ao final.

Protocolo de requisição

HTTP

Método de requisição HTTP

GET

Formato suportado

JSON

Parâmetros de consulta

Parâmetro	Tipo	Obrigatório	Valores válidos	Valor padrão	Descrição
scroll	STRING	Sim	Week, Day, Hour, minute, second		Especifique o período de validade para a próxima requisição de scroll. Defina este parâmetro em cada requisição. Por exemplo, 1m indica 1 minuto. As unidades de tempo suportadas incluem: w para Week, d para Day, h para Hour, m para minute e s para second.
search_type	STRING	Sim	scan		Obrigatório na primeira consulta. Dispensável nas consultas subsequentes, que são feitas especificando o scroll_id.
scroll_id	string	Sim			A primeira chamada ao método scroll retorna um scroll_id, mas não inclui dados. Em cada busca subsequente, especifique o scroll_id da resposta anterior. Os resultados seguintes incluirão tanto um novo scroll_id quanto os dados correspondentes. Este parâmetro é obrigatório em todas as consultas subsequentes.
query clause	string	Sim			Defina as condições de busca.
config clause	string	Sim			Defina o formato dos dados e a quantidade de documentos a retornar.
filter clause	string	Não			Defina as condições de filtro.
sort clause	string	Não			Defina as condições de ordenação de documentos. Suporta apenas ordenação por um único campo do tipo int. Restrito à API v3 e SDKs.
fetch_fields parameter	string	Não			Especifique quais campos da aplicação retornar.

Resultado retornado

Parâmetro	Tipo	Descrição
status	string	Resultado da execução. OK indica sucesso. FAIL indica falha. Em caso de falha na requisição, solucione o problema com base no código de erro retornado.
request_id	string	ID do registro de consulta. Usado principalmente para solução de problemas.
result	string	Resultado efetivamente retornado, incluindo searchtime (tempo de consulta), total (total de resultados do mecanismo), num (resultados retornados por esta requisição), viewtotal (máximo de resultados retornáveis por esta consulta), items (resultados da consulta), facet (resultados de agregação) e scorllid.
errors	string	Conteúdo do erro. error_message representa a mensagem de erro. Para mais informações sobre o significado de error_code, consulte o documento Error codes.

Nota

A API de scroll suporta atualmente apenas os formatos de resposta fulljson e json.

Exemplo de scroll

Nota

Na config clause, o parâmetro start é inválido. Use o parâmetro hit para definir a quantidade de documentos a recuperar em cada lote. Recursos como aggregate, distinct e expressões de ordenação aproximada e refinada são inválidos. A sort clause suporta apenas ordenação por um único campo do tipo int. Consultas com scroll em múltiplas aplicações não são suportadas. Fornecer um scroll_id inválido gera erro. Os formatos de resposta suportados são fulljson e json. A primeira consulta retorna apenas um scroll_id, sem dados de documentos. Faça outra consulta fornecendo o scroll_id da resposta anterior para recuperar os dados.

Primeira requisição

Nota

Este exemplo omite cabeçalhos de requisição, codificação e outros fatores.

http://$host/v3/openapi/apps/app_schema_demo/search?query=config=start:0,hit:1,format:fulljson,rerank_size:200&&query=name:'search'&&sort=+id&&filter=id>0&search_type=scan&scroll=1m&fetch_fields=id;name;phone;int_arr;literal_arr;float_arr;cate_id

Resposta bem-sucedida

{
  "status": "OK",
  "request_id": "150150574119953661605242",
  "result": {
    "searchtime": 0.005029,
    "total": 1,
    "num": 0,
    "viewtotal": 1,
    "scroll_id": "eJxtUMtuhDAM/BrvOYQC5cABdulvRFFIirsm2TpBavv1Ndut1EMlS36NZ0Y2ZHMxbueceAjIuWCMnrPjRITLyfzZm83y9V QVGT8x80U3PxQNUqieVZV1/an4ItbTUBPSx5wgXqKdvOSbmuKR8ZYjGWWirB4tvToAiX7u3G2eCNK77vnz8GlGPAV6suKBeqxAn0OiTd7NGEnesspyoyFLF6hecn4JUKjVgp0K3FnkfMfIyPoDuYWegX9GeYOpicY9TG8gwOSuBL04X1 MMg3ROwCesLlG6X7a2o=",
    "items": [],
    "facet": []
  },
  "errors": [],
  "tracer": ""
}

Requisições subsequentes

Nota

Este exemplo omite detalhes como cabeçalhos de requisição e codificação.

http://$host/v3/openapi/apps/app_schema_demo/search?fetch_fields=id;name;phone;int_arr;literal_arr;float_arr;cate_id&query=config=start:0,hit:1,format:fulljson,rerank_size:200&&query=name:'search'&&sort=+id&&filter=id>0&scroll=1m&scroll_id=eJxtUMtuhDAM/BrvOYQC5cABdulvRFFIirsm2TpBavv1Ndut1EMlS36NZ0Y2ZHMxbueceAjIuWCMnrPjRITLyfzZm83y9V+QVGT8x80U3PxQNUqieVZV1/an4ItbTUBPSx5wgXqKdvOSbmuKR8ZYjGWWirB4tvToAiX7u3G2eCNK77vnz8GlGPAV6suKBeqxAn0OiTd7NGEnesspyoyFLF6hecn4JUKjVgp0K3FnkfMfIyPoDuYWegX9GeYOpicY9TG8gwOSuBL04X1+MMg3ROwCesLlG6X7a2o=

Valor retornado

{
  "status": "OK",
  "request_id": "150150574119952551519970",
  "result": {
    "searchtime": 0.006293,
    "total": 1,
    "num": 1,
    "viewtotal": 1,
    "scroll_id": "eJxNT9tugzAM/RrznIRC4YEHaNlvRFFIhteQtE6Qtn39TNdJk2z5dnx8rIPJRdudcqKhl60Uir2Vp06ISv8b6s3QbZCVzpaCdp93XXBzg2wEW9MJ2dWq8q7YVXt0YckDLlBP0WyOw31N8YgYizZEnAUsjkx4VT4k8zexpjiNS/XYHX0NNkWP71BfVyxQjxLUxSfazFH4PYSPnCL3iMniDZq3jN98aFRCgGrZniy8/itkBHWGuYVeQH+B+QzTCUZ1NJ9gj4FVMfrQPr8Y+Hk+dgU14fIDVhtfTw==",
    "items": [
      {
        "fields": {
          "cate_id": "0",
          "float_arr": "0",
          "id": "1",
          "int_arr": "0",
          "literal_arr": "search",
          "name": "search",
          "phone": "123****5678",
          "index_name": "app_schema_demo"
        },
        "property": {},
        "attribute": {},
        "variableValue": {},
        "sortExprValues": [
          "1"
        ]
      }
    ],
    "facet": []
  },
  "errors": [],
  "tracer": ""
}