Opciones de consulta y de ordenamiento

Cuando utilizas solamente una string de consulta para llamar al método search(), los resultados se muestran según las opciones de consulta predeterminadas:

  • Los documentos se muestran ordenados en una clasificación descendiente.
  • Se muestran los documentos en grupos de 20 por vez.
  • Los documentos recuperados contienen todos sus campos originales.

Puedes usar una instancia de la clase Query como argumento de search() para cambiar estas opciones. La clase Query te permite especificar cuántos documentos se muestran a la vez. También permite personalizar los contenidos de los documentos recuperados. Puedes pedir solo documentos identificadores o solicitar que los documentos contengan solo un subconjunto de sus campos. También puedes crear campos personalizados en los documentos recuperados: fragmentos (recortes de campos de texto que muestran el texto que rodea una string que coincide) y expresiones de campo (campos con valores derivados de otros campos del documento).

Además de las opciones de consulta, la clase Query puede incluir una instancia de la clase SortOptions. Con las opciones de orden, puedes cambiar el orden y ordenar los resultados en claves múltiples.

Cómo realizar una búsqueda con la clase Query

Cuando realizas una búsqueda con una instancia de la clase Query, debes construir una instancia de la clase a través de varios pasos. Este es el orden general:

  1. Crear una cadena de consulta.
  2. Crear SortOptions si es necesario.
  3. Crear QueryOptions.
  4. Crea un objeto Query que incluya una string de consulta y QueryOptions (opcional).
  5. Llama al método de búsqueda en el objeto Query.

Para especificar las distintas consultas y opciones de orden, debes llamar a los definidores sobre las instancias de las clases QueryOptions.Builder y SortOptions.Builder como en este ejemplo:

Java 8

try {
  // Build the SortOptions with 2 sort keys
  SortOptions sortOptions =
      SortOptions.newBuilder()
          .addSortExpression(
              SortExpression.newBuilder()
                  .setExpression("price")
                  .setDirection(SortExpression.SortDirection.DESCENDING)
                  .setDefaultValueNumeric(0))
          .addSortExpression(
              SortExpression.newBuilder()
                  .setExpression("brand")
                  .setDirection(SortExpression.SortDirection.DESCENDING)
                  .setDefaultValue(""))
          .setLimit(1000)
          .build();

  // Build the QueryOptions
  QueryOptions options =
      QueryOptions.newBuilder()
          .setLimit(25)
          .setFieldsToReturn("model", "price", "description")
          .setSortOptions(sortOptions)
          .build();

  // A query string
  String queryString = "product: coffee roaster AND price < 500";

  //  Build the Query and run the search
  Query query = Query.newBuilder().setOptions(options).build(queryString);
  IndexSpec indexSpec = IndexSpec.newBuilder().setName(indexName).build();
  Index index = SearchServiceFactory.getSearchService().getIndex(indexSpec);
  Results<ScoredDocument> result = index.search(query);
  return result;
} catch (SearchException e) {
  // handle exception...
}

Java 7

try {
  // Build the SortOptions with 2 sort keys
  SortOptions sortOptions = SortOptions.newBuilder()
      .addSortExpression(SortExpression.newBuilder()
          .setExpression("price")
          .setDirection(SortExpression.SortDirection.DESCENDING)
          .setDefaultValueNumeric(0))
      .addSortExpression(SortExpression.newBuilder()
          .setExpression("brand")
          .setDirection(SortExpression.SortDirection.DESCENDING)
          .setDefaultValue(""))
      .setLimit(1000)
      .build();

  // Build the QueryOptions
  QueryOptions options = QueryOptions.newBuilder()
      .setLimit(25)
      .setFieldsToReturn("model", "price", "description")
      .setSortOptions(sortOptions)
      .build();

  // A query string
  String queryString = "product: coffee roaster AND price < 500";

  //  Build the Query and run the search
  Query query = Query.newBuilder().setOptions(options).build(queryString);
  IndexSpec indexSpec = IndexSpec.newBuilder().setName(indexName).build();
  Index index = SearchServiceFactory.getSearchService().getIndex(indexSpec);
  Results<ScoredDocument> result = index.search(query);
  return result;
} catch (SearchException e) {
  // handle exception...
}

QueryOptions

Debes usar QueryOptions.Builder para configurar las opciones de búsqueda. No tienes acceso a estas propiedades de forma directa.

Estas propiedades controlan cuántos resultados mostrar y en qué orden. Las opciones de offset y cursor, que son mutuamente excluyentes, son compatibles con la paginación. Especifican qué documentos seleccionados mostrar en los resultados.

Propiedad Descripción Valor predeterminado Máximo
Limit El máximo número de documentos que se muestran en los resultados. 20 1000
NumberFoundAccuracy Esta propiedad determina la exactitud de los resultados que muestra Results.getNumberFound(). Establece un límite para la cantidad de coincidencias que deben contarse y detiene la búsqueda cuando se alcanza ese límite.

Si el número de coincidencias en el índice es menor o igual al límite, el conteo mostrado es exacto. Si no, el conteo es una estimación basada en las coincidencias que se encontraron y en el tamaño y estructura del índice. Ten en cuenta que establecer un valor alto para esta propiedad puede afectar a la complejidad de la operación de búsqueda y causar tiempos de espera.
Si no se especifica, la exactitud se configura con el mismo valor que el Limit 25,000
Offset El offset del primer documento en los resultados que se muestran. 0. Los resultados incluirán todos los documentos que coincidan (hasta llegar al límite). 1,000
Cursor Puede usarse un cursor en lugar de un offset para recuperar grupos de documentos en un orden determinado. El cursor se actualiza a medida que entra y sale de consultas consecutivas, lo que permite que cada nueva búsqueda se continúe desde el final de la anterior. El cursor y el offset se explican en la página Administrar resultados. Nulo. Los resultados incluirán todos los documentos que coincidan (hasta llegar al límite). -
SortOptions Establece un objeto SortOptions para controlar cómo se ordenan los resultados de la búsqueda. Una instancia de SortOptions tiene su propio conjunto de propiedades, que se describen a continuación. Nulo. Ordenar por clasificación descendiente de documentos. -

Estas propiedades controlan qué campos de los documentos aparecen en los resultados.

Propiedad Descripción Valor predeterminado
ReturningIdsOnly Establecido en True o False. Si se establece en True, los documentos mostrados incluirán solo ID, sin campos. False (mostrar todos los campos).
FieldsToReturn Especifica qué campos de documentos deben incluirse en los resultados. Pueden especificarse no más de 100 campos. Mostrar todos los campos de documentos (hasta 100 campos).
ExpressionsToReturn Expresiones de campo que describen campos calculados que se agregan a cada documento que se muestra en los resultados de la búsqueda. Estos campos se agregan a la propiedad de expresiones del documento. Este valor de campo se especifica escribiendo una expresión que puede incluir uno o más campos de documentos. None
FieldsToSnippet Lista de nombres de campos de texto. Se genera un fragmento para cada campo. Este es un campo calculado que se agrega a la propiedad de expresiones de los documentos en los resultados de la búsqueda. El campo de fragmento tiene el mismo nombre que su campo de origen.

Esta opción utiliza, de forma implícita, la función de fragmento con solo dos argumentos. Crea un fragmento con, al menos, una string que coincida, basada en la misma string de consulta utilizada por la búsqueda para mostrar los resultados: snippet("query-string", field-name).

También puedes crear fragmentos personalizados con la opción ExpressionsToReturn si agregas un campo de expresión que llame a la función de fragmento de forma explícita.
None

SortOptions

Las propiedades de SortOptions controlan la forma en que se ordenan y puntúan los resultados de la búsqueda. Debes usar SortOptions.Builder para configurar las opciones de orden. No tienes acceso a estas propiedades de forma directa.

Las propiedades de SortOptions controlan la forma en que se ordenan y puntúan los resultados de la búsqueda.

Propiedad Descripción Valor predeterminado
SortExpressions Una lista de SortExpressions que representan un orden multidimensional de los documentos. None
MatchScorer Un objeto MatchScorer opcional. Cuando está presente, esta propiedad provocará que los documentos se puntúen de acuerdo con la frecuencia del término de búsqueda. La puntuación estará disponible en el campo _score. Puntuar documentos puede ser costoso (tanto en operaciones facturables como en tiempo de ejecución) y puede ralentizar tus búsquedas. Usa la puntuación con moderación. None
Limit Número máximo de objetos que se ordenan o puntúan. No puede ser mayor a 10,000. 1,000

Ordenar en varias claves

Puedes ordenar los resultados de la búsqueda en múltiples claves de orden. Cada clave puede ser un simple nombre de campo, o un valor que se calcula desde varios campos. Ten en cuenta que el término "expresión" se utiliza con varios significados cuando se habla sobre opciones de orden: SortOption en sí tiene un atributo de expresiones. Este atributo es una lista de objetos SortExpression que corresponden a claves de orden. Por último, cada objeto SortExpression contiene un atributo de expresión que especifica cómo calcular el valor de la clave de orden. Esta expresión se construye de acuerdo con las reglas de la sección siguiente.

Una SortExpression también define la dirección del orden y un valor de clave predeterminado que se usará en caso de que no pueda calcularse la expresión para un documento. A continuación, puedes ver la lista completa de propiedades:

Propiedad Descripción Valor predeterminado
Expression Una expresión que se evalúa cuando se ordenan los resultados para cada documento que coincide. None
Direction La dirección para ordenar los resultados de la búsqueda, puede ser ASCENDING o DESCENDING. DESCENDING
DefaultValue
DefaultValueDate
DefaultValueNumber
El valor predeterminado de la expresión, si no hay ningún campo presente y no puede calcularse para el documento. Debe especificarse un valor de texto para los órdenes de texto. Debe especificarse un valor numérico para los órdenes numéricos. None

Ordenar en campos de valores múltiples

Cuando ordenas en un campo con valores múltiples de un tipo particular, solo se usa el primer valor asignado al campo. Por ejemplo, piensa en dos documentos, DocA y DocB, ambos con un campo de texto con el nombre "color". Se asignan dos valores al campo de "color" de DocA en el orden (rojo, azul), y dos valores a DocB en el orden (verde, rojo). Cuando ejecutas un orden que especifica el campo de texto "color", DocA se ordena en el valor "rojo" y DocB en el valor "verde". No se usan los otros valores de campo en el orden.

Ordenar o no ordenar

Si no especificas ninguna opción de orden, los resultados de la búsqueda se muestran automáticamente por orden de clasificación descendiente. No hay un límite para el número de documentos que se muestran en este caso. Si especificas opciones de orden, el orden se realiza después de que se seleccionan los documentos que coinciden. Hay una propiedad explícita, "SortOptions.limit", que controla el tamaño del orden. No podrás ordenar más de 10,000 documentos; el tamaño predeterminado es 1,000. Si hay más documentos que coinciden que el número especificado en "SortOptions.limit", la búsqueda solo recupera, ordena y muestra esa cantidad limitada. Se seleccionan los documentos para ordenar de la lista de todos los documentos que coinciden, que está ordenada por clasificación descendiente. Es posible que una consulta seleccione más documentos que coinciden de los que puedes ordenar. Si usas opciones de orden y es importante que recuperes todos los documentos que coinciden, debes intentar asegurarte de que tu búsqueda no muestre más resultados que los que puedes ordenar.

Escritura de expresiones

Las expresiones se usan para definir expresiones de campo (que se establecen en las `QueryOptions`) y ordenar expresiones, que se establecen en las SortOptions. Se escriben como strings:

"price * quantity"
"(men + women)/2"
"min(daily_use, 10) * rate"
"snippet('rose', flower, 120)"

Las expresiones que incluyen campos de número pueden usar los operadores aritméticos (+, -, *, /) y las funciones numéricas incorporadas detalladas a continuación. Las expresiones que incluyen campos de puntos geográficos pueden usar las funciones de punto geográfico y distancia. Las expresiones para campos de texto y HTML pueden usar la función de fragmento.

Las expresiones también pueden incluir estos términos especiales:

Término Descripción
_rank La propiedad de clasificación. Se puede usar en expresiones de campo y expresiones de orden.
_score La puntuación asignada a un documento cuando incluye un MatchScorer en SortOptions. Este término solo puede aparecer en expresiones de orden; no puede usarse en expresiones de campo.

Funciones numéricas

Las expresiones que definen valores numéricos para FieldExpressions y SortExpressions pueden usar estas funciones incluidas. Los argumentos deben ser números, nombres de campos o expresiones que usen números o nombres de campos.

Función Descripción Ejemplo
max Muestra el mayor de sus argumentos. max(recommended_retail_price, discount_price, wholesale_price)
min Muestra el menor de sus argumentos. min(height, width, length)
log Muestra el algoritmo natural. log(x)
abs Muestra el valor absoluto. abs(x)
pow Toma dos argumentos numéricos. La llamada pow(x, y) calcula el valor de x elevado a la potencia y. pow(x, 2)
count Toma un nombre de campo de su argumento. Muestra el número de campos en el documento con ese nombre. No olvides que un documento puede contener múltiples campos o tipos diferentes con el mismo nombre. Nota: count solo puede usarse en FieldExpressions. No puede aparecer en SortExpressions. count(user)

Funciones de puntos geográficos

Estas funciones pueden usarse para expresiones que incluyen campos de puntos geográficos.

Función Descripción Ejemplo
geopoint Define un punto geográfico con una latitud y longitud determinadas. geopoint(-31.3, 151.4)
distance Calcula la distancia en metros entre dos puntos geográficos. Ten en cuenta que cualquiera de los dos argumentos puede ser el nombre de un campo de punto geográfico o una invocación de la función de punto geográfico. Sin embargo, solo un argumento puede ser un nombre de campo. distance(geopoint(23, 134), store_location)

Fragmentos

Se refiere a un fragmento de un campo de texto que coincide con una cadena de consulta y abarca el texto que lo rodea. Los fragmentos se crean llamando a la función snippet:

snippet(query, body, [max_chars])

query
Una cadena de consulta entrecomillada que especifica el texto que debe encontrarse en el campo.
body
El nombre de un campo de texto, HTML o atómico.
max_chars
La cantidad máxima de caracteres para mostrar en el fragmento. Este argumento es opcional, la cantidad predeterminada es de 160 caracteres.

La función muestra una string HTML. La string contiene un fragmento del valor del campo de cuerpo, con el texto que coincidió con la consulta en negrita.

¿Te ha resultado útil esta página? Enviar comentarios:

Enviar comentarios sobre...

Entorno estándar de App Engine para Java 8