API de búsqueda

Este documento describe la API de búsqueda v2 de Fess. Para el sobre de respuesta común, el modelo de errores y CSRF, consulte Descripción general de la API.

La URL base es http://<Server Name>/api/v2/ (ejemplo en entorno local: http://localhost:8080/api/v2).

El parámetro q admite la misma sintaxis de búsqueda que la pantalla de búsqueda habitual (búsqueda AND/OR/NOT, especificación de campos, comodines, búsqueda difusa, etc.). Para obtener más información sobre la sintaxis de búsqueda, consulte Guía de Usuario de Fess.

Búsqueda de documentos

Solicitud

Método HTTP GET
Endpoint /api/v2/search

Busca documentos que coincidan con la consulta y devuelve los resultados en el sobre común. Todos los nombres de campo del payload usan snake_case.

Parámetros de solicitud

Parámetros de solicitud
q Término de búsqueda (codificado en URL). La longitud máxima está limitada por api.param.max.length (valor predeterminado: 1000). Si se supera, se produce un error invalid_request (HTTP 400). Este límite es independiente de los límites del motor de búsqueda.
start Posición de inicio desde 0 (integer, >=0, valor predeterminado 0).
offset Desplazamiento desde start (integer, >=0, valor predeterminado 0).
num Tamaño de página (integer, >=1, valor predeterminado 10). <= 0 resulta en invalid_request. Los valores que superen el máximo configurado se ajustan silenciosamente. El ajuste puede detectarse comparando num en la solicitud con page_size en la respuesta.
sort Ordenación (ejemplo: score).
lang Idioma de búsqueda. Se puede repetir (array). Ejemplo: en.
ex_q Expresión de consulta adicional. Se puede repetir.
sdh Hash de documentos similares (similar-document hash).
fields.label Filtra por nombre de etiqueta. Se puede repetir. Este es el caso más común de la familia genérica fields.<name>: cualquier parámetro de consulta fields.<name> limita los resultados a documentos donde el campo <name> coincide con el valor especificado.
as.* Condiciones de búsqueda avanzada. Cualquier as.<name> (ejemplo: as.q, as.filetype) se pasa al constructor de condiciones de búsqueda avanzada. Se puede repetir por nombre.
track_total_hits Se reenvía al motor de búsqueda para controlar el recuento exacto de resultados (ejemplo: true o un umbral entero). Afecta si record_count_relation es EQUAL_TO o GREATER_THAN_OR_EQUAL_TO. false no se acepta y produce invalid_request.
facet.field Campo de faceta. Se puede repetir (array).
facet.query Consulta de faceta. Se puede repetir (array).
facet.size Número máximo de términos de faceta a devolver (integer, >=1). Cuando se indica junto con facet.field o facet.query, un valor de 0 o menos y un valor que no es un entero producen invalid_request (HTTP 400). Un valor superior a query.facet.fields.size.max (por defecto 1000) se limita silenciosamente.
facet.minDocCount Número mínimo de documentos que debe contener un término de faceta (integer). Cuando se indica junto con facet.field o facet.query, un valor que no es un entero produce invalid_request.
facet.sort Ordenación de facetas.
facet.missing Tratamiento de facetas para documentos sin valor.
geo.location.point Punto central de coordenadas geográficas (ejemplo: 35.0,139.0).
geo.location.distance Distancia desde el punto central (ejemplo: 10km).

Tabla: Parámetros de solicitud

Respuesta

En caso de éxito (200), se devuelven los siguientes campos directamente bajo response del sobre común.

{
  "response": {
    "status": 0,
    "q": "Fess",
    "query_id": "f8b1c2d3e4a5",
    "exec_time": 0.012,
    "query_time": 8,
    "page_size": 20,
    "page_number": 1,
    "record_count": 42,
    "record_count_relation": "EQUAL_TO",
    "page_count": 3,
    "highlight_params": "&hq=Fess",
    "next_page": true,
    "prev_page": false,
    "start_record_number": 1,
    "end_record_number": 20,
    "page_numbers": ["1", "2", "3"],
    "partial": false,
    "timed_out": false,
    "shard_failed": false,
    "search_query": "title:Fess OR content:Fess",
    "requested_time": 1717142400000,
    "related_query": ["enterprise search"],
    "related_contents": [],
    "data": [
      {
        "doc_id": "a1b2c3d4e5f6",
        "url": "https://example.com/",
        "title": "Example",
        "content_description": "An example document about Fess.",
        "score": 1.2345
      }
    ],
    "facet_field": [
      {
        "name": "label",
        "result": [
          { "value": "news", "count": 12 }
        ]
      }
    ],
    "facet_query": [
      { "value": "filetype:html", "count": 30 }
    ],
    "permission_state": "RESOLVED"
  }
}

Los campos son los siguientes:

Campos de respuesta
q Término de búsqueda (nullable).
query_id Identificador de la consulta.
exec_time Tiempo de ejecución (double, en segundos).
query_time Tiempo de consulta del motor de búsqueda (int64, en milisegundos).
page_size Tamaño de página.
page_number Número de página actual.
record_count Número de resultados encontrados (int64). El recuento exacto solo se calcula hasta query.track.total.hits (predeterminado: 10000); si hay más resultados, este valor es ese límite y record_count_relation es GREATER_THAN_OR_EQUAL_TO. El límite se puede cambiar en cada solicitud con track_total_hits.
record_count_relation Cuando es EQUAL_TO, indica un recuento exacto; cuando es GREATER_THAN_OR_EQUAL_TO, indica que solo se conoce el límite inferior.
page_count Número total de páginas.
highlight_params Cadena de parámetros de consulta para resaltado.
next_page Si existe página siguiente (bool).
prev_page Si existe página anterior (bool).
start_record_number Número de registro de inicio de esta página.
end_record_number Número de registro de fin de esta página.
page_numbers Array de números de página para mostrar en el paginador (cadenas de texto).
partial Si los resultados pueden ser parciales (bool). Siempre es true cuando timed_out o shard_failed es true; también puede ser true sin que lo sea ninguno de los dos, por ejemplo cuando no se pudo ejecutar la búsqueda.
timed_out Si se agotó el tiempo de espera de la consulta (query.timeout) y el motor de búsqueda dejó de recopilar resultados (bool).
shard_failed Si fallaron uno o más shards (bool).
search_query La consulta de búsqueda que se ejecutó realmente.
requested_time Hora de la solicitud (int64, epoch en milisegundos).
related_query Array de consultas relacionadas (cadenas de texto).
related_contents Array de contenidos relacionados (cadenas de texto).
data Array de resultados de búsqueda. Un elemento por documento. Solo se incluyen los campos permitidos por QueryFieldConfig#isApiResponseField; se excluyen los nulos y las claves vacías.
facet_field Array que solo existe cuando se solicitaron campos de faceta. Cada elemento tiene la forma {name, result:[{value, count}]}.
facet_query Array que solo existe cuando se solicitaron consultas de faceta. Cada elemento tiene la forma {value, count}.
permission_state Indica si se han resuelto los permisos de grupo y de rol del usuario que busca (RESOLVED, PENDING o FAILED). PENDING (todavía se están resolviendo) y FAILED (han fallado o solo se han resuelto en parte) significan que el usuario tiene menos permisos de los que debería, por lo que los resultados pueden omitir documentos que el usuario debería poder ver. Un invitado es RESOLVED.

Tabla: Campos de respuesta

Nota

Cuando un plugin envía la búsqueda a otro lugar en vez de ejecutarla (por ejemplo, un bang al estilo de DuckDuckGo como !g), la respuesta correcta contiene solo q y redirect_url. El cliente debe navegar a redirect_url.

Respuesta de error

Consulte Descripción general de la API para detalles del modelo de errores. Los estados HTTP que devuelve este endpoint son:

Respuesta de error
Código de estado Descripción
400 Bad Request Cuando la solicitud no es válida (por ejemplo, una consulta no válida, num de 0 o menos, un parámetro facet.* no válido o track_total_hits=false).
401 Unauthorized Cuando se requiere autenticación (el inicio de sesión obligatorio está habilitado y el llamante es anónimo, o la solicitud lleva un token de acceso no registrado o caducado).
405 Method Not Allowed Cuando el método HTTP no está permitido.
500 Internal Server Error Cuando se produce un error interno del servidor.
503 Service Unavailable Cuando el motor de búsqueda ha rechazado la búsqueda por falta de capacidad (respondió 429 o 503). error.code es service_unavailable y un encabezado Retry-After indica los segundos que hay que esperar (5). La consulta en sí es correcta, así que vuelva a intentarlo tras una breve espera.

Tabla: Respuesta de error

Obtención de todos los documentos (búsqueda por scroll - NDJSON)

Solicitud

Método HTTP GET
Endpoint /api/v2/documents/all

Transmite en streaming todos los documentos que coincidan con la consulta en formato NDJSON (application/x-ndjson). Cada línea es un objeto {"data":{...}} que contiene los campos permitidos por QueryFieldConfig#isApiResponseField. A diferencia de GET /search, no se incluye la puntuación de búsqueda score.

Si se produce un fallo a mitad del stream, se envía y vacía la siguiente línea como línea final:

{"error":{"code":"internal_error","message":"stream error"}}

Por este motivo, el cliente debe verificar la primera clave de la última línea para distinguir entre una finalización normal (data) y un error del servidor (error).

La consulta se construye con el mismo conjunto de parámetros que GET /search (q, sort, num, lang, ex_q, sdh, fields.*, as.*, track_total_hits, facet.*, geo.*). La búsqueda por scroll está deshabilitada de forma predeterminada (api.search.scroll=false). Mientras está deshabilitada, se devuelve invalid_request (400). Para habilitarla, establezca api.search.scroll=true en fess_config.properties (consulte Obtención Masiva de Resultados de Búsqueda).

Parámetros de solicitud

Los parámetros especificados explícitamente en la especificación son los siguientes:

Parámetros de solicitud
q Término de búsqueda.
sort Ordenación.
num Tamaño de página (lote de scroll) (integer, >=1). <= 0 resulta en invalid_request.
lang Idioma de búsqueda. Se puede repetir (array).
ex_q Expresión de consulta adicional. Se puede repetir (array).
fields.label Filtra por nombre de etiqueta. Se puede repetir (array). Forma parte de la familia genérica fields.<name> (consulte GET /search).
sdh Hash de documentos similares (similar-document hash).

Tabla: Parámetros de solicitud

Respuesta

En caso de éxito (200), el Content-Type es application/x-ndjson y se devuelve un documento por línea de la siguiente forma:

{"data":{"url":"https://example.com/","title":"Example"}}
{"data":{"url":"https://example.org/","title":"Example Org"}}

Respuesta de error

Consulte Descripción general de la API para detalles del modelo de errores. Los estados HTTP que devuelve este endpoint son:

Respuesta de error
Código de estado Descripción
400 Bad Request Consulta inválida, num <= 0, o búsqueda por scroll deshabilitada con api.search.scroll=false.
401 Unauthorized Cuando se requiere autenticación (el inicio de sesión obligatorio está habilitado y el llamante es anónimo, o la solicitud lleva un token de acceso no registrado o caducado).
405 Method Not Allowed Cuando el método HTTP no está permitido.
500 Internal Server Error Cuando se produce un error interno del servidor.

Tabla: Respuesta de error

Véase también