SanteSuite Help Portal
  • SanteSuite Help Portal
    • Disclaimer
  • Product Overview
    • SanteSuite Products
      • Introducing SanteDB CDR
        • SanteDB Solutions
      • Master Patient Index - SanteMPI
      • Immunization Management System - SanteIMS
      • Privacy & Security - SanteGuard
    • SanteDB Versions
  • Architecture
    • SanteDB Architecture
      • SanteDB History
    • Solution Architecture
    • Software Architecture
      • Publish / Subscribe Architecture
      • New ADO (nuado)
      • Roadmap
    • Data & Information Architecture
      • Conceptual Information Model
        • Concept Dictionary
          • Data Dictionary
        • Acts
          • State Machine
          • Act Relationships
          • Mood Concepts
          • Class Concepts
          • Data Dictionary
        • Entities
          • State Machine
          • Entity Relationships
          • Determiner Codes
          • Class Codes
          • Data Dictionary
        • Null Reasons
        • Extended Data
      • Physical Model
        • Act Data Dictionary
        • Entity Data Dictionary
        • Concept Dictionary Data Dictionary
      • Data Storage Patterns
        • Master Data Storage
      • SanteDB Object Identifiers (OIDs)
    • Security Architecture
    • Privacy Architecture
    • Matching Engine
    • HIE & Interoperability
  • Installation
    • Installation
    • Releases
      • 3.0 Releases
      • Queenston Release
    • Quick Start Guide
      • Seeding ONC Patient Matching Data
    • Operationalizing SanteDB
      • Information Gathering & Analysis
      • Planning & Preparation Work
        • Pre-flight Checklist
        • Develop a Business Architecture
        • Develop an Information Architecture
          • Establishing Minimum Datasets
          • Identity Environment
        • Develop Operational Technology Architecture
        • Developing Privacy Impact Assessments
        • Develop Threat / Risk Assessments
      • Deployment
        • Pre-Flight Checklist
        • Installing Software
          • SanteDB iCDR Server
            • Installation on Virtual or Physical Environments
              • Installation on Microsoft Windows
              • Installation on Linux and Unix
            • Installation using Appliances
              • Using Docker Containers
                • Adding Sample Data
                • Feature Configuration
                • SanteDB within Instant OpenHIE
              • Using Virtual Appliances
            • Installation Qualification
              • Master Patient Index / Client Registry Qualification
                • MPI/CR Test Cases for HL7v2
                  • TEST: OHIE-CR-02-HL7v2
                  • TEST: OHIE-CR-03-HL7v2
                  • TEST: OHIE-CR-04-HL7v2
                  • TEST: OHIE-CR-05-HL7v2
                  • TEST: OHIE-CR-06-HL7v2
                  • TEST: OHIE-CR-07-HL7v2
                  • TEST: OHIE-CR-08-HL7v2
                  • TEST: OHIE-CR-09-HL7v2
                  • TEST: OHIE-CR-10-HL7v2
                  • TEST: OHIE-CR-11-HL7v2
                  • TEST: OHIE-CR-12-HL7v2
                  • TEST: OHIE-CR-13-HL7v2
                  • TEST: OHIE-CR-14-HL7v2
                  • TEST: OHIE-CR-15-HL7v2
                  • TEST: OHIE-CR-16-HL7v2
                  • TEST: OHIE-CR-17-HL7v2
                  • TEST: OHIE-CR-18-HL7v2
                  • TEST: OHIE-CR-01-HL7v2
                  • HL7v2 Test Cases Instructions
                • MPI/CR Test Cases for FHIR
                  • TEST: OHIE-CR-01-FHIR
                  • TEST: OHIE-CR-02-FHIR
                  • TEST: OHIE-CR-03-FHIR
                  • TEST: OHIE-CR-04-FHIR
                  • TEST: OHIE-CR-05-FHIR
                  • TEST: OHIE-CR-06-FHIR
                  • TEST: OHIE-CR-07-FHIR
                  • TEST: OHIE-CR-08-FHIR
                  • TEST: OHIE-CR-09-FHIR
                  • FHIR Test Cases Instructions
              • Security Administration Testing
                • Administrative Panel Validation
                  • User Management Tests
                    • TEST: SECURITY-UM-01
                    • TEST: SECURITY-UM-02
                    • TEST: SECURITY-UM-03
                    • TEST: SECURITY-UM-04
                    • TEST: SECURITY-UM-05
                    • TEST: SECURITY-UM-06
                    • TEST: SECURITY-UM-07
                    • TEST: SECURITY-UM-08
                    • TEST: SECURITY-UM-09
                    • TEST: SECURITY-UM-10
                    • TEST: SECURITY-UM-11
                    • TEST: SECURITY-UM-12
                    • TEST: SECURITY-UM-13
                    • TEST: SECURITY-UM-14
                    • TEST: SECURITY-UM-15
                    • TEST: SECURITY-UM-16
                    • TEST: SECURITY-UM-17
                    • TEST: SECURITY-UM-18
                    • TEST: SECURITY-UM-19
                    • TEST: SECURITY-UM-20
                    • TEST: SECURITY-UM-21
                    • TEST: SECURITY-UM-22
                    • TEST: SECURITY-UM-23
                    • TEST: SECURITY-UM-24
                    • TEST: SECURITY-UM-25
                    • TEST: SECURITY-UM-26
                    • TEST: SECURITY-UM-27
                    • TEST: SECURITY-UM-28
                    • TEST: SECURITY-UM-29
                    • TEST: SECURITY-UM-30
                    • TEST: SECURITY-UM-31
                    • TEST: SECURITY-UM-32
                    • TEST: SECURITY-UM-33
                    • TEST: SECURITY-UM-34
                    • TEST: SECURITY-UM-35
                    • TEST: SECURITY-UM-36
                    • TEST: SECURITY-UM-37
                  • Group/Role Management Tests
                    • TEST: SECURITY-GRM-01
                    • TEST: SECURITY-GRM-02
                    • TEST: SECURITY-GRM-03
                    • TEST: SECURITY-GRM-04
                    • TEST: SECURITY-GRM-05
                    • TEST: SECURITY-GRM-06
                    • TEST: SECURITY-GRM-07
                    • TEST: SECURITY-GRM-08
                    • TEST: SECURITY-GRM-09
                    • TEST: SECURITY-GRM-10
                    • TEST: SECURITY-GRM-11
                    • TEST: SECURITY-GRM-12
                    • TEST: SECURITY-GRM-13
                    • TEST: SECURITY-GRM-14
                    • TEST: SECURITY-GRM-15
                  • Security Policy Management Tests
                    • TEST: SECURITY-PM-01
                    • TEST: SECURITY-PM-02
                    • TEST: SECURITY-PM-03
                    • TEST: SECURITY-PM-04
                  • Device Management Tests
                    • TEST: SECURITY-DM-01
                    • TEST: SECURITY-DM-02
                    • TEST: SECURITY-DM-03
                    • TEST: SECURITY-DM-04
                    • TEST: SECURITY-DM-05
                    • TEST: SECURITY-DM-06
                    • TEST: SECURITY-DM-07
                    • TEST: SECURITY-DM-08
                    • TEST: SECURITY-DM-09
                  • Application Management Tests
                    • TEST: SECURITY-AM-01
                    • TEST: SECURITY-AM-02
                    • TEST: SECURITY-AM-03
                    • TEST: SECURITY-AM-04
                    • TEST: SECURITY-AM-05
                    • TEST: SECURITY-AM-06
                    • TEST: SECURITY-AM-07
                    • TEST: SECURITY-AM-08
          • SanteDB dCDR Instances
            • Installing Web Access Gateway
            • Installing Disconnected Gateway
            • Installing Disconnected Windows Application
            • Installing the dCDR SDK
            • User Interface App Settings
        • Configuring Privacy Controls
        • Post Deployment Tuning
        • Securing SanteDB Configuration
        • Securing SanteDB Databases
        • Securing SanteDB APIs
      • Rollout
    • Demonstration Environments
  • Operations
    • SanteDB Operations
    • Server Administration
      • Configuration Tool
        • Messaging Settings
          • HL7 Version 2 Service
          • FHIR R4 Service
          • GS1 BMS XML Service
          • Health Data Services Interface
          • Administrative Management Interface
        • Diagnostics Settings
        • Persistence Settings
          • Retention Policies
          • Resource Manager Settings
          • Database Connections
        • System Settings
        • Performance Settings
        • Security Settings
          • Data Privacy Filtering
          • Auditing Configuration
        • Operating System Settings
      • Server Configuration File
        • Service API Configuration
          • REST Service Configuration
        • Connection Strings
        • Application Service Context Configuration
        • Applet Configuration
        • Diagnostics Configuration
        • Data Quality Services
      • SanteDB iCDR Host Command
      • Backup Procedures
      • Log File Management
    • CDR Administration
      • SanteDB Administration Portal
        • Logging In
        • Managing Your Profile
        • System Administration
          • Jobs
          • Logs
          • Pub/Sub Manager
          • Server Status
          • Dispatcher Queue
          • Probes
        • Reference Data Administration
          • Place Administration
          • Facility Administration
          • Materials
          • Identity Domain Management
        • Concept Dictionary Administration
          • Concept Sets
          • Concepts
          • Code Systems
        • CDR Administration
          • Importing Data
          • Data Quality Rules
          • Extensions
          • Decision Support Library
            • View CDSS Library
            • Edit CDSS Library
          • Matching Configuration
            • Creating / Viewing Configurations
            • General Configuration
            • Blocking Configuration
            • Scoring Configuration
            • Classification Configuration
            • Testing Match Configuration
            • Match Configuration XML Definition
        • Data Warehouse
        • Reports Centre
        • Security Administration
          • Managing User Accounts
          • Managing Groups
          • Managing Policies
          • Managing Devices
          • Managing Applications
          • Reviewing Audits
      • SanteDB Administration Console
        • User Administration
        • Group / Role Administration
        • Policy Administration
        • Device Administration
        • Application Administration
    • Standard Operating Procedures
      • User Management SOPs
        • SOP: Onboarding Users
        • SOP: User Lockout
        • SOP: Deactivating Users
      • Role Management SOPs
        • SOP: Role Policy Assignment
        • SOP: Assigning Users to Roles
        • SOP: Creating New Roles
      • Device Management SOPs
        • SOP: Onboarding new HL7v2 Device
        • SOP: Onboarding new dCDR Device
      • Application Management SOPs
      • Standard Operating Procedure Template
  • User Guides & Training
    • SanteDB User Guides
    • Common User Interface Elements
    • SanteMPI
      • Getting Started with the MPI
      • SanteMPI Matches
      • SanteMPI Searching
      • SanteMPI Power Search
      • SanteMPI Patient Detail
        • Demographics Tab
          • Demographic Information Panel
          • Identifiers Panel
          • Related Persons Panel
          • Entity Relationships Panel
        • Master Data Management Tab
          • Records of Truth
        • Data Quality Tab
      • SanteMPI Dashboard
    • SanteEMR
      • EMR Administration
        • Care Pathways
        • Visit Types & Flows
        • Clinical Templates
    • SanteGuard
  • Developers
    • Extending & Customizing SanteDB
    • Getting Started
    • SanteDB XML Schemas
    • Applets
      • Applet Use and Lifecycle
      • Applet SDK Components
        • Applet Development Environment
        • SanteDB Brain Bug
        • Package Manager
        • BRE Debugger
      • Applet Structure
      • JavaScript API
      • Business Intelligence Assets
        • BI Asset Definitions
          • Data Sources
          • Parameters
          • Queries
          • Reference Data
          • Views
          • Data Marts
          • Reports
          • Indicators
        • BI Render Controls
      • Localization
      • Customization & Branding
      • Assets
        • HTML Assets
        • HTML Widgets
        • Virtual Assets
      • AngularJS
      • Clinical Decision-Support
        • CDSS Definitions
        • Legacy CDSS
      • Business Rules
      • Dataset Files
      • External Data Maps
      • Applet Solution Packages
      • JavaScript API Reference
      • Recipes
        • Adding Security Policy based on Occupation
        • Assigning a Home Facility
        • Codified Address
        • Generating ID on Registration
    • .NET Plugins
      • Plugin Libraries
      • Host Context & Lifecycle
      • Business Model Objects
      • Services & Configuration
        • Configuration
          • Configuration Panels
          • Custom Docker Feature Configuration
        • Passive Services
        • Daemon Services
        • Service Definitions
          • Ad-Hoc Cache Provider
          • Application Identity Provider
          • Audit Dispatch Service
          • Barcode Generator Provider
          • Business Rules Service
          • Care Plan Generation Service
          • CDSS Clinical Protocol Repository
          • Concept/Terminology Provider
          • Configuration Manager Service
          • Daemon Service
          • Data Archiving Service
          • Data Privacy Enforcement Provider
          • Data Signing Service
          • dCDR Subscription Definition Provider
          • dCDR Subscription Execution Provider
          • Device Identity Provider
          • Exec-Once Message Persistence
          • Freetext Search Provider
          • IDataPersistenceService{TData}
          • IDataPersistenceServiceEx{TModel}
          • IDataQualityConfigurationProviderService
          • Identity Domain Provider
          • IDispatcherQueueManagerService
          • IElevatableIdentityProviderService
          • IExtensionTypeRepository
          • IFastQueryDataPersistenceService{TEntity}
          • IFastQueryRepositoryService{TEntity}
          • IPersistableQueryRepositoryService{TEntity}
          • IPubSubManagerService
          • IRecordMergingService{T}
          • IRepositoryService
          • ISecurityRepositoryService
          • ISqlDataPersistenceService
          • IStoredQueryDataPersistenceService{TEntity}
          • ITagPersistenceService
          • ITemplateDefinitionRepositoryService
          • IThreadPoolService
          • IUnionQueryDataPersistenceService{TEntity}
          • IValidatingRepositoryService{TModel}
          • Job Management Service
          • Localization Provider
          • Mail Repository Provider
          • Name Alias Provider
          • Network Metadata Provider
          • Password Hashing Service
          • Password Validation Service
          • Policy Decision Provider (PDP)
          • Policy Enforcement Provider (PEP)
          • Policy Information Provider (PIP)
          • Primary Data Caching Provider
          • Query Result Scoring Provider
          • Record Matching Configuration Provider
          • Record Matching Provider
          • Record Merging Provider
          • Repository Service
          • Repository Service with Cancellation Support
          • Repository Service with Extended Functions
          • Repository Service with Notification Support
          • Resource Checkout/Locking Provider
          • Resource Patching Provider
          • Resource Pointer Service
          • Role Provider
          • Security Challenge Authentication Provider
          • Security Challenge Storage Provider
          • Session Authentication Provider
          • Session Storage Provider
          • Stateful Query Provider
          • Stock Management Provider
          • Symmetric Encryption Provider
          • TFA/MFA Secret Generator
          • User Identity Provider
          • User Notification Relay Provider
          • User Notification Template Filler
          • User Notification Template Repository
      • Plugin Metadata
      • Database Patching
      • Custom Match Algorithms
      • Unit Testing Framework
      • Digital Signing Requirements
      • .NET API Reference
    • Service APIs
      • OpenID Connect
        • Consent & Privacy
      • Business Intelligence Service (BIS)
      • Administration Management Interface (AMI)
      • Health Data Service Interface (HDSI)
        • HTTP Request Verbs
        • HDSI Query Syntax
          • Filter Functions
        • API Responses
        • Patching
        • MDM Extensions for HDSI
        • Synchronization API
        • Visual Resource Pointer API
      • HL7v2
        • Enabling HL7v2 Interfaces
        • HL7 Authentication
        • SanteDB HL7v2 Implementation
      • HL7 FHIR
        • Enabling FHIR Interfaces
        • SanteDB FHIR Implementation
          • FHIR Subscriptions
          • Related Persons
        • Extending FHIR Functionality
      • GS1 BMS XML
      • Examples
        • Connecting to the FHIR API
        • Obtaining A Session
    • SanteDB Software Publishers
  • Knowledgebase
    • Knowledgebase
      • SanteDB 2.1.161+ on PostgreSQL 10 returns "websearch_to_tsquery" error
      • Upgrading SanteDB iCDR with large databases
      • Upgrading Gateway to SanteDB Langley (v2.0.30+) from SanteDB Kelowna and earlier
      • When sending a National Scoped ID in PID-19 (SSN) you receive "AuthorityUuid" missing error
      • After Installing dCDR you receive an error on SecurityUser
      • When logging into the dCDR you are immediately logged back out
      • PostgreSQL connections fail with block message
      • Backing up HDSI server database
      • You receive an "out of disk space" error on the IMS server
      • Setting up the "sherlock" service
      • Diagnosing service port issues
      • You receive a certificate expired or certificate not found error on startup
      • After updating a database field the values are not reflected in the application layer
      • Diagnosing Submission Errors From Mobile Device
      • Migrating A SanteDB Server
      • Pruning and Cleaning the Database
      • Improving Download Speeds on Slow Connections
      • You receive a client already running error message
      • Resetting the configuration of the Windows & Linux Applications
      • After setting up the application data appears to be missing
      • Disconnected Client Window is Scaled Improperly
      • Fatal Error on Startup
      • Synchronization Issues on Mobile
      • Installation on Mono 4.x does not permit joining of realm
      • Creating A Public Backup
      • Installing the SanteDB Disconnected Server
    • Fixes & Patches
      • 20170721-01
      • 20170725-01
      • 20170803-01
      • 20170804-01
      • 20170913-01
      • 20171003-01
      • 20171011-01
      • 20171016-01
      • 20171023-01
      • 20171030-01
      • 20171108-01
      • 20171124-01
      • 20180126-01
      • 20180131-01
      • 20180211-01
      • 20181112-01
      • 20181113-01
      • 20190322-01
      • 20190522-01
      • 20190625-01
      • 20200105-01
  • OpenIZ
    • About OpenIZ
      • Upgrading from OpenIZ to SanteDB
    • FAQ
    • OpenIZ Demonstration Servers
Powered by GitBook
On this page
  • Property Paths
  • And/Or Semantics
  • Operators
  • Collection Guards
  • Complex Guards
  • Casting
  • Coalesce
  • Variables
  • Built-In Variables
  • Matching Variables
  • CDSS Variables
  • Extension Functions
  • Control Parameters
  • Freetext Search
  • PostgreSQL tsvector Search
  • Performance Tips

Was this helpful?

  1. Developers
  2. Service APIs
  3. Health Data Service Interface (HDSI)

HDSI Query Syntax

PreviousHTTP Request VerbsNextFilter Functions

Last updated 7 months ago

Was this helpful?

Both the HDSI and AMI use a general purpose query syntax which provide methods for matching records within the database on those interfaces. The HDSI query syntax is mapped to the RIM objects (wire format) returned by those APIs.

The HDSI query syntax is translated from HTTP query headers to LINQ expression trees and then used within the SanteDB iCDR and dCDR instances where needed (running business rules, filtering lists, querying against the database).

When passing HDSI queries over HTTP you must URL encode them. The examples here are not URL encoded and only suitable in matching and care planning rules.

Property Paths

In general an HDSI query is executed using parameters found in the object which is being queried. For example, an HDSI query for all patients named TEST would be:

name.component.value=TEST

This query is translated into a .NET expression tree roughly equivalent to

o => o.Names.Any(name => name.Component.Any(component => component.Value == "TEST"))

The properties are traversed using dotted notation matching the property names in the returned object as illustrated below.

And/Or Semantics

By default all filters passed in an HDSI query string are AND unless the property path is the same, in which case multiples are treated as OR. For example, to find patients with any name component of either JOHN or SMITH

name.component.value=JOHN&name.component.value=SMITH

However, if guards are applied, we can execute given name JOHN and family name SMITH

name.component[Given].value=JOHN&name.component[Family].value=SMITH

If we wanted to query for given name of JOHN or JOHNNY and family name of SMITH

name.component[Given].value=JOHN&name.component[Given].value=JOHNNY&name.component[Family].value=SMITH

Operators

Operators allow for the filtering of values based on equality, negation, etc. The operators for HDSI query syntax are listed below:

Operation

Operator

Example

Equal

= or eq

name.component.value=JOHN

Not Equal

=! or ne

name.component.value=!JOHN name.component.value=neJOHN

Less Than

=< or lt

dateOfBirth=<2020-01-01 dateOfBirth=lt2020-01-01

Less Than or Equal

=<= or lte

dateOfBirth=<=2020-01-01 dateOfBirth=lte2020-01-01

Greater Than

=> or gt

dateOfBirth=>2020-01-01 dateOfBirth=gt2020-01-01

Greater Than or Equal

=>= or gte

dateOfBirth=>=2020-01-01 dateOfBirth=gte2020-01-01

About Equal (Pattern)

=~ or ap

name.component.value=~JO* name.component.value=apJO*

Starts With

=^

name.component.value=^JO

Ends With

=$

name.componentvalue=$HN

Collection Guards

By default any filter which is applied to a property which is a collection (identifiers, name, addresses, etc.) is filtered as ANY. The following example illustrates a match where any identifier of a patient equals 123-234-234:

identifier.value=123-234-234

In order to specify a particular instance on a traversal a guard is applied, guards are applied using square brackets and the code mnemonic of the classifier you want to guard on. For example, if we wanted only patients having an SSN of 123-234-234:

identifier[SSN].value=123-234-234

Classifiers on properties will depend on the type of property being filtered, a common list of properties and their classifiers are included below.

Type

Classifier

Example

Addresses

Address Use

address[HomeAddress].component.value=ON

Names

Name Use

name[Legal].component.value=SMITH

Identifiers

Identifier Assigner

identifier[SSN].value=123-123-123

Telecoms

Telecom Use

telecom[WorkPlace].value=304-043-2039

Relationships

Relationship Type

relationship[Mother].target=UUID

Participations

Participation Role

participation[RecordTarget].player=UUID

Name / Address Component

Component Type

name.component[Given].value=JOHN

If using multiple classifiers you can either represent them individually

name[Legal].component.value=SMITH&name[OfficialRecord].component.value=SMITH

However this is not recommended as the query builder will create two clauses, the query above roughly translates to:

o => o.Names.Where(
        guard => guard.NameUse.Mnemonic == "Legal"
     ).Any(
        name => name.Component.Any(
           component => component.Value == "SMITH"))
     || o.Names.Where(
        guard => guard.NameUse.Mnemonic == "OfficialRecord")
        .Any(
           name => name.Component.Any(
              component => component.Value == "SMITH"))

Instead you can combine the guards:

name[Legal|OfficialRecord].component.value=SMITH

Which translates to a reduced LINQ expression:

o => o.Names.Where(
          guard => guard.NameUse.Mnemonic == "Legal" 
                || guard.NameUse.Mnemonic == "OfficialRecord")
      .Any(
          name => name.Component.Any(
               component => component.Value == "SMITH"))

Complex Guards

This section documents a feature that is only available in SanteDB v3.0 or later

Guards can also contain complex expressions. Complex expressions in a guard are triggered by using the = sign in the guard. For example, to guard on a telecom address whose use is Home and type is an e-mail:

telecom[use.mnemonic=Home&amp;type.mnemonic=Internet].value=bob@bob.com

When submitting the request via a string or via HTTP directly the = in the guard expression must be URL escaped value of %3d

Casting

Sometimes an occasion arises where you wish to execute a sub-filter on a property which is of the wrong type. For example, if we wanted to filter for patients who have Mother with a date of birth before 1960, we would expect this query to work:

relationship[Mother].target.dateOfBirth=<1960

However, looking at the traversal for target on the EntityRelationship class, the type is of Entity rather than a Person. Entity does not have a dateOfBirth , we need to tell the query engine that we want to further restrict the target to be a Person, this is done with the CAST operator:

relationship[Mother].target@Person.dateOfBirth=<1960

Coalesce

Sometimes a traversal path may not have a value, this can cause issues when the iCDR attempts to execute filters against in-memory objects such as in the care planner or matching engine. In these scenarios you can use the coalesce operator (also known as the "Elvis" operator). This operator does null-safe traversal, for example, to match a patient with a gender code which may or may not be present:

genderConcept?.mnemonic=Male

Variables

Variables are either defined by the user (for example, in the data retention service) or by the host context (such as $index in the CDSS for repeated actions, or $input in the matcher for the inbound record).

Variables may be referenced as the value, for example, if a $mothersBirth variable was defined in a retention policy, it could be used in the filter as:

relationship[Mother].target@Person.dateOfBirth=<$mothersBirth

Variables can also be used as the root of another HDSI expression, for example, comparing the city in which an $input patient lives.

address.component[City].value=$input.address.component[City].value

Built-In Variables

The following variables are available when using the HDSI query syntax in any context.

Variable
Type
Description

$now

DateTimeOffset

The current timestamp on the iCDR or dCDR sever.

$today

DateTime

The current date (year, month and day) on the iCDR or dCDR server

Matching Variables

When using the SanteDB matching engine the HDSI query syntax is extended to include additional variables.

Variable
Type
Description

$input

Entity

The entity which is attempting to be registered.

CDSS Variables

When evaluating HDSI expressions in the CDSS engine the following additional variables are exposed.

Variable
Type
Description

$index

Integer

When the repeat clause is specified on a rule, this represents the current index of the repetition

$background

Boolean

When true, indicates that the CDSS rule is being called as part of a background process, when false indicates that the CDSS rule is being executed in the user interface.

Extension Functions

The default matching operations may be extended via SanteDB's query extension methods. These methods allow for custom matching parameters. These extension functions are enumerated below (with a discussion on which plugins must be enabled to activate them).

Functions are applied in the format:

property=:(extension|parameter1,parameter2)value

See: Filter Functions for more information on filter functions.

Control Parameters

HDSI query control parameters are prefixed with an underscore. These query parameters are not mapped to the internal data structures of the RIM for filtering, and are intended, to provide control over how the result set is returned.

_count

number

Controls the number of records which are returned in the result set.

_offset

number

Controls the offset of the first record to be returned in the result set.

_orderBy

field:[asc|desc]

Controls the ordering of results in the result set.

_any

string

Initiates a free text search (or rather, allows the server to control how the result set is queried).

_includeTotal

boolean

True if the response should include the total count - this is used to allow callers to indicate that they don't want the API to perform the extra step of COUNT of results.

Freetext Search

The _any parameter in a search allows clients to execute a filter on any data in the requested resource. The behavior of the _any parameter depends on the persistence layer and how the has been configured.

  • On PostgreSQL this search uses the tsvector type to execute web search queries.

  • On SQLite (before version 2.3 of the dCDR) the search uses a simple keyword search. Integration of the Lucene engine is being developed for version 2.3 of the dCDR

  • On Firebird the search maps to a query on name.component.value or address.component.value or identifier.value.

PostgreSQL tsvector Search

_any=Jim Smith

Additionally simple logic can be applied via and/or:

_any='Jim Smith' and 'Beamsville ON' and 'FHR-304'

Performance Tips

When writing your HDSI queries, you can ensure that you have higher performance by structuring your queries in a particular way. Some recommendations:

  1. Use Guards: Whenever possible use guard conditions, this reduces the records to be filtered by the database system and (if you've partitioned tables) can dictate particular partitions to use.

  2. Combine Guard Conditions: You can combine guard conditions as illustrated above, this ensures that results are filtered with one EXISTS condition in the database rather than multiple

  3. Special Indexing: You can (and should) apply additional indexing to your SanteDB database to take advantage of common functions and queries. For example, if you often use the SOUNDEX algorithm to search for addresses, you might want to create an index like: CREATE INDEX addr_cmp_val_soundex_idx ON addr_cmp_val_tbl(SOUNDEX(val));

  4. Partition Tables: You can partition collection tables based on their classifiers , this can make it easier for the database system to filter data based on classifiers. There is an partitioning script in the SQL\ directory of your iCDR installation folder. This sets up partitions for the entity relationship and act participations.

If configured, the iCDR running on PostgreSQL will use the search engine. Searches can be executed as a simple web search. For example to match based on name, address, identifier or telecom of Jim and Smith:

PostgreSQL FreeText