xDev Asia

Search parameter types (string, token, reference, date, number, quantity, uri), modifiers (:exact, :contains, :missing, :not), chaining, reverse chaining (_has), _include, _revinclude, _summary, _elements, _count, paging, Composite search parameters, custom SearchParameter.

HL7 FHIR - Chuẩn Dữ liệu Y tế từ Cơ bản đến Nâng cao

Phần 3: FHIR RESTful API và Data Exchange

xdev.asia

Xem bản video

1. Search Parameter Types

Type	Mô tả	Ví dụ
string	Tìm kiếm text	Patient?name=Nguyen
token	Code / identifier	Patient?gender=male
reference	Reference đến resource khác	Observation?subject=Patient/123
date	Ngày tháng	Patient?birthdate=1990-05-15
number	Số	RiskAssessment?probability=gt0.8
quantity	Số + đơn vị	Observation?value-quantity=gt5.4\|http://unitsofmeasure.org\|mg
uri	URI	ValueSet?url=http://hl7.org/fhir/ValueSet/example
composite	Kết hợp nhiều params	Observation?code-value-quantity=...
special	Đặc biệt	Location?near=42.2\|-71.0\|10\|km

2. String Search

# Default: starts-with, case-insensitive
GET /Patient?name=Nguyen

# Exact match
GET /Patient?name:exact=Nguyễn

# Contains
GET /Patient?name:contains=van

# Text (full-text search trên narrative)
GET /Patient?_text=hypertension

3. Token Search

# Chỉ code
GET /Patient?gender=male

# System + code
GET /Condition?code=http://hl7.org/fhir/sid/icd-10|I10

# Chỉ system (tìm tất cả codes trong system)
GET /Condition?code=http://snomed.info/sct|

# Identifier
GET /Patient?identifier=http://hospital.vn/mrn|MRN12345

# :not modifier
GET /Patient?gender:not=male

# :text modifier (tìm trên display text)
GET /Condition?code:text=hypertension

4. Date Search

# Exact date
GET /Patient?birthdate=1990-05-15

# Prefixes: eq, ne, gt, lt, ge, le, sa (starts after), eb (ends before)
GET /Patient?birthdate=gt1990-01-01
GET /Encounter?date=ge2025-01-01&date=le2025-01-31
GET /Observation?date=sa2025-01-01T00:00:00Z

# Precision matters
GET /Patient?birthdate=1990      # born in 1990
GET /Patient?birthdate=1990-05   # born in May 1990

5. Reference Search

# Relative reference
GET /Observation?subject=Patient/patient-001

# Chỉ ID (nếu type rõ ràng)
GET /Observation?subject=patient-001

# Absolute reference
GET /Observation?subject=https://fhir-server.example.com/fhir/r5/Patient/patient-001

# Identifier trên referenced resource
GET /Observation?subject:identifier=http://hospital.vn/mrn|MRN12345

6. Chaining — Tìm kiếm qua references

# Tìm Observation của Patient có tên "Nguyen"
GET /Observation?subject:Patient.name=Nguyen

# Chain sâu hơn
GET /Observation?subject:Patient.organization.name=Bach%20Mai

# Tìm MedicationRequest kê bởi Practitioner chuyên khoa Tim mạch
GET /MedicationRequest?requester:Practitioner.qualification=cardiology

7. Reverse Chaining (_has)

# Tìm Patient có Observation với code=hba1c và value>7
GET /Patient?_has:Observation:subject:code=4548-4&_has:Observation:subject:value-quantity=gt7

# Tìm Patient có Condition "hypertension" active
GET /Patient?_has:Condition:subject:code=I10&_has:Condition:subject:clinical-status=active

# Tìm Practitioner có ít nhất 1 Encounter
GET /Practitioner?_has:Encounter:participant:date=ge2025-01-01

8. _include và _revinclude

# _include: kéo theo referenced resources
# Tìm Encounter VÀ Patient của Encounter đó
GET /Encounter?date=ge2025-01-15&_include=Encounter:subject

# Multiple includes
GET /MedicationRequest?status=active
  &_include=MedicationRequest:subject
  &_include=MedicationRequest:requester
  &_include=MedicationRequest:medication

# _revinclude: kéo theo resources reference ngược lại
# Tìm Patient VÀ tất cả Observation, Condition reference đến Patient
GET /Patient?_id=patient-001
  &_revinclude=Observation:subject
  &_revinclude=Condition:subject

# :iterate — recursive include
GET /MedicationRequest?_include:iterate=MedicationRequest:medication

9. Result Parameters

# _count — số entry per page
GET /Patient?name=Nguyen&_count=20

# _sort — sắp xếp
GET /Observation?subject=Patient/patient-001&_sort=-date  # descending
GET /Patient?_sort=family,given                            # multi-sort

# _summary — trả về tóm tắt
GET /Patient?_summary=true      # chỉ `mandatory` elements
GET /Patient?_summary=count     # chỉ count, không trả resources
GET /Patient?_summary=text      # text + id + meta + mandatory

# _elements — chọn elements cụ thể
GET /Patient?_elements=name,birthDate,gender,identifier

# _total — kiểm soát tính total
GET /Patient?_total=accurate    # tính chính xác total
GET /Patient?_total=none        # không tính total (nhanh hơn)

10. Paging

{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 150,
  "link": [
    {"relation": "self",     "url": "...?_count=10&_offset=0"},
    {"relation": "first",    "url": "...?_count=10&_offset=0"},
    {"relation": "next",     "url": "...?_count=10&_offset=10"},
    {"relation": "last",     "url": "...?_count=10&_offset=140"}
  ]
}

Client follow link next để lấy trang tiếp theo. Không tự construct URL — luôn dùng link từ server response.

11. Custom SearchParameter

{
  "resourceType": "SearchParameter",
  "url": "http://hospital.vn/fhir/SearchParameter/patient-cccd",
  "name": "cccd",
  "status": "active",
  "description": "Tìm Patient theo số CCCD",
  "code": "cccd",
  "base": ["Patient"],
  "type": "token",
  "expression": "Patient.identifier.where(system='http://hospital.vn/cccd')"
}

# Sử dụng custom search parameter
GET /Patient?cccd=012345678901

12. Tổng kết

9 parameter types — string, token, reference, date, number, quantity, uri, composite, special
Modifiers — :exact, :contains, :missing, :not, :text, :identifier
Chaining — Tìm qua chain references (subject:Patient.name)
_has — Reverse chaining, tìm resource được reference bởi resource khác
_include / _revinclude — Kéo referenced resources vào kết quả
_summary, _elements, _sort, _count — Kiểm soát response

Bài 10: Search Parameters và tìm kiếm nâng cao