> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clinia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Search Parameters

> Understand how to structure and use search parameters for comprehensive querying in Clinia's Data Partition API

## Clinia Query Domain-Specific Language (DSL)

Search parameters define how to query and retrieve records from Clinia's data partitions. They provide comprehensive control over filtering, aggregation, and result presentation, enabling everything from simple lookups to complex multi-modal searches across your data.

<Info>
  The [registry API search endpoints](/api-reference/search/search-accross-resource-or-relationship-collections-in-the-registry) and [Data Partition API search endpoints](/api-reference/search/search-resources-of-a-specific-collection-in-the-data-partition) accept a single JSON-like object that controls all aspects of your search query.
</Info>

<Info>
  **Unified Query DSL**: Both [resources](/explanation/data-model/data-sources#resource) and [relationships](/explanation/data-model/data-sources#relationship) use the same DSL and search parameters, even though they have distinct API endpoints. You can search [resources](/api-reference/search/search-resources-of-a-specific-collection-in-the-data-partition) and [relationships](/api-reference/search/search-relationships-of-a-specific-type-in-the-data-partition) using identical query syntax and parameters.
</Info>

## Core Search Parameters

The foundation of every search request lies in these core parameters that control what data to retrieve and how to match it.

### Filtering

<ParamField path="filter" type="operator">
  Use for **exact matching** and **precise filtering**. Creates binary include/exclude decisions without affecting relevance scores.
</ParamField>

Perfect for status checks, date ranges, and categorical filters. Optimized for fast boolean operations.

```json Example: Status and Date Filtering theme={null}
{
  "filter": {
    "and": [
      { "eq": { "status": "active" } },
      { "gt": { "lastModified": "2024-01-01T00:00:00Z" } }
    ]
  }
}
```

### Query

<ParamField path="query" type="operator">
  Use for **relevance-based matching** and **content discovery**. Contributes to relevance scoring of results.
</ParamField>

Ideal for text search, semantic matching, and finding the most relevant content. Designed for scoring.

```json Example: Text and Semantic Search theme={null}
{
  "query": {
    "or": [
      {
        "match": {
          "description": {
            "value": "cardiac symptoms",
            "type": "phrase"
          }
        }
      },
      {
        "knn": {
          "content.vector": {
            "value": "heart condition treatment"
          }
        }
      }
    ]
  }
}
```

<Tip>
  Both `filter` and `query` accept any [operator](/explanation/operator) and can be combined in the same search request for hybrid filtering and scoring strategies.
</Tip>

## Sorting

Control the order of your search results with these parameters.

<ParamField path="sort" type="object">
  Apply explicit sorting independent of relevance scoring. Useful for chronological or alphabetical ordering.
</ParamField>

```json Example: Sort by Date theme={null}
{
  "sort": {
    "path": "lastModified",
    "direction": "DESC"
  }
}
```

**Sort Directions**:

* `ASC` (ascending)
* `DESC` (descending, default)

## Result Enhancement

Enhance your search results with additional context and related data.

### Highlighting

<ParamField path="highlighting" type="string[]">
  Request highlighted snippets for specific properties to show query matches in search results.
</ParamField>

Perfect for showing users **why** a result matched their query and which parts are most relevant.

<Tabs>
  <Tab title="Example: Highlight Multiple Fields">
    ```json theme={null}
    {
      "highlighting": [
        "title",
        "description",
        "content.chunks.text"
      ]
    }
    ```
  </Tab>

  <Tab title="Response: Highlighted Results">
    ```json theme={null}
    {
      "highlighting": {
        "description": [
          {
            "type": "textual",
            "highlight": "Treatment for <mark>cardiac</mark> conditions..."
          }
        ],
        "content.vector": [
          {
            "type": "vector",
            "score": 0.89,
            "path": "content.chunks.vector",
            "data": "Advanced cardiac rehabilitation techniques..."
          }
        ]
      }
    }
    ```
  </Tab>
</Tabs>

### Traversed Properties

<ParamField path="traversedProperties" type="string[]">
  Include data from connected resources linked by relationships without separate API calls. Essential for comprehensive result context.
</ParamField>

```json Example: Include Related Data theme={null}
{
  "traversedProperties": [
    "@worksAt.*",
    "@worksAt.@location.address",
    "@treatedBy.name.given"
  ]
}
```

**Traversed Property Path Syntax**:

* `*`: Return all traversed properties
* `@relationshipType.*`: All properties from a specific relationship
* `@relationshipType.@adjacentType.property`: Specific properties from chained relationships

## Aggregations

<ParamField path="aggregations" type="object[]">
  Generate summary statistics and faceted navigation data alongside search results. Build powerful filter interfaces and analytics.
</ParamField>

Aggregations can help you surface your data distribution and available filter options.
Aggregations are also referred to as **facets** in the search domain.

### Lexical Aggregation

Count and group records by discrete property values to create filter options and understand data patterns.

<CodeGroup>
  ```json Example: Aggregate by Specialty theme={null}
  {
    "aggregations": [
      {
        "type": "LEXICAL",
        "path": "specialty",
        "size": 10,
        "prefix": "card"
      }
    ]
  }
  ```

  ```json Response: Aggregation Results theme={null}
  {
    "aggregates": [
      {
        "type": "LEXICAL",
        "path": "specialty",
        "aggregate": [
          { "value": "Cardiology", "count": 45 },
          { "value": "Cardiac Surgery", "count": 12 }
        ]
      }
    ]
  }
  ```
</CodeGroup>

**Lexical Aggregation Parameters**:

| Parameter | Type    | Description                                   |
| --------- | ------- | --------------------------------------------- |
| `path`    | string  | Property to aggregate on                      |
| `size`    | integer | Maximum unique values to return (default: 20) |
| `prefix`  | string  | Optional filter to narrow aggregation values  |

## Pagination

<ParamField path="page" type="integer" default={0}>
  Zero-based page number for result pagination. Use with `perPage` to navigate through large result sets.
</ParamField>

<ParamField path="perPage" type="integer" default={20}>
  Number of results per page (1-250). Balance between performance and user experience needs.
</ParamField>

```json Example: Second Page with 50 Results theme={null}
{
  "page": 1,
  "perPage": 50
}
```

<Note>
  **Limits**: `perPage` supports 1-250 results, while `page` starts from 0 and has no pre-defined limit.
</Note>

## Search Patterns

Common search patterns and real-world examples to get you started quickly.

<Tabs>
  <Tab title="Basic Property Search">
    Simple filtering combined with text matching for straightforward queries over a single collection.

    <CodeGroup>
      ```json Profile theme={null}
      {
        "properties": {
          "name": {
            "type": "humanname"
          },
          "status": {
            "type": "code",
            "description": "State of the patient file",
            "binding": {
              "vocabulary": {
                "key": "patient-status",
                "strength": "required"
              }
            }
          }
        }
      }
      ```

      ```json Search Parameters theme={null}
      {
        "filter": {
          "eq": { "status": "active" }
        },
        "query": {
          "match": {
            "name.family": {
              "value": "Smith",
              "type": "wordPrefix"
            }
          }
        },
        "perPage": 10
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Hybrid Search">
    Combine keyword matching with vector similarity search for comprehensive coverage and intelligent results. Use [`knn`](/explanation/operator#knn-knn) for semantic matching.

    ```json theme={null}
    {
      "filter": {
        "eq": { "resourceType": "practitioner" }
      },
      "query": {
        "or": [
          {
            "match": {
              "specialties.name": {
                "value": "cardiology pediatric",
                "type": "phrase"
              }
            }
          },
          {
            "knn": {
              "specialties.vector": {
                "value": "pediatric cardiology specialist"
              }
            }
          },
          {
            "match": {
              "bio": {
                "value": "children heart specialist",
                "type": "word"
              }
            }
          }
        ]
      }
    }
    ```
  </Tab>

  <Tab title="Faceted Search">
    Build faceted navigation interfaces with [aggregations](/explanation/search#aggregations) and location filtering. Faceted search helps users discover and refine results by showing available filter options with counts.

    <Info>
      **Pre-computed Facets**: You can pre-compute facet values for commonly used filters and integrate them into your interface for improved performance and user experience. This allows dynamic filter interfaces that update in real-time whenever your data changes, or depending on the [query](/explanation/search#query).
    </Info>

    ```json theme={null}
    {
      "filter": {
        "geoDistance": {
          "location": {
            "coordinates": { "latitude": 45.5, "longitude": -73.6 },
            "radius": 25000
          }
        }
      },
      "aggregations": [
        {
          "type": "LEXICAL",
          "path": "specialty",
          "size": 15
        },
        {
          "type": "LEXICAL", 
          "path": "acceptingPatients",
          "size": 5
        }
      ],
      "highlighting": ["name.given", "name.family"]
    }
    ```
  </Tab>

  <Tab title="Federated Search">
    Search across multiple resource types ([resources](/explanation/data-model/data-sources#resource) and [relationships](/explanation/data-model/data-sources#relationship)) in a single query.

    <Info>
      **Important**: When searching across multiple resource types, notice how the paths differ:

      * Use `resources.practitioner.property` for practitioner data
      * Use `resources.organization.property` for organization data

      Each resource type requires its own path prefix in composite queries. This also allows to query relationships and resources in the same API call.
    </Info>

    ```json theme={null}
    {
      "query": {
        "or": [
          {
              "knn": {
                "resources.practitioner.specialties.vector": {
                  "value": "cardiology"
                }
              }
          },
          {
              "knn": {
                "resources.clinics.specialties.vector": {
                  "value": "cardiology"
                }
              }
          }
        ]
      }
    }
    ```
  </Tab>

  <Tab title="Conditional Result Enhancement">
    Use traversed properties selectively based on result types for dynamic data inclusion.

    ```json theme={null}
    {
      "query": {
        "any": {
          "resourceType": ["practitioner", "organization"]
        }
      },
      "traversedProperties": [
        "@worksAt.*",
        "@employs.*",
        "@affiliatedWith.name"
      ]
    }
    ```
  </Tab>

  <Tab title="Complex Nested Filtering">
    Use composite operators for deep property filtering across nested data structures.

    ```json theme={null}
    {
      "filter": {
        "and": [
          {
            "composite": {
              "address": [
                {
                  "eq": {
                    "address.city": "Montreal"
                  }
                },
                {
                  "eq": {
                    "address.postalCode": "H3*"
                  }
                }
              ]
            }
          },
          {
            "any": {
              "qualifications": ["MD", "DO", "MBBS"]
            }
          }
        ]
      }
    }
    ```
  </Tab>
</Tabs>

## Related Concepts

<CardGroup cols={2}>
  <Card title="Operators" icon="filter" href="/explanation/operator">
    Complete reference for filter and query conditions
  </Card>

  <Card title="Data Types" icon="database" href="/explanation/data-types/base-types">
    Understanding property types for accurate filtering
  </Card>

  <Card title="Semantic Search" icon="brain" href="/explanation/semantic-search">
    Deep dive into AI-powered search capabilities
  </Card>

  <Card title="Data Partition API" icon="code" href="/api-reference/search/search-resources-of-a-specific-collection-in-the-data-partition">
    Complete endpoint documentation
  </Card>
</CardGroup>