Query Syntax

The Content API uses a query language based on Lucene syntax.

Syntax

A query string is made up of any number of terms and operators. A term can be a single word (like panda or cub), or a phrase surrounded by double quotes (like "panda cub"). For an object to match the query, it must contain all terms.

panda           # search for the word 'panda'
"panda cub"     # search for the phrase 'panda cub'

Query operators will further customize the search result. This page lists the available options.

Field names

If no field name is specified for the query, matching is done against all free text fields plus a few 'special' fields (mostly fields used to identify an object, like uri, slug and originaltransmissionreference). To match only against a given field, use the field name operator:

headline:panda        # search for 'panda' in headline
headline:"panda cub"  # search for the phrase 'panda cub' in headline

Boolean operators

Search terms can be combined using AND OR and NOT, and grouped with parentheses.

panda AND cub                         # find baby pandas
crane NOT bird                        # find construction cranes
((panda AND cub) OR (crane NOT bird)) # find either pandas or cranes

Additionally, you can use + and - in a free text query to signify words that must or must not occur in the matched text. It is roughly equivalent to the boolean operators above, but sorting (if you are sorting by relevance) may be affected. Do note that since an object must match all terms anyway, using the + operator is largely redundant.

+panda +cub     # reduntantly find baby pandas as above
pada cub        # a simpler way of writing the same query
crane -bird     # find construction cranes as above

Finally, field values can also be grouped using boolean operators:

type:(picture OR video)

Wildcards

? matches a single character in a text field, and * matches zero or more characters.

St?ck                # Matches Stick, Stock, Stack, etc.
Stock*               # Matches Stockholm, Stockholder, Stocking, etc.
headline:Stock*      # As above, but only search the headline field

Regular expressions

Regular expressions can be used for matching, and must be enclosed by forward slashes:

/Agent 00\d+/               # Find any agent with 00 clearance
person.name:/Agent 00\d+/   # As above, but only search person.name

Ranges

Ranges are specified using the [x TO y] (inclusive) and {x TO y} (exclusive) expressions. They can be used with most field types, but are most useful for matching date and numeric fields. The character * signifies a open-ended range.

versioncreated:[2019-01-01 TO 2019-01-31] # inclusive
versioncreated:{2019-01-01 TO 2019-01-31} # exclusive
versioncreated:[2019-01-01 TO 2019-01-31} # inclusive + exclusive

urgency:[2 TO 3]    # urgency 2 or 3
urgency:[2 TO *]    # urgency from 2 and up

Open-ended ranges can also be specified using <, >, <= and >=:

versioncreated:>2019-01-01
urgency:<=2
urgency:>1

Relative dates

Relative date expressions start with either the keyword now (representing the current UTC time in milliseconds) or a date string ending with ||. It is followed by zero or more date match expressions:

• +1h - Add one hour
• -1w - Subtract one week
• /d - Round down to the nearest day

Supported time units:

Examples of relative date queries:

versioncreated:>now-1w      # documents created since last week
versioncreated:>now/d       # documents created since midnight
verisoncreated:[now-2w TO now-1w]

Exists query

To check if a field exists you can use either: _exists_:<field> or field:*

_exists_:slug
slug:*

Searchable fields

The following fields are available for matching TTNinjs documents. Some fields are only applicable certain media types.

Searchable subobjects

Many objects in the database also contain nested subobjects. Some fields of these subobjects are searchable using a dotted notation:

This way you can search for objects related to given organisations, places, people, or having certain product codes.

product.code:TTINR*          # find objects with product starting with TTINR
person.name:"Göran Persson"  # find objects related to Göran Persson

The associations and assignments subfields are themselves TTNinjs objects, and all fields listed above are also available for searching, if prefixed with associations. and assignments. respectively.

This query finds all object with an association of type picture:

associations.type:picture
associations.type:(picture OR video)

The renditions field is currently not searchable.

Geographical areas

Some documents have coordinates in its metadata representing the geographical place the document is associated with. You can search for documents with coordinates within a given geographical area. There are two types of areas: 'county' and 'municipality'. To do this, provide the area type and the numeric code (?) for the area to search in:

place.geo:county-23            // find documents with coordinates within Jämtlands län

place.geo:municipality-0115    // find documents with coordinates within Vallentuna kommun