Skip to main content

How to query a knowledge box

Search parameters​

Query​

Simple query​

A simple text search can be performed using a plain text value.

Example:

This query would return results containing the words little and prince:

Little Prince

By putting words into quotes, you can search for an exact match:

"Little Prince"

In that case, you will get only results containing the word sequence little prince.

Using the minus sign - in front of a word, you can exclude a word from the search:

Little Prince -sheep

This query would return results containing the words little and prince but not sheep.

Filters​

The filters parameter allows to filter the results depending on the value of different attributes.

The following attributes are supported:

  • t: resource tags
  • l: resource labels
  • n: type of element i (Icon)
  • e: entities e/type/entityid
  • s: languages (p for principal, and s for all languages)
  • u: contributors (s for source and o for origin)
  • p: paragraph labels

Examples:

  • To retrieve PNG images only, use:

    filters=/n/i/image/png

  • To retieve results which principal language is Italian, use:

    filters=/s/p/it

  • To retrieve results referring to the UNESCO organization entity, use:

    filters=/e/ORG/UNESCO

Filters can be combined by repeating the filters parameter:

filters=/u/Eric&filters=/n/i/application/pdf

Search in a specific field​

To restrict the search to a specific field, you can use the field parameter. It supports different field types:

  • a: generic fields (= basic attributes, like title or summary)
  • t: text fields
  • f: file fields
  • u: link fields

Example:

fields=a/title

To search in several fields, the parameter can be repeated:

fields=a/title&fields=a/summary

Regarding content fields, when used through the resource /search endpoint, it allows to restrict the search to one content only and when used through the main /search endpoint, it allows to restrict the search to all contents having a given id in all resources.

Structured query​

Logical operators and grouping​

Nuclia supports logical operators and parenthesis grouping to create structured queries.

Examples:

Catwoman OR "Selina Kyle"
(Catwoman OR "Selina Kyle") AND Gotham

Term boosting​

You can boost a term using the ^weight syntax.

Example to boost results mentioning Selina Kyle compare to results mentioning Catwoman:

"Selina Kyle"^5 OR Catwoman^0.5

Result options​

Features​

A search query can be executed against different targets. The target is defined by the features parameter which supports 4 values:

  • document: the query is executed as full-text search against all resources texts (including attributes like title or summary, and all content fields). The result will contain fulltext (listing text sequences matching the query) and resources (listing resources matching the query).
  • paragraph: the query is executed as fuzzy search against all paragraphs texts. The result will contain paragraphs (listing paragraphs matching the query) and resources (listing resources containing these paragraphs).
  • vector: the query is executed as semantic search against all resources texts. The result will contain sentences (listing sentences semantically close to the query) and resources (listing resources containing these sentences).
  • relations: the query is executed as graph search against all resources entities. The result will contain resources (listing resources related to the entities identified in the query).

These features can be combined by repeating the features parameter:

features=document&features=vector

Facets​

By using the faceted parameter, you will get a facets attribute in paragraphs, sentences and fulltext.

This parameter takes the same values as the filters parameter.

Examples:

  • To get total amount of matches for each image file type (like jpg, png, gif, etc.), use:

    faceted=/n/i/image

  • To get total amount of matches for each language (like en, it, fr, etc.), use:

    faceted=/s/p

Highlight matching words​

By setting the split parameter to true, you will get start and end positions of each matching word in paragraphs and fulltext results.

If, in addition, you set the highlight parameter to true, the matching words are enclosed into <mark> tags.

How to call the search endpoint​

API

To search in all resources, the search endpoint path is:

https://<zone>.nuclia.cloud/api/v1/kb/<your-knowledge-box-id>/search

Search endpoint must be call with a GET request.

A typical curl command to call the search endpoint is:

https://<zone>.nuclia.cloud/api/v1/kb/<your-knowledge-box-id>/search?query=Batman&features=document&features=paragraph

If your knowledge box is not public, you must provide the X-STF-Serviceaccount header with the service account token or an Authorization header.

To search in a specific resource, the search endpoint path is:

https://<zone>.nuclia.cloud/api/v1/kb/<your-knowledge-box-id>/resource/<resource-id>/search

Reference documentation​

The Nuclia API documentation is available here.