search

Documentation

Overview

Package search contains types and helpers to work with FHIR Search. You can use these to provide search capabilities for your custom implementation.

Currently, only an API with cursor-based pagination is supported. Parameters for offset based pagination might be added eventually if there is demand.

Example

import "github.com/DAMEDIC/fhir-toolbox-go/capabilities/search"

func (b *myAPI) SearchCapabilitiesObservation() search.Capabilities {
	// return supported search capabilities
	return search.Capabilities{
		Params: map[string]search.ParamDesc{
			"_id": {Type: search.Token},
		},
	}
}

func (b *myAPI) SearchObservation(ctx context.Context, options search.Options) (search.Result, capabilities.FHIRError) {
	// return the search result
	return search.Result{ ... }, nil
}

Index

• Constants
• Variables
• type AndList
• type Capabilities
• type Cursor
• type DatePrecision
  • func ParseDate(value string, tz *time.Location) (time.Time, DatePrecision, error)
• type Modifier
• type Options
  • func ParseOptions(searchCapabilities Capabilities, params url.Values, tz *time.Location, ...) (Options, error)
  • func (o Options) QueryString() string
• type OrList
• type ParamDesc
• type ParamType
• type Params
  • func (p Params) Query() url.Values
• type Prefix
• type Result
• type Value
  • func (v Value) String() string

Constants

const (
	DateFormatOnlyYear   = "2006"
	DateFormatUpToMonth  = "2006-01"
	DateFormatUpToDay    = "2006-01-02"
	DateFormatHourMinute = "2006-01-02T15:04Z07:00"
	DateFormatFullTime   = "2006-01-02T15:04:05.999999999Z07:00"
)

Format strings for precision aware parsing and encoding.

Variables

var KnownPrefixes = []Prefix{Equal, NotEqual, GreaterThan, LessThan, GreaterOrEqual, LessOrEqual, StartsAfter, EndsBefore}

Types

type AndList

type AndList []OrList

type Capabilities

type Capabilities struct {
	Params   map[string]ParamDesc
	Includes []string
}

Capabilities describe what search capabilities the server provides.

It can be used to derive CapabilityStatements which describe what a FHIR system can do.

type Cursor

type Cursor string

Cursor is used for pagination.

It references where the server shall pick up querying additional results for multi-page queries.

type DatePrecision

type DatePrecision string

DatePrecision represents the precision of date value.

const (
	PrecisionYear       DatePrecision = "year"
	PrecisionMonth      DatePrecision = "month"
	PrecisionDay        DatePrecision = "day"
	PrecisionHourMinute DatePrecision = "hourMinute"
	PrecisionFullTime   DatePrecision = "time"
)

func ParseDate

func ParseDate(value string, tz *time.Location) (time.Time, DatePrecision, error)

type Modifier

type Modifier string

Modifier supported by an implementation.

const (
	// ModifierAbove on reference, token, uri: Tests whether the value in a resource is or subsumes the supplied parameter value (is-a, or hierarchical relationships).
	ModifierAbove Modifier = "above"
	// ModifierBelow on reference, token, uri: Tests whether the value in a resource is or is subsumed by the supplied parameter value (is-a, or hierarchical relationships).
	ModifierBelow Modifier = "below"
	// ModifierCodeText on reference, token: Tests whether the textual display value in a resource (e.g., CodeableConcept.text, Coding.display, or Reference.display) matches the supplied parameter value.
	ModifierCodeText Modifier = "code-text"
	// ModifierContains on string, uri: Tests whether the value in a resource includes the supplied parameter value anywhere within the field being searched.
	ModifierContains Modifier = "contains"
	// ModifierExact on string: Tests whether the value in a resource exactly matches the supplied parameter value (the whole string, including casing and accents).
	ModifierExact Modifier = "exact"
	// ModifierIdentifier on reference: Tests whether the Reference.identifier in a resource (rather than the Reference.reference) matches the supplied parameter value.
	ModifierIdentifier Modifier = "identifier"
	// ModifierInModifier on token: Tests whether the value in a resource is a member of the supplied parameter ValueSet.
	ModifierInModifier = "in"
	// ModifierIterate Not allowed anywhere by default: The search parameter indicates an inclusion directive (_include, _revinclude) that is applied to an included resource instead of the matching resource.
	ModifierIterate Modifier = "iterate"
	// ModifierMissing on date, number, quantity, reference, string, token, uri: Tests whether the value in a resource is present (when the supplied parameter value is true) or absent (when the supplied parameter value is false).
	ModifierMissing Modifier = "missing"
	// ModifierNot on token: Tests whether the value in a resource does not match the specified parameter value. Note that this includes resources that have no value for the parameter.
	ModifierNot Modifier = "not"
	// ModifierNotIn on reference, token: Tests whether the value in a resource is not a member of the supplied parameter ValueSet.
	ModifierNotIn Modifier = "not-in"
	// ModifierOfType on token (only Identifier): Tests whether the Identifier value in a resource matches the supplied parameter value.
	ModifierOfType Modifier = "of-type"
	// ModifierText on reference, token: Tests whether the textual value in a resource (e.g., CodeableConcept.text, Coding.display, Identifier.type.text, or Reference.display) matches the supplied parameter value using basic string matching (begins with or is, case-insensitive).
	//
	//on string: The search parameter value should be processed as input to a search with advanced text handling.
	ModifierText Modifier = "text"
	// ModifierTextAdvancedModifier on reference, token: Tests whether the value in a resource matches the supplied parameter value using advanced text handling that searches text associated with the code/value - e.g., CodeableConcept.text, Coding.display, or Identifier.type.text.
	ModifierTextAdvancedModifier = "text-advanced"
	// ModifierType on reference: Tests whether the value in a resource points to a resource of the supplied parameter type. Note: a concrete ResourceType is specified as the modifier (e.g., not the literal :[type], but a value such as :Patient).
	ModifierType Modifier = "[type]"
)

type Options

type Options struct {
	Params   Params
	Includes []string
	Count    int
	Cursor   Cursor
}

Options passed to a search implementation.

func ParseOptions

func ParseOptions(
	searchCapabilities Capabilities,
	params url.Values,
	tz *time.Location,
	maxCount, defaultCount int,
) (Options, error)

ParseOptions parses search options from a url.Values query string.

Only parameters supported by the backing implementation as described by the passed `searchCapabilities` are used.

Result modifying parameters are parsed into separate fields on the Options object. All other parameters are parsed into [options.Params].

func (Options) QueryString

func (o Options) QueryString() string

QueryString of the search options.

Search parameters are sorted alphabetically, result modifying parameters like `_include` are appended at the end. The function is deterministic, the same `option` input will always yield the same output.

type OrList

type OrList []Value

type ParamDesc

type ParamDesc struct {
	Type      ParamType
	Modifiers []Modifier
}

ParamDesc describes a parameter that is supported by the implementation.

type ParamType

type ParamType string

ParamType is the type of the parameter

const (
	Number    ParamType = "number"
	Date      ParamType = "date"
	String    ParamType = "string"
	Token     ParamType = "token"
	Reference ParamType = "reference"
	Composite ParamType = "composite"
	Quantity  ParamType = "quantity"
	Uri       ParamType = "uri"
	Special   ParamType = "special"
)

type Params

type Params map[string]AndList

func (Params) Query

func (p Params) Query() url.Values

Query representing the search parameters.

All contained values are sorted, but the returned url.Values is backed by a map. To obtain a deterministic query string you can call url.Values.Encode, because it will sort the keys alphabetically.

type Prefix

type Prefix = string

A Prefix that some parameter types can use to change search behavior. See https://hl7.org/fhir/search.html#prefix.

const (
	Equal          Prefix = "eq"
	NotEqual       Prefix = "ne"
	GreaterThan    Prefix = "gt"
	LessThan       Prefix = "lt"
	GreaterOrEqual Prefix = "ge"
	LessOrEqual    Prefix = "le"
	StartsAfter    Prefix = "sa"
	EndsBefore     Prefix = "eb"
)

type Result

type Result struct {
	Resources []model.Resource
	Included  []model.Resource
	Next      Cursor
}

Result contains the result of a search operation.

type Value

type Value struct {
	Prefix        Prefix
	Modifier      Modifier
	DatePrecision DatePrecision
	Value         any
}

A Value to search for.

func (Value) String

func (v Value) String() string

String formats the value as string.

Prefixes and date precision are taken into account.