Availability Task

Purpose

An Availability Task is a standardised request triggered by a researcher asking for a count of individuals matching a defined cohort specification. The task includes metadata such as the collection ID, and task ID, along with the cohort definition expressed as structured rules.

Upon retrieving the task, Bunny securely queries the OMOP dataset within the Data Custodian’s environment. The result is a numerical count of matching records, subject to disclosure controls.

💡

No raw or identifiable data leaves the system; only the count is returned.

Example Input Schema

An example Availability task:

This task uses one Rule, to instruct Bunny to query the OMOP condition_occurrence table for individuals who have a recorded condition concept ID equal to 4323688, which represents a specific clinical condition (“Cough at rest”).

The time field specifies a time constraint:

1|:TIME:M indicates the condition must have occurred at least one month ago (i.e. the record’s start date is at least one month before the time of query execution).

Only individuals with at least one such condition occurrence meeting this time constraint will match this rule.

{
  "task_id" : "job-2025-02-14-09:03:27-RQ-87808b58-b878-4b59-839f-3537727c64a6",
  "project" : "project_id",
  "owner" : "user1",
  "cohort" : {
    "groups": [
      {
        "rules": [
          {
            "varname": "OMOP",
            "varcat": "Condition",
            "type": "TEXT",
            "oper": "=",
            "value": "4323688",
            "time": "1|:TIME:M"
          }
        ],
        "rules_oper": "OR"
      }
    ],
    "groups_oper": "AND"
  },
  "collection": "collection_id",
  "protocol_version" : "v2",
  "char_salt" : "salt",
  "uuid" : "9541374b-8b97-41a4-9717-4a2a25f437ae"
}

This is the SQL executed by Bunny in response to the task.

It calculates an anonymised count of individuals who have a record matching a specific concept ID (4323688) in any of the four core OMOP tables: measurement, observation, condition_occurrence, or drug_exposure, with the relevant event date occurring on or before 2025-04-08 21:05:24.471729. -UNION Subqueries: Each subquery selects person_ids from a different domain table where the concept_id matches 4323688. -Time Filter: Each subquery includes only rows with a date on or before 2025-07-01 09:14:26.842531. -OR Logic: A person is included if they appear in any one of the four subqueries. -Deduplication: UNION ensures each person_id appears only once, even if matched in multiple tables. -Outer Query: Counts the total number of unique person_ids returned from the union.

Disclosure control:

The count is rounded to the nearest 10 for disclosure control (ROUND(count / 10) * 10).
The result is only returned if at least 10 people meet the criteria (HAVING count(*) >= 10).

WITH final_group_0 AS
        ((SELECT measurement.person_id AS person_id
          FROM measurement
          WHERE measurement.measurement_concept_id = 4323688
            AND measurement.measurement_date <= '2025-07-01 09:14:26.842531'
          
          UNION
          
          SELECT observation.person_id AS person_id
          FROM observation
          WHERE observation.observation_concept_id = 4323688
            AND observation.observation_date <= '2025-07-01 09:14:26.842531'
          
          UNION
          
          SELECT condition_occurrence.person_id AS person_id
          FROM condition_occurrence
          WHERE condition_occurrence.condition_concept_id = 4323688
            AND condition_occurrence.condition_start_date <= '2025-07-01 09:14:26.842531'
          
          UNION
          
          SELECT drug_exposure.person_id AS person_id
          FROM drug_exposure
          WHERE drug_exposure.drug_concept_id = 4323688
            AND drug_exposure.drug_exposure_start_date <= '2025-07-01 09:14:26.842531'
 
          UNION
 
          SELECT procedure_occurrence.person_id AS person_id 
          FROM procedure_occurrence 
          WHERE procedure_occurrence.procedure_concept_id = 4323688 
            AND procedure_occurrence.procedure_date <= '2025-07-01 09:14:26.842531'))
 
SELECT round(count(*) / CAST(10 AS NUMERIC), 0) * 10 AS anon_1
FROM (SELECT final_group_0.person_id AS person_id
      FROM final_group_0) AS anon_2
HAVING count(*) >= 10

Location filtering

varcat: "Location" filters patients by geographic location, using the GEO_RADIUS rule type. It must be enabled with OMOP_LOCATION_ENABLED (see Configuration), and requires an OMOP CDM v5.4 database — see Requirements.

type: "GEO_RADIUS" matches patients whose location falls within a given radius of a centre point. The value field is a pipe-delimited latitude|longitude|radius_metres string. Patients with no recorded latitude/longitude are never matched.

{
  "varname": "OMOP",
  "varcat": "Location",
  "type": "GEO_RADIUS",
  "oper": "=",
  "value": "51.5074|-0.1278|5000"
}

This example matches patients within 5km of central London. Set "oper": "!=" to exclude patients within the radius instead.

Death filtering

varcat: "Death" filters patients by whether, and how, they died, using the OMOP death table. It must be enabled with OMOP_DEATH_ENABLED (see Configuration).

type: "TEXT" is used for all Death rules. The value field is optional — leave it empty to match on the presence of a death record at all, or set it to an OMOP concept ID to match a specific cause of death (death.cause_concept_id).

Deceased patients (any cause):

{
  "varname": "OMOP",
  "varcat": "Death",
  "type": "TEXT",
  "oper": "=",
  "value": ""
}

Living patients — set "oper": "!=" with an empty value to match patients with no death record:

{
  "varname": "OMOP",
  "varcat": "Death",
  "type": "TEXT",
  "oper": "!=",
  "value": ""
}

Specific cause of death — set value to a concept ID to match patients whose recorded cause of death is that concept:

{
  "varname": "OMOP",
  "varcat": "Death",
  "type": "TEXT",
  "oper": "=",
  "value": "4329847"
}

Combine a Death rule with rules from other varcats in the same group (rules_oper: "AND") to find, for example, deceased patients who also have a specific condition recorded.

Response Schema

Bunny returns a structured JSON response upon completing an Availability Query.

The key field is the queryResult.count, the number of individuals in the dataset who met the specified criteria.

{
  "status": "ok",
  "protocolVersion": "v2",
  "uuid": "9541374b-8b97-41a4-9717-4a2a25f437ae",
  "queryResult": {
    "count": 10,
    "datasetCount": 0,
    "files": []
  },
  "message": "",
  "collection_id": "collection_id"
}

Disclosure Controls Distribution Task