Blog

Apresentando a interface de usuário de regras de consulta do Elasticsearch no Kibana.

Aprenda a usar a interface de regras de consulta do Elasticsearch para adicionar ou excluir documentos de consultas de pesquisa usando conjuntos de regras personalizáveis no Kibana, sem afetar o ranking orgânico.

Jhon Guzmán
Noções básicasExperiência do Desenvolvedor

A função de um mecanismo de busca é retornar resultados relevantes. No entanto, existem necessidades comerciais que vão além disso — como destacar promoções, priorizar produtos sazonais ou exibir itens patrocinados — e os desenvolvedores nem sempre podem fazer isso na consulta de pesquisa.

Além disso, esses casos de uso geralmente são sensíveis ao tempo, e passar pelas etapas típicas de desenvolvimento (criar uma ramificação de código e depois esperar por um novo lançamento) é um processo demorado.

E se pudéssemos realizar todo esse processo com apenas uma chamada de API, ou melhor ainda, com apenas alguns cliques no Kibana?

Interface do usuário de regras de consulta

O Elasticsearch 8.10 introduziu as Regras de Consulta e o Recuperador de Regras. São ferramentas projetadas para inserir resultados fixados nas consultas sem afetar a classificação dos resultados orgânicos com base em regras. Eles apenas adicionam lógica de negócios aos resultados de forma declarativa e simples.

Alguns casos de uso comuns para regras de consulta são:

  • Destacar anúncios ou promoções: Exibir itens em promoção ou patrocinados no topo.

  • Exclusão por contexto ou geolocalização: Ocultar determinados itens quando as regulamentações locais não permitem que você os mostre.

  • Priorizar resultados-chave: Garantir que as pesquisas populares ou fixas estejam sempre no topo, independentemente do ranking orgânico.

Para acessar a interface e interagir com essas ferramentas, você precisa clicar no menu lateral do Kibana e ir para Regras de Consulta, em Relevância:

Acessando regras de consulta no Elasticsearch em termos de relevância.

Assim que o menu de regras de consulta aparecer, clique em Criar seu primeiro conjunto de regras:

Criando seu primeiro conjunto de regras de consulta no Elasticsearch

Em seguida, você precisa dar um nome ao seu conjunto de regras.

Como nomear seu conjunto de regras de consulta no Elasticsearch

O formulário para definir cada regra possui três componentes principais:

  • Critérios: As condições que devem ser cumpridas para que a regra se aplique. Por exemplo, “quando o campo query_string contém o valor Christmas” ou “quando o campo country é CO”.

  • Ação: Isto é o que você deseja que aconteça quando as condições forem atendidas. Ele pode ser fixado (fixando um documento nos primeiros resultados) ou excluído (ocultando um documento).

  • Metadados: São os campos que acompanham a consulta quando ela é executada. Podem incluir informações do usuário (como localização ou idioma), bem como dados de pesquisa (query_string). Esses são os valores usados pelos critérios para decidir se uma regra deve ou não ser aplicada.

Exemplo: itens populares

Vamos imaginar que temos um site de comércio eletrônico com diversos itens. Ao analisarmos as métricas, notamos que um dos itens mais vendidos na categoria de consoles é o "Controle sem fio DualShock 4", especialmente quando os usuários pesquisam pelas palavras-chave "PS4" ou "PlayStation 4". Assim, decidimos colocar este produto no topo dos resultados, sempre que um usuário pesquisar por essas palavras-chave.

Primeiro, vamos indexar os documentos de cada item usando uma solicitação de API em lote:

POST _bulk
{ "index": { "_index": "products", "_id": "1" } }
{ "id": "1", "name": "PlayStation 4 Slim 1TB", "category": "console", "brand": "Sony", "price": 1200 }
{ "index": { "_index": "products", "_id": "2" } }
{ "id": "2", "name": "DualShock 4 Wireless Controller", "category": "accessory", "brand": "Sony", "price": 250 }
{ "index": { "_index": "products", "_id": "3" } }
{ "id": "3", "name": "PlayStation 4 Camera", "category": "accessory", "brand": "Sony", "price": 200 }
{ "index": { "_index": "products", "_id": "4" } }
{ "id": "4", "name": "PlayStation 4 VR Headset", "category": "accessory", "brand": "Sony", "price": 900 }
{ "index": { "_index": "products", "_id": "5" } }
{ "id": "5", "name": "Charging Station for DualShock 4", "category": "accessory", "brand": "Sony", "price": 80 }

Se não intervirmos na consulta, o item geralmente aparece em quarto lugar. Eis a pergunta:

GET products/_search
{
 "query": {
   "match": {
     "name": "PlayStation 4"
   }
 }
}

E aqui estão os resultados.

{
 "took": 1,
 "timed_out": false,
 "_shards": {
   "total": 1,
   "successful": 1,
   "skipped": 0,
   "failed": 0
 },
 "hits": {
   "total": {
     "value": 5,
     "relation": "eq"
   },
   "max_score": 0.6973252,
   "hits": [
     {
       "_index": "products",
       "_id": "3",
       "_score": 0.6973252,
       "_source": {
         "id": "3",
         "name": "PlayStation 4 Camera",
         "category": "accessory",
         "brand": "Sony",
         "price": 200
       }
     },
     {
       "_index": "products",
       "_id": "1",
       "_score": 0.6260078,
       "_source": {
         "id": "1",
         "name": "PlayStation 4 Slim 1TB",
         "category": "console",
         "brand": "Sony",
         "price": 1200
       }
     },
     {
       "_index": "products",
       "_id": "4",
       "_score": 0.6260078,
       "_source": {
         "id": "4",
         "name": "PlayStation 4 VR Headset",
         "category": "accessory",
         "brand": "Sony",
         "price": 900
       }
     },
     {
       "_index": "products",
       "_id": "2",
       "_score": 0.08701137,
       "_source": {
         "id": "2",
         "name": "DualShock 4 Wireless Controller",
         "category": "accessory",
         "brand": "Sony",
         "price": 250
       }
     },
     {
       "_index": "products",
       "_id": "5",
       "_score": 0.07893815,
       "_source": {
         "id": "5",
         "name": "Charging Station for DualShock 4",
         "category": "accessory",
         "brand": "Sony",
         "price": 80
       }
     }
   ]
 }
}

Vamos criar uma regra de consulta para alterar isso. Primeiro, vamos adicioná-lo ao conjunto de regras assim:

Como editar um conjunto de regras de consulta no Elasticsearch

Ou solicitação de API equivalente:

PUT _query_rules/my-rules
{
  "rules": [
    {
      "rule_id": "rule-1232",
      "type": "pinned",
      "criteria": [
        {
          "type": "exact",
          "metadata": "query_string",
          "values": [
            "PS4",
            "PlayStation 4"
          ]
        }
      ],
      "actions": {
        "docs": [
          {
            "_index": "products",
            "_id": "2"
          }
        ]
      }
    }
  ]
}

Para usar o conjunto de regras em nossa consulta, devemos usar um tipo de regra de consulta. Esse tipo de consulta é composto por duas partes principais:

GET /products/_search
{
 "retriever": {
   "rule": {
     "retriever": {
       "standard": {
         "query": {
           "match": { "name": "PlayStation 4" }
         }
       }
     },
     "match_criteria": {
       "query_string": "PlayStation 4"
     },
     "ruleset_ids": ["my-rules"]
   }
 }
}

  • match_criteria: São os metadados usados para comparar com a consulta do usuário. Neste exemplo, o conjunto de regras é ativado quando o campo query_string tem o valor “PlayStation 4”.

  • consulta: a consulta propriamente dita que será usada para pesquisar e obter os resultados orgânicos.

Dessa forma, primeiro você executa a consulta orgânica e, em seguida, o Elasticsearch aplica as regras do seu conjunto de regras:

{
 "took": 17,
 "timed_out": false,
 "_shards": {
   "total": 1,
   "successful": 1,
   "skipped": 0,
   "failed": 0
 },
 "hits": {
   "total": {
     "value": 5,
     "relation": "eq"
   },
   "max_score": 1.7014122e+38,
   "hits": [
     {
       "_index": "products",
       "_id": "2",
       "_score": 1.7014122e+38,
       "_source": {
         "id": "2",
         "name": "DualShock 4 Wireless Controller",
         "category": "accessory",
         "brand": "Sony",
         "price": 250
       }
     },
     {
       "_index": "products",
       "_id": "3",
       "_score": 0.6973252,
       "_source": {
         "id": "3",
         "name": "PlayStation 4 Camera",
         "category": "accessory",
         "brand": "Sony",
         "price": 200
       }
     },
     {
       "_index": "products",
       "_id": "1",
       "_score": 0.6260078,
       "_source": {
         "id": "1",
         "name": "PlayStation 4 Slim 1TB",
         "category": "console",
         "brand": "Sony",
         "price": 1200
       }
     },
     {
       "_index": "products",
       "_id": "4",
       "_score": 0.6260078,
       "_source": {
         "id": "4",
         "name": "PlayStation 4 VR Headset",
         "category": "accessory",
         "brand": "Sony",
         "price": 900
       }
     },
     {
       "_index": "products",
       "_id": "5",
       "_score": 0.07893815,
       "_source": {
         "id": "5",
         "name": "Charging Station for DualShock 4",
         "category": "accessory",
         "brand": "Sony",
         "price": 80
       }
     }
   ]
 }
}

Exemplo: metadados baseados no usuário

Outra aplicação interessante das Regras de Consulta é usar metadados para exibir documentos específicos com base em informações contextuais do usuário ou da página da web.

Por exemplo, vamos supor que queremos destacar itens ou ofertas personalizadas com base no nível de fidelidade do usuário, representado por um valor numérico.

Podemos fazer isso inserindo esses metadados diretamente na consulta, de forma que as regras sejam ativadas quando o valor atender a determinados critérios.

Primeiro, vamos indexar um documento que somente usuários com um alto nível de fidelidade podem ver:

POST _bulk
{ "index": { "_index": "products", "_id": "6" } }
{ "id": "6", "name": "PlayStation Plus Deluxe Card - 12 months", "category": "membership", "brand": "Sony", "price": 300 }

Agora, vamos criar uma nova regra dentro do mesmo conjunto de regras para que, quando o nível de lealdade for igual ou superior a 80, o item apareça no topo dos resultados.

Como editar um conjunto de regras de consulta no Elasticsearch

Salve a regra e o conjunto de regras.

Aqui está a solicitação REST equivalente:

PUT _query_rules/my-rules
{
  "rules": [
    {
      "rule_id": "pin-premiun-user",
      "type": "pinned",
      "criteria": [
        {
          "type": "gte",
          "metadata": "loyalty_level",
          "values": [
            80
          ]
        }
      ],
      "actions": {
        "docs": [
          {
            "_index": "products",
            "_id": "6"
          }
        ]
      }
    }
  ]
}

Agora, ao executar uma consulta, precisamos incluir o novo parâmetro loyalty_level nos metadados. Se a condição da regra for atendida, o novo documento aparecerá no topo dos resultados.

Por exemplo, ao enviar uma consulta onde o nível de lealdade é 80:

POST /products/_search
{
  "retriever": {
    "rule": {
      "retriever": {
        "standard": {
          "query": {
            "match": {
              "name": "PlayStation"
            }
          }
        }
      },
      "match_criteria": {
        "query_string": "PlayStation",
        "loyalty_level": 80
      },
      "ruleset_ids": ["my-rules"]
    }
  }
}

Veremos o documento de fidelidade acima dos resultados:

{
  "took": 31,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 4,
      "relation": "eq"
    },
    "max_score": 1.7014122e+38,
    "hits": [
      {
        "_index": "products",
        "_id": "6",
        "_score": 1.7014122e+38,
        "_source": {
          "id": "6",
          "name": "PlayStation Plus Deluxe Card - 12 months",
          "category": "membership",
          "brand": "Sony",
          "price": 300
        }
      },
      {
        "_index": "products",
        "_id": "3",
        "_score": 0.5054567,
        "_source": {
          "id": "3",
          "name": "PlayStation 4 Camera",
          "category": "accessory",
          "brand": "Sony",
          "price": 200
        }
      },
      {
        "_index": "products",
        "_id": "1",
        "_score": 0.45618832,
        "_source": {
          "id": "1",
          "name": "PlayStation 4 Slim 1TB",
          "category": "console",
          "brand": "Sony",
          "price": 1200
        }
      },
      {
        "_index": "products",
        "_id": "4",
        "_score": 0.45618832,
        "_source": {
          "id": "4",
          "name": "PlayStation 4 VR Headset",
          "category": "accessory",
          "brand": "Sony",
          "price": 900
        }
      }
    ]
  }
}

No caso abaixo, como o nível de fidelidade é 70, a regra não é atendida e o item não deve aparecer no topo:

POST /products/_search
{
  "retriever": {
    "rule": {
      "retriever": {
        "standard": {
          "query": {
            "match": {
              "name": "PlayStation"
            }
          }
        }
      },
      "match_criteria": {
        "query_string": "PlayStation",
        "loyalty_level": 70
      },
      "ruleset_ids": ["my-rules"]
    }
  }
}

Aqui estão os resultados:

{
  "took": 7,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 4,
      "relation": "eq"
    },
    "max_score": 0.5054567,
    "hits": [
      {
        "_index": "products",
        "_id": "3",
        "_score": 0.5054567,
        "_source": {
          "id": "3",
          "name": "PlayStation 4 Camera",
          "category": "accessory",
          "brand": "Sony",
          "price": 200
        }
      },
      {
        "_index": "products",
        "_id": "1",
        "_score": 0.45618832,
        "_source": {
          "id": "1",
          "name": "PlayStation 4 Slim 1TB",
          "category": "console",
          "brand": "Sony",
          "price": 1200
        }
      },
      {
        "_index": "products",
        "_id": "4",
        "_score": 0.45618832,
        "_source": {
          "id": "4",
          "name": "PlayStation 4 VR Headset",
          "category": "accessory",
          "brand": "Sony",
          "price": 900
        }
      },
      {
        "_index": "products",
        "_id": "6",
        "_score": 0.3817649,
        "_source": {
          "id": "6",
          "name": "PlayStation Plus Deluxe Card - 12 months",
          "category": "membership",
          "brand": "Sony",
          "price": 300
        }
      }
    ]
  }
}

Exemplo: exclusão imediata

Vamos supor que nosso Controle Sem Fio DualShock 4 (ID 2) esteja temporariamente indisponível e não possa ser vendido. Assim, em vez de excluir o documento manualmente ou esperar que algum processamento de dados seja iniciado, a equipe comercial decide removê-lo dos resultados da pesquisa enquanto isso.

Usaremos um processo semelhante ao que acabamos de aplicar aos itens populares, mas desta vez, em vez de selecionar "Fixados", escolheremos "Excluir". Essa regra funciona como uma espécie de lista negra. Altere os critérios para "Sempre" para que a exclusão funcione sempre que a consulta for executada.

A regra deve ser assim:

Exemplo de um conjunto de regras de exclusão imediata no Elasticsearch

Salve a regra e o conjunto de regras para aplicar as alterações. Aqui está a solicitação REST equivalente:

PUT _query_rules/my-rules
{
  "rules": [
    {
      "rule_id": "rule-6358",
      "type": "pinned",
      "criteria": [
        {
          "type": "always"
        }
      ],
      "actions": {
        "docs": [
          {
            "_index": "products",
            "_id": "2"
          }
        ]
      }
    }
  ]
}

Agora, ao executar a consulta novamente, você verá que o item não está mais nos resultados, mesmo que a regra anterior fosse fixá-lo. Isso ocorre porque as exclusões têm prioridade sobre a fixação dos resultados.

{
 "took": 6,
 "timed_out": false,
 "_shards": {
   "total": 1,
   "successful": 1,
   "skipped": 0,
   "failed": 0
 },
 "hits": {
   "total": {
     "value": 4,
     "relation": "eq"
   },
   "max_score": 2.205655,
   "hits": [
     {
       "_index": "products",
       "_id": "3",
       "_score": 2.205655,
       "_source": {
         "id": "3",
         "name": "PlayStation 4 Camera",
         "category": "accessory",
         "brand": "Sony",
         "price": 200
       }
     },
     {
       "_index": "products",
       "_id": "1",
       "_score": 1.9738505,
       "_source": {
         "id": "1",
         "name": "PlayStation 4 Slim 1TB",
         "category": "console",
         "brand": "Sony",
         "price": 1200
       }
     },
     {
       "_index": "products",
       "_id": "4",
       "_score": 1.9738505,
       "_source": {
         "id": "4",
         "name": "PlayStation 4 VR Headset",
         "category": "accessory",
         "brand": "Sony",
         "price": 900
       }
     },
     {
       "_index": "products",
       "_id": "5",
       "_score": 0.69247496,
       "_source": {
         "id": "5",
         "name": "Charging Station for DualShock 4",
         "category": "accessory",
         "brand": "Sony",
         "price": 80
       }
     }
   ]
 }
}

Conclusão

As regras de consulta tornam muito fácil ajustar a relevância sem qualquer alteração de código. A nova interface do Kibana permite que você Para fazer essas alterações em questão de segundos, você e sua equipe terão mais controle sobre os resultados da pesquisa.

Além do comércio eletrônico, as Regras de Consulta podem ser aplicadas em muitos outros cenários: destacar guias de solução de problemas em portais de suporte, exibir documentos internos importantes em bases de conhecimento, promover notícias de última hora em sites de notícias ou filtrar anúncios de emprego ou conteúdo expirados. Eles podem até mesmo impor regras de conformidade, como ocultar material restrito por função de usuário ou região.

Conteúdo relacionado

Noções básicas

Como migrar dados entre diferentes versões do Elasticsearch e entre clusters

Kofi Bartlett
JavascriptNoções básicas

Elasticsearch em JavaScript da maneira correta, parte II

Jeffrey Rengifo
Noções básicas

Implementação de busca semântica: Construindo uma busca de receitas com Elasticsearch

Andre Luiz
Noções básicas

Como implantar o Elasticsearch no AWS Marketplace

Eduard Martin
Noções básicas

Como implantar o Elasticsearch no Azure AKS automaticamente

Eduard Martin

Pronto para criar buscas de última geração?

Uma pesquisa suficientemente avançada não se consegue apenas com o esforço de uma só pessoa. O Elasticsearch é impulsionado por cientistas de dados, especialistas em operações de aprendizado de máquina, engenheiros e muitos outros que são tão apaixonados por buscas quanto você. Vamos nos conectar e trabalhar juntos para construir a experiência de busca mágica que lhe trará os resultados desejados.

Experimente você mesmo(a)