text Operator

Description

The text operator performs full-text search on articles, using tokenisation and analysis to find relevant matches. It's ideal for general word-based searches where you want to find articles containing specific terms, even if they're not exact matches. The search is scored by relevance, so more relevant results appear first.

Use this operator when searching for:

• Article titles, summaries, or content containing specific words
• Multiple related terms (automatically handles stemming and analysis)

Syntax

{
  "text": {
    "query": "<search-text>",
    "path": "<field-to-search>",
    "score": <score-options>
  }
}

Options

Examples

Search a single field

Find articles with "tournament" in the title:

{
  "query": {
    "text": {
      "query": "tournament",
      "path": "heroMedia.title"
    }
  }
}

Search multiple fields

Search for "cup final" across title and content text:

{
  "query": {
    "text": {
      "query": "cup final",
      "path": ["heroMedia.title", "content.text"]
    }
  }
}

Fuzzy search

Search for "goalkeeper" with fuzzy matching to catch misspellings and variations:

{
  "query": {
    "text": {
      "query": "goalkeeper",
      "path": "content.text",
      "fuzzy": true
    }
  }
}

How fuzzy matching works:

Fuzzy matching uses edit distance (Levenshtein distance) to find terms that are similar to the search query, allowing matches even when there are spelling mistakes or minor variations.

What it catches:

• Misspellings: "goalkeper" matches "goalkeeper"
• Transpositions: "gaolkeeper" matches "goalkeeper"
• Missing characters: "goalkeeer" matches "goalkeeper"
• Extra characters: "goalkepr" matches "goalkeeper"

Edit distance tolerance:

• Terms with 1-2 characters: exact match required
• Terms with 3-5 characters: 1 edit allowed
• Terms with 6+ characters: 2 edits allowed

Use cases:

• User input with potential typos
• Searches where spelling variations are common
• Languages with multiple accepted spellings

Note: Fuzzy matching can reduce query performance and may return less relevant results. Use sparingly and only when necessary.

Search with score boost

Boost articles with "breaking" in the title:

{
  "query": {
    "text": {
      "query": "breaking",
      "path": "heroMedia.title",
      "score": {
        "boost": {
          "value": 3.0
        }
      }
    }
  }
}

Per-field boosting

Give higher weight to matches in the title than in the content:

{
  "query": {
    "compound": {
      "should": [
        {
          "text": {
            "query": "championship",
            "path": "heroMedia.title",
            "score": {
              "boost": {
                "value": 5.0
              }
            }
          }
        },
        {
          "text": {
            "query": "championship",
            "path": "content.text",
            "score": {
              "boost": {
                "value": 1.0
              }
            }
          }
        }
      ]
    }
  }
}

Multiple field or wildcard matching

Find articles with specific text in multiple fields or using wildcards:

{
  "query": {
    "text": {
      "query": "championship",
      "path": ["heroMedia.title", "content.*"]
    }
  }
}

Using the operator parameter

Control how multiple terms in a query are combined:

OR operator (any term matches):

{
  "query": {
    "text": {
      "query": "cup final",
      "path": "heroMedia.title",
      "operator": "OR"
    }
  }
}

This matches articles containing "cup" OR "final" (or both).

AND operator (all terms required):

{
  "query": {
    "text": {
      "query": "cup final",
      "path": "heroMedia.title",
      "operator": "AND"
    }
  }
}

This matches only articles containing both "cup" AND "final".

Default behaviour:

If operator is not specified, the default is "AND", meaning all terms must be present.

Important: Multi-field operator behaviour

When searching multiple fields, the operator parameter is applied to each field individually, not across fields.

This is an important distinction that can affect your search results. Consider this example:

{
  "query": {
    "text": {
      "query": "cup final",
      "path": ["heroMedia.title", "content.text"],
      "operator": "AND"
    }
  }
}

This query is executed as:

(+heroMedia.title:cup +heroMedia.title:final) OR (+content.text:cup +content.text:final)

What this means:

• The query matches if a single field contains both terms
• It does NOT require terms to be split across fields
• An article with "cup final" in the title matches (both terms in title)
• An article with "final cup match" in the content matches (both "cup" and "final" in content)
• An article with "cup" in the title and "final" in the content does NOT match (only one term per field)

Why this matters:

This behaviour is field-centric. Each field is evaluated independently with the operator applied within that field. The results from each field are then combined with OR logic.

If you need different behaviour:

Use a compound query with separate text operators for fine-grained control:

{
  "query": {
    "compound": {
      "must": [
        {
          "text": {
            "query": "cup",
            "path": ["heroMedia.title", "content.text"]
          }
        },
        {
          "text": {
            "query": "final",
            "path": ["heroMedia.title", "content.text"]
          }
        }
      ]
    }
  }
}

This ensures "cup" appears in at least one field AND "final" appears in at least one field, regardless of which fields they're in.

Notes

• The text operator uses full-text analysis, meaning it tokenises the query and applies linguistic analysis (stemming, lowercasing, etc.)
• For exact matches without analysis, use the equal operator instead
• When searching multiple fields, results that match in multiple fields score higher
• The default operator is "AND", requiring all terms to be present
• With multiple fields, the operator is applied per-field (see the warning above for implications)
• Single-word queries are unaffected by the operator parameter

phrase Operator

Description

The phrase operator finds articles where words appear in an exact sequence. Unlike the text operator which matches individual words anywhere in the field, phrase requires the words to appear in the specified order.

Use this operator when:

• Searching for exact phrases or quotes (e.g., "Division One")
• The word order matters for the search intent
• You need precise matches rather than general relevance

Syntax

{
  "phrase": {
    "query": "<phrase-to-match>",
    "path": "<field-to-search>",
    "score": <score-options>
  }
}

Options

Examples

Match an exact phrase

Find articles with the exact phrase "Team A FC":

{
  "query": {
    "phrase": {
      "query": "Team A FC",
      "path": "heroMedia.title"
    }
  }
}

This will match:

• "Team A FC wins the cup"
• "The Team A FC victory"

This will NOT match:

• "FC plays at Team A" (wrong order)
• "Team A City and FC" (words not adjacent)

Search multiple fields

Search for "National Cup Final" in title or text content:

{
  "query": {
    "phrase": {
      "query": "National Cup Final",
      "path": ["heroMedia.title", "content.text"]
    }
  }
}

Phrase search with boost

Boost articles with "breaking news" in the title:

{
  "query": {
    "phrase": {
      "query": "breaking news",
      "path": "heroMedia.title",
      "score": {
        "boost": {
          "value": 2.5
        }
      }
    }
  }
}

Search for quotes

Find exact quotes in article content:

{
  "query": {
    "phrase": {
      "query": "We played our hearts out",
      "path": "content.text"
    }
  }
}

Per-field boosting

Give higher weight to phrase matches in the title:

{
  "query": {
    "compound": {
      "should": [
        {
          "phrase": {
            "query": "championship final",
            "path": "heroMedia.title",
            "score": {
              "boost": {
                "value": 3.0
              }
            }
          }
        },
        {
          "phrase": {
            "query": "championship final",
            "path": "content.text",
            "score": {
              "boost": {
                "value": 1.0
              }
            }
          }
        }
      ]
    }
  }
}

Multiple field or wildcard matching

Find articles with a specific phrase in multiple fields or using wildcards:

{
  "query": {
    "phrase": {
      "query": "Team A FC",
      "path": ["heroMedia.title", "content.*"]
    }
  }
}

Notes

• The phrase operator requires words to appear in the exact order specified
• It still uses text analysis (lowercasing, stemming), so "Running" will match "run"
• For completely exact matches without any analysis, use the equal operator
• When searching multiple fields, only fields containing the phrase in order will match
• Common use cases include searching for team names, competition names, or exact quotes

equal operator

Description

The equal operator finds articles where a specified field matches a given value exactly. It supports various data types including:

• boolean
• keyword
• number
• date
• null

If at least one element in an array field matches the given value, the article is considered a match.

Syntax

{
  "equal": {
    "path": "<field-to-search>",
    "value": <boolean>|<keyword>|<number>|<date>|null,
    "score": <score-options>
  }
}

Options

Examples

Match a Boolean value

Find all articles that are pinned:

{
  "query": {
    "equal": {
      "path": "pinned",
      "value": true
    }
  }
}

Match a keyword value

Find articles with a specific language:

{
  "query": {
    "equal": {
      "path": "language",
      "value": "en"
    }
  }
}

Match a keyword in nested field

Find articles with a specific category ID:

{
  "query": {
    "nested": {
      "path": "linkedIds",
      "query": {
        "compound": {
          "filter": [
            {
              "equal": {
                "path": "linkedIds.sourceSystem",
                "value": "OPTA_FOOTBALL_TEAM"
              }
            },
            {
              "equal": {
                "path": "linkedIds.sourceSystemId",
                "value": "team-1234"
              }
            }
          ]
        }
      }
    }
  }
}

Match with score boost

Find articles with a specific tag and boost their score:

{
  "query": {
    "equal": {
      "path": "tags",
      "value": "breaking-news",
      "score": {
        "boost": {
          "value": 2.0
        }
      }
    }
  }
}

Multiple field matching

Find articles tagged or with categories:

{
  "query": {
    "equal": {
      "value": "featured",
      "path": ["tags", "categories.id"]
    }
  }
}

Multiple field or wildcard matching

Find articles with a specific value in multiple fields or using wildcards:

{
  "query": {
    "equal": {
      "value": "sports",
      "path": ["tags", "categories.*"]
    }
  }
}

Notes

• If a field is an array (like tags), the article matches if any element in the array equals the specified value
• For exact matches on keyword fields, the comparison is case-sensitive
• For nested fields, when querying only a single field (e.g., categories.id), the nested wrapper is optional and provides no benefit. However, when querying multiple fields within the same nested object, the nested operator is required to ensure conditions match the same object
• Use the in operator when matching against multiple possible values
• Use the text or phrase operators for analysed text search rather than exact matching

in operator

Description

The in operator finds articles where a field matches any value from a specified list. This is useful when you want to match multiple possible values without writing multiple separate queries.

Use this operator when:

• Searching for articles matching any of several category IDs, slugs, or tags
• Filtering by multiple tags or values
• Matching any value from a predefined list

Syntax

{
  "in": {
    "path": "<field-to-search>",
    "values": [<value1>, <value2>, ...],
    "score": <score-options>
  }
}

Options

Examples

Match multiple category IDs

Find articles in any of the specified categories:

{
  "query": {
    "nested": {
      "path": "categories",
      "query": {
        "in": {
          "path": "categories.id",
          "values": [
            "5a3c1e8b-4f2d-4a1c-9b8e-1234567890ab",
            "7b4d2f9c-5e3a-4b2d-8c9f-2345678901bc",
            "9c5e3a0d-6f4b-4c3e-9d0a-3456789012cd"
          ]
        }
      }
    }
  }
}

Filter by article tags

Find articles tagged with any of the specified tags:

{
  "query": {
    "in": {
      "path": "tags",
      "values": ["breaking-news", "exclusive", "match-report"]
    }
  }
}

Match multiple languages

Find articles in English, Spanish, or French:

{
  "query": {
    "in": {
      "path": "language",
      "values": ["en", "es", "fr"]
    }
  }
}

With score boost

Boost articles with priority tags:

{
  "query": {
    "in": {
      "path": "tags",
      "values": ["breaking-news", "exclusive"],
      "score": {
        "boost": {
          "value": 2.0
        }
      }
    }
  }
}

Combined with compound queries

Use within a compound query to create complex filtering:

{
  "query": {
    "compound": {
      "filter": [
        {
          "in": {
            "path": "categories.id",
            "values": [
              "5a3c1e8b-4f2d-4a1c-9b8e-1234567890ab",
              "7b4d2f9c-5e3a-4b2d-8c9f-2345678901bc"
            ]
          }
        },
        {
          "equal": {
            "path": "pinned",
            "value": true
          }
        }
      ]
    }
  }
}

Multiple field or wildcard matching

Find articles with a specific value in multiple fields or using wildcards:

{
  "query": {
    "in": {
      "path": ["tags", "categories.*"],
      "values": ["sports", "news"]
    }
  }
}

Notes

• If a field is an array (like tags), the article matches if the field contains any of the specified values
• More efficient than using multiple equal operators combined with should in a compound query
• The order of values in the array does not affect matching
• All values in the array must be of the same data type
• When querying only a single field within a nested object (like categories.id), the nested wrapper is optional and provides no benefit. However, when querying multiple fields within the same nested object, the nested operator is required to ensure conditions match the same object
• Use equal when matching a single specific value
• Use range when matching a continuous range of values

range operator

Description

The range operator finds articles where a field value falls within a specified range. This is commonly used for numeric values, dates, and other comparable data types.

Use this operator when:

• Filtering articles by publication date ranges
• Searching for content within age or price ranges
• Querying time-based data (last 7 days, this month, etc.)

Syntax

{
  "range": {
    "path": "<field-to-search>",
    "gte": <value>,
    "gt": <value>,
    "lte": <value>,
    "lt": <value>,
    "score": <score-options>
  }
}

Options

*At least one range parameter (gte, gt, lte, lt) must be specified.

Examples

Date range: Last 30 days

Find articles published in the last 30 days:

{
  "query": {
    "range": {
      "path": "publishDate",
      "gte": "now-30d"
    }
  }
}

Date range: Specific period

Find articles published between two dates:

{
  "query": {
    "range": {
      "path": "publishDate",
      "gte": "2024-01-01",
      "lte": "2024-12-31"
    }
  }
}

Numeric range

Find articles with read time between 5 and 15 minutes:

{
  "query": {
    "range": {
      "path": "readTimeMinutes",
      "gte": 5,
      "lte": 15
    }
  }
}

Exclusive bounds

Find articles with version greater than 1 but less than 5 (excluding 1 and 5):

{
  "query": {
    "range": {
      "path": "version",
      "gt": 1,
      "lt": 5
    }
  }
}

Open-ended range

Find articles published after a specific date (no upper limit):

{
  "query": {
    "range": {
      "path": "publishDate",
      "gte": "2024-06-01"
    }
  }
}

Combined with other operators

Find pinned articles from the last 7 days:

{
  "query": {
    "compound": {
      "filter": [
        {
          "equal": {
            "path": "pinned",
            "value": true
          }
        },
        {
          "range": {
            "path": "publishDate",
            "gte": "now-7d"
          }
        }
      ]
    }
  }
}

With score boost

Boost recent articles:

{
  "query": {
    "range": {
      "path": "publishDate",
      "gte": "now-24h",
      "score": {
        "boost": {
          "value": 2.0
        }
      }
    }
  }
}

Note: It is recommended to use score functions (such as gauss) for more gradual scoring adjustments over time. See Score Functions.

Numeric range example

Find articles with read time between 1 to 5 minutes:

{
  "query": {
    "range": {
      "path": "readTimeMinutes",
      "gte": 1,
      "lte": 5
    }
  }
}

Date math examples

For date fields, you can use relative date expressions:

• now - Current date/time
• now-1d - 1 day ago
• now-7d - 7 days ago
• now-1M - 1 month ago
• now-1y - 1 year ago
• now+1h - 1 hour from now

Supported units: y (year), M (month), w (week), d (day), h (hour), m (minute), s (second)

Notes

• For date fields, use ISO 8601 format: YYYY-MM-DD or YYYY-MM-DDTHH:mm:ss
• Date math expressions like now-30d are evaluated at query time
• Use gte/lte for inclusive ranges (most common)
• Use gt/lt for exclusive ranges (when you need to exclude boundary values)
• You can combine any range parameters (e.g., only gte, both gte and lte, etc.)
• Range queries work on numeric and date fields; ensure the field type supports range operations

prefix operator

Description

The prefix operator finds articles where a field value starts with a specified prefix. This is particularly useful for autocomplete and typeahead search functionality, where you want to match partial input as users type.

Use this operator when:

• Implementing autocomplete or search-as-you-type features
• Finding articles based on partial words or prefixes
• Searching for values starting with specific characters

Syntax

{
  "prefix": {
    "query": "<prefix-text>",
    "path": "<field-to-search>",
    "score": <score-options>
  }
}

Options

Examples

Basic autocomplete

Find tags that start with "foot":

{
  "query": {
    "prefix": {
      "query": "foot",
      "path": "tags"
    }
  }
}

This will match:

• "football"
• "footgolf"

This will NOT match:

• "basketball" (doesn't start with "foot")
• "barefoot-running" (word doesn't start at field beginning)

Category ID search

Find articles in categories starting with "division":

{
  "query": {
    "nested": {
      "path": "categories",
      "query": {
        "prefix": {
          "query": "division",
          "path": "categories.id"
        }
      }
    }
  }
}

Matches: "division-one", "division-two", etc.

Source system ID search

Find articles with source system IDs starting with "t" (teams):

{
  "query": {
    "nested": {
      "path": "linkedIds",
      "query": {
        "prefix": {
          "query": "t",
          "path": "linkedIds.sourceSystemId"
        }
      }
    }
  }
}

Matches: "t123", "t456", etc.

Search with score boost

Boost articles with tags starting with "break":

{
  "query": {
    "prefix": {
      "query": "break",
      "path": "tags",
      "score": {
        "boost": {
          "value": 2.0
        }
      }
    }
  }
}

Matches: "breaking-news", "breaking-analysis", etc.

Slug autocomplete

Find articles with slugs starting with "article-202":

{
  "query": {
    "prefix": {
      "query": "article-202",
      "path": "slug"
    }
  }
}

Matches: "article-2024-final", "article-2025-preview", etc.

Multiple field or wildcard matching

Find articles with fields starting with a prefix across multiple fields or using wildcards:

{
  "query": {
    "prefix": {
      "query": "break",
      "path": ["tags", "categories.*"]
    }
  }
}

Notes

• Case sensitivity: Case-sensitive for keyword fields (e.g., slug, tags, language), case-insensitive for analysed text fields (e.g., heroMedia.title, content.text)
• Typically works best on keyword fields or text fields
• Common in autocomplete features where users type partial words
• Unlike text, this doesn't match the prefix anywhere in the text—only at the beginning

Performance tips

• Consider debouncing user input to reduce query frequency
• Limit the number of results for autocomplete to improve speed
• Use appropriate field mappings (e.g., keyword type) for optimal prefix matching