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.

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
search_pager = client.search.query(
2
    index_id="<YOUR_INDEX_ID>",
3
    query_text="<YOUR_QUERY>",
4
    search_options=["visual"],
5
    filter=json.dumps({"id":["<YOUR_VIDEO_ID>"]})
6
)

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_pager = client.search.query(
2
    index_id="<YOUR_INDEX_ID>",
3
    query_text="<YOUR_QUERY>",
4
    search_options=["visual"],
5
    filter=json.dumps({"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_pager = client.search.query(
2
    index_id="<YOUR_INDEX_ID>",
3
    query_text="<YOUR_QUERY>",
4
    search_options=["visual"],
5
    filter=json.dumps({
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 returns only the results found in the videos for which the value of the views field equals 120000.

1
search_pager = client.search.query(
2
    index_id="<YOUR_INDEX_ID>",
3
    query_text="<YOUR_QUERY>",
4
    search_options=["visual"],
5
    filter=json.dumps({"views":120000})
6
)