Imagen Query Language
      Back to home
      1. Knowledge Base
      2. Find
      3. Imagen Query Language

      Understanding Imagen Query Language 👨‍🏫

      Imagen Query Language is a search feature that uses a variety of parameters to narrow down results.

      Overview

      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 

      ⚡Pro tip: You can order your results by media.archivedTime instead. This will return the media most recently stored. This may help if you use your system to host multiple media files per record and routinely add content to pre-existing records.

      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.

      Metadata field names are not necessarily the display names visible in records. Metadata field names will not display spaces or punctuation, sometimes these are swapped for underscores. Always use proper metadata field names in your queries. ‘value’ refers to the metadata within that field.

      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.

      ⚠️Warning: Imagen query language uses single and double quotes to specify a partial or an exact match:

      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

      ⚡ Pro tip: An additional operator is available, to include a wider range of content, in the shape of OR. This allows you to showcase a wider collection of content based on metadata, as it will display results where one condition is true OR the other is true. OR statements should be held within brackets and preceded by an AND, as you will find different results if brackets are not included. This means the structure to follow is:

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

      this will return results where those two conditions are true (can be used for different fields for different cross sections or the same field for multiple values of that field, e.g. a multi select dropdown).

      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())