BunnyQuickstart

Quickstart

The easiest way to run Bunny is by using the provided Bunny Image command line interface to query an OMOP CDM database, without needing an upstream Task API.

This guide will help you quickly set up a local OMOP CDM database and run a query against it.

Prerequisites

  • Docker

Run a query

Get the Demo Compose file

Download the sample Bunny Demo Compose file by running the command:

curl -O https://raw.githubusercontent.com/Health-Informatics-UoN/hutch/refs/heads/main/samples/Bunny/compose/bunny-demo.compose.yml

Or manually saving it to a file bunny-demo.compose.yml

Get the Demo Availability Query

Download the sample Availability Query

For simplicity, ensure the file is next to the Compose file from Step 1.

curl -O https://raw.githubusercontent.com/Health-Informatics-UoN/hutch-bunny/refs/heads/main/tests/queries/availability/availability.json

Or manually saving it to a file availability.json

The query file is a JSON file that contains the query to run, which is a simple cohort definition, querying the Person table for 8507.

availability.json
{
  "task_id": "job-2023-01-13-14: 20: 38-project",
  "project": "project_id",
  "owner": "user1",
  "cohort": {
    "groups": [
      {
        "rules": [
          {
            "varname": "OMOP",
            "varcat": "Person",
            "type": "TEXT",
            "oper": "=",
            "value": "8507"
          }
        ],
        "rules_oper": "AND"
      }
    ],
    "groups_oper": "OR"
  },
  "collection": "collection_id",
  "protocol_version": "v2",
  "char_salt": "salt",
  "uuid": "unique_id"
}
👍

You can also provide your own Availability Query to run via the Bunny CLI.

Run the Compose file

This will start the database, initialise it with a synthetic OMOP CDM dataset, and run a query against it.

Note that we also need to bind mount a docker volume so the Bunny container can access the input query.

docker compose -f bunny-demo.compose.yml \
run \
-v "$(pwd)"/availability.json:/var/queries/availability.json:ro \
bunny bunny \
--body /var/queries/availability.json --output /tmp/output.json

This will take a minute or so to download the images and start the containers.

🎉
Congratulations on your first Bunny query!

View the results

You should see output like the following:

{
  "status": "ok",
  "protocolVersion": "v2",
  "uuid": "unique_id",
  "queryResult": {
    "count": 40,
    "datasetCount": 0,
    "files": []
  },
  "message": "",
  "collection_id": "collection_id"
}

That contains the results of the query, which was 44.

Clean up

docker compose -f bunny-demo.compose.yml down

This will stop the database and remove the containers.

To remove the images, run:

docker rmi -f ghcr.io/health-informatics-uon/omop-lite:latest ghcr.io/health-informatics-uon/hutch/bunny:edge

Next Steps

To connect your Bunny to a upstream Task API, read the deployment guide.

BunnyDeploy Bunny