Search [VC 21.3.1 GEN]

Search for items and collections.

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.

List all items and collections

GET /search

Browses items and collections.

Content Parameters:	See Retrieving item information
Query Parameters:	first (integer) – From the resulting list of items, start return list from specified offset. Default is `1`, start return list from beginning. cursor (string) – New in version 5.4. `` - The initial cursor. `string-from-search` - Cursor string returned from the search results. If set, the cursorMark / search after features from Solr/Elasticsearch are used to improve the deep paging performance during a search. When `cursor` is used, the value of `first` will be ignored. number* (integer) – The number of entities to fetch. Default is `100`. count (boolean) – `true` (default) - Return hits in result. `false` - Do not return hits in result, in order to produce results faster. p (string) – Comma-separated list of paths specifying the content to include. Overrides the content and filter parameters. content (string) – Comma-separated list of the types of content to retrieve. Valid values are `metadata`, `uri`, `shape`, `poster`, `thumbnail`, `access`, `merged-access`, `external`. interval (string) – 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 as `interval=generic,-INF-+INF` `result` - Can be used when retrieving metadata from a search result. Will return time spans that overlap with the search result. (New in 5.5.) field (string) – 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 (string) – Comma-separated list. group-name - Return specified group. group-name `+` - Return specified group and subgroups. 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 (string) – 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. sampleRate* (string) – 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 (string) – 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. include (string) – A list of keys. Includes additional field specific data. Additionally, if set to `type` the type definition of the field will be retrieved. includeValues (boolean) – Return the value enumeration for each metadata field. conflict (string) – `yes` (default) - Include all metadata conflicts, unresolved. `no` - Return conflicts resolved according to field rules. terse (string) – `yes` - Return metadata in terse format. `no` (default) - Return metadata in verbose format. defaultValue (boolean) – `true` - For unset fields, return default values. `false` (default) - Do not return default values. includeTransientMetadata (boolean) – `true` (default) - Include transient metadata. `false` - Do not include transient metadata in response. revision (string) – Specifying which metadata revision to display. Only used if requesting a single item or collection. mergedType (string) – The type of operation to check for. mergedPermission (string) – The lowest required permission level. mergedExtradata (string) – Any possible extra data. uriType (string) – Comma-separated list of format types (container format) to return. scheme (string) – URI scheme to return. storageType (string) – Only return URIs for files from storages of this type. methodType (string) – 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 (string) – Metadata used with storage method. tag (string) – A URI parameter: Comma-separated list of shape tags to return. version (string) – Specifying which essence version to return for shapes. If special value `all`, display all versions. If special value `latest` (default), display latest version of shapes. closedFiles (boolean) – A URI parameter: `true` (default) - Return only URIs that point to closed files. `false` - Return all URIs. storage (string[]) – List of storage ids. Return only files from specific storages. Can be specified multiple times. storageGroup (string) – Storage group id. Return only files from storages specified in the storage group. noauth-url (boolean) – `true` Return URIs that do not need authentication. `false` (default) Return normal URIs baseURI (string) – Which base URI to use for the thumbnail URLs. save (boolean) – `true` - Returns a `303 See Other`, with a `Location` header containing an URI to fetch the search result `false` (default) - Returns a regular search result
Produces:	application/xml, application/json – SearchResultDocument
Role:	_item_search
Role:	_collection_read
Role:	_metadata_read (`content=metadata`)
Role:	_item_uri (`content=uri`)
Role:	_thumbnail_read (`content=poster` and `content=thumbnail`)
Role:	_access_control_read (`content=access` and `content=merged-access`)
Role:	_item_id_read (`content=external`)

Search items and collections

PUT /search

Searches items and collections with a shared search query.

This resource doesn’t support joint search, use PUT /item, PUT /search/shape or PUT /search/file for item, shape or file joint search respectively.

Content Parameters:	See Retrieving item information
Query Parameters:	first (integer) – From the resulting list of items, start return list from specified offset. Default is `1`, start return list from beginning. cursor (string) – New in version 5.4. `` - The initial cursor. `string-from-search` - Cursor string returned from the search results. If set, the cursorMark / search after features from Solr/Elasticsearch are used to improve the deep paging performance during a search. When `cursor` is used, the value of `first` will be ignored. number* (integer) – The number of entities to fetch. Default is `100`. count (boolean) – `true` (default) - Return hits in result. `false` - Do not return hits in result, in order to produce results faster. p (string) – Comma-separated list of paths specifying the content to include. Overrides the content and filter parameters. content (string) – Comma-separated list of the types of content to retrieve. Valid values are `metadata`, `uri`, `shape`, `poster`, `thumbnail`, `access`, `merged-access`, `external`. interval (string) – 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 as `interval=generic,-INF-+INF` `result` - Can be used when retrieving metadata from a search result. Will return time spans that overlap with the search result. (New in 5.5.) field (string) – 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 (string) – Comma-separated list. group-name - Return specified group. group-name `+` - Return specified group and subgroups. 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 (string) – 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. sampleRate* (string) – 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 (string) – 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. include (string) – A list of keys. Includes additional field specific data. Additionally, if set to `type` the type definition of the field will be retrieved. includeValues (boolean) – Return the value enumeration for each metadata field. conflict (string) – `yes` (default) - Include all metadata conflicts, unresolved. `no` - Return conflicts resolved according to field rules. terse (string) – `yes` - Return metadata in terse format. `no` (default) - Return metadata in verbose format. defaultValue (boolean) – `true` - For unset fields, return default values. `false` (default) - Do not return default values. includeTransientMetadata (boolean) – `true` (default) - Include transient metadata. `false` - Do not include transient metadata in response. revision (string) – Specifying which metadata revision to display. Only used if requesting a single item or collection. mergedType (string) – The type of operation to check for. mergedPermission (string) – The lowest required permission level. mergedExtradata (string) – Any possible extra data. uriType (string) – Comma-separated list of format types (container format) to return. scheme (string) – URI scheme to return. storageType (string) – Only return URIs for files from storages of this type. methodType (string) – 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 (string) – Metadata used with storage method. tag (string) – A URI parameter: Comma-separated list of shape tags to return. version (string) – Specifying which essence version to return for shapes. If special value `all`, display all versions. If special value `latest` (default), display latest version of shapes. closedFiles (boolean) – A URI parameter: `true` (default) - Return only URIs that point to closed files. `false` - Return all URIs. storage (string[]) – List of storage ids. Return only files from specific storages. Can be specified multiple times. storageGroup (string) – Storage group id. Return only files from storages specified in the storage group. noauth-url (boolean) – `true` Return URIs that do not need authentication. `false` (default) Return normal URIs baseURI (string) – Which base URI to use for the thumbnail URLs. save (boolean) – `true` - Returns a `303 See Other`, with a `Location` header containing an URI to fetch the search result `false` (default) - Returns a regular search result
Accepts:	application/xml, application/json – ItemSearchDocument
Produces:	application/xml, application/json – SearchResultDocument
Role:	_item_search
Role:	_collection_read
Role:	_metadata_read (`content=metadata`)
Role:	_item_uri (`content=uri`)
Role:	_thumbnail_read (`content=poster` and `content=thumbnail`)
Role:	_access_control_read (`content=access` and `content=merged-access`)
Role:	_item_id_read (`content=external`)

Example

NONE

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>

HTML/XML

<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

GET /search/shape

PUT /search/shape

Searches shapes. Using GET is identical as performing a search with an empty search document.

Query Parameters:	first (integer) – From the resulting list of items, start return list from specified offset. Default is `1`, start return list from beginning. number (integer) – The number of entities to fetch. Default is `100`. count (boolean) – `true` (default) - Return hits in result. `false` - Do not return hits in result, in order to produce results faster. content (string) – Comma-separated list of the types of content to retrieve. One of `component`, `metadata`, `essenceVersion`, `tag`, `mimeType` and ``. methodType* (string) – Return URIs from storage methods with a particular type. By default, return URLs with empty `methodType`. storageType (string) – Only return URIs for files from storages of this type. methodMetadata (string[]) – metadata used with storage method. scheme (string) – URI scheme to return. save (boolean) – `true` - Returns a `303 See Other`, with a `Location` header containing an URI to fetch the search result `false` (default) - Returns a regular search result
Accepts:	application/xml, application/json – ShapeSearchDocument
Produces:	application/xml, application/json – ShapeListDocument
Role:	_item_shape_read

Search files

GET /search/file

PUT /search/file

Searches files. Using GET is identical as performing a search with an empty search document.

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 parameters versus search documents. When using a search document it is also possible to perform joins.

Query Parameters:	first (integer) – From the resulting list of items, start return list from specified offset. Default is `1`, start return list from beginning. number (integer) – The number of entities to fetch. Default is `100`. count (boolean) – `true` (default) - Return hits in result. `false` - Do not return hits in result, in order to produce results faster. methodType (string) – Return URIs from storage methods with a particular type. By default, return URLs with empty `methodType`. storageType (string) – Only return URIs for files from storages of this type. methodMetadata (string[]) – metadata used with storage method. scheme (string) – URI scheme to return. save (boolean) – `true` - Returns a `303 See Other`, with a `Location` header containing an URI to fetch the search result `false` (default) - Returns a regular search result
Accepts:	application/xml, application/json – FileSearchDocument
Produces:	application/xml, application/json – FileListDocument
Role:	_file_read

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”:

NONE

PUT /search/autocomplete
Content-Type: application/xml

<AutocompleteRequestDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <text>orig</text>
  <maximumSuggestions>3</maximumSuggestions>
</AutocompleteRequestDocument

HTML/XML

<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”:

HTML/XML

<AutocompleteRequestDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <text>original dur</text>
  <maximumSuggestions>3</maximumSuggestions>
</AutocompleteRequestDocument>

HTML/XML

<AutocompleteResponseDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <suggestion>original duration</suggestion>
</AutocompleteResponseDocument>

Autocomplete on one metadata field

Auto-complete on one metadata field is supported. 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:

HTML/XML

<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”:

NONE

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:

HTML/XML

<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

NONE

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>

HTML/XML

<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

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.

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.

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 the 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 (boolean) – `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