---
title: Advanced Patterns & Edge Cases
url: https://docs.kaltura.com/docs/rich-media-cms-apis/content-management/esearch-advanced-patterns-edge-cases
---

## Advanced Patterns & Edge Cases


* **10,000 Result Limit:** Elasticsearch enforces a 10K result cap (500/page x 20 pages max). To traverse larger result sets, use `KalturaESearchRange` on `created_at` with scroll-forward pagination — move the date window after each 10K batch.
* **Large Result Sets:** Always use the `pager` parameter (`pageIndex`, `pageSize`) to retrieve results in manageable chunks. Iterate through pages by incrementing `pageIndex` until the number of returned objects is less than `pageSize` or zero.
* **Highlighting Context:** Remember that highlights (`<em>` tags) are embedded in the text. You might need to parse or display this HTML carefully. The `itemsData` array provides more context for matches in captions or metadata than the top-level `highlight` array.
* **Partial vs. Exact Match:** `PARTIAL` (`itemType=2`) is powerful due to synonyms but might return less precise results than `EXACT_MATCH` (`itemType=1`). Choose based on the desired recall vs. precision. Use `ignoreSynonym=true` in `searchParams` to disable synonym expansion if needed.
* **NOT Operator Shorthand:** Use the `!` prefix in `freeText` (e.g., `searchTerm=!excluded`) to exclude matches. For structured queries, use `KalturaESearchOperatorType` with `NOT_OP` (`3`).
* **Performance:** Unified searches (`KalturaESearchUnifiedItem`) are convenient but can be slower than targeted searches using specific `fieldName`s (like `NAME` or `CAPTIONS_CONTENT`) because they query more fields. Optimize by specifying fields when possible.
* **Abstract vs. Concrete Types:** Several Kaltura object types are abstract base classes that cannot be used directly in API calls. Using an abstract type returns `OBJECT_TYPE_ABSTRACT`. For `orderBy`, use `KalturaESearchEntryOrderByItem` (not `KalturaESearchOrderByItem`). For aggregations, use `KalturaESearchEntryAggregationItem` (not `KalturaESearchAggregationItem`). Each search action (entry, category, user, group) has its own concrete types.
* **Aggregation Path Nesting:** The aggregations parameter has double nesting: `searchParams[aggregations][aggregations][0]`. The outer `aggregations` is the `KalturaESearchAggregation` container object; the inner `aggregations` is the array property holding the items. Using `searchParams[aggregations][0]` (single level) silently returns no aggregations.
* **Caption Timestamps Are Milliseconds:** `startsAt` and `endsAt` in `KalturaESearchCaptionItemData` are integers in milliseconds (e.g., `16700` = 16.7 seconds). Divide by 1000 for seconds.
* **JSON Body Support:** The API v3 backend accepts both `application/x-www-form-urlencoded` (bracket notation) and `application/json` (nested objects) with identical results. JSON is easier for programmatic construction and SDK integration.
* **Schema Reference:** The Kaltura API schema (XML) is the definitive source for all object structures, properties, enums, and their exact names. Refer to it frequently.