Understanding Imagen Query Language 👨‍🏫

Overview

• How a query is constructed
  • Example syntax
• Additional metadata parameters
  • Building metadata parameters

    • Example syntax

  • Free Text Fields
    • Exact match
    • Partial Match

    • Conditional Operators

• Adding your Metadata Parameter to your query statement

• Additional considerations for related records imagen query language statements
• Querying dates in Imagen query language
  
  

How a query is constructed

WHERE is the foundation of any query as it will establish the conditions of your query. You can then use the following code to refine the parameters of your search:

media.State = 'Archived' / 'Failed'

Where

‘Archived’ identifies records that have media files stored against them

'Failed' indicates that a problem has taken place during ingestion - troubleshooting guide

AND identifies an additional parameter

media.ParentID = null } identifies records that are not segments or children created from other records

ORDER BY indicates an order by which to display results:

Where

DESC for descending order, with the highest value first

ASC for ascending order, with the lowest value first

Date is the field by which the results will be ordered

LIMIT {n} establishes the total number of items to load, where n is the number

Example syntax

• WHERE Field = 'value'
• WHERE Field = 'value' LIMIT 100
  • Updating the Limit of results will increase or decrease the number of media items shown across widget pages
• WHERE Field = 'value' ORDER BY Date ASC 
  • Changing the ORDER BY from DESC to ASC will instead sort by the smallest value first
• WHERE Field = 'value' ORDER BY Field
  • Changing the field used to ORDER BY to a text field will order Alphanumerically 

ADDITIONAL METADATA PARAMETERS

Building Metadata Parameters

The Imagen Query Language is scalable so you can easily add additional parameters to selectively display specific cross-sections of your media. The added parameters will query your media’s metadata to identify it, so it is important to know your metadata field names and associated values.

Example syntax

Field_Name = ‘value’ will return results matching that criteria, e.g. 

Colour = ‘blue’ 

This will return a match if you have a metadata field called 'Colour' and media with the value of 'blue' in your system.

Free Text Fields

When querying a free-type text field (Title field or a Description/Summary, as an example), you can specify multiple separate keywords (with commas) to search for or specify an exact sequence of those words to display.

Exact match
This query will only return results where both words exist within that field,  As an example, Title = “rock candy” will only show the results where both words are specified in that order, with no words in between, so only “Rock Candy sales Soar” will not be returned

Field_Name = ‘value1’ 

Partial Match

The following query will return results where both words feature in the title, regardless of their order, including results like ‘Rock Candy Sales Soar’ and ‘Boy loses Candy at Rock Concert’

Field_Name = “value1 value2”

Conditional Operators

Instead of using the equals = operator conditions using the following parameters instead of the straight equals (=) operation. These include:

-> Returns numerical values or dates that are greater than the specified condition

{some_field} -> {Value}

-< Returns numerical values or dates that are less than the specified condition

{some_field} < {Value}

!= excludes the metadata value you are specifying. For example, where something is not equal to. 

!={some_field} != {Value}

Adding your Metadata Parameter to your query statement

To add the Metadata Parameter to your Imagen Query Language statement, you will need to use the following structure:

 AND Field_Name = ‘value’

The additional metadata parameter must be included between the media.ParentID and the ORDER BY parts of your query (as per the below). Including them, anywhere else may return different results (as your added parameter may not be considered in your query).

WHERE media.State = 'Archived' AND media.ParentID = null AND Field_Name = ‘value’ ORDER BY Date DESC LIMIT 4

You may add multiple Metadata Parameters to further drill down your content

AND (Field_Name = ‘Value1’ OR Field_Name = ‘Value2’) ; 

Additional considerations for related records imagen query language statements

For Related Records, the notion of a token, or variable value is introduced. This understands the value of the field from the current page you are visiting and applies it to your search. A token is expressed by surrounding the Field_Name with % either side instead of a value, give the following style of structure:

WHERE Field_Name = %Field_Name%

When configuring a Related Record query, you can use static values, though these will be the same across all your records pages. This is why you would rather want a formula such as

WHERE Colour = %Colour% 

to display all records which are the same colour as the one you are

viewing, rather than

WHERE Colour = ‘Blue’ 

which would only ever display Blue records regardless of the record you are currently viewing, making them less ‘related’ . You can amend the wording of Related Media in some themes to support this change in purpose.

Querying dates in Imagen query language

If you wish to present a cross-section based on dates (e.g. a ‘This day in history’ style of feature), Imagen Query Language supports:

• DATE(
• DAYOFYEAR(
• DAYOFMONTH(
• DAYOFWEEK(
  
  
• NOW(

This allows you to build statements which only interpret certain aspects of the date stored against your media, and should be used in the following format: DATE(Field_Name) = DATE(NOW())

The NOW() operator acts as a variable which prints the current date & time. To present all records marked as this calendar date, you would need to use the following format: DAYOFYEAR(fieldClass.Date) = DAYOFYEAR(NOW())