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 with ;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> <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 afterwards.
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 autoRefresh=true
- The library has an updateFrequencey set.
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.
|autoRefresh||true or false (default)||If true, items will be tracked as their metadata is modified.|
|updateFrequency||positive integer||If set, the library will be rebuilt periodically. The integer describes the minimum time, in minutes, between updates.|
Having 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> <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 updateMode TRANSIENT.