Metadata includes technical and contextual information about each video uploaded to the platform. user-defined metadata allows you to add more data to your videos, providing more detailed, specialized, or context-specific information.

The values you provide must be of the following types: string, integer, float or boolean. If you want to store other types of data such as objects or arrays, you must convert your data into string values.

Provide user-defined metadata

Once the platform has finished indexing your videos, you can provide user-defined metadata by invoking the update method of the indexes.videos object with the following parameters:

• index_id: A string representing the unique identifier of the index containing the video for which you want to provide user-defined metadata.
• video_id: A string representing the unique identifier of the video
• user_metadata: A dictionary containing your user-defined metadata. In this example, the metadata dictionary has four keys: views, downloads, language and country. The views and downloads keys are integers, and thecreation_date and country keys are strings.

1
from twelvelabs import TwelveLabs
2
3
client.indexes.videos.update(
4
    index_id="<YOUR_INDEX_ID>",
5
    video_id="<YOUR_VIDEO_ID>",
6
    user_metadata={
7
        "views": 12000,
8
        "downloads": 40000,
9
        "language": "en-us",
10
        "country": "USA"
11
    }
12
)

Filter on user-defined metadata

Once you’ve added user-defined metadata to your videos, you can use it to filter your search results.

The example code below filters on a custom field named views of type integer. The platform will return only the results found in the videos for which the value of the views field equals 120000.

1
from twelvelabs import TwelveLabs
2
3
search_results = client.search.query(
4
  index_id="<YOUR_INDEX_ID>",
5
  query_text= "<YOUR_QUERY>",
6
  search_options=["visual"],
7
  filter = "{ "views": 120000}"
8
)

For more details on filtering search results, see the Filtering page.