Breadcrumbs

Bulky metadata [VC 21.3 GEN]

Bulky metadata can be used to store large amounts of timed metadata. The metadata is arranged in a key-value fashion, where the key is the quintuple (field, start, end, stream, channel).

The metadata is not indexed, but is typically used as a temporary container for metadata that is to be processed later, for example using auto-projection rules.



Managing bulky metadata

Both items and shapes can hold bulky metadata.

Insert values in bulk

PUT /item/(item-id)/metadata/bulky/ PUT /item/(item-id)/shape/(shape-id)/metadata/bulky/ Inserts all key-value pairs from a given document. Accepts: application/xml, application/json – BulkyMetadataDocument Role: _metadata_write

Example 

PUT /item/VX-250/metadata/bulky
Content-Type: application/xml

<BulkyMetadataDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <field start="3" end="5">
      <key>mykey</key>
      <value>This is the value of mykey for the first interval.</value>
   </field>
   <field start="5" end="9">
      <key>mykey</key>
      <value>This is the value of mykey for the second interval.</value>
   </field>
</BulkyMetadataDocument>

Retrieve all keys used in the bulky metadata

GET /item/(item-id)/metadata/bulky/ GET /item/(item-id)/shape/(shape-id)/metadata/bulky/ Retrieves a list of all keys in the bulky metadata. Produces: application/xml, application/json – URIListDocument text/plain – CRLF-delimited list of keys Role: _metadata_read

Delete all keys used in the bulky metadata

DELETE /item/(item-id)/metadata/bulky/ DELETE /item/(item-id)/shape/(shape-id)/metadata/bulky/ Removes all the keys in the bulky metadata. Role: _metadata_write

Read values

GET /item/(item-id)/metadata/bulky/(key) GET /item/(item-id)/shape/(shape-id)/metadata/bulky/(key) Retrieves all values of a certain key over a specified interval. All values for that key can be retrieved by specifying start as “-INF” and end as “+INF”. Query Parameters: start (string) – A time code that defines the start of the interval. end (string) – A time code that defines the end of the interval. Produces: application/xml, application/json – BulkyMetadataDocument Role: _metadata_read

Example 

GET /item/VX-123/metadata/bulky/mykey?start=-INF&end=+INF

<BulkyMetadataDocument id="VX-123" xmlns="http://xml.vidispine.com/schema/vidispine">
   <field start="3" end="5">
      <key>mykey</key>
      <value>This is the value of mykey for the first interval.</value>
   </field>
   <field start="5" end="9">
      <key>mykey</key>
      <value>This is the value of mykey for the second interval.</value>
   </field>
</BulkyMetadataDocument>

Returning bulky metadata as a file

GET /item/(item-id)/metadata/bulky/(key)/as-file GET /item/(item-id)/shape/(shape-id)/metadata/bulky/(key)/as-file Bulky metadata that is stored as a map and that has the keys filename and content can be retrieved as a file. If the map contains several entries with those keys, the first one will be returned. To have more granular control over which entry is returned, the query parameters below can be use to select which entry to match on. Query Parameters: start (string) – A time code that defines the start of the interval. end (string) – A time code that defines the end of the interval. stream (integer) – The stream index. channel (integer) – The audio channel index. itemTrack (string) – The track in the item. extraMapValues (string) – Additional map values to filter on in the format key=value. This parameter can be used multiple times. Produces: application/octet-stream – The binary file content Role: _metadata_read

Example 

<BulkyMetadataDocument id="VX-123" xmlns="http://xml.vidispine.com/schema/vidispine">
   <field start="-INF" end="+INF">
      <key>mykey</key>
      <maps>
        <map>
          <entry key="filename">my_pdf.pdf</entry>
          <entry key="content">...</entry>
          <entry key="type">PDF</entry>
        </map>
        <map>
          <entry key="filename">my_xml.xml</entry>
          <entry key="content">...</entry>
          <entry key="type">XML</entry>
        </map>
     </maps>
   </field>
   <field start="10" end="30">
      <key>mykey</key>
      <maps>
        <map>
          <entry key="filename">another_pdf.pdf</entry>
          <entry key="content">...</entry>
          <entry key="type">PDF</entry>
        </map>
        <map>
          <entry key="filename">another_xml.xml</entry>
          <entry key="content">...</entry>
          <entry key="type">XML</entry>
        </map>
      </maps>
   </field>
</BulkyMetadataDocument>

If we want to retrieve the “my_pdf.pdf” entry as a binary file, we can use the following request (note that the = sign in the extraMapValues parameter is URL encoded in this example):

GET /item/VX-123/metadata/bulky/mykey/as-file?start=-INF&end=+INF&extraMapValues=type%3DPDF

But the follwing request would also get the same file:

GET /item/VX-123/metadata/bulky/mykey/as-file?start=-INF&end=+INF&extraMapValues=filename%3Dmy_pdf.pdf

Insert values

PUT /item/(item-id)/metadata/bulky/(key) PUT /item/(item-id)/shape/(shape-id)/metadata/bulky/(key) Inserts a value at the specified interval for the given key. If the key already has a value at that specific interval then that value will be overwritten. Query Parameters: start (string) – A time code that defines the start of the interval. end (string) – A time code that defines the end of the interval. stream (integer) – The stream index. channel (integer) – The audio channel index. itemTrack (string) – The track in the item. Accepts: text/plain – The value to set. Role: _metadata_write

Example 

PUT /item/VX-123/metadata/bulky/mykey?start=3&end=5
Content-Type: text/plain

This is the value of mykey for the first interval.

PUT /item/VX-123/metadata/bulky/mykey?start=5&end=9
Content-Type: text/plain

This is the value of mykey for the second interval.

Remove values

DELETE /item/(item-id)/metadata/bulky/(key) DELETE /item/(item-id)/shape/(shape-id)/metadata/bulky/(key) Removes all the values for a certain key over the specified interval. Query Parameters: start (string) – A time code that defines the start of the interval. end (string) – A time code that defines the end of the interval. Role: _metadata_write