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.

The registry API search endpoints and Data Partition API search endpoints accept a single JSON-like object that controls all aspects of your search query.

Unified Query DSL: Both resources and relationships use the same DSL and search parameters, even though they have distinct API endpoints. You can search resources and relationships using identical query syntax and parameters.

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

filterpathoperator

Use for exact matching and precise filtering. Creates binary include/exclude decisions without affecting relevance scores.

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

Example: Status and Date Filtering

{
  "filter": {
    "and": [
      { "eq": { "status": "active" } },
      { "gt": { "lastModified": "2024-01-01T00:00:00Z" } }
    ]
  }
}

Query

querypathoperator

Use for relevance-based matching and content discovery. Contributes to relevance scoring of results.

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

Example: Text and Semantic Search

{
  "query": {
    "or": [
      {
        "match": {
          "description": {
            "value": "cardiac symptoms",
            "type": "phrase"
          }
        }
      },
      {
        "knn": {
          "content.vector": {
            "value": "heart condition treatment"
          }
        }
      }
    ]
  }
}

Both filter and query accept any operator and can be combined in the same search request for hybrid filtering and scoring strategies.

Sorting

Control the order of your search results with these parameters.

sortpathobject

Apply explicit sorting independent of relevance scoring. Useful for chronological or alphabetical ordering.

Example: Sort by Date

{
  "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

highlightingpathstring[]

Request highlighted snippets for specific properties to show query matches in search results.

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

{
  "highlighting": [
    "title",
    "description",
    "content.chunks.text"
  ]
}

Traversed Properties

traversedPropertiespathstring[]

Include data from connected resources linked by relationships without separate API calls. Essential for comprehensive result context.

Example: Include Related Data

{
  "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

aggregationspathobject[]

Generate summary statistics and faceted navigation data alongside search results. Build powerful filter interfaces and analytics.

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.

{
  "aggregations": [
    {
      "type": "LEXICAL",
      "path": "specialty",
      "size": 10,
      "prefix": "card"
    }
  ]
}

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

pagepathintegerdefault: 0

Zero-based page number for result pagination. Use with perPage to navigate through large result sets.

perPagepathintegerdefault: 20

Number of results per page (1-250). Balance between performance and user experience needs.

Example: Second Page with 50 Results

{
  "page": 1,
  "perPage": 50
}

Limits: perPage supports 1-250 results, while page starts from 0 and has no pre-defined limit.

Search Patterns

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

Simple filtering combined with text matching for straightforward queries over a single collection.

{
  "properties": {
    "name": {
      "type": "humanname"
    },
    "status": {
      "type": "code",
      "description": "State of the patient file",
      "binding": {
        "vocabulary": {
          "key": "patient-status",
          "strength": "required"
        }
      }
    }
  }
}