Add near Search Param for Location Resource

.github/scripts/search-location-near.sh

@@ -0,0 +1,35 @@
+#!/bin/bash -e
+
+script_dir="$(dirname "$(readlink -f "$0")")"
+. "$script_dir/util.sh"
+
+base="http://localhost:8080/fhir"
+
+location() {
+cat <<END
+{
+  "resourceType": "Location",
+  "name": "$1",
+  "position": {
+    "latitude": $2,
+    "longitude": $3
+  }
+}
+END
+}
+
+location "Leipzig" "51.3397" "12.3731" | create "$base/Location" >/dev/null
+location "Jakarta" "-6.2" "106.8167" | create "$base/Location" >/dev/null
+
+response="$(curl -s -H "Content-Type: application/fhir+json" "$base/Location?near=43.77925|11.24626|900|km")"
+
+test "Location 900km from Florence finds Leipzig" "$(echo "$response" | jq -r .total)" "1"
+
+match_extension="$(echo "$response" | jq '.entry[0] | .search.extension[0]')"
+if echo "$match_extension" | jq -er '.valueDistance.unit == "m"' >/dev/null \
+  && echo "$match_extension" | jq -er '.url == "http://hl7.org/fhir/StructureDefinition/location-distance"' >/dev/null; then
+  echo "✅ the search result contains a location-distance extension"
+else
+  echo "🆘 the search does not contain a location-distance extension"
+  exit 1
+fi

.github/workflows/build.yml

@@ -1318,6 +1318,9 @@ jobs:
     - name: Control Character Handling
       run: .github/scripts/control-character-handling.sh
 
+    - name: Search for Location using near Search Param
+      run: .github/scripts/search-location-near.sh
+
     - name: Prometheus Metrics
       run: .github/scripts/test-metrics.sh
       if: ${{ matrix.variant == 'standalone' }}

docs/api/interaction/search-type.md

@@ -40,6 +40,10 @@ Search for `Resource.meta.profile` is supported using the `_profile` search para
 
 When searching for date/time with a search parameter value without timezone like `2024` or `2024-02-16`, Blaze calculates the range of the search parameter values based on [UTC][2]. That means that a resource with a date/time value staring at `2024-01-01T00:00:00+01:00` will be not found by a search with `2024`. Please comment on [issue #1498](https://github.com/samply/blaze/issues/1498) if you like to have this situation improved.
 
+## Geopositional Search
+
+Blaze implements the [positional](https://hl7.org/fhir/R4/location.html#positional) search parameter `near` for resources with a geospatial position (i.e., Location). The search parameter takes a latitude, longitude, distance and unit as search parameter values in the form `longitude|latitude[|distance[|unit]]`. Defaults for `distance` and `unit` are `1` and `km`. The [Haversine formula](https://en.wikipedia.org/wiki/Haversine_formula) is used to calculate the distance between the search parameter value and the resource's location, which simplifies calculation by assuming a spherical earth and has an error of less than approximately 0.5%.
+
 ## Sorting
 
 The special search parameter `_sort` supports the values `_id`, `_lastUpdated` and `-_lastUpdated`.

modules/db-protocols/src/blaze/db/impl/protocols.clj

@@ -139,9 +139,13 @@
     [search-param batch-db compartment tid compiled-value]
     [search-param batch-db compartment tid compiled-value start-id]
     "Returns a reducible collection.")
-  (-matcher [_ batch-db modifier values])
+  (-matcher [_ batch-db modifier compiled-values])
   (-single-version-id-matcher [_ batch-db tid modifier compiled-values])
-  (-second-pass-filter [search-param batch-db values])
+  (-postprocess-matches
+    [search-param batch-db values compiled-values]
+    "Returns a transducer that will be applied on every matching resource-handle
+     at the end of the query execution. Can also be used to finally remove
+     unwanted matches.")
   (-compartment-ids [_ resolver resource])
   (-index-values [_ resolver resource])
   (-index-value-compiler [_]))

modules/db/java/blaze/db/impl/index/ResourceHandle.java

@@ -7,7 +7,7 @@
 
 import static java.util.Objects.requireNonNull;
 
-public final class ResourceHandle implements ILookup, IKeywordLookup {
+public final class ResourceHandle implements ILookup, IKeywordLookup, IObj {
 
     public static final Comparator<ResourceHandle> ID_CMP = Comparator.comparing(rh -> rh.id);
 
@@ -85,14 +85,16 @@ public static Keyword op(long state) {
     private final long t;
     private final Hash hash;
     private final long state;
+    private final IPersistentMap meta;
 
-    public ResourceHandle(Keyword fhirType, int tid, String id, long t, Hash hash, long state) {
+    public ResourceHandle(Keyword fhirType, int tid, String id, long t, Hash hash, long state, IPersistentMap meta) {
         this.fhirType = requireNonNull(fhirType);
         this.tid = tid;
         this.id = requireNonNull(id);
         this.t = t;
         this.hash = requireNonNull(hash);
         this.state = state;
+        this.meta = meta;
     }
 
     @Override
@@ -124,6 +126,16 @@ public ILookupThunk getLookupThunk(Keyword key) {
         return null;
     }
 
+    @Override
+    public IObj withMeta(IPersistentMap meta) {
+        return new ResourceHandle(fhirType, tid, id, t, hash, state, meta);
+    }
+
+    @Override
+    public IPersistentMap meta() {
+        return meta;
+    }
+
     @Override
     public boolean equals(Object o) {
         if (this == o) return true;

modules/db/src/blaze/db/impl/index.clj

@@ -125,11 +125,11 @@
      (let [ordered-index-handles #(ordered-index-handles* batch-db tid % start-id)]
        (intersection-index-handles (map ordered-index-handles clauses))))))
 
-(defn- second-pass-filter [batch-db clauses]
+(defn- postprocess-matches [batch-db clauses]
   (transduce
    (keep
-    (fn [[search-param _ values]]
-      (p/-second-pass-filter search-param batch-db values)))
+    (fn [[search-param _ values compiled-values]]
+      (p/-postprocess-matches search-param batch-db values compiled-values)))
    comp
    clauses))
 
@@ -203,7 +203,7 @@
 (defn- resource-handle-mapper*
   ([batch-db tid clauses]
    (comp (u/resource-handle-xf batch-db tid)
-         (second-pass-filter batch-db clauses)))
+         (postprocess-matches batch-db clauses)))
   ([batch-db tid clauses other-clauses]
    (comp (other-clauses-index-handle-filter batch-db tid other-clauses)
          (resource-handle-mapper* batch-db tid clauses))))

modules/db/src/blaze/db/impl/index/resource_as_of.clj

@@ -410,3 +410,22 @@
               (rf result handle)
               result)
             result)))))))
+
+(defn- encode-seek-key [tid]
+  (-> (bb/allocate codec/tid-size)
+      (bb/put-int! tid)
+      bb/flip!
+      (bs/from-byte-buffer!)))
+
+(defn estimated-scan-size
+  "Returns a relative estimation for the amount of work to do while scanning the
+  ResourceAsOf index with the prefix consisting of `tid`.
+
+  The metric is relative and unitless. It can be only used to compare the amount
+  of scan work between different prefixes.
+
+  Returns an anomaly if estimating the scan size isn't supported by `kv-store`."
+  [kv-store tid]
+  (let [seek-key (encode-seek-key tid)
+        key-range [seek-key (bs/concat seek-key (bs/from-hex "FF"))]]
+    (kv/estimate-scan-size kv-store :resource-as-of-index key-range)))

modules/db/src/blaze/db/impl/index/resource_handle.clj

@@ -47,7 +47,8 @@
        id
        t
        hash
-       state))))
+       state
+       nil))))
 
 (defn resource-handle?
   "Returns `true` if `x` is a resource handle."

modules/db/src/blaze/db/impl/search_param.clj

@@ -13,6 +13,7 @@
    [blaze.db.impl.search-param.date]
    [blaze.db.impl.search-param.has]
    [blaze.db.impl.search-param.list]
+   [blaze.db.impl.search-param.near]
    [blaze.db.impl.search-param.number]
    [blaze.db.impl.search-param.quantity]
    [blaze.db.impl.search-param.string]

modules/db/src/blaze/db/impl/search_param/chained.clj

@@ -157,7 +157,7 @@
         nil
         (single-version-id-targets batch-db tid single-version-id ref-c-hash ref-tid)))))
 
-  (-second-pass-filter [_ _ _]))
+  (-postprocess-matches [_ _ _ _]))
 
 (defn chained-search-param
   "Creates a new chaining search param from the following arguments:

modules/db/src/blaze/db/impl/search_param/composite/token_quantity.clj

@@ -82,7 +82,7 @@
     (spq/single-version-id-matcher batch-db tid c-hash prefix-length
                                    compiled-values))
 
-  (-second-pass-filter [_ _ _])
+  (-postprocess-matches [_ _ _ _])
 
   (-index-values [_ resolver resource]
     (when-ok [values (fhir-path/eval resolver main-expression resource)]

modules/db/src/blaze/db/impl/search_param/composite/token_token.clj

@@ -61,7 +61,7 @@
   (-matcher [_ batch-db _ compiled-values]
     (r-sp-v/value-prefix-filter (:snapshot batch-db) c-hash compiled-values))
 
-  (-second-pass-filter [_ _ _])
+  (-postprocess-matches [_ _ _ _])
 
   (-index-values [_ resolver resource]
     (when-ok [values (fhir-path/eval resolver main-expression resource)]

modules/db/src/blaze/db/impl/search_param/date.clj

@@ -445,7 +445,7 @@
   (-single-version-id-matcher [_ batch-db tid _ values]
     (single-version-id-matcher batch-db tid c-hash values))
 
-  (-second-pass-filter [_ _ _])
+  (-postprocess-matches [_ _ _ _])
 
   (-index-values [search-param resolver resource]
     (when-ok [values (fhir-path/eval resolver expression resource)]

modules/db/src/blaze/db/impl/search_param/has.clj

@@ -150,7 +150,7 @@
           (p/-matcher search-param batch-db modifier compiled-values)
           (map svi/from-resource-handle)))
 
-  (-second-pass-filter [_ _ _])
+  (-postprocess-matches [_ _ _ _])
 
   (-index-values [_ _ _]
     []))

modules/db/src/blaze/db/impl/search_param/list.clj

@@ -89,7 +89,7 @@
   (-ordered-compartment-index-handles [_ _ _ _ _ _]
     (ba/unsupported))
 
-  (-second-pass-filter [_ _ _])
+  (-postprocess-matches [_ _ _ _])
 
   (-index-values [_ _ _]
     []))