# Query path

This document describes how to specify which fields to search using the `path` parameter, including single fields, nested fields, multiple fields, and wildcards.

# Overview

The `path` parameter specifies which field within an article or page should be searched or evaluated. It is a required parameter for most query operators. The `path` parameter supports:

| Format              | Description                                        | Example                               |
| ------------------- | -------------------------------------------------- | ------------------------------------- |
| Single field name   | Search a single field                              | `"heroMedia.title"`                   |
| Dot-separated path  | Navigate nested fields                             | `"categories.id"`                     |
| Array of paths      | Search multiple fields                             | `["heroMedia.title", "content.text"]` |
| Wildcard characters | Match multiple fields at various levels of nesting | `"categories.*"`                      |

Note: Not all operators support all path formats (e.g., arrays or wildcards). Refer to the specific operator documentation for details.

# Usage

## Single field

Search for a value in a single field:

```json
{
  "path": "heroMedia.title"
}
```

## Nested field

Search within a nested field using dot notation:

```json
{
  "path": "categories.id"
}
```

## Multiple fields

Search across multiple fields:

```json
{
  "path": ["heroMedia.title", "content.text"]
}
```

## Wildcard matching

Wildcards can appear at any position in a path pattern, allowing flexible field matching.

### Wildcard Types

The single-level wildcard `*` matches exactly one path segment at the wildcard position.

| Pattern       | Matches                                                             | Does Not Match             |
| ------------- | ------------------------------------------------------------------- | -------------------------- |
| `heroMedia.*` | `heroMedia.title`, `heroMedia.summary`                              | (no deeper nesting)        |
| `*.text`      | `content.text`, `categories.text`, `linkedIds.text`                 | (no deeper nesting)        |
| `linkedIds.*` | `linkedIds.sourceSystem`, `linkedIds.sourceSystemId`                | (no deeper nesting)        |
| `*.id`        | `categories.id`, `displayCategory.id`, `content.id`, `linkedIds.id` | (matches all `*.id` paths) |

The multi-level wildcard `**` matches zero or more path segments at the wildcard position.

| Pattern        | Matches                                                                             |
| -------------- | ----------------------------------------------------------------------------------- |
| `content.**`   | `content`, `content.text`, `content.title`, `content.contentType`, `content.id`     |
| `**.text`      | `content.text`, `categories.text`, `linkedIds.text`, `sponsors.text`                |
| `**.id`        | `id`, `categories.id`, `displayCategory.id`, `content.id`, `linkedIds.id`           |
| `linkedIds.**` | `linkedIds`, `linkedIds.sourceSystem`, `linkedIds.sourceSystemId`, `linkedIds.text` |

### Wildcard Examples

#### Trailing single-level: `heroMedia.*`

```json
{ "path": "heroMedia.*" }
```

Expands to: `["heroMedia.title", "heroMedia.summary", "heroMedia.contentType", "heroMedia.sourceSystem", "heroMedia.sourceSystemId"]`

***

#### Trailing multi-level: `content.**`

```json
{ "path": "content.**" }
```

Expands to: `["content", "content.text", "content.title", "content.contentType", "content.altText", "content.id", "content.tags", "content.sourceSystem", "content.sourceSystemId", ...]`

***

#### Leading single-level: `*.title`

```json
{ "path": "*.title" }
```

Expands to: `["heroMedia.title", "content.title", "author.title"]`

***

#### Leading multi-level: `**.text`

```json
{ "path": "**.text" }
```

Expands to: `["content.text", "categories.text", "displayCategory.text", "linkedIds.text", "sponsors.text"]`

***

#### Leading single-level: `*.id`

```json
{ "path": "*.id" }
```

Expands to: `["categories.id", "displayCategory.id", "content.id"]`

***

#### Leading multi-level: `**.id`

```json
{ "path": "**.id" }
```

Expands to: `["id", "categories.id", "displayCategory.id", "content.id"]`

***

#### Trailing single-level on nested: `linkedIds.*`

```json
{ "path": "linkedIds.*" }
```

Expands to: `["linkedIds.sourceSystem", "linkedIds.sourceSystemId", "linkedIds.text"]`

***

#### Trailing single-level: `sponsors.*`

```json
{ "path": "sponsors.*" }
```

Expands to: `["sponsors.text", "sponsors.imageUrl", "sponsors.linkUrl"]`

***

#### Explicit paths (no wildcards)

```json
{ "path": ["heroMedia.title", "content.text", "author.name"] }
```

No expansion - uses exact paths as specified.

**Performance note:** Wildcards can significantly increase query cost, especially on fields with many children. Use explicit field lists when possible for better performance.

## Additional wildcard examples

Search all hero media fields:

```json
{
  "text": {
    "query": "championship",
    "path": "heroMedia.*"
  }
}
```

This searches across `heroMedia.title`, `heroMedia.summary`, etc.

Search all author fields:

```json
{
  "text": {
    "query": "John Smith",
    "path": "author.*"
  }
}
```

This searches `author.name`, `author.title`.

Search all 'text' fields across the schema:

```json
{
  "text": {
    "query": "Breaking News",
    "path": "**.text"
  }
}
```

This searches `content.text`, `categories.text`, `displayCategory.text`, `linkedIds.text`, `sponsors.text`.

Search all 'title' fields:

```json
{
  "text": {
    "query": "Premier League",
    "path": "*.title"
  }
}
```

This searches `heroMedia.title`, `content.title`, `author.title`.

Search all content fields:

```json
{
  "text": {
    "query": "video",
    "path": "content.**"
  }
}
```

This searches all fields under content: `content.text`, `content.title`, `content.contentType`, `content.altText`, etc.

Filter by any sourceSystem field:

```json
{
  "equal": {
    "path": "*.sourceSystem",
    "value": "OPTA_FOOTBALL_TEAM"
  }
}
```

This matches `heroMedia.sourceSystem`, `content.sourceSystem`, `linkedIds.sourceSystem`.