Labels data source

Use the Labels data source type to filter content with a label expression and optionally control order with labels priority and order type.

For what labels are, where they come from, and how filter and priority work together, see Labels mechanism. This page covers the Labels data source parameters and expression types.

Label expressions

Define a logical expression with metadata labels and AND / OR operators. Only content that matches the expression is fetched.

Examples

• Example 1: 2022 AND LA Lakers AND Highlight
  Displays LA Lakers game highlights from the 2022 season.

• Example 2: 2022 AND (LA Lakers OR NYC Knicks) AND Highlight
  Displays highlights from the 2022 season for the LA Lakers or NYC Knicks.

• Example 3: 2022 AND Leo Messi AND UCL AND (Goal OR Assist)
  Displays clips of Leo Messi's goals or assists in the UEFA Champions League during the 2022 season.

How an expression is structured

A label expression is a tree, not a flat list. Each AND or OR is a node that holds operands, and any operand can be a label or another whole expression. The parentheses in the examples above mark where one expression sits inside another.

Take Example 2, 2022 AND (LA Lakers OR NYC Knicks) AND Highlight. The outer node is an AND over three operands, and the second operand is itself an OR:

AND
  - 2022
  - OR
      - LA Lakers
      - NYC Knicks
  - Highlight

The order of nesting is what gives an expression its meaning. A AND (B OR C) requires A plus one of B or C. (A AND B) OR C is satisfied by C alone. The same labels in the same operators produce a different content set depending on which node contains which.

The SDK builds this tree with the expression types described in the following sections. Each type creates one node, and you place a node inside another by passing it as an operand.

Parameters

See Ordering and item limits for orderType, advancedOrderType, and item count options.

Search and labels

The Search (free text) data source has an optional label expression parameter (blazeWidgetLabel on Android, labels on iOS). Use it to scope search results to content that matches a label expression.

In Search, the label expression is filter-only. Search does not support label priority or ordering.

See Free text search for search modes and implementation.

Label expression types

Each type creates one node in the expression tree.

Combining label expressions

mustInclude and atLeastOneOf accept plain labels, other label expressions, or a mix of both. That is how a tree gets built: nest an expression by creating it first, then passing it as an operand to the expression that contains it.

To build Example 2 from earlier, 2022 AND (LA Lakers OR NYC Knicks) AND Highlight, create the OR first, then pass it into the AND alongside the two plain labels:

teams      = atLeastOneOf("LA Lakers", "NYC Knicks")
expression = mustInclude("2022", teams, "Highlight")

The serialized result is [and, 2022, [or, LA Lakers, NYC Knicks], Highlight]. Nest to any depth to build more specific targeting.

Nesting is the only supported way to combine expressions. Writing one expression type after another does not place one inside the other: on iOS and Android a chained call doesn't compile, and on React Native and Web it runs but builds a different tree, an OR at the top level that matches any single operand.

For the exact syntax and worked examples on each platform:

iOS | Android | React Native | Web