Skip to main content
View as Markdown

Advanced Patterns & Edge Cases - Content Management

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 fieldNames (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.