Compartir a través de

Ejemplos de consultas de búsqueda sencillas en Búsqueda de Azure AI

  • Artículo

En Azure AI Search, la sintaxis de consulta simple invoca el analizador de consultas predeterminado para realizar búsquedas de texto completo. Este analizador es rápido y gestiona escenarios comunes, incluida la búsqueda de texto completo, la búsqueda por facetas, la búsqueda filtrada y la búsqueda por prefijos. En este artículo se usan ejemplos para ilustrar el uso de la sintaxis simple en una solicitud de Search Documents (API REST).

Nota:

Una sintaxis de consulta alternativa es Lucene, que admite estructuras de consulta más complejas, como la búsqueda aproximada y con caracteres comodín. Para obtener más información, vea Ejemplos de sintaxis de búsqueda completa de Lucene .

Índice hotels-sample

Las siguientes consultas se basan en el índice hotels-sample-index, que puede crear siguiendo las instrucciones de Inicio rápido: Creación de un índice de búsqueda en Azure Portal.

Las consultas de ejemplo se articulan mediante la API REST y las solicitudes POST. Puede pegarlas y ejecutarlas en un cliente REST. O bien, puede usar la vista JSON del Explorador de búsqueda en Azure Portal. En la vista JSON, puede pegar los ejemplos de consulta que se muestran aquí en este artículo.

Los encabezados de solicitud deben tener los siguientes valores:

Llave Value
Tipo de contenido application/json
api-key <your-search-service-api-key>, ya sea una consulta o una clave de administración

Los parámetros de URI deben incluir el punto de conexión del servicio de búsqueda con el nombre del índice, las colecciones de documentos, el comando de búsqueda y la versión de la API de manera similar al ejemplo siguiente:

https://{{service-name}}.search.windows.net/indexes/hotels-sample-index/docs/search?api-version=2024-07-01

El cuerpo de la solicitud debe formarse como JSON válido:

{
    "search": "*",
    "queryType": "simple",
    "select": "HotelId, HotelName, Category, Tags, Description",
    "count": true
}

  • search establecer en * es una consulta no especificada, equivalente a la búsqueda nula o vacía. No es especialmente útil, pero es la búsqueda más sencilla que se puede hacer y muestra todos los campos recuperables en el índice, con todos sus valores.

  • queryType establecer en simple es el valor predeterminado y se puede omitir, pero se incluye para resaltar que los ejemplos de consulta de este artículo se expresan en la sintaxis simple.

  • select establecer en una lista delimitada por comas de campos se usa para la composición de resultados de búsqueda, incluidos solo los campos que son útiles en el contexto de los resultados de búsqueda.

  • count devuelve el número de documentos que coinciden con los criterios de búsqueda. En una cadena de búsqueda vacía, el número es todos los documentos que haya en el índice (50 en hotels-sample-index).

Ejemplo 1: Búsqueda de texto completo

La búsqueda de texto completo sirve para cualquier número de términos independientes o frases entrecomilladas, con o sin operadores booleanos.

POST /indexes/hotel-samples-index/docs/search?api-version=2024-07-01
{
    "search": "pool spa +airport",
    "searchMode": "any",
    "queryType": "simple",
    "select": "HotelId, HotelName, Category, Description",
    "count": true
}

Una búsqueda de palabras clave que se compone de términos o frases importantes suele funcionar mejor. Los campos de cadena se someten al análisis de texto durante la indexación y la consulta, y se quitan las palabras que no son esenciales, como el/la, y, eso. Para ver cómo se descompone en tokens una cadena de consulta en el índice, pase la cadena al índice en una llamada a la API de análisis de texto.

El parámetro searchMode controla la precisión y la recuperación. Si quiere mayor coincidencia, use el valor predeterminado cualquier, que devuelve un resultado si se produce una coincidencia con cualquier parte de la cadena de consulta. Si favorece la precisión, donde deben coincidir todas las partes de la cadena, cambie searchMode a todas. Pruebe la consulta anterior de ambas maneras para ver cómo searchMode cambia el resultado.

La respuesta de la consulta de grupo spa +airport debe ser similar al ejemplo siguiente.

"@odata.count": 4,
"value": [
{
    "@search.score": 6.090657,
    "HotelId": "12",
    "HotelName": "Winter Panorama Resort",
    "Description": "Plenty of great skiing, outdoor ice skating, sleigh rides, tubing and snow biking. Yoga, group exercise classes and outdoor hockey are available year-round, plus numerous options for shopping as well as great spa services. Newly-renovated with large rooms, free 24-hr airport shuttle & a new restaurant. Rooms/suites offer mini-fridges & 49-inch HDTVs.",
    "Category": "Resort and Spa"
},
{
    "@search.score": 4.314683,
    "HotelId": "21",
    "HotelName": "Good Business Hotel",
    "Description": "1 Mile from the airport. Free WiFi, Outdoor Pool, Complimentary Airport Shuttle, 6 miles from Lake Lanier & 10 miles from downtown. Our business center includes printers, a copy machine, fax, and a work area.",
    "Category": "Suite"
},
{
    "@search.score": 3.575948,
    "HotelId": "27",
    "HotelName": "Starlight Suites",
    "Description": "Complimentary Airport Shuttle & WiFi. Book Now and save - Spacious All Suite Hotel, Indoor Outdoor Pool, Fitness Center, Florida Green certified, Complimentary Coffee, HDTV",
    "Category": "Suite"
},
{
    "@search.score": 2.6926985,
    "HotelId": "25",
    "HotelName": "Waterfront Scottish Inn",
    "Description": "Newly Redesigned Rooms & airport shuttle. Minutes from the airport, enjoy lakeside amenities, a resort-style pool & stylish new guestrooms with Internet TVs.",
    "Category": "Suite"
}
]

Fíjese en la puntuación de búsqueda de la respuesta. Esta es la puntuación de relevancia de la coincidencia. De forma predeterminada, cualquier servicio de búsqueda devuelve las 50 coincidencias principales en función de esta puntuación.

Las puntuaciones uniformes de tipo 1.0 se producen cuando no hay ninguna clasificación, bien porque la búsqueda no era de texto completo, o bien porque no se proporcionaron criterios. Por ejemplo, en el caso de una búsqueda vacía (search=*), las filas se devuelven en un orden arbitrario. Al incluir criterios reales, verá que las puntuaciones de búsqueda evolucionan hasta convertirse en valores significativos.

Ejemplo 2: Búsqueda por identificador

Una vez que se devuelven los resultados de la búsqueda, un siguiente paso lógico es proporcionar una página de detalles que incluya más campos del documento. En este ejemplo se muestra cómo devolver un único documento mediante Obtener documento pasando el id. del documento.

GET /indexes/hotels-sample-index/docs/41?api-version=2024-07-01

Todos los documentos tienen un identificador único. Si usa Azure Portal, seleccione en índice en la pestaña Índices y, después, examine las definiciones de campo para determinar qué campo es la clave. En la API de REST, la llamada Obtener índice devuelve la definición de índice en el cuerpo de la respuesta.

La respuesta de la consulta anterior consta del documento cuya clave es 41. Cualquier campo que esté marcado como recuperable en la definición del índice se puede devolver en los resultados de la búsqueda y se puede representar en la aplicación.

{
    "HotelId": "41",
    "HotelName": "Windy Ocean Motel",
    "Description": "Oceanfront hotel overlooking the beach features rooms with a private balcony and 2 indoor and outdoor pools. Inspired by the natural beauty of the island, each room includes an original painting of local scenes by the owner. Rooms include a mini fridge, Keurig coffee maker, and flatscreen TV. Various shops and art entertainment are on the boardwalk, just steps away.",
    "Description_fr": "Cet hôtel en bord de mer donnant sur la plage propose des chambres dotées d'un balcon privé et de 2 piscines intérieure et extérieure. Inspiré par la beauté naturelle de l'île, chaque chambre comprend une peinture originale de scènes locales par le propriétaire. Les chambres comprennent un mini-réfrigérateur, une cafetière Keurig et une télévision à écran plat. Divers magasins et divertissements artistiques se trouvent sur la promenade, à quelques pas.",
    "Category": "Suite",
    "Tags": [
    "pool",
    "air conditioning",
    "bar"
    ],
    "ParkingIncluded": true,
    "LastRenovationDate": "2021-05-10T00:00:00Z",
    "Rating": 3.5,
    "Location": {
    "type": "Point",
    "coordinates": [
        -157.846817,
        21.295841
    ],
    "crs": {
        "type": "name",
        "properties": {
        "name": "EPSG:4326"
        }
    }
    },
    "Address": {
    "StreetAddress": "1450 Ala Moana Blvd 2238 Ala Moana Ctr",
    "City": "Honolulu",
    "StateProvince": "HI",
    "PostalCode": "96814",
    "Country": "USA"
    }
}

Ejemplo 3: Filtrado por texto

La sintaxis de filtro es una expresión de OData que se puede usar con search. Cuando se usa juntos en la misma solicitud, filter se aplica primero a todo el índice y, a continuación, el search se realiza en los resultados del filtro. Por lo tanto, los filtros pueden ser una técnica útil para mejorar el rendimiento porque reducen el conjunto de documentos en los que se debe procesar la consulta de búsqueda.

Los filtros se pueden definir en cualquier campo marcado como filterable en la definición del índice. En hotels-sample-index, los campos filtrables son Category, Tags, ParkingIncluded, Rating y la mayoría de los campos de dirección.

POST /indexes/hotels-sample-index/docs/search?api-version=2024-07-01
{
    "search": "art tours",
    "queryType": "simple",
    "filter": "Category eq 'Boutique'",
    "searchFields": "HotelName,Description,Category",
    "select": "HotelId,HotelName,Description,Category",
    "count": true
}

La respuesta de la consulta anterior se limita solo a los hoteles clasificados como Boutique, y que incluyen los términos art o tours. En este caso, solo hay una coincidencia.

"value": [
{
    "@search.score": 1.2814453,
    "HotelId": "2",
    "HotelName": "Old Century Hotel",
    "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music.",
    "Category": "Boutique"
}
]

Ejemplo 4: Funciones de filtro

Las expresiones de filtro pueden incluir funciones search.ismatch y search.ismatchscoring, lo que le permite crear una consulta de búsqueda dentro del filtro. Esta expresión de filtro usa un carácter comodín en free (gratis) para determinados servicios, wifi gratis, parking gratuito, etc.

POST /indexes/hotels-sample-index/docs/search?api-version=2024-07-01
  {
    "search": "",
    "filter": "search.ismatch('free*', 'Tags', 'full', 'any')",
    "select": "HotelName, Tags, Description",
    "count": true
  }

La respuesta de la consulta anterior coincide con 27 hoteles que ofrecen servicios gratuitos. Observe que la puntuación de búsqueda es un uniforme de1 a lo largo de los resultados. Esto se debe a que la expresión de búsqueda es NULL o está vacía, lo que da lugar a coincidencias de filtro textuales, pero no se realiza ninguna búsqueda de texto completo. Las puntuaciones de relevancia solo se devuelven en la búsqueda de texto completo. Si usa filtros sin search, asegúrese de que tiene suficientes campos que puedan ordenarse para poder controlar el rango de búsqueda.

  "@odata.count": 27,
  "value": [
    {
      "@search.score": 1,
      "HotelName": "Country Residence Hotel",
      "Description": "All of the suites feature full-sized kitchens stocked with cookware, separate living and sleeping areas and sofa beds. Some of the larger rooms have fireplaces and patios or balconies. Experience real country hospitality in the heart of bustling Nashville. The most vibrant music scene in the world is just outside your front door.",
      "Tags": [
        "laundry service",
        "restaurant",
        "free parking"
      ]
    },
    {
      "@search.score": 1,
      "HotelName": "Downtown Mix Hotel",
      "Description": "Mix and mingle in the heart of the city. Shop and dine, mix and mingle in the heart of downtown, where fab lake views unite with a cheeky design.",
      "Tags": [
        "air conditioning",
        "laundry service",
        "free wifi"
      ]
    },
    {
      "@search.score": 1,
      "HotelName": "Starlight Suites",
      "Description": "Complimentary Airport Shuttle & WiFi. Book Now and save - Spacious All Suite Hotel, Indoor Outdoor Pool, Fitness Center, Florida Green certified, Complimentary Coffee, HDTV",
      "Tags": [
        "pool",
        "coffee in lobby",
        "free wifi"
      ]
    },
. . .

Ejemplo 5: Filtros de intervalo

Se admite el filtrado de intervalo mediante expresiones de filtro para cualquier tipo de datos. En los siguientes ejemplos se muestran intervalos numéricos y de cadena. Los tipos de datos son importantes en los filtros de rango y funcionan mejor cuando los campos numéricos contienen datos numéricos y los de cadena, datos de cadena. Los datos numéricos de los campos de cadena no son adecuados para los intervalos, ya que las cadenas numéricas no se pueden comparar.

La consulta siguiente es un intervalo numérico: En hotels-sample-index, el único campo numérico filtrable es Rating.

POST /indexes/hotels-sample-index/docs/search?api-version=2024-07-01
{
    "search": "*",
    "filter": "Rating ge 2 and Rating lt 4",
    "select": "HotelId, HotelName, Rating",
    "orderby": "Rating desc",
    "count": true
}

La respuesta de esta consulta debe ser similar al ejemplo siguiente, recortada para mayor brevedad.

"@odata.count": 27,
"value": [
{
    "@search.score": 1,
    "HotelId": "22",
    "HotelName": "Lion's Den Inn",
    "Rating": 3.9
},
{
    "@search.score": 1,
    "HotelId": "25",
    "HotelName": "Waterfront Scottish Inn",
    "Rating": 3.8
},
{
    "@search.score": 1,
    "HotelId": "2",
    "HotelName": "Old Century Hotel",
    "Rating": 3.6
},
...

La consulta siguiente es un filtro de intervalo en un campo de cadena (Address/StateProvince):

POST /indexes/hotels-sample-index/docs/search?api-version=2024-07-01
{
    "search": "*",
    "filter": "Address/StateProvince ge 'A*' and Address/StateProvince lt 'D*'",
    "select": "HotelId, HotelName, Address/StateProvince",
    "count": true
}

La respuesta de esta consulta debe ser similar al ejemplo siguiente, recortada para mayor brevedad. En este ejemplo, no es posible ordenar por StateProvince porque el campo no se atribuye como ordenable en la definición de índice.

{
  "@odata.count": 9,
  "value": [
    {
      "@search.score": 1,
      "HotelId": "39",
      "HotelName": "White Mountain Lodge & Suites",
      "Address": {
        "StateProvince": "CO"
      }
    },
    {
      "@search.score": 1,
      "HotelId": "9",
      "HotelName": "Smile Up Hotel",
      "Address": {
        "StateProvince": "CA "
      }
    },
    {
      "@search.score": 1,
      "HotelId": "7",
      "HotelName": "Roach Motel",
      "Address": {
        "StateProvince": "CA "
      }
    },
    {
      "@search.score": 1,
      "HotelId": "34",
      "HotelName": "Lakefront Captain Inn",
      "Address": {
        "StateProvince": "CT"
      }
    },
    {
      "@search.score": 1,
      "HotelId": "37",
      "HotelName": "Campus Commander Hotel",
      "Address": {
        "StateProvince": "CA "
      }
    },
. . .

El índice hotels-sample incluye un campo Ubicación con las coordenadas de latitud y longitud. En este ejemplo se usa la función geo.distance, que filtra en documentos dentro de la circunferencia de un punto de partida, hasta la distancia arbitraria (en kilómetros) que proporcione. Puede ajustar el último valor en la consulta (10) para reducir o ampliar el área expuesta de la consulta.

POST /indexes/v/docs/search?api-version=2024-07-01
{
    "search": "*",
    "filter": "geo.distance(Location, geography'POINT(-122.335114 47.612839)') le 10",
    "select": "HotelId, HotelName, Address/City, Address/StateProvince",
    "count": true
}

La respuesta de esta consulta devuelve todos los hoteles a una distancia de 10 kilómetros de las coordenadas proporcionadas:

{
  "@odata.count": 3,
  "value": [
    {
      "@search.score": 1,
      "HotelId": "45",
      "HotelName": "Happy Lake Resort & Restaurant",
      "Address": {
        "City": "Seattle",
        "StateProvince": "WA"
      }
    },
    {
      "@search.score": 1,
      "HotelId": "24",
      "HotelName": "Uptown Chic Hotel",
      "Address": {
        "City": "Seattle",
        "StateProvince": "WA"
      }
    },
    {
      "@search.score": 1,
      "HotelId": "16",
      "HotelName": "Double Sanctuary Resort",
      "Address": {
        "City": "Seattle",
        "StateProvince": "WA"
      }
    }
  ]
}

Ejemplo 7: Valores booleanos con searchMode

La sintaxis simple admite operadores booleanos en forma de caracteres (+, -, |) para admitir los operadores lógicos AND, OR y NOT. La búsqueda booleana se comporta del modo esperado, con algunas excepciones destacadas.

En una búsqueda booleana, considere la posibilidad de agregar el parámetro searchMode como mecanismo para influir en la precisión y la recuperación. Los valores válidos incluyen "searchMode": "any" favorecer la recuperación (un documento que satisface cualquiera de los criterios se considera una coincidencia) y "searchMode": "all" favorecer la precisión (todos los criterios deben coincidir en un documento).

En el contexto de una búsqueda booleana, el uso de "searchMode": "any" como valor predeterminado, puede llevar a confusión si se apila una consulta con varios operadores y se obtienen resultados más amplios, en lugar de más restringidos. Esto sucede especialmente con el operador NOT, donde los resultados incluyen todos los documentos que no contienen un término o una frase específicos.

Esto se muestra en el ejemplo siguiente. La consulta busca coincidencias en restaurante que excluyen la frase aire acondicionado. Si ejecuta la consulta siguiente con searchMode (cualquiera), se devuelven 43 documentos: los que contienen el término restaurante, además de todos los documentos que no tienen la frase *aire acondicionado.

Observe que no hay espacio entre el operador booleano (-) y aire acondicionado. Las comillas se escapan (\").

POST /indexes/hotels-sample-index/docs/search?api-version=2024-07-01
{
    "search": "restaurant -\"air conditioning\"",
    "searchMode": "any",
    "searchFields": "Tags",
    "select": "HotelId, HotelName, Tags",
    "count": true
}

Al cambiar a "searchMode": "all" se aplica un efecto acumulativo en los criterios y se devuelve un conjunto de resultados más pequeño (siete coincidencias) que consta de documentos que contienen el término restaurante, menos los que contienen la frase aire acondicionado.

La respuesta de esta consulta ahora tendría un aspecto similar al ejemplo siguiente, recortado para mayor brevedad.

{
  "@odata.count": 14,
  "value": [
    {
      "@search.score": 3.1383743,
      "HotelId": "18",
      "HotelName": "Ocean Water Resort & Spa",
      "Tags": [
        "view",
        "pool",
        "restaurant"
      ]
    },
    {
      "@search.score": 2.028083,
      "HotelId": "22",
      "HotelName": "Lion's Den Inn",
      "Tags": [
        "laundry service",
        "free wifi",
        "restaurant"
      ]
    },
    {
      "@search.score": 2.028083,
      "HotelId": "34",
      "HotelName": "Lakefront Captain Inn",
      "Tags": [
        "restaurant",
        "laundry service",
        "coffee in lobby"
      ]
    },
...

Ejemplo 8: Paginación de resultados

En los ejemplos anteriores, ha aprendido sobre los parámetros que afectan a la composición de los resultados de la búsqueda, incluido select, que determina qué campos se encuentran en un resultado, los criterios de ordenación y cómo incluir un recuento de todas las coincidencias. Este ejemplo es una continuación de la composición del resultado de la búsqueda en forma de parámetros de paginación que permiten procesar por lotes el número de resultados que aparecen en una página determinada.

De forma predeterminada, un servicio de búsqueda devuelve las 50 coincidencias principales. Para controlar el número de coincidencias en cada página, use top para definir el tamaño del lote y, después, use skip para seleccionar lotes posteriores.

En el ejemplo siguiente se usa un filtro y un criterio de ordenación en el campo Rating (clasificación es filtrable y ordenable), ya que es más fácil ver los efectos de la paginación en los resultados ordenados. En una consulta de búsqueda completa normal, las coincidencias principales se clasifican y se paginan mediante @search.score.

POST /indexes/hotels-sample-index/docs/search?api-version=2024-07-01
{
    "search": "*",
    "filter": "Rating gt 4",
    "select": "HotelName, Rating",
    "orderby": "Rating desc",
    "top": 5,
    "count": true
}

La consulta busca 21 documentos coincidentes, pero dado que especificó top, la respuesta devuelve solo las cinco primeras coincidencias, con clasificaciones a partir de 4,9 y que termina en 4,7 con Lakeside B & B.

Para obtener los cinco siguientes, omita el primer lote:

POST /indexes/hotels-sample-index/docs/search?api-version=2024-07-01
{
    "search": "*",
    "filter": "Rating gt 4",
    "select": "HotelName, Rating",
    "orderby": "Rating desc",
    "top": 5,
    "skip": 5,
    "count": true
}

La respuesta del segundo lote omite las cinco primeras coincidencias y devuelve las cinco siguientes, empezando por Pull'r Inn Motel. Para continuar con más lotes, mantendría top en cinco y luego incrementaría skip en cinco en cada nueva solicitud (skip=5, skip=10, skip=15, etc.).

{
  "@odata.count": 21,
  "value": [
    {
      "@search.score": 1,
      "HotelName": "Head Wind Resort",
      "Rating": 4.7
    },
    {
      "@search.score": 1,
      "HotelName": "Sublime Palace Hotel",
      "Rating": 4.6
    },
    {
      "@search.score": 1,
      "HotelName": "City Skyline Antiquity Hotel",
      "Rating": 4.5
    },
    {
      "@search.score": 1,
      "HotelName": "Nordick's Valley Motel",
      "Rating": 4.5
    },
    {
      "@search.score": 1,
      "HotelName": "Winter Panorama Resort",
      "Rating": 4.5
    }
  ]
}

Contenido relacionado

Ahora que tiene más práctica con la sintaxis de consulta básica, pruebe a especificar consultas en el código. El siguiente vínculo conduce a un artículo en el que se explica cómo configurar las consultas de búsqueda para los SDK de Azure.

En los vínculos siguientes, se pueden encontrar una referencia de la sintaxis, la arquitectura de las consultas y ejemplos: