Skip to main content

​
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, ranking, aggregation, and result presentation, enabling everything from simple lookups to complex multi-modal searches across your data.
The 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

​
filter
operator
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

​
query
operator
Use for relevance-based matching and content discovery. Contributes to relevance scoring and ranking of results.
Ideal for text search, semantic matching, and finding the most relevant content. Designed for ranking and 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 ranking strategies.

​
Ranking and Sorting

Control the order and relevance scoring of your search results with these parameters.

​
Ranking

​
ranking
object
Controls how results are scored and ordered. Choose between default relevance algorithms or AI-powered semantic ranking.
  • Default Ranking
  • Semantic Ranking
Uses Clinia’s standard relevance algorithms based on text matching and field importance.
{
  "ranking": {
    "type": "DEFAULT"
  }
}

​
Sort

​
sort
object
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)
When both ranking and sort are specified, sorting takes precedence over ranking for result ordering.

​
Result Enhancement

Enhance your search results with additional context and related data.

​
Highlighting

​
highlighting
string[]
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.
  • Example: Highlight Multiple Fields
  • Response: Highlighted Results
{
  "highlighting": [
    "title",
    "description",
    "content.chunks.text"
  ]
}

​
Traversed Properties

​
traversedProperties
string[]
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

​
aggregations
object[]
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:
ParameterTypeDescription
pathstringProperty to aggregate on
sizeintegerMaximum unique values to return (default: 20)
prefixstringOptional filter to narrow aggregation values

​
Pagination

​
page
integer
default:0
Zero-based page number for result pagination. Use with perPage to navigate through large result sets.
​
perPage
integer
default: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 only has no pre-defined limit.

​
Search Patterns

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

Operators

Complete reference for filter and query conditions

Data Types

Understanding property types for accurate filtering

Semantic Search

Deep dive into AI-powered search capabilities

Data Partition API

Complete endpoint documentation
⌘I