When you perform a search, the platform returns all the relevant matches. Filtering narrows the scope of your query. The platform allows you to filter your search results based on metadata or the level of confidence that the search results match your query.

Filtering search results based on metadata

To filter your search results based on metadata, use the filter parameter.

The filter parameter is of type Object and can contain both system-generated and user-provided metadata fields.fields. For details on system-generated metadata, see the Video object page. For details on providing custom metadata, see the Update video information page.

To indicate the relationship between a field and its value, you can use the exact match or comparison operators.

Exact match operator

The exact match operator matches only the results that equal the value you specify. The syntax is as follows: <field>: <value>.

Comparison operators

Use the comparison operators (lte and gte) to match based on the arithmetic comparison. The syntax is as follows: <field>:{"gte": <value>, "lte": <value}.

Filter composition

You can filter on multiple fields by adding the fields you want to filter on to the filter parameter as shown in the Filter on size, width, and height section below.

Filtering on the level of confidence

The level of confidence represents the degree of similarity between your query and the search results. You can use the threshold parameter to filter on the level of confidence. This allows you to narrow down a response obtained from the platform by retrieving only the most relevant results. The threshold parameter can take one of the following values:

• low (this is the default value)
• medium
• high

For a description of each field in the request and response, see the API Reference > Make any-to-video search request page.

Examples

Filter on a specific video ID

The following example code uses the id field of the filter parameter to filter on a specific video ID:

1
from twelvelabs import TwelveLabs
2
3
client = TwelveLabs(api_key="<YOUR_API_KEY>")
4
5
search_results = client.search.query(
6
  index_id="<YOUR_INDEX_ID>",
7
  query_text= "<YOUR_QUERY>",
8
  options=["visual"],
9
  filter={"id":["<YOUR_VIDEO_ID>"]}
10
)

Filter on multiple video IDs

The following example code uses the id field of the filter query parameter to filter on multiple video IDs:

1
search_results = client.search.query(
2
  index_id="<YOUR_INDEX_ID>",
3
  query_text= "<YOUR_QUERY>",
4
  options=["visual"],
5
  filter={"id":["<FIRST_VIDEO_ID>", "<SECOND_VIDEO_ID>"]}
6
)

Filter on size, width, and height

The example code below uses the size, width, and height fields of the filter parameter to return only the matches found in videos that meet all the following criteria:

• Size is greater than or equal to 50000000 bytes and less and equal to 53000000 bytes.
• Width is greater than or equal to 850.
• Height is greater than or equal to 400 and less and equal to 500.

1
search_results = client.search.query(
2
  index_id="<YOUR_INDEX_ID>",
3
  query_text= "<YOUR_QUERY>",
4
  options=["visual"],
5
  filter={
6
    "size": {
7
      "gte": 50000000, "lte": 53000000
8
    },
9
    "width":
10
      {
11
        "gte": 850
12
      },
13
    "height":
14
      {
15
        "gte": 400, "lte": 500
16
      }
17
  }
18
)

Filter on custom metadata

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. For details about specifying custom metadata, see the Provide custom metadata section.

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

Filtering on the level of confidence

The following example code specifies that the minimum level of confidence shouldn’t be lower than medium:

1
search_results = client.search.query(
2
  index_id="<YOUR_INDEX_ID>",
3
  query_text= "<YOUR_QUERY>",
4
  options=["visual"],
5
  threshold='medium'
6
)