API Overview

Query Syntax Overview

A query is composed of one or more clauses, each specifying a condition to filter documents. Queries follow the Lucene query syntax.

• Simple Clause: A clause can reference an attribute and its expected value, such as genre: action, which will search for documents where the genre is action
• Compound Clauses: Multiple clauses can be combined using conditional operators like AND or OR:
  • AND/&&/&: Ensures both conditions are met. For example, genre: drama AND director: Nolan or genre: drama && director: Nolan or genre: drama & director: Nolan returns documents matching both genre: drama and director: Nolan
  • OR/||/|: Requires at least one condition to be met. For instance, genre: drama OR crime or genre: drama || crime or genre: drama | crime will return documents that match either genre: drama or genre: crime
  • NOT/!/-: Excludes documents that meet a certain condition. For example, title: Normandy NOT Operation or title: Normandy ! Operation or title: Normandy -Operation will return documents where the “title” contains the term Normandy, but not Operation
    
    

    📘 For compound clause our current version supports AND operator for searching on different fields, OR and NOT are supported for the same field search only.

    For an example you can search like this:

    title:Superman returns OR Operation Normandy NOT Overload

    and this:

    title:Superman returns AND genre:drama AND director:Richard Donner

    But not like this:

    title:Superman returns OR genre:crime NOT director:Christopher Nolan

• Exact Match: When searching for a specific phrase or multiple words, wrap the value in double quotes (”). For example, title:"All quiet on the western front" searches for documents with the exact title all quiet on the western front
• Lists of Values: Clauses can include multiple values. For example, genre: comedy drama retrieves documents where the genre is either comedy or drama

Wildcard Searches:

Admin search supports single and multiple character wildcard searches within single terms (not within phrase queries).

• To perform a single character wildcard search use the `? symbol.
• To perform a multiple character wildcard search use the ”*” symbol.
• The single character wildcard search looks for terms that match that with the single character replaced. For example, to search for text or test you can use the search:
  te?t
• Multiple character wildcard searches look for 0 or more characters. For example, to search for test, tests or tester, you can use the search:
  test*
• We can also use wildcard searches in the middle of a term.
  te*t
  Note: You cannot use a * or ? symbol as the first character of a search.

Example

Multiple character search:

curl -X GET \
'https://manage.api.{environment}.vmnd.tv/v1/search?query=Operation*&sortOrder=desc&sortBy=create-time&types=asset%2Ccategory' \
--header 'Content-Type: application/json' \
--header 'Authorization: <auth_token>'

Single character search:

curl -X GET \
'https://manage.api.{environment}.vmnd.tv/v1/search?query=N?rmandy&sortOrder=desc&sortBy=create-time&types=asset%2Ccategory' \
--header 'Content-Type: application/json' \
--header 'Authorization: <auth_token>'

Fuzzy Searches:

We support fuzzy searches based on the Levenshtein Distance, or Edit Distance algorithm.

• To do a fuzzy search use the tilde, ~, symbol at the end of a Single word Term. For example to search for a term similar in spelling to “moon” use the fuzzy search:
  moon~
• This search will find terms like main, moon, maroon
• parameter can specify the required similarity. The value is between 0 and 1.
• With a value closer to 1 only terms with a higher similarity will be matched. For example:
  moon~0.8

Example :

curl -X GET \
'https://manage.api.{environment}.vmnd.tv/v1/search?query=moon~&sortOrder=desc&sortBy=create-time&types=asset%2Ccategory' \
--header 'Content-Type: application/json' \
--header 'Authorization: <auth_token>'

• Negation: A clause can be negated using a minus sign (-) before the clause. For example, genre:-Comedy searches for all genres except Comedy

Sorting

sortOrder parameter is being used in combination with sortBy to sort the result in ascending or descending order. sortBy parameter is used for sorting search results based on a specific attribute.

Allowed values for sortOrder is asc desc

asc: sort in ascending order
desc: sort in descending order

Allowed values for sortBy are title create-time live-broadcast-time or update-time

default is ""(content sorted by relevance)

• create-time: timestamp the content was created at
• update-time: timestamp the content was updated at
• title: content title
• live-broadcast-time: only relevant for assets, content sorted by broadcast time

Example:

Search through all the existing assets by entering passing search words as query parameter and the response will be sorted based on create-time field in descending order:

curl -X GET \
'https://manage.api.{environment}.vmnd.tv/v1/search?query=Killers%2520Of%2520The%2520Flower%2520Moon&sortOrder=desc&sortBy=create-time&types=asset' \
--header 'Content-Type: application/json' \
--header 'Authorization: <auth_token>'


# search in ascending order based on update-time on all assets, categories and contentpanels
curl -X GET \
'https://manage.api.{environment}.vmnd.tv/v1/search?query=Killers%2520Of%2520The%2520Flower%2520Moon&sortOrder=asc&sortBy=update-time' \
--header 'Content-Type: application/json' \
--header 'Authorization: <auth_token>'

Pagination

To handle search requests that return a large number of documents, the API supports pagination using the from and size query parameters.

from: The starting index for the search results, default value is 0
size: Indicates the number of results to be returned per page. The default value is 25

Example:

Search for assets, categories and contentpanels and the first 10 results will be returned.

curl -X GET \
'https://manage.api.{environment}.vmnd.tv/v1/search?from=0&size=10' \
--header 'Content-Type: application/json' \
--header 'Authorization: <auth_token>'

Limitations

While the API provides powerful search capabilities, there are a few constraints to keep in mind when constructing your queries. Understanding these limitations will help you use the API more effectively and avoid unsupported query structures.

• No Mixing of Operators Across Fields: Although the API uses a syntax similar to Lucene, it doesn’t allow combining different operators across separate fields. For example, you can’t use a query like title:"Easy Company" AND genre:war OR director:Nutter. You’ll need to structure your query more simply, focusing on one operator at a time.
• No Grouping of Conditions: The API doesn’t support grouping conditions using parentheses. This means you can’t nest or group parts of your query, like ((title:"Band of Brothers" AND genre:war) OR director:Nutter) or like (title:"Band of Brothers" AND genre:war). Each condition has to be written separately without using parenthesis () .
• No Boosting a Term: Though Lucene allows to boost a term using the caret, ”^”, symbol with a boost factor (a number) at the end of the term you are searching, our admin search API is not supporting this feature right now, though using the caret (^) won’t result to any error the search results may not be what you really expect. Currently the results are boosted by title by default.
• No Range Queries : Range Queries allow matching documents where field values fall between specified lower and upper bounds. These queries can include or exclude the upper and lower bounds. Sorting of the results is done lexicographically. Our API currently doesn’t support this feature.