Aidbox User Docs
Run Aidbox locallyRun Aidbox in SandboxTalk to us Ask community
  • Aidbox FHIR platform documentation
    • Features
    • Architecture
  • Getting Started
    • Run Aidbox in Sandbox
    • Run Aidbox locally
    • Run Aidbox on AWS
    • Upload Sample Data
  • Tutorials
    • CRUD, Search Tutorials
      • Delete data
      • Set up uniqueness in Resource
      • Search Tutorials
        • Custom SearchParameter tutorial
        • Create custom Aidbox Search resource
        • Multilingual search tutorial
        • Migrate from Aidbox SearchParameter to FHIR SearchParameter
        • Change sort order by locale collation
    • Bulk API Tutorials
      • 🎓Synthea by Bulk API
      • 🎓$dump-sql tutorial
    • Security & Access Control Tutorials
      • Allow patients to see their own data
      • Restrict operations on resource type
      • Relationship-based access control
      • Creating user & set up full user access
      • Restricting Access to Patient Data
      • Create and test access control
      • RBAC
        • Flexible RBAC built-in to Aidbox
        • RBAC with JWT containing role
        • RBAC with ACL
      • Set-up token introspection
      • Prohibit user to login
      • Debug access control
      • Managing Admin Access to the Aidbox UI Using Okta Groups
      • Run Multibox locally
      • How to enable labels-based access control
      • How to enable patient data access API
      • How to enable SMART on FHIR on Patient Access API
      • How to enable hierarchical access control
      • How to configure Audit Log
    • Terminology Tutorials
      • Load ICD-10 terminology into Aidbox
      • Uploading IG terminology content to external FHIR terminology server
    • Validation Tutorials
      • Upload FHIR Implementation Guide
        • Environment Variable
        • Aidbox UI
          • IG Package from Aidbox Registry
          • Public URL to IG Package
          • Local IG Package
        • Aidbox FHIR API
        • UploadFIG Tool
      • ISiK
      • Carin BB
      • US Core
      • Davinci Pdex
      • mCode
    • Integration Toolkit Tutorials
      • Postmark integration tutorial
      • Mailgun integration tutorial
    • Subscriptions Tutorials
      • AidboxTopicSubscription NATS tutorial
    • Other tutorials
      • Run Aidbox with FHIR R6
      • Migrate from Multibox to Aidbox
      • SDC with Custom Resources
      • How to create FHIR NPM package
      • Migrate from legacy licence portal to Aidbox portal
      • How to run Aidbox in GCP Cloud Run
  • Overview
    • Licensing and Support
    • Aidbox user portal
      • Projects
      • Licenses
      • Members
    • Aidbox UI
      • Aidbox Notebooks
      • REST Console
      • Database Console
      • Attrs stats
      • DB Tables
      • DB Queries
    • Versioning
    • Release Notes
    • Contact us
  • Configuration
    • Settings
    • Configure Aidbox and Multibox
    • Init Bundle
  • API
    • REST API
      • CRUD
        • Create
        • Read
        • Update
        • Patch
        • Delete
      • FHIR Search
        • SearchParameter
        • Include and Revinclude
        • Chaining
      • Aidbox Search
      • Bundle
      • History
      • $everything on Patient
      • Other
        • Aidbox & FHIR formats
        • Capability Statement
        • $document
        • Observation/$lastn
        • $validate
        • SQL endpoints
        • $matcho
        • $to-format
        • Aidbox version
        • Health check
    • Bulk API
      • Configure Access Policies for Bulk API
      • $dump
      • $dump-sql
      • $dump-csv
      • $export
      • $load & /fhir/$load
      • $import & /fhir/$import
      • aidbox.bulk data import
      • Bulk import from an S3 bucket
    • Batch/Transaction
    • GraphQL API
    • Other APIs
      • Plan API
        • Provider Directory API
          • Practitioner
          • PractitionerRole
          • Organization
          • OrganizationAffiliation
        • Plan API Overview
      • Archive/Restore API
        • create-archive
        • restore-archive
        • prune-archived-data
        • delete-archive
      • ETAG support
      • Cache
      • Changes API
      • RPC API
      • Sequence API
      • Encryption API
      • Batch Upsert
  • Modules
    • Profiling and validation
      • FHIR Schema Validator
        • Aidbox FHIR IGs Registry
        • Setup Aidbox with FHIR Schema validation engine
      • Skip validation of references in resource using request header
      • Asynchronous resource validation
    • Security & Access Control
      • Authentication Flows
        • Basic Auth
        • Client Credentials Grant
        • Resource Owner Grant
        • Authorization Code Grant
        • Implicit Grant
        • Two Factor Authentication
        • External OAuth 2.0 Providers
        • Token Exchange
      • External identity providers
        • Aidbox
        • Okta
        • Azure AD
        • Azure AD with certificate authentication
        • Keycloak
        • GitHub
        • Microsoft AD FS
        • Apple
      • Access Control
        • AccessPolicy
        • Evaluation engines
        • Role-Based Access Control (/RBAC)
        • Attribute-based Access Control (/ABAC)
        • Multitenancy
        • Access control lists (/ACL)
        • Access policy dev tool
        • AccessPolicy best practices
      • Audit
        • Audit Log
    • Observability
      • Getting started
        • Run Aidbox with OpenTelemetry locally
        • How to export telemetry to the OTEL collector
      • Logs
        • How-to guides
          • OpenTelemetry logs
          • Elastic Logs and Monitoring Integration
          • Datadog Log management integration
          • Loki Log management integration
        • Tutorials
          • Log analysis and visualization tutorial
          • Export logs to Datadog tutorial
        • Extending Aidbox Logs
        • Technical reference
          • Log appenders
          • Log transformations
          • Log Schema
          • OTEL logs exporter parameters
      • Metrics
        • How-to guides
          • How to export metrics to the OTEL collector
          • Use Aidbox Metrics Server
          • Set-up Grafana integration
        • Technical reference
          • OpenTelemetry Metrics
          • OTEL metrics exporter parameters
      • Traces
        • How to use tracing
        • OTEL traces exporter parameters
    • Subscriptions
      • Aidbox topic-based subscriptions
        • Kafka AidboxTopicDestination
        • Webhook AidboxTopicDestination
        • GCP Pub/Sub AidboxTopicDestination
        • Tutorial: produce QuestionnaireResponse to Kafka topic
      • Aidbox SubSubscriptions
    • Aidbox Forms
      • Getting started
      • Aidbox Forms Interface
      • Aidbox UI Builder
        • UI Builder Interface
        • Form creation
          • Form Settings
          • Widgets
          • Components
          • Versioning
          • Form customisation in Theme Editor
          • Form signature
          • How-to guides
            • How to: populate forms with data
            • How to extract data from forms
            • How to calculate form filling percentage
          • Multilingual forms
          • FHIRPath Editor
        • Import Questionnaire
        • Form sharing
        • Printing forms
          • Template-based PDF generation
        • FHIR versions
        • Offline forms
        • Embedding
          • Request Interception
        • Configuration
        • Forms multitenancy
        • Building reports using SQL on FHIR
        • Integration with external terminology servers
        • External FHIR servers as a data backend
        • Store attachments in S3-like storages
      • Access Control in Forms
      • Audit Logging in Forms
      • Aidbox Form Gallery
    • Define extensions
      • Extensions using StructureDefinition
      • Extensions using FHIRSchema
    • Custom Resources
      • Custom resources using FHIR Schema
      • Custom resources using StructureDefinition
      • Migrate to FHIR Schema
        • Migrate custom resources defined with Entity & Attributes to FHIR Schema
        • Migrate custom resources defined with Zen to FHIR Schema
    • Aidbox terminology module
      • Concept
        • $translate-concepts
        • Handling hierarchies using ancestors
      • ValueSet
        • ValueSet Expansion
        • ValueSet Code Validation
        • Create a ValueSet
      • CodeSystem
        • CodeSystem Concept Lookup
        • CodeSystem Subsumption testing
        • CodeSystem Code Composition
      • Import external terminologies
        • Import flat file (/CSV)
        • $import operation
        • Ready-to-use terminologies
      • $translate on ConceptMap
    • SQL on FHIR
      • Defining flat views with View Definitions
      • Query data from flat views
      • Reference
    • Integration toolkit
      • C-CDA / FHIR Converter
        • List of supported templates
          • Admission Diagnosis Section (/V3)
          • Advance Directives Section (/entries optional) (/V3)
          • Advance Directives Section (/entries required) (/V3)
          • Allergies and Intolerances Section (/entries optional) (/V3)
          • Allergies and Intolerances Section (/entries required) (/V3)
          • Assessment Section
          • Chief Complaint Section
          • Chief Complaint and Reason for Visit Section
          • Complications Section (/V3)
          • Course of Care Section
          • DICOM Object Catalog Section - DCM 121181
          • Default Section Rules
          • Discharge Diagnosis Section (/V3)
          • Document Header
          • Encounters Section (/entries optional) (/V3)
          • Encounters Section (/entries required) (/V3)
          • Family History Section (/V3)
          • Functional Status Section (/V2)
          • General Status Section
          • Goals Section
          • Health Concerns Section (/V2)
          • History of Present Illness Section
          • Hospital Consultations Section
          • Hospital Course Section
          • Hospital Discharge Instructions Section
          • Hospital Discharge Physical Section
          • Hospital Discharge Studies Summary Section
          • Immunizations Section (/entries optional) (/V3)
          • Immunizations Section (/entries required) (/V3)
          • Medical (/General) History Section
          • Medical Equipment Section (/V2)
          • Medications Administered Section (/V2)
          • Medications Section (/entries optional) (/V2)
          • Medications Section (/entries required) (/V2)
          • Mental Status Section (/V2)
          • Notes
          • Nutrition Section
          • Objective Section
          • Operative Note Fluids Section
          • Operative Note Surgical Procedure Section
          • Past Medical History (/V3)
          • Payers Section (/V3)
          • Plan of Treatment Section (/V2)
          • Postprocedure Diagnosis Section (/V3)
          • Preoperative Diagnosis Section (/V3)
          • Problem Section (/entries optional) (/V3)
          • Problem Section (/entries required) (/V3)
          • Procedure Description Section
          • Procedure Disposition Section
          • Procedure Estimated Blood Loss Section
          • Procedure Implants Section
          • Procedure Specimens Taken Section
          • Procedures Section (/entries optional) (/V2)
          • Procedures Section (/entries required) (/V2)
          • Reason for Visit Section
          • Results Section (/entries optional) (/V3)
          • Results Section (/entries required) (/V3)
          • Review of Systems Section
          • Social History Section (/V3)
          • Vital Signs Section (/entries optional) (/V3)
          • Vital Signs Section (/entries required) (/V3)
        • How to deploy the service
        • Producing C-CDA documents
        • How to customize conversion rules
      • HL7 v2 Integration
        • HL7 v2 integration with Aidbox Project
        • Mappings with lisp/mapping
      • X12 message converter
      • Analytics
        • Power BI
      • Mappings
      • Email Providers integration
        • Setup SMTP provider
    • SMARTbox | FHIR API for EHRs
      • Get started
        • Set up Smartbox locally
        • Deploy Smartbox with Kubernetes
      • (/g)(/10) Standardized API for patient and population services
      • The B11 Decision Support Interventions
        • Source attributes
        • Feedback Sections
      • How-to guides
        • Pass Inferno tests with Smartbox
        • Perform EHR launch
        • Pass Inferno Visual Inspection and Attestation
        • Revoke granted access
        • Set up EHR-level customization
        • Check email templates
        • Setup email provider
        • Register users
        • Set up SSO with Auth0
        • Publish Terms of Use link onto the documentation page
        • Find out what resources were exported during the $export operation
        • Find documentation endpoint
      • Background information
        • Considerations for Testing with Inferno ONC
        • Adding Clients for Inferno tests
        • Multitenancy approach
        • What is Tenant
        • Email templating
    • ePrescription
      • Getting started
      • Authentication with mTLS
      • Pharmacies synchronization
      • Prescribing
        • NewRx Message
        • CancelRx Message
        • How to test Callback
      • Directory
        • DirectoryDownload Message
        • GetProviderLocation Message
        • AddProviderLocation Message
        • UpdateProviderLocation Message
        • DisableProviderLocation Message
      • Medications
        • FDB
      • References
        • Environment Variables
      • Frequently Asked Questions
    • Other modules
      • MDM
        • Train model
        • Configure MDM module
        • Find duplicates: $match
        • Mathematical details
      • MCP
  • Database
    • Overview
    • Database schema
    • PostgreSQL Extensions
    • AidboxDB
      • HA AidboxDB
    • Tutorials
      • Migrate to AidboxDB 16
      • Working with pgAgent
  • File storage
    • AWS S3
    • GCP Cloud Storage
    • Azure Blob Storage
    • Oracle Cloud Storage
  • Deployment and maintenance
    • Deploy Aidbox
      • Run Aidbox on Kubernetes
        • Deploy Production-ready Aidbox to Kubernetes
        • Deploy Aidbox with Helm Charts
        • Highly Available Aidbox
        • Self-signed SSL certificates
      • Run Aidbox on managed PostgreSQL
      • How to inject env variables into Init Bundle
    • Backup and Restore
      • Crunchy Operator (/pgBackRest)
      • pg_dump
      • pg_basebackup
      • WAL-G
    • Indexes
      • Get suggested indexes
      • Create indexes manually
  • App development
    • Use Aidbox with React
    • Aidbox SDK
      • Aidbox JavaScript SDK
      • Apps
      • NodeJs SDK
      • Python SDK
    • Examples
  • Reference
    • FHIR Schema reference
    • Settings reference
      • General
      • FHIR
      • Security & Access Control
      • Modules
      • Database
      • Web Server
      • Observability
      • Zen Project
    • Environment variables
      • Aidbox required environment variables
      • Optional environment variables
      • AidboxDB environment variables
    • System resources reference
      • IAM Module Resources
      • SDC Module Resources
      • Base Module Resources
      • Bulk Module Resources
      • AWF Module Resources
      • Cloud Module Resources
      • HL7v2 Module Resources
      • SQL on FHIR Module Resources
    • Email Providers reference
      • Notification resource reference
      • Mailgun environment variables
      • Postmark environment variables
    • Aidbox Forms reference
      • FHIR SDC API
      • Aidbox SDC API
      • Generating Questionnaire from PDF API
    • Aidbox SQL functions
  • Deprecated
    • Deprecated
      • Zen-related
        • RPC reference
          • aidbox
            • mdm
              • aidbox.mdm/update-mdm-tables
              • aidbox.mdm/match
        • FTR
        • Aidbox configuration project
          • Run Aidbox locally using Aidbox Configuraiton project
          • Aidbox configuration project structure
          • Set up and use configuration projects
          • Enable IGs
          • Repository
          • Seed Import
          • Manage Indexes in Zen Project
          • Seed v2
          • 🎓Migrate to git Aidbox Configuration Projects
          • Aidbox Configuration project reference
            • Zen Configuration
            • Aidbox project RPC reference
            • aidbox.config/config
          • Custom resources using Aidbox Project
          • First-Class Extensions using Zen
          • Zen Indexes
        • US Core IG
          • US Core IG support reference
        • Workflow Engine
          • Task
            • Aidbox Built-in Tasks
            • Task Executor API
            • Task User API
          • Workflow
            • Workflow User API
          • Services
          • Monitoring
        • FHIR conformance Deprecated guides
          • Touchstone FHIR 4.0.1 basic server
          • Touchstone FHIR USCore ClinData
          • How to enable US Core IG
            • Start Aidbox locally with US Core IG enabled
            • Add US Core IG to a running Aidbox instance
          • HL7 FHIR Da Vinci PDex Plan Net IG
        • Terminology Deprecated Tutorials
          • Inferno Test-Suite US Core 3.1.1
        • API constructor (/beta)
        • zen-lang validator
          • Write a custom zen profile
          • Load zen profiles into Aidbox
        • FHIR topic-based subscriptions
          • Set up SubscriptionTopic
          • Tutorial: Subscribe to Topic (/R4B)
          • API Reference
            • Subscription API
        • 🏗️FHIR Terminology Repository
          • FTR Specification
          • Create an FTR instance
            • FTR from CSV
            • FTR from FHIR IG
            • FTR from FTR — Direct Dependency
            • FTR from FTR — Supplement
          • FTR Manifest
          • Load SNOMED CT into Aidbox
          • Load LOINC into Aidbox
          • Load ICD-10-CM into Aidbox
          • Load RxNorm into Aidbox
          • Load US VSAC Package to Aidbox
          • Import via FTR
        • Zen Search Parameters
      • Entity / Attribute
        • Entities & Attributes
        • First-Class Extensions using Attribute
        • Custom Resources using Entity
        • Working with Extensions
        • Aidbox Search Parameters
      • Forms
      • Other
        • Custom Search
        • SearchQuery
        • Subscribe to new Patient resource
        • App Development Deprecated Tutorials
          • Receive logs from your app
            • X-Audit header
          • Working with Aidbox from .NET
          • Patient Encounter notification Application
        • Other Deprecated Tutorials
          • Resource generation with map-to-fhir-bundle-task and subscription triggers
          • APM Aidbox
          • Automatically archive AuditEvent resources in GCP storage guide
          • HL7 v2 pipeline with Patient mapping
          • How to migrate to Apline Linux
          • How to migrate transaction id to bigint
          • How to fix broken dates
          • Configure multi-tenancy
        • AidboxProfile
        • GCP Pub/Sub
Powered by GitBook
On this page
  • SearchParameter example
  • SearchParameter fields
  • Search Parameter Types
  • string
  • token
  • uri
  • reference
  • date
  • number
  • quantity
  • composite
  • special
  • Supported special FHIR SearchParameters
  • _id
  • _list
  • _lastUpdated
  • _profile
  • _text and _content
  • _ilike
  • _elements
  • _count
  • _page
  • _include
  • _revinclude
  • _filter
  • _has
  • _source
  • _security
  • _sort
  • _summary
  • Location.near
  • _tag
  • Custom Search Parameter

Was this helpful?

Edit on GitHub
  1. API
  2. REST API
  3. FHIR Search

SearchParameter

PreviousFHIR SearchNextInclude and Revinclude

Last updated 7 days ago

Was this helpful?

defines how a specific resource property can be used in search operations. It specifies:

  • The name of the parameter used in the URL

  • The type of parameter (string, token, reference, etc., explained below)

  • The path to the property in the resource that is being searched

  • Any special handling rules or modifiers that apply

For example, the Patient resource like:

  • name - Search by patient name (string type)

  • birthdate - Search by date of birth (date type)

  • identifier - Search by patient identifier (token type)

Search parameters can be defined in:

  • The core FHIR specification (e.g. )

  • Implementation guides (e.g. )

  • Aidbox itself in app.aidbox.main package (see )

SearchParameter example

Patient SearchParameters can be found at the end of or in AidboxUI (see ).

Patient's name SearchParameter example:

{
  "url": "http://hl7.org/fhir/SearchParameter/Patient-name",
  "id": "Patient-name",
  "base": [
    "Patient"
  ],
  "expression": "Patient.name",
  "code": "name",
  "name": "name",
  "status": "draft",
  "type": "string",
  "version": "4.0.1",
  "resourceType": "SearchParameter",
  "description": "A server defined search that may match any of the string fields in the HumanName, including family, give, prefix, suffix, suffix, and/or text"
}

SearchParameter fields

This table contains properties required by the FHIR specification and properties that Aidbox interprets.

Property
FHIR datatype
Description

url

uri

Search parameter unique canonical url

version

string

Search parameter version

name

string

Search parameter name, Aidbox ignores it

status

code

draft | active | retired | unknown

description

markdown

Human readable description of the search parameter

code

code

The code used in the URL to invoke this search parameter

base

code[]

The resource type(s) this search parameter applies to

type

code

number | date | string | token | reference | composite | quantity | uri | special

expression

string

component

BackboneElement

For Composite SearchParameters to define the parts

Search Parameter Types

SearchParameter type is defined in the SearchParameter.type field. It is important to understand the type of SearchParameter because there are differences in how they are processed.

For example, if the search parameter with code title is of type 'token', the search:

GET /fhir/Patient?title=smith

will match resources with title exactly equal to "smith", not "Smith" or "smiths". But it title is of type string, the search will match "smith", "Smith", "smiths", etc.

The list of SearchParameter types:

Type
Description
Example

String

Plain text matching

name=smith

Token

Coded or identifier values

status=active, code=123

Reference

Links to other resources

patient=Patient/123

Date

Date/time values and ranges

birthdate=2020, date=ge2019-01

Number

Numeric values and ranges

age=55, length=gt100

Quantity

Values with units

weight=100

Uri

URIs

url=http://example.com

Composite

Combines multiple values

component-code-value-quantity=code$value

Special

Implementation specific

_filter, _text, _content

string

String search parameters match against sequences of characters. Common search parameters of this type include names, addresses, and narrative text.

String searches are case-insensitive and accent-insensitive by default. The search matches if the field value equals or starts with the search parameter value.

For example:

  • name=John will match "John", "Johnny", "Johnson"

  • name=eve will match "Eve" and "Steven"

  • name=andré will match "Andre", "André", "Andres"

String searches support these modifiers:

  • :contains - Matches if the parameter value appears anywhere in the field (not just the start)

  • :exact - Matches the entire string exactly, including case and accents

  • :missing - Matches resources that do not have a value in the field

  • :text - Matches if the textual value in a resource matches the supplied parameter value using basic string matching (begins with or is, case-insensitive)

  • :starts - Matches if the parameter value appears at the start of the field

  • :ends - Matches if the parameter value appears at the end of the field

For example:

  • name:contains=eve will match "Eve", "Steven", "Genevieve"

  • name:exact=John will only match "John", not "john" or "Johnny"

token

Token search is used to search by exact match of status codes, terminology codes, identifiers, etc.

For example:

  • status=active will match resources with status exactly equal to "active"

  • code=123 will match resources with code exactly equal to "123"

Token searches support these modifiers:

Modifier
Description
Example

:missing

Matches resources that do not have a value in the field

code:missing=true

:text

Matches if the textual value in a resource matches the supplied parameter value using basic string matching (begins with or is, case-insensitive)

code:text=test

:in

Search within a ValueSet

code:in=/ValueSet/test-codes

:i

Case-insensitive search

code:i=TEST123

:not

Negates the search value

code:not=inactive

:of-type

Search for resource identifier

`identifier:of-type=system

uri

Uri search parameters match against URIs (RFC 3986). Common search parameters of this type include URLs, URNs, and other URI-based identifiers.

Uri searches are case-sensitive and match the entire URI string exactly.

For example:

  • url=http://example.com will match exactly "http://example.com"

  • url=urn:oid:1.2.3.4 will match exactly "urn:oid:1.2.3.4"

URI searches support these modifiers:

Modifier
Description
Example

:missing

Matches resources that do not have a value in the field

url:missing=true

:below

Tests whether the value in a resource is or is subsumed by the supplied parameter value (is-a, or hierarchical relationships)

url:below=http://acme.org/fhir/

:not

Negates the search value

url:not=http://example.com

reference

Reference search parameters match against references to other resources. They are used to search for resources that reference a specific resource.

For example:

  • subject=Patient/123 will match resources that reference the Patient resource with ID "123"

  • author=Practitioner/456 will match resources that reference the Practitioner resource with ID "456"

  • subject=123 will match resources that reference any resource with ID "123" (depending on the SearchParameter definition)

Reference searches support these modifiers:

Modifier
Description
Example

:identifier

Tests whether the Reference.identifier in a resource (rather than the Reference.reference) matches the supplied parameter value (logical reference)

patient:identifier=system

:missing

Matches resources that do not have a value in the field

patient:missing=true

:not

Negates the search value

patient:not=Patient/123

date

FHIR Ranges

All date comparisons in FHIR are range-based. The range consists of a lower bound and an upper bound.

The lower bound of the FHIR dateTime is the earliest complete datetime, which matches the FHIR dateTime value. For 2020, the lower bound is 2020-01-01T00:00:00Z.

Vice versa, the upper bound of the FHIR dateTime is the latest complete datetime.

Search using ranges

Searching by date is done by comparing the search range and the resource (target) range. The search range is the range of the search value.

For example, searching GET /fhir/Patient?birthdate=2020 means that the search range is 2020-01-01T00:00:00Z—2020-12-31T23:59:59Z.

Resource range is the range of the target resource value. For example, if the Patient resource contains birthDate 2020-01-01, the resource range is 2020-01-01T00:00:00Z—2020-01-01T23:59:59Z.

Description of FHIR prefixes:

number

Number search parameters match against decimal and integer values. They support the same prefixes as date parameters for range comparisons:

Prefix
Description
Example

eq

Equal (default)

probability=0.8

ne

Not equal

probability=ne0.8

gt

Greater than

probability=gt0.8

lt

Less than

probability=lt0.8

ge

Greater than or equal

probability=ge0.8

le

Less than or equal

probability=le0.8

Numbers can be expressed in decimal or exponential format:

  • probability=0.8

  • probability=8e-1

The number search parameter also supports the :missing modifier to test for the presence/absence of values:

  • probability:missing=true matches resources with no probability value

  • probability:missing=false matches resources that have a probability value

Multiple values can be combined with a comma for OR logic:

  • probability=0.8,0.9 matches resources with a probability of either 0.8 OR 0.9

Note that Aidbox does not involve an implicit range while searching on decimals, as FHIR suggests. Aidbox always searches for an exact number.

quantity

Quantity search parameters match against values with units. They support the same prefixes as number parameters for range comparisons:

Prefix
Description
Example

eq

Equal (default)

weight=100

ne

Not equal

weight=ne100

gt

Greater than

weight=gt100

However, Aidbox supports only numbers, not system with code. For example, weight=100 will match resources with weight exactly equal to "100", the unit is ignored.

composite

Since version 2308, Aidbox supports Composite Search Parameters.

id: my-observation
component:
- code: loinc|12907-2
  valueQuantity: 
    value: 1
- code: loinc|12907-1
  valueQuantity: 
    value: 2
# ...

If we want the search to match my-observation only if some component has both code = loinc|12907-2 and valueQuantity=1, we must use composite search:

GET /fhir/Observation?code-value-quantity=loinc|12907-2$1 // found
GET /fhir/Observation?code-value-quantity=loinc|12907-2$2 // not found
GET /fhir/Observation?code-value-quantity=loinc|12907-1$1 // not found
GET /fhir/Observation?code-value-quantity=loinc|12907-1$2 // found

However, if we use simple intersection, my-observation may be found in all cases:

GET /fhir/Observation?code=loinc|12907-2&value-quantity=1 // found
GET /fhir/Observation?code=loinc|12907-2&value-quantity=2 // found
GET /fhir/Observation?code=loinc|12907-1&value-quantity=1 // found
GET /fhir/Observation?code=loinc|12907-1&value-quantity=2 // found

special

Special search parameters have unique search behavior that cannot be expressed using the standard search parameter types. The behavior of special search parameters must be explicitly defined in their SearchParameter definition. Special parameters are useful for cases where the standard parameter types (string, token, reference, etc.) cannot adequately express the desired search functionality.

For example, the _filter parameter is a special parameter that allows complex boolean expressions for advanced filtering. The Location.near parameter is another special parameter that enables geographic proximity searches.

Supported special FHIR SearchParameters

_id

Search by resource ID:

GET /fhir/Patient?_id=pt-1

_list

 GET /fhir/Patient?_list=42

This request returns all Patient resources referenced from the list found at /List/42 in List.entry.item (which are not labeled as deleted by List.entry.item.deleted). While it is possible to retrieve the list and then iterate through he entries in the list, fetching each patient, using a list as a search criterion allows for additional search criteria to be specified. For instance:

 GET /fhir/Patient?_list=42&gender=female

This request will return all female patients on the list. The server can return the list referred to in the search parameter as an included resource, but is not required to do so. In addition, a system can support searching by lists by their logical function. For example:

GET /fhir/AllergyIntolerance?patient=42&_list=$current-allergies

This request will return all allergies in the patient 42's "Current Allergy List". The server returns all relevant AllergyIntolerance resources, and can also choose to return the list.

_lastUpdated

Search by the last modification time of the resource meta.lastUpdated (ts column in the database table)

GET /fhir/Patient?_lastUpdated=2019-01-01

You can use operators lt,le,gt,ge like in other date search parameters.

_profile

GET /fhir/Patient?_profile=http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient

_text and _content

  • to search by narrative using _text

  • to search by retaining the resource content using _content

GET /fhir/Patient?_text=John
GET /fhir/Patient?_content=New-York

Full-text search requests support grouping and logical operations:

GET /fhir/Patient?_content=(NOT bar OR baz) AND foo

If you want to search by the phrase, just quote it:

GET /fhir/Patient?_content="Mad Max"

_ilike

With _ilike search parameter, you search for term inclusion as a substring in the text representation of FHIR resource. It can provide quick feedback to the user about matches without forcing to print the whole word (as with full text search). For example jo will find Johns and Jolie or asp will match Aspirin.

GET /fhir/Patient?_ilike=joh+smit,jes+park

With _ilike parameter, your term is separated with a space, combined with AND and separated by comma , with OR. The example above is translated into a SQL query like this:

SELECT * FROM patient
WHERE
resource::text ilike '%joh%' AND ... ilike '%smit%'
OR
resource::text ilike '%jes%' AND ... '%park%'

ILIKE search can be efficiently indexed with the trigram PostgreSQL extension and GIN Index, responding to tens of milliseconds on millions of records.

CREATE INDEX patient_trgm_idx  on patient
USING gin (
  (id || ' ' || resource::text) gin_trgm_ops
);

VACUUM ANALYZE patient;

_elements

A client can request a specific set of elements to be returned as part of a resource in the search results using the _elements parameter:

GET /fhir/Patient?_elements=birthDate,name.given,address.city

The _elements parameter consists of a comma-separated list of element paths. Only element paths that are listed should be returned. The list of elements does not apply to included resources.

If you want to exclude specific elements, you can prefix them with the - sign:

GET /fhir/Patient?_elements=-text,-identifier

You can include or exclude nested elements using a dot-separated path to an element:

GET /fhir/Patient?_elements=name.given,name.family

The _elements parameter is not applied to included resources. If you want to filter included resource elements, prefix the element path with resourceType. For example:

GET /fhir/Encounter?_include=patient&_elements=id,type,Patient.name

Result will contain id and type elements from Encounter and the Patient's name. The - prefix will exclude elements (for example -Patient.identifier will exclude the identifier from Patient resources).

_count

_count is used to limit the number of records on the page.

GET /fhir/Patient?_count=10

Will return 10 records or fewer if no more records are available.

_page

Search results can contain many records, and for more convenient work, we can use pagination.

GET /fhir/Patient?_count=10&_page=3

Will return 10 records from the third page.

You can see the next, previous, first, and last pages in the response:

resourceType: Bundle
type: searchset
entry:
- resource:
    # ...
total: 206
link:
- {relation: first, url: '/Patient?_count=10&_page=1'}
- {relation: self, url: '/Patient?_count=10&_page=3'}
- {relation: next, url: '/Patient?_count=10&_page=4'}
- {relation: previous, url: '/Patient?_count=10&_page=2'}
- {relation: last, url: '/Patient?_count=10&_page=21'}

_total

By default, for all search requests, Aidbox returns the total number in the result, which represents how many resources matched the criteria. But to do this, we run the second query for the count, which takes some additional time.

Sometimes the count query is longer than your query.

To get a response faster, you can change this behavior using the _total parameter. The _total parameter can have the following values:

  • none - do not run count query (fastest)

  • estimate - roughly estimate the number of results (fast, additional request is EXPLAIN request)

  • accurate- run accurate count (could be slow, additional request is COUNT(*) request)

Note: if you use _total=none you still get total when you don't use _page and the number of returned resources is less than _count.

_include

See:

_revinclude

See:

_filter

GET /fhir/Patient?_filter=name co 'smi' or birthdate gt '1996-06-06'

Supported _filter operators:

Operation
String
Number
Date
Token
Reference
Quantity

eq

+

+**

+

+*

n/a

+***

ne

-

+**

+

-

n/a

+***

co

+

-

-

n/a

n/a

n/a

sw

+

n/a

n/a

n/a

n/a

n/a

ew

+

n/a

n/a

n/a

n/a

n/a

gt/ge/lt/le

-

+

+

n/a

n/a

+***

po

n/a

n/a

-

n/a

n/a

n/a

pr****

+

+

+

+

+

+

ss

n/a

n/a

n/a

-

n/a

n/a

sb

n/a

n/a

n/a

-

n/a

n/a

in

n/a

n/a

n/a

-

n/a

n/a

re

n/a

n/a

n/a

n/a

-

n/a

* token search is case sensitive

** number search doesn't support implicit precision

*** support only numbers, not system with code

**** available since version 2503

Additionally, Aidbox supports:

  • forward-chained search parameters in the _filter query

  • dot expressions in _filter query

Examples:

# returns patient with specific id
GET /fhir/Patient?_filter=id eq 'pt-2'

# returns patients with name that contain specific substring e.g. Smith
GET /fhir/Patient?_filter=name co 'smi'

# returns patients with address.city starting with provided string, e.g. London
GET /fhir/Patient?_filter=address-city sw 'Lon'

# returns all patients with birthdate >= (<=) provided date
GET /fhir/Patient?_filter=birthdate ge 1996-06-06
GET /fhir/Patient?_filter=birthdate le 1996-06-06

# logical expressions support
GET /fhir/Patient?_filter=(name co 'smi' or name co 'fed') or name co 'unex'

# forward chains
GET /fhir/Patient?_filter=(organization:Organization.name eq 'myorg')

# dot expressions
GET /fhir/Patient?_filter=.name.0.family eq 'Doe'
GET /fhir/Patient?_filter=.name isnull true

_has

See:

_source

Examples:

GET /fhir/Patient?_source=http://example.com/Organization/123
GET /fhir/Patient?_source:below=http://example.com/

_security

Example:

GET /fhir/Observation?_security=http://terminology.hl7.org/CodeSystem/v3-Confidentiality|R

_sort

Supports all search parameter types.

GET /fhir/Organization?_sort=name
GET /fhir/Patient?_sort=.name.0.family

You can sort by multiple parameters:

GET /fhir/Organization?_sort=name,_id

Sorting direction

You can change the sorting direction by prefixing the parameter with - sign

GET /fhir/Organization?_sort=-name,-lastUpdated

_summary

The client can request the server to return only summary elements of the resources by using the parameter _summary

Request:

GET /fhir/Patient?_summary=true

Response:

resourceType: Bundle
type: searchset
entry:
- resource: {id: Patient.active, isSummary: true, resourceType: Attribute}
  fullUrl: /Attribute/Patient.active
- resource: {id: Patient.address, isSummary: true, resourceType: Attribute}
  fullUrl: /Attribute/Patient.address
- resource: {id: Patient.animal, isSummary: true, resourceType: Attribute}
  fullUrl: /Attribute/Patient.animal
- resource: {id: Patient.animal.breed, isSummary: true, resourceType: Attribute}
  fullUrl: /Attribute/Patient.animal.breed
# .....

Values table:

Value
Description

Return only the "text" element, the 'id' element, the 'meta' element, and only top-level mandatory elements

Remove the text element

Search only: just return a count of the matching resources, without returning the actual matches

Return all parts of the resource(s)

The intent of the _summary parameter is to reduce the total processing load on the server, client, and resources between them, such as the network. It is most useful for resources that are large, particularly ones that include images or elements that may repeat many times.

The purpose of the summary form is to allow a client to quickly retrieve a large set of resources and let a user pick the appropriate one. The summary for an element is defined to allow a user to quickly sort and filter the resources, and typically omits important content on the basis that the entire resource will be retrieved when the user selects a resource.

Limitations

  • You can't expect only a summary response as requested. There is a limited number of summary forms defined for resources to allow servers to store the summarized form(s) in advance.

  • _include and _revinclude cannot be mixed with _summary=text.

Location.near

The request:

GET /fhir/Location?near=<latitude>|<longitude>|[distance]|[units]

Latitude and longitude are required.

If the units are omitted, then kms are assumed.

If the distance is also omitted, then Aidbox treats "near" as 3 km.

Examples

  1. Get locations within 11.2 km of some geo-coded position:

#                   latitude |longitude|distance|units
GET /fhir/Location?near=-83.674810|42.266500|11.20|km

Response:

resourceType: Bundle
total: 1
entry:
  - resource:
      position:
        latitude: -83.69481
        longitude: 42.2565
      id: >- loc-1
      resourceType: Location
  1. Search in miles:

GET /fhir/Location?near=-83.674810|42.266500|11.20|[mi_us]
  1. Search without distance and units

# distance = 3, units = km
GET /fhir/Location?near=-83.674810|42.266500

_tag

The _tag search parameter allows searching for resources tagged with specific codes. Tags are metadata that can be attached to any resource and are useful for categorizing or marking resources for various purposes.

Example:

GET /fhir/Patient?tag=emergency

Custom Search Parameter

See tutorials:

expression that extracts the values

identifier=mysystem|123 will match resources with exactly equal to "123" of system "mysystem"

As mentioned in , Date parameters may be used with the date, dateTime, instant, Period, or Timing data types. Every date in the search matches yyyy-mm-ddThh:mm:ss[Z|(+|-)hh:mm] format.

FHIR value can be an incomplete datetime. E.g. 2020 is a FHIR dateTime, but it is an incomplete datetime, since it doesn't specify month, day, etc.

For FHIR lower bound is the lower bound of the Period.start, similarly for the upper bound. Missing start or end in the period is treated as infinity.

Let (s,S)(s, S)(s,S) be the search range; (r,R)(r, R)(r,R)​ be the resource range.

eq - equal. Formula: (s,S)⊃(r,R)(s, S) \supset (r, R)(s,S)⊃(r,R)​

ne - not equal. Formula: (s,S)⊅(r,R)(s, S) \not\supset (r, R)(s,S)⊃(r,R)​

lt - less than. Formula: r≤sr \le sr≤s​

le - less than or equal. Formula: r≤Sr \le Sr≤S

gt - greater than. Formula: R>SR > SR>S

ge - greater than or equal. Formula: R≥sR \ge sR≥s​

sa - starts after. Formula: r≥Sr \ge Sr≥S​

eb - ends before. Formula: R≤sR \le sR≤s

are special search parameters that match resources by two or more values, separated by a $ sign. Such search parameters will search not by simple intersection like search-param1=value1&search-param2=value2, but more strictly.

For example, take a look at resource structure and suppose we have the following resource:

See also .

The _list parameter allows for the retrieval of resources that are referenced by a resource.

Search by the

by resources can be achieved:

Aidbox offers partial support for the . The most common use case to use _filter instead of the usual combination of search parameters is OR logic. In FHIR, it is impossible to use OR logic with 2 different search parameters without _filter,:

matches resources based on source information in the element.

The _security search parameter matches resources based on security labels in the element.

Aidbox also supports sorting with :

Return a limited subset of elements from the resource. This subset SHOULD consist solely of all supported elements that are marked as "summary" in the base definition of the resource(s) (see )

is used to search locations by coordinates using the WGS84 datum. Geopositional search is supported in Aidbox only with Aidboxdb 15.3 and later. Search for locations near the specified geo-coded position. Supported units are km and [mi_us].

See also :

SearchParameter FHIR resource
has search parameters
4.0.1
US Core
Custom Search Parameter tutorial
FHIR Patient page
Custom Search Parameter tutorial
identifier
FHIR Search specification
dateTime
Period
Composite Search Parameters
Observation
List
resource profile
Full-text-search
Include and Revinclude
Include and Revinclude
FHIR _filter API
Chaining
_source search parameter
Resource.meta.source
Resource.meta.security
Location search
Custom SearchParameter
Create Custom Aidbox Search resource
Aidbox Search page
FHIRPath
true
ElementDefinition.isSummary
text
data
count
false
Aidbox special search parameters
dot expressions
Aidbox special search parameters
Search resource
dot-expressions
AidboxQuery