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 Fields
You can reference user fields in queries using the following syntax:
clip.userFields[Unn]
Where nn is the number of the user field. For example to test whether U3 contains the text ‘hello’ you would use:
((clip.userFields[U3])has(hello))
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.) |