---
title: Advanced Topics & Use Cases
url: https://docs.kaltura.com/docs/rich-media-cms-apis/content-management/esearch-advanced-topics-use-cases
---

## Advanced Topics & Use Cases


* **Aggregations (`searchParams[aggregations]`):**
    * **Use Case:** Get a summary view without retrieving all results, e.g., "Show me the count of videos vs. images matching 'tutorial'".
    * **How:** Specify the field (e.g., `KalturaESearchEntryAggregateByFieldName::MEDIA_TYPE`) in a `KalturaESearchEntryAggregationItem` within the `searchParams`.
    * **Response:** The `aggregations` array in the response will contain buckets with counts for each media type found.
* **Searching Different Object Types:**
    * **Use Case:** Find categories tagged "Education" or users named "John Doe".
    * **How:** Use the appropriate action (`searchCategory`, `searchUser`, `searchGroup`) and the corresponding `searchParams` type (`KalturaESearchCategoryParams`, `KalturaESearchUserParams`, `KalturaESearchGroupParams`). The structure of `searchOperator` and `searchItems` remains similar, but you use object-specific field names (e.g., `KalturaESearchCategoryFieldName::TAGS`, `KalturaESearchUserFieldName::FULL_NAME`).

    **searchCategory example:**
    ```bash
    curl -X POST "$KALTURA_SERVICE_URL/service/elasticsearch_esearch/action/searchCategory" \
      -d "ks=$KALTURA_KS" \
      -d "format=1" \
      -d "searchParams[objectType]=KalturaESearchCategoryParams" \
      -d "searchParams[searchOperator][objectType]=KalturaESearchCategoryOperator" \
      -d "searchParams[searchOperator][operator]=1" \
      -d "searchParams[searchOperator][searchItems][0][objectType]=KalturaESearchCategoryItem" \
      -d "searchParams[searchOperator][searchItems][0][fieldName]=name" \
      -d "searchParams[searchOperator][searchItems][0][itemType]=2" \
      -d "searchParams[searchOperator][searchItems][0][searchTerm]=Education"
    ```

    **searchUser example:**
    ```bash
    curl -X POST "$KALTURA_SERVICE_URL/service/elasticsearch_esearch/action/searchUser" \
      -d "ks=$KALTURA_KS" \
      -d "format=1" \
      -d "searchParams[objectType]=KalturaESearchUserParams" \
      -d "searchParams[searchOperator][objectType]=KalturaESearchUserOperator" \
      -d "searchParams[searchOperator][operator]=1" \
      -d "searchParams[searchOperator][searchItems][0][objectType]=KalturaESearchUserItem" \
      -d "searchParams[searchOperator][searchItems][0][fieldName]=full_name" \
      -d "searchParams[searchOperator][searchItems][0][itemType]=2" \
      -d "searchParams[searchOperator][searchItems][0][searchTerm]=John"
    ```

    **searchGroup example:**
    ```bash
    curl -X POST "$KALTURA_SERVICE_URL/service/elasticsearch_esearch/action/searchGroup" \
      -d "ks=$KALTURA_KS" \
      -d "format=1" \
      -d "searchParams[objectType]=KalturaESearchGroupParams" \
      -d "searchParams[searchOperator][objectType]=KalturaESearchGroupOperator" \
      -d "searchParams[searchOperator][operator]=1" \
      -d "searchParams[searchOperator][searchItems][0][objectType]=KalturaESearchGroupItem" \
      -d "searchParams[searchOperator][searchItems][0][fieldName]=screen_name" \
      -d "searchParams[searchOperator][searchItems][0][itemType]=2" \
      -d "searchParams[searchOperator][searchItems][0][searchTerm]=Engineering"
    ```

    All four actions (`searchEntry`, `searchCategory`, `searchUser`, `searchGroup`) return the same response structure: `{ objects: [...], totalCount, objectType }`. Each object is wrapped in `{ object, itemsData, highlight }`.
* **Caption Timestamps for Clip Playback:**
    * **Use Case:** "Play the part where they discuss training programs" — find the exact timestamp range within a video.
    * **How:** Use `KalturaESearchCaptionItem` with `fieldName=content`, `addHighlight=true`. The response's `itemsData[].items[]` array contains `KalturaESearchCaptionItemData` objects with `startsAt` and `endsAt` fields (integers in **milliseconds**). Use the first match's `startsAt` as clip start and the last match's `endsAt` as clip end. Divide by 1000 to get seconds.
    * **Curl:**
        ```bash
        curl -X POST "$KALTURA_SERVICE_URL/service/elasticsearch_esearch/action/searchEntry" \
        -d "ks=$KALTURA_KS" \
        -d "searchParams[searchOperator][searchItems][0][objectType]=KalturaESearchCaptionItem" \
        -d "searchParams[searchOperator][searchItems][0][searchTerm]=training programs" \
        -d "searchParams[searchOperator][searchItems][0][itemType]=2" \
        -d "searchParams[searchOperator][searchItems][0][fieldName]=content" \
        -d "searchParams[searchOperator][searchItems][0][addHighlight]=true" \
        -d "searchParams[searchOperator][objectType]=KalturaESearchEntryOperator" \
        -d "searchParams[objectType]=KalturaESearchEntryParams" \
        -d "format=1" | jq '.objects[0].itemsData[] | select(.itemsType=="caption") | .items[] | {startsAt, endsAt, content}'
        ```
    * **Response excerpt:** `{"startsAt": 16700, "endsAt": 20600, "content": "...training programs..."}` — clip from 16.7s to 20.6s.
* **Nested Queries:**
    * **Use Case:** Combining complex AND/OR/NOT logic as shown in Scenario E.
    * **How:** Place a `KalturaESearchEntryOperator` (or similar) within the `searchItems` array of another operator. This allows nesting conditions (e.g., `A AND (B OR (NOT C))`).