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.
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 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 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 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" } }
Enables AI-powered relevance using vector embeddings for more intelligent content matching. { "ranking" : { "type" : "SEMANTIC" , "query" : "cardiac rehabilitation programs" , "path" : "content.description" , "modelId" : "mte-base-knowledge-rank-v1" } }
Sort Apply explicit sorting independent of relevance scoring. Useful for chronological or alphabetical ordering.
{ "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 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" ] }
{ "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..." } ] } }
Traversed Properties Include data from connected resources linked by relationships without separate API calls. Essential for comprehensive result context.
Example: Include Related Data
{ "traversedProperties" : [ "@worksAt.*" , "@[email protected] " , "@treatedBy.name.given" ] }
Traversed Property Path Syntax :
*: Return all traversed properties@relationshipType.*: All properties from a specific relationship@[email protected] : Specific properties from chained relationships
Aggregations 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.
Example: Aggregate by Specialty
Response: Aggregation Results
{ "aggregations" : [ { "type" : "LEXICAL" , "path" : "specialty" , "size" : 10 , "prefix" : "card" } ] }
Lexical Aggregation Parameters :Parameter Type Description pathstring Property to aggregate on sizeinteger Maximum unique values to return (default: 20) prefixstring Optional filter to narrow aggregation values
Zero-based page number for result pagination. Use with perPage to navigate through large result sets.
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.
Simple filtering combined with text matching for straightforward queries over a single collection. { "type" : "ROOT" , "properties" : { "name" : { "type" : "humanname" }, "status" : { "type" : "code" , "description" : "State of the patient file" , "binding" : { "vocabulary" : { "key" : "patient-status" , "strength" : "required" } } } } }
Combine keyword matching with vector similarity search for comprehensive coverage and intelligent results. { "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" } } } ] }, "ranking" : { "type" : "SEMANTIC" , "query" : "pediatric heart specialist" , "path" : "bio" , "modelId" : "mte-base-knowledge-rank-v1" } }
Build faceted navigation interfaces with aggregations and location filtering. Faceted search helps users discover and refine results by showing available filter options with counts. 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 updates in real-time whenever your data changes, or depending on the query .{ "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" ] }
Search across multiple resource types (resources , relationships , objects ) in a single query. 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. { "query" : { "or" : [ { "knn" : { "resources.practitioner.specialties.vector" : { "value" : "cardiology" } } }, { "knn" : { "resources.clinics.specialties.vector" : { "value" : "cardiology" } } } ] } }
Use traversed properties selectively based on result types for dynamic data inclusion. { "query" : { "any" : { "resourceType" : [ "practitioner" , "organization" ] } }, "traversedProperties" : [ "@worksAt.*" , "@employs.*" , "@affiliatedWith.name" ] }
Use composite operators for deep property filtering across nested data structures. { "filter" : { "and" : [ { "composite" : { "address" : [ { "eq" : { "address.city" : "Montreal" } }, { "eq" : { "address.postalCode" : "H3*" } } ] } }, { "any" : { "qualifications" : [ "MD" , "DO" , "MBBS" ] } } ] } }
