Whereas collections are more of a generic container for entities, the strength of libraries lies in the ability to have the library content dynamically updated based on a query.
Use libraries to for example:
- Manage the current search performed by a user.
- To represent saved searches created by your users.
- To implement dynamic storage rules or access control restrictions based on the metadata of items.
When searching for items you can create a library containing the items
matching the query by specifying
result=library. If used together
autoRefresh=true you can create a “saved search”. When
accessing the library later, its content will return
PUT /item?updateMode=REPLACE&autoRefresh=TRUE&result=library HTTP/1.1 Accept: application/xml Content-type: application/xml
<ItemSearchDocument xmlns="http://xml.vidispine.com/schema/vidispine"> <field> <name>project_priority</name> <value>urgent</value> </field> </ItemSearchDocument>
<ItemListDocument xmlns="http://xml.vidispine.com/schema/vidispine"> <library>VX*19</library> <item>VX-13</item> <item>VX-14</item> <item>VX-71</item> </ItemListDocument>
Check the library settings to find out how a library was created, or why a library contains a specific set of items, for example when using self-refreshing libraries.
<LibrarySettingsDocument xmlns="http://xml.vidispine.com/schema/vidispine"> <id>VX*67</id> <username>admin</username> <updateMode>REPLACE</updateMode> <autoRefresh>true</autoRefresh> <query> <field> <name>originalWidth</name> <range> <value>640</value> <value>720</value> </range> </field> </query> </LibrarySettingsDocument>
Libraries without a query¶
Libraries can also be created using
POST /library. You will need to
specify the items that the library should contain, but this can also be changed
POST /library HTTP/1.1 Content-Type: application/xml <ItemListDocument xmlns="http://xml.vidispine.com/schema/vidispine"> <item id="VX-250"/> <item id="VX-1000"/> </ItemListDocument>
<URIListDocument xmlns="http://xml.vidispine.com/schema/vidispine"> <uri>VX*48</uri> </URIListDocument>
Check the library settings and you will see that it does not specify a query, in comparison to libraries created when searching.
Libraries will be automatically deleted after having not being accessed for a period of 24 hours. There are some exception to this rule. If any of the following conditions apply, the library will not be automatically deleted:
- The library is part of a collection
- The library has a storage rule set
- The library has a site rule set
- The library has
- The library has an
Libraries can be set to keep their contents up to date with the queries in two ways (see the table below). The two different methods can either be used together or separately. Neither of these modes will have an affect on transient libraries, as they will always be kept up to date.
||positive integer||If set, the library will be rebuilt periodically. The integer describes the minimum time, in minutes, between updates.|
autoRefresh set means that metadata changes will have an almost
immediate effect on libraries. But it has the drawback that libraries using
variables, such as a timestamp search containing ranges with the “NOW”
variable, will not be updated unless a user changes its metadata. To remedy
this libraries can be updated periodically. From a performance point of view
though, it is more efficient to check if an item belongs to a library then to
refresh an entire library – so period updates should be done with care.
Queries involving variables
Using variables in queries, e.g. the use of the word “NOW” when searching timestamped metadata, is not reliable for libraries unless they are either set as TRANSIENT or they are set to be updated periodically.
- In this mode any items that matches query will be added to the library without removing any existing items.
- Unlike MERGE, this mode will also remove items that no longer matches the query.
- This mode has the same semantics as REPLACE, with some important differences. It only contains items on a logical basis, so instead of simply retrieving its items it needs to perform a search every time its contents is being requested. This leads to a faster creation time than REPLACE, but slower lookup and cannot be used to restrict item access.
Creating a library that contains items created within the last 5 days.
PUT /item?autoRefresh=false&updateFrequency=60&updateMode=REPLACE&result=library Content-Type: application/xml <ItemSearchDocument xmlns="http://xml.vidispine.com/schema/vidispine"> <field> <name>created</name> <range> <value>NOW-5DAYS</value> <value>NOW</value> </range> </field> </ItemSearchDocument>
Setting access controls on a library will cascade down on the items. This means that
libraries can be used to batch update access controls on a set of items. Note that
this does not work on libraries with