The Resources.Search class provides methods to perform searches.

Methods

Make a search request

Description: This method performs a search across a specific index based on the provided parameters and returns the first page of results.

Function signature and example:

async query(
  {
    indexId,
    query,
    queryText,
    queryMediaType,
    queryMediaFile,
    queryMediaUrl,
    options: searchOptions,
    groupBy,
    threshold,
    operator,
    conversationOption,
    filter,
    pageLimit,
    sortOption,
    adjustConfidenceLevel,
  }: SearchOptions,
  options: RequestOptions = {},
): Promise<Models.SearchResult>

function printSearchData(data) {
  console.log(`  Score: ${data.score}`);
  console.log(`  Start: ${data.start}`);
  console.log(`  End: ${data.end}`);
  console.log(`  Video ID: ${data.videoId}`);
  console.log(`  Confidence: ${data.confidence}`);
  console.log(`  Thumbnail URL: ${data.thumbnailUrl}`);
}

const result = await client.search.query({
  indexId: "<YOUR_INDEX_ID>",
  queryText: "<YOUR_QUERY>",
  options: ["visual", "audio"],
  groupBy: "clip",
  threshold: "medium",
  operator: "or",
  filter: {
     "metadata.language": "en",
  },
  sortOption: "score",
  adjustConfidenceLevel: 0.5,
  pageLimit: 5
});

// Print the search pool information
console.log("Search pool:");
console.log(`  Total count: ${result.pool.totalCount}`);
console.log(`  Total duration: ${result.pool.totalDuration}`);
console.log(`  Index ID: ${result.pool.indexId}`);

// Print the search results
console.log("Search Results:");
result.data.forEach(item => {
  if ('clips' in item) {  // This is equivalent to isinstance(item, GroupByVideoSearchData)
    console.log(`Video ID: ${item.id}`);
    if (item.clips) {
      item.clips.forEach(clip => {
        printSearchData(clip);
      });
    }
  } else {
    printSearchData(item);
  }
});

// Print the page information
console.log("Page information:");
console.log(`  Limit per page: ${result.pageInfo.limitPerPage}`);
console.log(`  Total results: ${result.pageInfo.totalResults}`);
console.log(`  Page expired at: ${result.pageInfo.pageExpiresAt}`);
console.log(`  Next page token: ${result.pageInfo.nextPageToken}`);
console.log(`  Previous page token: ${result.pageInfo.prevPageToken}`);

Parameters:

Name	Type	Required	Description
`params`	`SearchOptions`	Yes	Parameters for performing the search.
`options`	`RequestOptions`	No	Additional options for the request. Defaults to `{}`.

The SearchOptions interface defines the parameters for performing a search request:

Name	Type	Required	Description
`indexId`	`string`	Yes	The unique identifier of the index to search.
`queryText`	`string`	No	The text query to search for. This parameter is required for text queries.
`queryMediaType`	`'image'`	No	The type of media you wish to use. This parameter is required for media queries. For example, to perform an image-based search, set this parameter to `image`.
`queryMediaFile`	`Buffer \| NodeJS.ReadableStream \| string`	No	The media file to be used as a query. This parameter can be a `Buffer`, a `ReadableStream`, or a string representing the path to the file.
`queryMediaUrl`	`string`	No	The publicly accessible URL of a media file to use as a query. This parameter is required for media queries if `query_media_file` is not provided.
`options`	`('visual' \| 'audio')[]`	No	Specifies the sources of information the platform uses when performing a search
`groupBy`	`'video' \| 'clip'`	No	Use this parameter to group or ungroup items in a response.
`threshold`	`'high' \| 'medium' \| 'low'`	No	Filter on the level of confidence that the results match your query.
`operator`	`'or' \| 'and'`	No	TLogical operator for combining search options.
`filter`	`Record<string, any>`	No	Additional filters for the search. This parameter can contain any key-value pairs.
`pageLimit`	`number`	No	The maximum number of results per page.
`sortOption`	`'score' \| 'clip_count'`	No	The sort order for the response.
`adjustConfidenceLevel`	`number`	No	The strictness of the thresholds for assigning the high, medium, or low confidence levels to search results.

Return value: Returns a Promise that resolves to a Models.SearchResult object containing the search results.

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

Related guides:

Retrieve a specific page of search results

Description: This method retrieves a specific page of search results.

📘
Note
This method provides direct pagination. Choose it mainly when the total number of items is manageable, or you must fetch a single page of results. When your application must retrieve a large number of items, choose iterative pagination. For details, see the Iterative pagination section.

Function signature and example:

async byPageToken(pageToken: string, options: RequestOptions = {}): Promise<Models.SearchResult>

function printSearchData(data) {
  console.log(`  Score: ${data.score}`);
  console.log(`  Start: ${data.start}`);
  console.log(`  End: ${data.end}`);
  console.log(`  Video ID: ${data.videoId}`);
  console.log(`  Confidence: ${data.confidence}`);
  console.log(`  Thumbnail URL: ${data.thumbnailUrl}`);
}

const result = await client.search..by_page_token("<YOUR_PAGE_TOKEN>");

// Print the search pool information
console.log("Search pool:");
console.log(`  Total count: ${result.pool.totalCount}`);
console.log(`  Total duration: ${result.pool.totalDuration}`);
console.log(`  Index ID: ${result.pool.indexId}`);

// Print the search results
console.log("Search Results:");
result.data.forEach(item => {
  if ('clips' in item) { 
    console.log(`Video ID: ${item.id}`);
    if (item.clips) {
      item.clips.forEach(clip => {
        printSearchData(clip);
      });
    }
  } else {
    printSearchData(item);
  }
});

// Print the page information
console.log("Page information:");
console.log(`  Limit per page: ${result.pageInfo.limitPerPage}`);
console.log(`  Total results: ${result.pageInfo.totalResults}`);
console.log(`  Page expired at: ${result.pageInfo.pageExpiresAt}`);
console.log(`  Next page token: ${result.pageInfo.nextPageToken}`);
console.log(`  Previous page token: ${result.pageInfo.prevPageToken}`);

Parameters:

Name	Type	Required	Description
`pageToken`	`string`	Yes	A token that identifies the page to retrieve.
`options`	`RequestOptions`	No	Additional options for the request. Defaults to `{}`.

Return value: Returns a Promise that resolves to a Models.SearchResult object containing the search results.

API Reference: For a description of each field in the request and response, see the Retrieve a specific page of search results page.

Related guides:

Iterative pagination

If your application must retrieve a large number of items, use iterative pagination. To retrieve the first page of results, invoke the query method of the search object. To retrieve subsequent pages of results, use the async iterator protocol.

function printSearchData(data) {
  console.log(`  Score: ${data.score}`);
  console.log(`  Start: ${data.start}`);
  console.log(`  End: ${data.end}`);
  console.log(`  Video ID: ${data.videoId}`);
  console.log(`  Confidence: ${data.confidence}`);
  console.log(`  Thumbnail URL: ${data.thumbnailUrl}`);
}

function printPage(result, pageNumber) {
  console.log(`Page ${pageNumber}`);
  
  // Print the search results
  console.log("Search Results:");
  const data = result.data || result;
  data.forEach(item => {
    if ('clips' in item) {
      console.log(`Video ID: ${item.id}`);
      if (item.clips) {
        item.clips.forEach(clip => {
          printSearchData(clip);
        });
      }
    } else {
      printSearchData(item);
    }
  });
}

let searchResults = await client.search.query({
  indexId: "<YOUR_INDEX_ID>",
  queryText: "<YOUR_QUERY>",
  options: ["visual", "audio"],
  groupBy: "clip",
  threshold: "medium",
  operator: "or",
  filter: {
     "metadata.language": "en",
  },
  sortOption: "score",
  adjustConfidenceLevel: 0.5,
  pageLimit: 5
});

// Print the search pool information
console.log("Search pool:");
console.log(`  Total count: ${searchResults.pool.totalCount}`);
console.log(`  Total duration: ${searchResults.pool.totalDuration}`);
console.log(`  Index ID: ${searchResults.pool.indexId}`);

let pageNumber = 1;
printPage(searchResults, pageNumber);

while (true) {
  const nextPage = await searchResults.next();
  if (nextPage === null) break;
  pageNumber++;
  printPage(nextPage, pageNumber);
}

console.log("No more results.");

Methods

Make a search request

Retrieve a specific page of search results

📘Note

Iterative pagination

📘
Note