Text Search

List endpoints support text searches. You can filter results by specifying text fragments to search for in the data.

This feature uses Apache Lucene to perform a text search on certain indexed properties, determined by the API and the database configuration. Usually, label properties such as rdfs:label and skos:prefLabel will be indexed.

Use the search query parameter to specify the text fragments to search for. To search for multiple terms, separate each term with a space. Only results whose text contains all of the specified terms will be returned.

You can use the wildcard character * in a text fragment to denote an arbitrary string of characters.

Search Modifiers

You can customise your search request by supplying the following parameters with the search parameter:

Parameter	Description
`fuzzy`	Performs a fuzzy text search for the supplied text fragments.
`raw-search`	Treats the supplied text as a raw Lucene query and directly performs the query.

The fuzzy and raw-search parameters are flags, so you don’t need to supply a value for them.

If you request a “raw” search, your search parameter value should be written in the Lucene query syntax.

Text Search Path

You can request a text search on related resources by supplying the searchPath parameter.

The parameter value should be a .-separated property path from the root resource to the set of related resources that you want to treat as the subject of the text search. Then you can specify the search terms with the search parameter as usual.

A text search path can be used in conjunction with the usual search modifiers.

This approach may be useful in cases where the root resources returned by the endpoint don’t have any text-indexed properties, but their related resources do.

Note

This feature is only available when the endpoint has defined views.

Multi-Field Text Index Support

The Jena text indexer creates a Lucene document for each indexed resource, and the document has a single field comprised by any number of RDF property values. As such, it’s not usually possible to query for a specific property.

However, the database may use a custom text indexer (eg. ppd-index), to maintain a multi-field text index, where each field corresponds to a certain RDF property. In this case, it’s possible to query each indexed property individually. This section explains how to request text searches on properties that are indexed in this way.

TODO - document in model-doc when a property is indexed

When dealing with a multi-field text indexes you have two options:

specify text search terms for one or more indexed properties using search-{property}={term} parameter instead of the usual search, or
specify a full raw query on the search root using the search={raw-query} parameter and raw-search flag.

If you supply both a search-{property} parameter and a searchPath parameter, the text search will be performed on the given property of the resources referenced by the given search path.

Examples

The following examples show some possible usages of the text search API:

Query	Meaning
`search={term}`	Return only results whose text contains the given term.
`search={term1%term2}`	Return only results whose text contains the given terms.
`search={term}&fuzzy`	Return only results whose text is similar to the given term.
`search={query}&raw-search`	Return the results of the given Lucene query.
`searchPath={path}&search={term}`	Return only results for which the related resource located by the given path contains the given term.
`search-{prop}={term}`	Return only results whose property contains the given term.