Search¶
Search items and collections¶
Items and collections be browsed and searched with a single request. This type of search essentially has the combined set of the functionality of item search and collection search.
Browse items and collections¶
-
GET
/search
¶ Browses items and collections.
Content Parameters: Matrix Parameters: - first – Integer, from resulting list of items, start return list from specified offset.
Default is
1
, start return list from beginning. - number – Integer, set a limit on maximum number of hits.
Default
100
.
Query Parameters: - count –
true
(default) - Return hits in result.false
- Do not return hits in result, in order to produce results faster.
- p –
Comma separated list of paths specifying the content to include. Overrides the content and filter parameters.
New in version 4.5.
- content – Comma-separated list of the types of content to retrieve,
possible values are
metadata
,uri
,shape
,poster
,thumbnail
,access
,merged-access
,external
. - interval –
Comma-separated list
- time-span - Filter out metadata, return only metadata for specified time span.
generic
- Return all non-timed metadata.all
(default) - Return all metadata, same asinterval=generic,-INF-+INF
- field –
Comma-separated list.
- field-name - Return specified field.
- field-name ”:” new-name - Return specified field, renamed to a new name in return value.
- “-” field-name - Exclude specified field.
- (default) - Return all fields.
- group –
Comma-separated list.
- group-name - Return specified group.
- group-name
+
- Return specified group and subgroups.New in version 4.1.
- group-name
:
new-name - Return specified group, renamed to a new name in return value. -
group-name - Exclude specified group.- (default) - Return all groups.
- language –
Comma separated list.
- language-tag -
Return metadata for specific language, e.g.
en_US
. Wildcards may be used, e.g.*_CA
for both Canadian French and Canadian English. none
- Return all metadata without language specification.all
(default) - Return all metadata, with or without language specification.
- language-tag -
Return metadata for specific language, e.g.
- sampleRate – Convert all outgoing time instants to specified rate. NB! Time codes which cannot be expressed in an integer number of samples will be returned as a decimal number, with risk of losing precision.
- track –
Comma separated list.
- track-type track-number -
Return metadata for specified track. Example of track is
A2
. - track-type t1
-
t2 - Return metadata for specified track interval, e.g.A2-4
. - track-type
*
- Return metadata for all tracks of specified type, e.g.A*
. generic
- Return all non-tracked metadata.all
(default) - All metadata, with or without track specification, are returned.
- track-type track-number -
Return metadata for specified track. Example of track is
- include – A list of keys. Includes additional field specific data.
Additionally, if set to
type
the type definition of the field will be retrieved. - includeValues – Return the value enumeration for each metadata field.
- conflict –
yes
(default) - Include all metadata conflicts, unresolved.no
- Return conflicts resolved according to field rules.
- terse –
yes
- Return metadata in terse format.no
(default) - Return metadata in verbose format.
- defaultValue –
true
- For unset fields, return default values.false
(default) - Do not return default values.
- includeTransientMetadata –
true
(default) - Include transient metadata.false
- Do not include transient metadata in response.
- revision – Optional revision, specifying which metadata to display. Only used if requesting a single item or collection.
- mergedType – The type of operation to check for.
- mergedPermission – The lowest required permission level.
- mergedExtradata – Any possible extradata.
- uriType – Optional comma-separated list of format types (container format) to return.
- scheme – URI scheme to return.
- storageType – Only return URIs for files from storages of this type.
- methodType –
Optional type of access method.
AUTO
- Gives an APInoauth URI to the media. Access to file is tunneled through Vidispine.AZURE_SAS
- If the storage schema is azure:// you can get direct access to the media. The resulting URI will not tunnel through Vidispine but rather point directly to the media location at the azure storage.
- methodMetadata – Optional metadata used with storage method.
- tag – A URI parameter: Optional comma-separated list of shape tags to return.
- version – Optional integer, specifying which essence version to return for shapes.
If special value
all
, display all versions. If special valuelatest
(default), display latest version of shapes. - closedFiles –
true
(default) - Return only URIs that point to closed files.false
- Return all URIs.
- noauth-url –
true
Return URIs that do not need authentication.false
(default) Return normal URIs
- baseURI – Which base URI to use for the thumbnail URLs.
- save –
true
- Returns a303 See Other
, with aLocation
header containing an URI to fetch the search resultfalse
(default) - Returns a regular search result
New in version 4.7.
Produces: - application/xml, application/json – SearchResultDocument
Role: _item_search
Role: _collection_read
- first – Integer, from resulting list of items, start return list from specified offset.
Default is
Search items and collections¶
-
PUT
/search
¶ Searches items and collections with a shared search query.
Note
This resource doesn’t support joint search, use
PUT /item
,PUT /search/shape
orPUT /search/file
for item, shape or file joint search respectively.Content Parameters: Matrix Parameters: - first – Integer, from resulting list of items, start return list from specified offset.
Default is
1
, start return list from beginning. - number – Integer, set a limit on maximum number of hits.
Default
100
.
Query Parameters: - count –
true
(default) - Return hits in result.false
- Do not return hits in result, in order to produce results faster.
- p –
Comma separated list of paths specifying the content to include. Overrides the content and filter parameters.
New in version 4.5.
- content – Comma-separated list of the types of content to retrieve,
possible values are
metadata
,uri
,shape
,poster
,thumbnail
,access
,merged-access
,external
. - interval –
Comma-separated list
- time-span - Filter out metadata, return only metadata for specified time span.
generic
- Return all non-timed metadata.all
(default) - Return all metadata, same asinterval=generic,-INF-+INF
- field –
Comma-separated list.
- field-name - Return specified field.
- field-name ”:” new-name - Return specified field, renamed to a new name in return value.
- “-” field-name - Exclude specified field.
- (default) - Return all fields.
- group –
Comma-separated list.
- group-name - Return specified group.
- group-name
+
- Return specified group and subgroups.New in version 4.1.
- group-name
:
new-name - Return specified group, renamed to a new name in return value. -
group-name - Exclude specified group.- (default) - Return all groups.
- language –
Comma separated list.
- language-tag -
Return metadata for specific language, e.g.
en_US
. Wildcards may be used, e.g.*_CA
for both Canadian French and Canadian English. none
- Return all metadata without language specification.all
(default) - Return all metadata, with or without language specification.
- language-tag -
Return metadata for specific language, e.g.
- sampleRate – Convert all outgoing time instants to specified rate. NB! Time codes which cannot be expressed in an integer number of samples will be returned as a decimal number, with risk of losing precision.
- track –
Comma separated list.
- track-type track-number -
Return metadata for specified track. Example of track is
A2
. - track-type t1
-
t2 - Return metadata for specified track interval, e.g.A2-4
. - track-type
*
- Return metadata for all tracks of specified type, e.g.A*
. generic
- Return all non-tracked metadata.all
(default) - All metadata, with or without track specification, are returned.
- track-type track-number -
Return metadata for specified track. Example of track is
- include – A list of keys. Includes additional field specific data.
Additionally, if set to
type
the type definition of the field will be retrieved. - includeValues – Return the value enumeration for each metadata field.
- conflict –
yes
(default) - Include all metadata conflicts, unresolved.no
- Return conflicts resolved according to field rules.
- terse –
yes
- Return metadata in terse format.no
(default) - Return metadata in verbose format.
- defaultValue –
true
- For unset fields, return default values.false
(default) - Do not return default values.
- includeTransientMetadata –
true
(default) - Include transient metadata.false
- Do not include transient metadata in response.
- revision – Optional revision, specifying which metadata to display. Only used if requesting a single item or collection.
- mergedType – The type of operation to check for.
- mergedPermission – The lowest required permission level.
- mergedExtradata – Any possible extradata.
- uriType – Optional comma-separated list of format types (container format) to return.
- scheme – URI scheme to return.
- storageType – Only return URIs for files from storages of this type.
- methodType –
Optional type of access method.
AUTO
- Gives an APInoauth URI to the media. Access to file is tunneled through Vidispine.AZURE_SAS
- If the storage schema is azure:// you can get direct access to the media. The resulting URI will not tunnel through Vidispine but rather point directly to the media location at the azure storage.
- methodMetadata – Optional metadata used with storage method.
- tag – A URI parameter: Optional comma-separated list of shape tags to return.
- version – Optional integer, specifying which essence version to return for shapes.
If special value
all
, display all versions. If special valuelatest
(default), display latest version of shapes. - closedFiles –
true
(default) - Return only URIs that point to closed files.false
- Return all URIs.
- noauth-url –
true
Return URIs that do not need authentication.false
(default) Return normal URIs
- baseURI – Which base URI to use for the thumbnail URLs.
- save –
true
- Returns a303 See Other
, with aLocation
header containing an URI to fetch the search resultfalse
(default) - Returns a regular search result
New in version 4.7.
Accepts: - application/xml, application/json – ItemSearchDocument
Produces: - application/xml, application/json – SearchResultDocument
Role: _item_search
Role: _collection_read
- first – Integer, from resulting list of items, start return list from specified offset.
Default is
Example¶
PUT /search?content=metadata&field=title
Content-Type: application/xml
<ItemSearchDocument xmlns="http://xml.vidispine.com/schema/vidispine">
<field>
<name>title</name>
<value>Something</value>
</field>
</ItemSearchDocument>
<SearchResultDocument xmlns="http://xml.vidispine.com/schema/vidispine">
<hits>3</hits>
<entry start="-INF" end="+INF" type="Item" id="DE-42">
<item id="DE-42" start="-INF" end="+INF">
<metadata>
<revision>DE-278,DE-276,DE-277</revision>
<timespan start="-INF" end="+INF">
<field uuid="e527b7f3-1bfa-4067-8dde-753368c09617" user="admin" timestamp="2012-03-23T10:10:42.845+01:00" change="DE-278">
<name>title</name>
<value uuid="38609429-67d1-4357-980c-64e7559768ff" user="admin" timestamp="2012-03-23T10:10:42.845+01:00" change="DE-278">Something</value>
</field>
</timespan>
</metadata>
</item>
<timespan start="-INF" end="+INF"/>
</entry>
<entry start="-INF" end="+INF" type="Collection" id="DE-13">
<collection>
<id>DE-13</id>
<metadata>
<revision>DE-273,DE-279</revision>
<timespan start="-INF" end="+INF">
<field uuid="c203856a-e8e3-4d50-8287-642821941791" user="admin" timestamp="2012-03-23T10:10:57.103+01:00" change="DE-279">
<name>title</name>
<value uuid="f80fb9a1-1eca-479a-8b1a-11d30f93fa5d" user="admin" timestamp="2012-03-23T10:10:57.103+01:00" change="DE-279">Something</value>
</field>
</timespan>
</metadata>
</collection>
<timespan start="-INF" end="+INF"/>
</entry>
<entry start="-INF" end="+INF" type="Item" id="DE-37">
<item id="DE-37" start="-INF" end="+INF">
<metadata>
<revision>DE-255,DE-280,DE-256</revision>
<timespan start="-INF" end="+INF">
<field uuid="f1ac0198-6b8f-43a0-9caa-e8c36e80eee8" user="admin" timestamp="2012-03-23T10:11:16.849+01:00" change="DE-280">
<name>title</name>
<value uuid="dcd6a3bb-bf70-4cb7-8d77-e2adfe1e3b1c" user="admin" timestamp="2012-03-23T10:11:16.849+01:00" change="DE-280">Something</value>
</field>
</timespan>
</metadata>
</item>
<timespan start="-INF" end="+INF"/>
</entry>
</SearchResultDocument>
Search shapes¶
New in version 4.2.2.
Search shapes¶
-
GET
/search/shape
¶
-
PUT
/search/shape
¶ Searches shapes. Using GET is identical as performing a search with an empty search document.
Matrix Parameters: - first – Integer, from resulting list of items, start return list from specified offset.
Default is
1
, start return list from beginning. - number – Integer, set a limit on maximum number of hits.
Default
100
.
Query Parameters: - count –
true
(default) - Return hits in result.false
- Do not return hits in result, in order to produce results faster.
- content – Comma-separated list of the types of content to retrieve, possible values are
component
,metadata
,essenceVersion
,tag
,mimeType
and*
. - methodType – Return URIs from storage methods with a particular type.
By default, return URLs with empty
methodType
. - storageType – Only return URIs for files from storages of this type.
- methodMetadata – Optional metadata used with storage method.
- scheme – URI scheme to return.
- save –
true
- Returns a303 See Other
, with aLocation
header containing an URI to fetch the search resultfalse
(default) - Returns a regular search result
New in version 4.7.
Accepts: - application/xml, application/json – ShapeSearchDocument
Produces: - application/xml, application/json – ShapeListDocument
Role: _item_shape_read
- first – Integer, from resulting list of items, start return list from specified offset.
Default is
Search files¶
New in version 4.2.2.
Search files¶
-
GET
/search/file
¶
-
PUT
/search/file
¶ Searches files. Using GET is identical as performing a search with an empty search document.
Note
This resource searches the same index and will produce the same results as
GET /storage/(storage-id)/file
. The only difference is the syntax, that is, the query/matrix parameters versus search documents. When using a search document it is also possible to perform joins.Matrix Parameters: - first – Integer, from resulting list of items, start return list from specified offset.
Default is
1
, start return list from beginning. - number – Integer, set a limit on maximum number of hits.
Default
100
.
Query Parameters: - count –
true
(default) - Return hits in result.false
- Do not return hits in result, in order to produce results faster.
- methodType – Return URIs from storage methods with a particular type.
By default, return URLs with empty
methodType
. - storageType – Only return URIs for files from storages of this type.
- methodMetadata – Optional metadata used with storage method.
- scheme – URI scheme to return.
- save –
true
- Returns a303 See Other
, with aLocation
header containing an URI to fetch the search resultfalse
(default) - Returns a regular search result
New in version 4.7.
Accepts: - application/xml, application/json – FileSearchDocument
Produces: - application/xml, application/json – FileListDocument
Role: _file_read
- first – Integer, from resulting list of items, start return list from specified offset.
Default is
Autocompletion¶
There are two ways to get autocomplete suggestions. The first way is to make a separate autocomplete request to the API, this will generate a result set spanning over all items that the user has access to. The second way is to embed the request in a search document. When performed in this way, the autocomplete suggestions will only span the matching result set.
Autocomplete text¶
Text can be autocompleted against the search index.
-
PUT
/search/autocomplete
¶ Requests suggestion matching text in all or a specific metadata field.
Status Codes: - 400 Bad request – A parameter was invalid.
Accepts: - application/xml, application/json – AutocompleteRequestDocument
Produces: - application/xml, application/json – AutocompleteResponseDocument
Role: _search
Example¶
Assuming the user intends to type “original duration”. The user first starts typing “original”:
PUT /search/autocomplete
Content-Type: application/xml
<AutocompleteRequestDocument xmlns="http://xml.vidispine.com/schema/vidispine">
<text>orig</text>
<maximumSuggestions>3</maximumSuggestions>
</AutocompleteRequestDocument
<AutocompleteResponseDocument xmlns="http://xml.vidispine.com/schema/vidispine">
<suggestion>original</suggestion>
<suggestion>origin</suggestion>
<suggestion>originated</suggestion>
</AutocompleteResponseDocument>
Then the user continues to start typing “duration”:
<AutocompleteRequestDocument xmlns="http://xml.vidispine.com/schema/vidispine">
<text>original dur</text>
<maximumSuggestions>3</maximumSuggestions>
</AutocompleteRequestDocument>
<AutocompleteResponseDocument xmlns="http://xml.vidispine.com/schema/vidispine">
<suggestion>original duration</suggestion>
</AutocompleteResponseDocument>
Auto-complete on one metadata field¶
New in version 4.1.
Since 4.1 auto-complete on one metadata field is supported. And in order to
make the auto-complete case insensitive, the metadata field should be set as
<index>extend</index>
.
Example:¶
A metadata field foo_bar
with config:
<MetadataFieldDocument xmlns="http://xml.vidispine.com/schema/vidispine">
<type>string-exact</type>
<index>extend</index>
</MetadataFieldDocument>
and this filed contains multiple values: “Animal”, “Sky”, “Animal and Sky”, “animal and sky”
An auto-complete request with user input “animal a”:
PUT /search/autocomplete
Content-Type: application/xml
<AutocompleteRequestDocument xmlns="http://xml.vidispine.com/schema/vidispine">
<field>foo_bar</field>
<text>animal a</text>
</AutocompleteRequestDocument>
will give result:
<AutocompleteResponseDocument xmlns="http://xml.vidispine.com/schema/vidispine">
<suggestion>Animal and Sky</suggestion>
<suggestion>animal and sky</suggestion>
</AutocompleteResponseDocument>
Autocompletion as part of a search¶
To perform an autocomplete within a search, just append one or more
<autocomplete>
elements in the search document. The syntax is the
same as for a separate autocomplete request.
Example¶
PUT /item
Content-Type: application/xml
<ItemSearchDocument xmlns="http://xml.vidispine.com/schema/vidispine">
<field>
<name>my_category</name>
<value>stock_photo</value>
</field>
<autocomplete>
<field>my_tag</field>
<text>hi</text>
</autocomplete>
</ItemSearchDocument>
<ItemListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
<hits>5</hits>
<item id="VX-6934" start="-INF" end="+INF">
<timespan start="-INF" end="+INF"/>
</item>
<item id="VX-3464" start="-INF" end="+INF">
<timespan start="-INF" end="+INF"/>
</item>
<item id="VX-2658" start="-INF" end="+INF">
<timespan start="-INF" end="+INF"/>
</item>
<item id="VX-7234" start="-INF" end="+INF">
<timespan start="-INF" end="+INF"/>
</item>
<item id="VX-3723" start="-INF" end="+INF">
<timespan start="-INF" end="+INF"/>
</item>
<autocomplete>
<field>my_tag</field>
<suggestion>highres</suggestion>
<suggestion>hills</suggestion>
<suggestion>history</suggestion>
</autocomplete>
</ItemListDocument>
Optimize index¶
New in version 4.1.
If you wish to optimize the Solr index then we recommend that this is done via this API instead of sending an optimize request to Solr directly.
Note
Solr needs twice the disk space when optimizing the index. Make sure there’s enough free space on the drive hosting the Solr index before optimizing.
Note
Solr will not accept updates while optimizing, meaning that new or updated item will not appear in the search results until the optimize operation has finished.
Optimize search index¶
-
POST
/search/optimize
¶ Submits an optimize request to Solr.
This request can be made to block until the optimize request has completed using the
blocking
parameter.Query Parameters: - blocking –
true
- The request will block until the Solr optimize request has finished.false
(default) - Optimize will be scheduled and the request will return immediately.
- timeout – Integer, block for maximum number of specified milliseconds.
Default is
0
, which means block indefinitely.
Status Codes: - 200 OK – If the operation finished successfully. Only if
blocking=true
. - 202 Accepted – If the operation was accepted but not yet finished.
- 500 Internal Server Error – If an error occurs.
Role: _administrator
- blocking –