BROWSE CATDV SUPPORT MANUALS

The CatDV REST API supports a rich set of queries that can be applied to the collection of clips on the server. The clip filter query is passed as the ‘filter’ URL parameter in the GET method of the ‘clips’ endpoint.

Because of the requirement to pass the filter query as a URL parameter many of the symbols that might normally be used to represent a query (such as space, ‘=’ ,‘&’ and ‘”’) are not available. It would be possible to escape these symbols, but this would make it difficult to manually type queries, which is very useful for testing. Therefore the syntax chosen uses textual representations for all operators and encloses every element in round brackets.

A filter query consists of any number of clauses. The format of each clause is:

[and|or|andNot|orNot]((<field_specifier>)<operation>(<value>))

e.g.

and((clip.name)HAS(car))and((catalog.name)EQ(Race Day))

The ‘and’,‘or’,’andNot’ and ‘orNot’ prefix specifies the conditionality of this clause. Where multiple clauses are present all ‘and’ clauses must evaluate to true and at least one ‘or’ clause must evaluate to true.

Field Specifier

The field specifier determines which field the filter clause will test.

The specifier consists of two parts – the object name and the field name e.g.

clip.name
tape.description

The object name may be omitted for the fields of clip object itself. For other objects the name refers to the objects associated with a given clip. In the above example ‘tape’ refers to the TapeInfo object associated with a given clip.

Supported values are:

Object Field Type
clip ID INT
clip name STRING
clip tape STRING
clip notes TEXT
clip in INT_FRAMES
clip out INT_FRAMES
clip duration INT_FRAMES
clip in2 INT_FRAMES
clip out2 INT_FRAMES
clip duration2 INT_FRAMES
clip bin STRING
clip good CHAR
clip recordedDate DATETIME
clip importNotes TEXT
clip type INT
clip seq INT
clip transition STRING
clip modifiedDate DATETIME
clip gmtDate DATETIME
clip marked BOOL
clip hidden BOOL
clip format STRING
clip tcFmt INT
clip text TEXT
clip anytext TEXT
clip clockAdjust STRING
clip tapeName STRING
clip clipref STRING
clip status STRING
clip history TEXT
clip events TEXT
clip bigNotes TEXT
clip rating INT
clip userFields (see notes below)
media ID INT
media meatadata TEXT
media mediaDate INT
media audioFormat STRING
media videoFormat STRING
media importer STRING
media technical STRING
media fileDir STRING
media fileName STRING
media filePath STRING
media archiveStatus STRING
media aspectRatio FLOAT
media fileSize INT
catalog ID INT
catalog name STRING
catalog notes TEXT
catalog createdDate DATETIME
catalog extendedDate DATETIME
catalog savedDate DATETIME
catalog publishedDate DATETIME
tape name STRING
tape description TEXT
tape notes TEXT
tape location STRING
tape format STRING
tape history TEXT
tape reel STRING
tape videographer STRING
tape project STRING
tape status STRING
tape subject STRING
tape media STRING
tape createdDate DATETIME
tape loggedDate DATETIME
tape modifiedDate DATETIME
importSrc ID INT
importSrc metadata TEXT
importSrc filename STRING
importSrc importDate DATETIME
event name INT
event description TEXT
event metadata TEXT
event history TEXT
event startDate DATETIME
event endDate DATETIME

 Notes – Referencing User Defined Fields

You can reference user defined fields in queries using the following syntax:

clip.userFields[<field_identifier>]

or for SourceMedia or ImportSource objects:

[media|importSource].metadata[<field_identifier>]

Where <field_identifier> is the identifier of the FieldDefinition of the user defined field. For example to test whether field ‘default.animal’ contains the text ‘seal’ you would use:

((clip.userFields[default.animal])has(seal))

The type of the field will depend on how it has been defined and this will affect what operators are valid on that field as per that above table.

Operation

The ‘operation’ part of the clause specifies a comparison operator to be applied between the field and the value.

Supported operations are:

Operator Meaning
eq The field is equal to value
le The field is less than or equal to the value (numeric/date fields only)
ge The field is greater than or equal to the value (numeric/date fields only)
has The field contains the value (text fields only)
startsWith The field starts with the value (text fields only)
endsWith The field end with the value (text fields only)
isBlank The field is blank. Takes empty parameter e.g. ((notes)isBlank()) – (text fields only
isOneOf The field equals one of the specified values (comma separated) (text fields only)
hasOneOf The field contains one of the specified values (comma separated) (text fields only)
hasAll The field contains all of the specified values (comma separated) (text fields only)
between The date is between the two specified dates (comma separated) values (date fields only – dates specified in milliseconds since 1/1/1970)
older The date is older than the specified length of time (in seconds)
newer The date is newer than the specified length of time (in seconds)

 

Escaping Values

The value part of the clause contains the literal value enclosed in round brackets.

Strings do not have quotation marks around them.  Strings that contain bracket characters should have the following substitutions applied:

Character Escaped value
( ~28
) ~29
~ ~7E

Include Associated Data

The clip query methods take an ‘include’ parameter that specifies what related data should be included in the result set. The parameter is a comma separated list that can contain any of the following values:

Value Include
importSource Clip’s Import Source
userFields Clip’s User Fields
metadata Metadata associated with Clip’s Source Media
history History of operations performed on clips
markers Event markers
tapeinfo Tape Information

Fetch Related Data

The clip query methods take a ‘fetchRelated’ parameter that tells the server to include in the result set clips that are related to the clips that match the query. The possible values of fetchRelated are:

Value Meaning
true Return the component clips of any sequences in the result set and any members of any metaclips. These value is implied if any of the other fetchRelated values listed below are specified.
sameTape Include all clips that are from the same tape as any of the matching clips.
sameCatalog Include all clips that are in the same catalog as any of the matching clips.
similarDate(d) Include all clips with a date within ‘d’ days of the matching clips.
similarTimecode(f) Include all clips with an in or out point within ‘f’ frames of the matching clips.
sameFields(f1,f2,..) Include all clips with where all the specified fields match the same field of the matching clips. (see Field Specifiers above for format of f1, f2, etc.)